Paddle Products API

openapi: 3.0.1
info:
  title: Paddle 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: Products
  - name: Prices
  - name: Customers
  - name: Addresses
  - name: Businesses
  - name: Subscriptions
  - name: Transactions
  - name: Adjustments
  - name: Discounts
  - name: Reports
  - name: Notifications
  - name: Notification Settings
  - name: Events
  - name: Event Types
paths:
  /products:
    get:
      operationId: list-products
      tags: [Products]
      summary: List products
      parameters:
        - $ref: '#/components/parameters/after'
        - $ref: '#/components/parameters/perPage'
        - name: status
          in: query
          schema:
            type: string
            enum: [active, archived]
      responses:
        '200':
          description: Returns a paginated list of products.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductCollection'
    post:
      operationId: create-product
      tags: [Products]
      summary: Create a product
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductCreate'
      responses:
        '201':
          description: Returns the created product.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductEntity'
  /products/{product_id}:
    parameters:
      - $ref: '#/components/parameters/productId'
    get:
      operationId: get-product
      tags: [Products]
      summary: Get a product
      responses:
        '200':
          description: Returns a product.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductEntity'
    patch:
      operationId: update-product
      tags: [Products]
      summary: Update a product
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductCreate'
      responses:
        '200':
          description: Returns the updated product.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductEntity'
  /prices:
    get:
      operationId: list-prices
      tags: [Prices]
      summary: List prices
      parameters:
        - $ref: '#/components/parameters/after'
        - $ref: '#/components/parameters/perPage'
      responses:
        '200':
          description: Returns a paginated list of prices.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceCollection'
    post:
      operationId: create-price
      tags: [Prices]
      summary: Create a price
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PriceCreate'
      responses:
        '201':
          description: Returns the created price.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceEntity'
  /prices/{price_id}:
    parameters:
      - $ref: '#/components/parameters/priceId'
    get:
      operationId: get-price
      tags: [Prices]
      summary: Get a price
      responses:
        '200':
          description: Returns a price.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceEntity'
    patch:
      operationId: update-price
      tags: [Prices]
      summary: Update a price
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PriceCreate'
      responses:
        '200':
          description: Returns the updated price.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceEntity'
  /pricing-preview:
    post:
      operationId: preview-prices
      tags: [Prices]
      summary: Preview prices
      description: >-
        Previews calculated totals for a set of prices for a given location,
        including localized currency and tax, without creating a transaction.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                items:
                  type: array
                  items:
                    type: object
                    properties:
                      price_id:
                        type: string
                      quantity:
                        type: integer
                customer_id:
                  type: string
                address:
                  type: object
                currency_code:
                  type: string
      responses:
        '200':
          description: Returns a pricing preview with localized totals.
          content:
            application/json:
              schema:
                type: object
  /customers:
    get:
      operationId: list-customers
      tags: [Customers]
      summary: List customers
      parameters:
        - $ref: '#/components/parameters/after'
        - $ref: '#/components/parameters/perPage'
      responses:
        '200':
          description: Returns a paginated list of customers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerCollection'
    post:
      operationId: create-customer
      tags: [Customers]
      summary: Create a customer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerCreate'
      responses:
        '201':
          description: Returns the created customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerEntity'
  /customers/{customer_id}:
    parameters:
      - $ref: '#/components/parameters/customerId'
    get:
      operationId: get-customer
      tags: [Customers]
      summary: Get a customer
      responses:
        '200':
          description: Returns a customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerEntity'
    patch:
      operationId: update-customer
      tags: [Customers]
      summary: Update a customer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerCreate'
      responses:
        '200':
          description: Returns the updated customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerEntity'
  /customers/{customer_id}/addresses:
    parameters:
      - $ref: '#/components/parameters/customerId'
    get:
      operationId: list-addresses
      tags: [Addresses]
      summary: List addresses for a customer
      responses:
        '200':
          description: Returns a paginated list of addresses.
          content:
            application/json:
              schema:
                type: object
    post:
      operationId: create-address
      tags: [Addresses]
      summary: Create an address for a customer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Address'
      responses:
        '201':
          description: Returns the created address.
          content:
            application/json:
              schema:
                type: object
  /customers/{customer_id}/addresses/{address_id}:
    parameters:
      - $ref: '#/components/parameters/customerId'
      - $ref: '#/components/parameters/addressId'
    get:
      operationId: get-address
      tags: [Addresses]
      summary: Get an address for a customer
      responses:
        '200':
          description: Returns an address.
          content:
            application/json:
              schema:
                type: object
    patch:
      operationId: update-address
      tags: [Addresses]
      summary: Update an address for a customer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Address'
      responses:
        '200':
          description: Returns the updated address.
          content:
            application/json:
              schema:
                type: object
  /customers/{customer_id}/businesses:
    parameters:
      - $ref: '#/components/parameters/customerId'
    get:
      operationId: list-businesses
      tags: [Businesses]
      summary: List businesses for a customer
      responses:
        '200':
          description: Returns a paginated list of businesses.
          content:
            application/json:
              schema:
                type: object
    post:
      operationId: create-business
      tags: [Businesses]
      summary: Create a business for a customer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Business'
      responses:
        '201':
          description: Returns the created business.
          content:
            application/json:
              schema:
                type: object
  /customers/{customer_id}/businesses/{business_id}:
    parameters:
      - $ref: '#/components/parameters/customerId'
      - $ref: '#/components/parameters/businessId'
    get:
      operationId: get-business
      tags: [Businesses]
      summary: Get a business for a customer
      responses:
        '200':
          description: Returns a business.
          content:
            application/json:
              schema:
                type: object
    patch:
      operationId: update-business
      tags: [Businesses]
      summary: Update a business for a customer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Business'
      responses:
        '200':
          description: Returns the updated business.
          content:
            application/json:
              schema:
                type: object
  /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'
  /transactions:
    get:
      operationId: list-transactions
      tags: [Transactions]
      summary: List transactions
      parameters:
        - $ref: '#/components/parameters/after'
        - $ref: '#/components/parameters/perPage'
        - name: status
          in: query
          schema:
            type: string
            enum: [draft, ready, billed, paid, completed, canceled, past_due]
      responses:
        '200':
          description: Returns a paginated list of transactions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionCollection'
    post:
      operationId: create-transaction
      tags: [Transactions]
      summary: Create a transaction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Returns the created transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionEntity'
  /transactions/{transaction_id}:
    parameters:
      - $ref: '#/components/parameters/transactionId'
    get:
      operationId: get-transaction
      tags: [Transactions]
      summary: Get a transaction
      responses:
        '200':
          description: Returns a transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionEntity'
    patch:
      operationId: update-transaction
      tags: [Transactions]
      summary: Update a transaction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Returns the updated transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionEntity'
  /transactions/{transaction_id}/invoice:
    parameters:
      - $ref: '#/components/parameters/transactionId'
    get:
      operationId: get-transaction-invoice
      tags: [Transactions]
      summary: Get a PDF invoice for a transaction
      responses:
        '200':
          description: Returns a URL to the PDF invoice for the transaction.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      url:
                        type: string
                        format: uri
  /adjustments:
    get:
      operationId: list-adjustments
      tags: [Adjustments]
      summary: List adjustments
      parameters:
        - $ref: '#/components/parameters/after'
        - $ref: '#/components/parameters/perPage'
      responses:
        '200':
          description: Returns a paginated list of adjustments.
          content:
            application/json:
              schema:
                type: object
    post:
      operationId: create-adjustment
      tags: [Adjustments]
      summary: Create an adjustment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdjustmentCreate'
      responses:
        '201':
          description: Returns the created adjustment.
          content:
            application/json:
              schema:
                type: object
  /adjustments/{adjustment_id}/credit-note:
    parameters:
      - $ref: '#/components/parameters/adjustmentId'
    get:
      operationId: get-adjustment-credit-note
      tags: [Adjustments]
      summary: Get a PDF credit note for an adjustment
      responses:
        '200':
          description: Returns a URL to the PDF credit note for the adjustment.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      url:
                        type: string
                        format: uri
  /discounts:
    get:
      operationId: list-discounts
      tags: [Discounts]
      summary: List discounts
      parameters:
        - $ref: '#/components/parameters/after'
        - $ref: '#/components/parameters/perPage'
      responses:
        '200':
          description: Returns a paginated list of discounts.
          content:
            application/json:
              schema:
                type: object
  /reports:
    get:
      operationId: list-reports
      tags: [Reports]
      summary: List reports
      responses:
        '200':
          description: Returns a paginated list of reports.
          content:
            application/json:
              schema:
                type: object
    post:
      operationId: create-report
      tags: [Reports]
      summary: Create a report
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Returns the created report.
          content:
            application/json:
              schema:
                type: object
  /reports/{report_id}:
    parameters:
      - $ref: '#/components/parameters/reportId'
    get:
      operationId: get-report
      tags: [Reports]
      summary: Get a report
      responses:
        '200':
          description: Returns a report.
          content:
            application/json:
              schema:
                type: object
  /reports/{report_id}/csv:
    parameters:
      - $ref: '#/components/parameters/reportId'
    get:
      operationId: get-report-csv
      tags: [Reports]
      summary: Get a CSV file for a report
      responses:
        '200':
          description: Returns a URL to download the report as CSV.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      url:
                        type: string
                        format: uri
  /notifications:
    get:
      operationId: list-notifications
      tags: [Notifications]
      summary: List notifications
      responses:
        '200':
          description: Returns a paginated list of notifications.
          content:
            application/json:
              schema:
                type: object
  /notifications/{notification_id}:
    parameters:
      - $ref: '#/components/parameters/notificationId'
    get:
      operationId: get-notification
      tags: [Notifications]
      summary: Get a notification
      responses:
        '200':
          description: Returns a notification.
          content:
            application/json:
              schema:
                type: object
  /notifications/{notification_id}/replay:
    parameters:
      - $ref: '#/components/parameters/notificationId'
    post:
      operationId: replay-notification
      tags: [Notifications]
      summary: Replay a notification
      responses:
        '200':
          description: Returns the notification that was queued for replay.
          content:
            application/json:
              schema:
                type: object
  /notification-settings:
    get:
      operationId: list-notification-settings
      tags: [Notification Settings]
      summary: List notification settings (destinations)
      responses:
        '200':
          description: Returns a list of notification settings.
          content:
            application/json:
              schema:
                type: object
    post:
      operationId: create-notification-setting
      tags: [Notification Settings]
      summary: Create a notification setting (destination)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationSetting'
      responses:
        '201':
          description: Returns the created notification setting.
          content:
            application/json:
              schema:
                type: object
  /notification-settings/{notification_setting_id}:
    parameters:
      - $ref: '#/components/parameters/notificationSettingId'
    get:
      operationId: get-notification-setting
      tags: [Notification Settings]
      summary: Get a notification setting
      responses:
        '200':
          description: Returns a notification setting.
          content:
            application/json:
              schema:
                type: object
    patch:
      operationId: update-notification-setting
      tags: [Notification Settings]
      summary: Update a notification setting
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationSetting'
      responses:
        '200':
          description: Returns the updated notification setting.
          content:
            application/json:
              schema:
                type: object
    delete:
      operationId: delete-notification-setting
      tags: [Notification Settings]
      summary: Delete a notification setting
      responses:
        '204':
          description: The notification setting was deleted.
  /events:
    get:
      operationId: list-events
      tags: [Events]
      summary: List events
      parameters:
        - $ref: '#/components/parameters/after'
        - $ref: '#/components/parameters/perPage'
      responses:
        '200':
          description: Returns a paginated list of events.
          content:
            application/json:
              schema:
                type: object
  /event-types:
    get:
      operationId: list-event-types
      tags: [Event Types]
      summary: List event types
      responses:
        '200':
          description: Returns a list of available event types.
          content:
            application/json:
              schema:
                type: object
