openapi: 3.0.1
info:
  title: Paddle Addresses Subscriptions API
  description: Paddle Billing API for subscription and recurring revenue management. As a merchant of record, Paddle manages products, prices, customers, addresses, businesses, subscriptions, transactions, invoices, adjustments, discounts, reports, and webhook notifications while handling global sales tax, payment processing, fraud, and compliance on the seller's behalf. This is a curated OpenAPI description of the public REST endpoints; Paddle publishes the canonical OpenAPI at https://github.com/PaddleHQ/paddle-openapi.
  termsOfService: https://www.paddle.com/legal/terms
  contact:
    name: Paddle Support
    url: https://www.paddle.com/support
  version: '1.0'
servers:
- url: https://api.paddle.com
  description: Production
- url: https://sandbox-api.paddle.com
  description: Sandbox
security:
- bearerAuth: []
tags:
- name: Subscriptions
paths:
  /subscriptions:
    get:
      operationId: list-subscriptions
      tags:
      - Subscriptions
      summary: List subscriptions
      parameters:
      - $ref: '#/components/parameters/after'
      - $ref: '#/components/parameters/perPage'
      - name: status
        in: query
        schema:
          type: string
          enum:
          - active
          - canceled
          - past_due
          - paused
          - trialing
      responses:
        '200':
          description: Returns a paginated list of subscriptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionCollection'
  /subscriptions/{subscription_id}:
    parameters:
    - $ref: '#/components/parameters/subscriptionId'
    get:
      operationId: get-subscription
      tags:
      - Subscriptions
      summary: Get a subscription
      responses:
        '200':
          description: Returns a subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionEntity'
    patch:
      operationId: update-subscription
      tags:
      - Subscriptions
      summary: Update a subscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Returns the updated subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionEntity'
  /subscriptions/{subscription_id}/activate:
    parameters:
    - $ref: '#/components/parameters/subscriptionId'
    post:
      operationId: activate-subscription
      tags:
      - Subscriptions
      summary: Activate a trialing subscription
      responses:
        '200':
          description: Returns the activated subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionEntity'
  /subscriptions/{subscription_id}/pause:
    parameters:
    - $ref: '#/components/parameters/subscriptionId'
    post:
      operationId: pause-subscription
      tags:
      - Subscriptions
      summary: Pause a subscription
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Returns the paused subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionEntity'
  /subscriptions/{subscription_id}/resume:
    parameters:
    - $ref: '#/components/parameters/subscriptionId'
    post:
      operationId: resume-subscription
      tags:
      - Subscriptions
      summary: Resume a paused subscription
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Returns the resumed subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionEntity'
  /subscriptions/{subscription_id}/cancel:
    parameters:
    - $ref: '#/components/parameters/subscriptionId'
    post:
      operationId: cancel-subscription
      tags:
      - Subscriptions
      summary: Cancel a subscription
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                effective_from:
                  type: string
                  enum:
                  - next_billing_period
                  - immediately
      responses:
        '200':
          description: Returns the canceled subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionEntity'
  /subscriptions/{subscription_id}/charge:
    parameters:
    - $ref: '#/components/parameters/subscriptionId'
    post:
      operationId: create-one-time-charge
      tags:
      - Subscriptions
      summary: Create a one-time charge for a subscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Returns the updated subscription with the one-time charge.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionEntity'
  /subscriptions/{subscription_id}/update-payment-method-transaction:
    parameters:
    - $ref: '#/components/parameters/subscriptionId'
    get:
      operationId: get-update-payment-method-transaction
      tags:
      - Subscriptions
      summary: Get a transaction to update payment method
      responses:
        '200':
          description: Returns a transaction used to update the payment method.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionEntity'
components:
  parameters:
    after:
      name: after
      in: query
      description: Return entities after the specified cursor for keyset pagination.
      schema:
        type: string
    perPage:
      name: per_page
      in: query
      description: Number of entities per page.
      schema:
        type: integer
        default: 50
        maximum: 200
    subscriptionId:
      name: subscription_id
      in: path
      required: true
      schema:
        type: string
  schemas:
    Transaction:
      type: object
      properties:
        id:
          type: string
          example: txn_01gsz4t5hdjse780zja8vvr7jg
        status:
          type: string
          enum:
          - draft
          - ready
          - billed
          - paid
          - completed
          - canceled
          - past_due
        customer_id:
          type: string
          nullable: true
        subscription_id:
          type: string
          nullable: true
        currency_code:
          type: string
        origin:
          type: string
        collection_mode:
          type: string
          enum:
          - automatic
          - manual
        items:
          type: array
          items:
            type: object
        details:
          type: object
        created_at:
          type: string
          format: date-time
    SubscriptionCollection:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Subscription'
        meta:
          $ref: '#/components/schemas/Meta'
    SubscriptionEntity:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Subscription'
        meta:
          $ref: '#/components/schemas/Meta'
    TransactionEntity:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Transaction'
        meta:
          $ref: '#/components/schemas/Meta'
    Subscription:
      type: object
      properties:
        id:
          type: string
          example: sub_01gsz4t5hdjse780zja8vvr7jg
        status:
          type: string
          enum:
          - active
          - canceled
          - past_due
          - paused
          - trialing
        customer_id:
          type: string
        address_id:
          type: string
        currency_code:
          type: string
        billing_cycle:
          type: object
        current_billing_period:
          type: object
          nullable: true
        items:
          type: array
          items:
            type: object
        next_billed_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
    Meta:
      type: object
      properties:
        request_id:
          type: string
        pagination:
          type: object
          properties:
            per_page:
              type: integer
            next:
              type: string
            has_more:
              type: boolean
            estimated_total:
              type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Authenticate with your Paddle API key passed in the Authorization header with the Bearer prefix, e.g. `Authorization: Bearer pdl_live_apikey_...`.'