Dodo Payments Products API

openapi: 3.0.1
info:
  title: Dodo Payments API
  description: >-
    REST API for the Dodo Payments merchant-of-record (MoR) platform. Covers
    products, one-time payments, subscriptions, customers, checkout sessions,
    discounts, license keys, payouts, refunds, disputes, and webhooks. Dodo
    Payments acts as the seller of record and handles global sales tax, VAT,
    and GST calculation, collection, and remittance.
  termsOfService: https://dodopayments.com/legal/terms-of-service
  contact:
    name: Dodo Payments Support
    url: https://docs.dodopayments.com
    email: support@dodopayments.com
  version: '1.0'
servers:
  - url: https://live.dodopayments.com
    description: Live mode
  - url: https://test.dodopayments.com
    description: Test mode
security:
  - bearerAuth: []
tags:
  - name: Products
  - name: Payments
  - name: Subscriptions
  - name: Customers
  - name: Checkout Sessions
  - name: Discounts
  - name: Licenses
  - name: License Keys
  - name: Payouts
  - name: Refunds
  - name: Disputes
  - name: Webhooks
paths:
  /products:
    get:
      operationId: listProducts
      tags:
        - Products
      summary: List products
      parameters:
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A paginated list of products.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductList'
    post:
      operationId: createProduct
      tags:
        - Products
      summary: Create a product
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProductRequest'
      responses:
        '200':
          description: The created product.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
  /products/{id}:
    get:
      operationId: getProduct
      tags:
        - Products
      summary: Get a product
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: The product.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
    patch:
      operationId: updateProduct
      tags:
        - Products
      summary: Update a product
      parameters:
        - $ref: '#/components/parameters/IdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProductRequest'
      responses:
        '200':
          description: The product was updated.
  /products/{id}/archive:
    post:
      operationId: archiveProduct
      tags:
        - Products
      summary: Archive a product
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: The product was archived.
  /products/{id}/unarchive:
    post:
      operationId: unarchiveProduct
      tags:
        - Products
      summary: Unarchive a product
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: The product was unarchived.
  /payments:
    get:
      operationId: listPayments
      tags:
        - Payments
      summary: List payments
      parameters:
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
        - name: customer_id
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
      responses:
        '200':
          description: A paginated list of payments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentList'
    post:
      operationId: createPayment
      tags:
        - Payments
      summary: Create a one-time payment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentRequest'
      responses:
        '200':
          description: The created payment, including a hosted payment link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
  /payments/{id}:
    get:
      operationId: getPayment
      tags:
        - Payments
      summary: Get a payment
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: The payment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
  /payments/{id}/invoice:
    get:
      operationId: getPaymentInvoice
      tags:
        - Payments
      summary: Get the invoice for a payment
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: The invoice PDF for the payment.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
  /payments/{id}/line-items:
    get:
      operationId: getPaymentLineItems
      tags:
        - Payments
      summary: Retrieve payment line items
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: The line items for the payment.
  /subscriptions:
    get:
      operationId: listSubscriptions
      tags:
        - Subscriptions
      summary: List subscriptions
      parameters:
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A paginated list of subscriptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionList'
    post:
      operationId: createSubscription
      tags:
        - Subscriptions
      summary: Create a subscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubscriptionRequest'
      responses:
        '200':
          description: The created subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
  /subscriptions/{id}:
    get:
      operationId: getSubscription
      tags:
        - Subscriptions
      summary: Get a subscription
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: The subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
    patch:
      operationId: updateSubscription
      tags:
        - Subscriptions
      summary: Update a subscription
      parameters:
        - $ref: '#/components/parameters/IdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata:
                  type: object
                  additionalProperties:
                    type: string
                tax_id:
                  type: string
                status:
                  type: string
      responses:
        '200':
          description: The subscription was updated.
  /subscriptions/{id}/charge:
    post:
      operationId: createSubscriptionCharge
      tags:
        - Subscriptions
      summary: Create an on-demand charge on a subscription
      parameters:
        - $ref: '#/components/parameters/IdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - product_price
              properties:
                product_price:
                  type: integer
                  description: Amount in the smallest currency unit.
                adaptive_currency_fees_inclusive:
                  type: boolean
      responses:
        '200':
          description: The on-demand charge was created.
  /subscriptions/{id}/change-plan:
    post:
      operationId: changeSubscriptionPlan
      tags:
        - Subscriptions
      summary: Change a subscription plan
      parameters:
        - $ref: '#/components/parameters/IdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - product_id
                - proration_billing_mode
              properties:
                product_id:
                  type: string
                quantity:
                  type: integer
                proration_billing_mode:
                  type: string
                  enum:
                    - prorated_immediately
                    - full_immediately
      responses:
        '200':
          description: The plan was changed.
  /customers:
    get:
      operationId: listCustomers
      tags:
        - Customers
      summary: List customers
      parameters:
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
        - name: email
          in: query
          schema:
            type: string
      responses:
        '200':
          description: A paginated list of customers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerList'
    post:
      operationId: createCustomer
      tags:
        - Customers
      summary: Create a customer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerRequest'
      responses:
        '200':
          description: The created customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
  /customers/{id}:
    get:
      operationId: getCustomer
      tags:
        - Customers
      summary: Get a customer
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: The customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
    patch:
      operationId: updateCustomer
      tags:
        - Customers
      summary: Update a customer
      parameters:
        - $ref: '#/components/parameters/IdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerRequest'
      responses:
        '200':
          description: The customer was updated.
  /customers/{id}/customer-portal/session:
    post:
      operationId: createCustomerPortalSession
      tags:
        - Customers
      summary: Create a customer portal session
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: A customer portal session with a hosted link.
          content:
            application/json:
              schema:
                type: object
                properties:
                  link:
                    type: string
                    format: uri
  /checkouts:
    post:
      operationId: createCheckoutSession
      tags:
        - Checkout Sessions
      summary: Create a checkout session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCheckoutSessionRequest'
      responses:
        '200':
          description: The created checkout session, including a hosted checkout URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutSession'
  /checkouts/{session_id}:
    get:
      operationId: getCheckoutSession
      tags:
        - Checkout Sessions
      summary: Get a checkout session
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The checkout session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutSession'
  /discounts:
    get:
      operationId: listDiscounts
      tags:
        - Discounts
      summary: List discounts
      parameters:
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A paginated list of discounts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscountList'
    post:
      operationId: createDiscount
      tags:
        - Discounts
      summary: Create a discount
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDiscountRequest'
      responses:
        '200':
          description: The created discount.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Discount'
  /discounts/{discount_id}:
    get:
      operationId: getDiscount
      tags:
        - Discounts
      summary: Get a discount
      parameters:
        - name: discount_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The discount.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Discount'
    patch:
      operationId: updateDiscount
      tags:
        - Discounts
      summary: Update a discount
      parameters:
        - name: discount_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDiscountRequest'
      responses:
        '200':
          description: The discount was updated.
    delete:
      operationId: deleteDiscount
      tags:
        - Discounts
      summary: Delete a discount
      parameters:
        - name: discount_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The discount was deleted.
  /licenses/validate:
    post:
      operationId: validateLicense
      tags:
        - Licenses
      summary: Validate a license key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - license_key
              properties:
                license_key:
                  type: string
                license_key_instance_id:
                  type: string
      responses:
        '200':
          description: License validation result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid:
                    type: boolean
  /licenses/activate:
    post:
      operationId: activateLicense
      tags:
        - Licenses
      summary: Activate a license key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - license_key
                - name
              properties:
                license_key:
                  type: string
                name:
                  type: string
                  description: Name for the license key instance.
      responses:
        '200':
          description: The created license key instance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LicenseKeyInstance'
  /licenses/deactivate:
    post:
      operationId: deactivateLicense
      tags:
        - Licenses
      summary: Deactivate a license key instance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - license_key
                - license_key_instance_id
              properties:
                license_key:
                  type: string
                license_key_instance_id:
                  type: string
      responses:
        '200':
          description: The license key instance was deactivated.
  /license_keys:
    get:
      operationId: listLicenseKeys
      tags:
        - License Keys
      summary: List license keys
      parameters:
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A paginated list of license keys.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LicenseKeyList'
  /license_keys/{id}:
    get:
      operationId: getLicenseKey
      tags:
        - License Keys
      summary: Get a license key
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: The license key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LicenseKey'
    patch:
      operationId: updateLicenseKey
      tags:
        - License Keys
      summary: Update a license key
      parameters:
        - $ref: '#/components/parameters/IdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                activations_limit:
                  type: integer
                disabled:
                  type: boolean
                expires_at:
                  type: string
                  format: date-time
      responses:
        '200':
          description: The license key was updated.
  /payouts:
    get:
      operationId: listPayouts
      tags:
        - Payouts
      summary: List payouts
      parameters:
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A paginated list of payouts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutList'
  /refunds:
    get:
      operationId: listRefunds
      tags:
        - Refunds
      summary: List refunds
      parameters:
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A paginated list of refunds.
    post:
      operationId: createRefund
      tags:
        - Refunds
      summary: Create a refund
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - payment_id
              properties:
                payment_id:
                  type: string
                amount:
                  type: integer
                  description: Partial refund amount in the smallest currency unit. Omit for a full refund.
                reason:
                  type: string
      responses:
        '200':
          description: The created refund.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
  /refunds/{refund_id}:
    get:
      operationId: getRefund
      tags:
        - Refunds
      summary: Get a refund
      parameters:
        - name: refund_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The refund.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
  /disputes:
    get:
      operationId: listDisputes
      tags:
        - Disputes
      summary: List disputes
      parameters:
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A paginated list of disputes.
  /disputes/{dispute_id}:
    get:
      operationId: getDispute
      tags:
        - Disputes
      summary: Get a dispute
      parameters:
        - name: dispute_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The dispute.
  /webhooks:
    get:
      operationId: listWebhooks
      tags:
        - Webhooks
      summary: List webhook endpoints
      parameters:
        - $ref: '#/components/parameters/PageNumber'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A paginated list of webhook endpoints.
    post:
      operationId: createWebhook
      tags:
        - Webhooks
      summary: Create a webhook endpoint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
      responses:
        '200':
          description: The created webhook endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
  /webhooks/{webhook_id}:
    get:
      operationId: getWebhook
      tags:
        - Webhooks
      summary: Get a webhook endpoint
      parameters:
        - $ref: '#/components/parameters/WebhookIdPath'
      responses:
        '200':
          description: The webhook endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
    patch:
      operationId: updateWebhook
      tags:
        - Webhooks
      summary: Update a webhook endpoint
      parameters:
        - $ref: '#/components/parameters/WebhookIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                description:
                  type: string
                disabled:
                  type: boolean
      responses:
        '200':
          description: The webhook endpoint was updated.
    delete:
      operationId: deleteWebhook
      tags:
        - Webhooks
      summary: Delete a webhook endpoint
      parameters:
        - $ref: '#/components/parameters/WebhookIdPath'
      responses:
        '200':
          description: The webhook endpoint was deleted.
  /webhooks/{webhook_id}/headers:
    get:
      operationId: getWebhookHeaders
      tags:
        - Webhooks
      summary: Get webhook endpoint headers
      parameters:
        - $ref: '#/components/parameters/WebhookIdPath'
      responses:
        '200':
          description: The configured headers for the webhook endpoint.
    patch:
      operationId: updateWebhookHeaders
      tags:
        - Webhooks
      summary: Update webhook endpoint headers
      parameters:
        - $ref: '#/components/parameters/WebhookIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                headers:
                  type: object
                  additionalProperties:
                    type: string
      responses:
        '200':
          description: The webhook headers were updated.
  /webhooks/{webhook_id}/secret:
    get:
      operationId: getWebhookSigningKey
      tags:
        - Webhooks
      summary: Get the webhook signing key
      parameters:
        - $ref: '#/components/parameters/WebhookIdPath'
      responses:
        '200':
          description: The signing secret used to verify webhook payloads.
          content:
            application/json:
              schema:
                type: object
                properties:
                  secret:
                    type: string
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Authenticate with your Dodo Payments API key as a bearer token:
        `Authorization: Bearer YOUR_API_KEY`. Use a test-mode key against
        https://test.dodopayments.com and a live-mode key against
        https://live.dodopayments.com.
  parameters:
    IdPath:
      name: id
      in: path
      required: true
      schema:
        type: string
    WebhookIdPath:
      name: webhook_id
      in: path
      required: true
      schema:
        type: string
    PageNumber:
      name: page_number
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
    PageSize:
      name: page_size
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
  schemas:
    Price:
      type: object
      properties:
        type:
          type: string
          enum:
            - one_time_price
            - recurring_price
        price:
          type: integer
          description: Amount in the smallest currency unit.
        currency:
          type: string
          example: USD
        payment_frequency_interval:
          type: string
          enum:
            - Day
            - Week
            - Month
            - Year
        payment_frequency_count:
          type: integer
        tax_inclusive:
          type: boolean
    Product:
      type: object
      properties:
        product_id:
          type: string
        name:
          type: string
        description:
          type: string
        business_id:
          type: string
        price:
          $ref: '#/components/schemas/Price'
        tax_category:
          type: string
          enum:
            - digital_products
            - saas
            - e_book
            - edtech
        is_recurring:
          type: boolean
        license_key_enabled:
          type: boolean
        created_at:
          type: string
          format: date-time
    CreateProductRequest:
      type: object
      required:
        - name
        - price
        - tax_category
      properties:
        name:
          type: string
        description:
          type: string
        price:
          $ref: '#/components/schemas/Price'
        tax_category:
          type: string
        license_key_enabled:
          type: boolean
    ProductList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Product'
    BillingAddress:
      type: object
      required:
        - country
        - city
        - state
        - street
        - zipcode
      properties:
        country:
          type: string
          description: Two-letter ISO country code.
        city:
          type: string
        state:
          type: string
        street:
          type: string
        zipcode:
          type: string
    OneTimeProductCartItem:
      type: object
      required:
        - product_id
        - quantity
      properties:
        product_id:
          type: string
        quantity:
          type: integer
        amount:
          type: integer
    Payment:
      type: object
      properties:
        payment_id:
          type: string
        business_id:
          type: string
        total_amount:
          type: integer
        currency:
          type: string
        status:
          type: string
          enum:
            - succeeded
            - failed
            - cancelled
            - processing
            - requires_customer_action
        payment_link:
          type: string
          format: uri
        customer:
          $ref: '#/components/schemas/Customer'
        created_at:
          type: string
          format: date-time
    CreatePaymentRequest:
      type: object
      required:
        - billing
        - customer
        - product_cart
      properties:
        billing:
          $ref: '#/components/schemas/BillingAddress'
        customer:
          $ref: '#/components/schemas/CustomerRequest'
        product_cart:
          type: array
          items:
            $ref: '#/components/schemas/OneTimeProductCartItem'
        payment_link:
          type: boolean
        return_url:
          type: string
          format: uri
        discount_code:
          type: string
        metadata:
          type: object
          additionalProperties:
            type: string
    PaymentList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Payment'
    Subscription:
      type: object
      properties:
        subscription_id:
          type: string
        business_id:
          type: string
        product_id:
          type: string
        customer:
          $ref: '#/components/schemas/Customer'
        recurring_pre_tax_amount:
          type: integer
        currency:
          type: string
        status:
          type: string
          enum:
            - pending
            - active
            - on_hold
            - cancelled
            - failed
            - expired
        payment_frequency_interval:
          type: string
        payment_frequency_count:
          type: integer
        next_billing_date:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
    CreateSubscriptionRequest:
      type: object
      required:
        - billing
        - customer
        - product_id
        - quantity
      properties:
        billing:
          $ref: '#/components/schemas/BillingAddress'
        customer:
          $ref: '#/components/schemas/CustomerRequest'
        product_id:
          type: string
        quantity:
          type: integer
        payment_link:
          type: boolean
        return_url:
          type: string
          format: uri
        trial_period_days:
          type: integer
        discount_code:
          type: string
        metadata:
          type: object
          additionalProperties:
            type: string
    SubscriptionList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Subscription'
    Customer:
      type: object
      properties:
        customer_id:
          type: string
        business_id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
        phone_number:
          type: string
        created_at:
          type: string
          format: date-time
    CustomerRequest:
      type: object
      description: >-
        Either an existing customer reference (customer_id) or new customer
        details (email, name) used to attach a payment or subscription.
      properties:
        customer_id:
          type: string
        email:
          type: string
          format: email
        name:
          type: string
        create_new_customer:
          type: boolean
    CreateCustomerRequest:
      type: object
      required:
        - email
        - name
      properties:
        email:
          type: string
          format: email
        name:
          type: string
        phone_number:
          type: string
    CustomerList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Customer'
    CheckoutSession:
      type: object
      properties:
        session_id:
          type: string
        checkout_url:
          type: string
          format: uri
        status:
          type: string
        created_at:
          type: string
          format: date-time
    CheckoutSessionProductCartItem:
      type: ob

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