components:
  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_...`.
  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
    productId:
      name: product_id
      in: path
      required: true
      schema:
        type: string
    priceId:
      name: price_id
      in: path
      required: true
      schema:
        type: string
    customerId:
      name: customer_id
      in: path
      required: true
      schema:
        type: string
    addressId:
      name: address_id
      in: path
      required: true
      schema:
        type: string
    businessId:
      name: business_id
      in: path
      required: true
      schema:
        type: string
    subscriptionId:
      name: subscription_id
      in: path
      required: true
      schema:
        type: string
    transactionId:
      name: transaction_id
      in: path
      required: true
      schema:
        type: string
    adjustmentId:
      name: adjustment_id
      in: path
      required: true
      schema:
        type: string
    reportId:
      name: report_id
      in: path
      required: true
      schema:
        type: string
    notificationId:
      name: notification_id
      in: path
      required: true
      schema:
        type: string
    notificationSettingId:
      name: notification_setting_id
      in: path
      required: true
      schema:
        type: string
  schemas:
    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
    Product:
      type: object
      properties:
        id:
          type: string
          example: pro_01gsz4t5hdjse780zja8vvr7jg
        name:
          type: string
        description:
          type: string
          nullable: true
        type:
          type: string
          enum: [standard, custom]
        tax_category:
          type: string
          enum:
            - digital-goods
            - ebooks
            - implementation-services
            - professional-services
            - saas
            - software-programming-services
            - standard
            - training-services
            - website-hosting
        image_url:
          type: string
          nullable: true
        custom_data:
          type: object
          nullable: true
        status:
          type: string
          enum: [active, archived]
        created_at:
          type: string
          format: date-time
    ProductCreate:
      type: object
      required: [name, tax_category]
      properties:
        name:
          type: string
        tax_category:
          type: string
        description:
          type: string
        image_url:
          type: string
        custom_data:
          type: object
    ProductEntity:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Product'
        meta:
          $ref: '#/components/schemas/Meta'
    ProductCollection:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Product'
        meta:
          $ref: '#/components/schemas/Meta'
    Price:
      type: object
      properties:
        id:
          type: string
          example: pri_01gsz8x8sawmvhz1pv30nge1ke
        product_id:
          type: string
        description:
          type: string
        type:
          type: string
          enum: [standard, custom]
        billing_cycle:
          type: object
          nullable: true
          properties:
            interval:
              type: string
              enum: [day, week, month, year]
            frequency:
              type: integer
        trial_period:
          type: object
          nullable: true
        unit_price:
          $ref: '#/components/schemas/Money'
        status:
          type: string
          enum: [active, archived]
    PriceCreate:
      type: object
      required: [product_id, description, unit_price]
      properties:
        product_id:
          type: string
        description:
          type: string
        unit_price:
          $ref: '#/components/schemas/Money'
        billing_cycle:
          type: object
        trial_period:
          type: object
    PriceEntity:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Price'
        meta:
          $ref: '#/components/schemas/Meta'
    PriceCollection:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Price'
        meta:
          $ref: '#/components/schemas/Meta'
    Money:
      type: object
      properties:
        amount:
          type: string
          description: Amount in the lowest denomination of the currency (e.g. cents).
        currency_code:
          type: string
          example: USD
    Customer:
      type: object
      properties:
        id:
          type: string
          example: ctm_01gsz4t5hdjse780zja8vvr7jg
        name:
          type: string
          nullable: true
        email:
          type: string
          format: email
        marketing_consent:
          type: boolean
        locale:
          type: string
        status:
          type: string
          enum: [active, archived]
        custom_data:
          type: object
        

# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paddle/refs/heads/main/openapi/paddle-openapi.yml