# Dodo Payments Documentation: English API Reference

> Documentation for Dodo Payments — the all-in-one payments, billing, and merchant of record platform for SaaS, AI, and digital products.

## API Reference

### API Reference

- [Introduction](https://docs.dodopayments.com/api-reference/introduction.md): The Dodo Payments API provides comprehensive endpoints for payment processing, subscription management, and digital product delivery. Our RESTful API follows industry standards with detailed responses for all operations.
- [Error Codes](https://docs.dodopayments.com/api-reference/error-codes.md): Reference for Dodo Payments API and business-logic error codes, grouped by category, with triggers, messages, and how to resolve them.
- [Transaction Failures](https://docs.dodopayments.com/api-reference/transaction-failures.md): Understand every Dodo Payments transaction failure code, whether it is a soft or hard decline, and the recommended action to recover the payment.
- [Metadata Guide](https://docs.dodopayments.com/api-reference/metadata.md): Learn how to use metadata to store additional information about your Dodo Payments objects

### Checkout Sessions

- [Create Checkout Session](https://docs.dodopayments.com/api-reference/checkout-sessions/create.md): Unified endpoint for creating checkout sessions for all types of billing requirements.
- [Preview Checkout Session](https://docs.dodopayments.com/api-reference/checkout-sessions/preview.md): Preview a checkout session to calculate pricing, taxes, and totals without creating an actual session.
- [Get Checkout Session](https://docs.dodopayments.com/api-reference/checkout-sessions/get-checkouts.md): Retrieve the status of a specific checkout session by its ID, including the resulting payment ID and payment status.

### Payments

- [List Payments](https://docs.dodopayments.com/api-reference/payments/get-payments.md): Get a list of all payments associated with your account.
- [Get Payment Detail](https://docs.dodopayments.com/api-reference/payments/get-payments-1.md): Get detailed information about a specific payment.
- [Get Invoice](https://docs.dodopayments.com/api-reference/payments/get-invoice.md): Get an invoice by Payment ID.
- [Retrieve Line Items](https://docs.dodopayments.com/api-reference/payments/retrieve-line-items.md): Retrieve line items for a specific payment.
- [Create One-Time Payment](https://docs.dodopayments.com/api-reference/payments/post-payments.md): Create a one-time payment for a customer.

### Subscriptions

- [List Subscriptions](https://docs.dodopayments.com/api-reference/subscriptions/get-subscriptions-1.md): Get a list of all subscriptions associated with your account.
- [Get Subscription Detail](https://docs.dodopayments.com/api-reference/subscriptions/get-subscriptions.md): Get detailed information about a specific subscription.
- [Change Plan](https://docs.dodopayments.com/api-reference/subscriptions/change-plan.md): Modify an existing subscription's plan, enabling both upgrades and downgrades to different pricing tiers.<br/><br/>Note&colon; By default this uses the customer's existing payment information. Set collect_via_payment_link to charge via a hosted checkout page instead.
- [Preview Plan Change](https://docs.dodopayments.com/api-reference/subscriptions/preview-change-plan.md): Preview the effects of a subscription plan change before committing to it. Returns the immediate charge amount and the new subscription details without making any actual changes.
- [Cancel Scheduled Plan Change](https://docs.dodopayments.com/api-reference/subscriptions/cancel-change-plan.md): Cancel a scheduled plan change for a subscription.
- [Update Subscription](https://docs.dodopayments.com/api-reference/subscriptions/patch-subscriptions.md): Update a subscription's details.
- [Create Charge (On-Demand)](https://docs.dodopayments.com/api-reference/subscriptions/create-charge.md): Create a charge for a subscription. This is useful for on-demand billing.
- [Get Subscription Usage History](https://docs.dodopayments.com/api-reference/subscriptions/get-usage-history.md): Retrieve the complete usage history for a subscription with usage-based billing.
- [Retrieve Credit Usage](https://docs.dodopayments.com/api-reference/subscriptions/retrieve-credit-usage.md): Retrieve the credit usage for a subscription.
- [Update Payment Method](https://docs.dodopayments.com/api-reference/subscriptions/update-payment-method.md): Update the payment method for an existing subscription. You can either add a new payment method or use an existing one from the customer's saved payment methods.
- [Create Subscription](https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions.md): Create a subscription for a customer.

### Discounts

- [List Discounts](https://docs.dodopayments.com/api-reference/discounts/list-discounts.md): Retrieve a list of all discounts associated with your account.
- [Create Discount](https://docs.dodopayments.com/api-reference/discounts/create-discount.md): Create a discount for your account.
- [Get Discount](https://docs.dodopayments.com/api-reference/discounts/validate-discount.md): Retrieve a discount by its unique discount_id.
- [Get Discount by Code](https://docs.dodopayments.com/api-reference/discounts/get-discount-by-code.md): Validate and retrieve a discount by its code name (e.g., 'SAVE20') instead of using the internal discount ID.
- [Update Discount](https://docs.dodopayments.com/api-reference/discounts/update-discount.md): Update a discount in your account.
- [Delete Discount](https://docs.dodopayments.com/api-reference/discounts/delete-discount.md): Delete a discount from your account.
- [List Discount Customers](https://docs.dodopayments.com/api-reference/discounts/list-discount-customers.md): Get a paginated list of the customers attached to a discount's allowlist.
- [Add Discount Customers](https://docs.dodopayments.com/api-reference/discounts/add-discount-customers.md): Idempotently attach customers to a discount's allowlist, which backs a customer_eligibility of specific.
- [Remove Discount Customer](https://docs.dodopayments.com/api-reference/discounts/remove-discount-customer.md): Detach a single customer from a discount's allowlist so they are no longer eligible for the discount.

### Licenses

- [Create License Key](https://docs.dodopayments.com/api-reference/licenses/create-license-key.md): Import an existing license key from another system. The key string, customer, and product are all required.
- [Activate License](https://docs.dodopayments.com/api-reference/licenses/activate-license.md): This endpoint allows you to activate a license for the user.
- [Deactivate License](https://docs.dodopayments.com/api-reference/licenses/deactivate-license.md): This endpoint allows you to deactivate a license for the user.
- [Validate License](https://docs.dodopayments.com/api-reference/licenses/validate-license.md): This endpoint allows you to validate a license for the user.
- [List License Keys](https://docs.dodopayments.com/api-reference/licenses/list-license-keys.md): Retrieve a list of license keys associated with your account.
- [Get License Key](https://docs.dodopayments.com/api-reference/licenses/get-license-key.md): Retrieve the details of a specific license key by its ID.
- [Update License Key](https://docs.dodopayments.com/api-reference/licenses/update-license-key.md): This endpoint allows you to update a license key by its ID.
- [List License Key Instances](https://docs.dodopayments.com/api-reference/licenses/get-license-key-instances.md): Retrieve a list of license key instances. Optionally filter by `license_key_id` to scope results to a specific license key, or by `grant_id` to scope to an entitlement grant.
- [Get License Key Instance](https://docs.dodopayments.com/api-reference/licenses/get-license-key-instance.md): Retrieve details of a specific license key instance by its ID.
- [Update License Key Instance](https://docs.dodopayments.com/api-reference/licenses/update-license-key-instance.md): This endpoint allows you to update a specific license key instance by its ID.

### Entitlements

- [List Entitlements](https://docs.dodopayments.com/api-reference/entitlements/list-entitlements.md): List all entitlements for your business with optional filtering by integration type.
- [Create Entitlement](https://docs.dodopayments.com/api-reference/entitlements/create-entitlement.md): Create a new entitlement of any integration type — License Key, Digital Files, Feature Flag, Discord, GitHub, Telegram, Figma, Framer, or Notion.
- [Get Entitlement](https://docs.dodopayments.com/api-reference/entitlements/get-entitlement.md): Retrieve a single entitlement with its resolved integration configuration. For Digital Files entitlements, file metadata and presigned download URLs are populated in the response.
- [Update Entitlement](https://docs.dodopayments.com/api-reference/entitlements/update-entitlement.md): Update an entitlement's name, description, integration configuration, or metadata.
- [Delete Entitlement](https://docs.dodopayments.com/api-reference/entitlements/delete-entitlement.md): Soft-delete an entitlement. Existing grants on the entitlement are unaffected.
- [Upload File](https://docs.dodopayments.com/api-reference/entitlements/upload-file.md): Upload a file to a Digital Files entitlement. Files are streamed to storage; the maximum size is 500 MiB. The returned file ID is appended to the entitlement's digital_file_ids list.
- [Delete File](https://docs.dodopayments.com/api-reference/entitlements/delete-file.md): Remove a file from a Digital Files entitlement. The file is deleted from storage and removed from the entitlement's digital_file_ids list.
- [List Grants](https://docs.dodopayments.com/api-reference/entitlements/list-grants.md): List all grants for an entitlement, with optional filters by status and customer ID. Each grant carries the per-customer fulfillment state, including license keys and digital file download URLs where applicable.
- [List Customer Grants](https://docs.dodopayments.com/api-reference/entitlements/list-customer-grants.md): List all of a customer's entitlement grants across every entitlement, one row per grant, with optional filters by status and integration type. Feature-flag grants include the typed feature payload.
- [Fulfill License Key Grant](https://docs.dodopayments.com/api-reference/entitlements/fulfill-license-key.md): Manually fulfill a pending license-key grant by supplying the key value. Inserts the key, delivers it to the customer by email, and transitions the grant to delivered.
- [Revoke Grant](https://docs.dodopayments.com/api-reference/entitlements/revoke-grant.md): Manually revoke a grant. The customer's platform access is removed (for OAuth/bot integrations) and license keys are disabled. Manual revokes use revocation_reason "manual" and are not auto-regranted on subscription renewal.

### Customers

- [Create Customer](https://docs.dodopayments.com/api-reference/customers/create-customer.md): Create a new customer in your Dodo Payments account.
- [List Customers](https://docs.dodopayments.com/api-reference/customers/get-customers.md): Get a list of all customers associated with your account.
- [Get Customer Detail](https://docs.dodopayments.com/api-reference/customers/get-customers-1.md): Get detailed information about a specific customer.
- [Update Customer](https://docs.dodopayments.com/api-reference/customers/patch-customer.md): Update a customer's information.
- [Create Customer Portal Session](https://docs.dodopayments.com/api-reference/customers/create-customer-portal-session.md): Create a session of the Customer Portal for a specific customer.
- [List Payment Methods](https://docs.dodopayments.com/api-reference/customers/get-customer-payment-methods.md): List all payment methods associated with a specific customer.
- [Delete Payment Method](https://docs.dodopayments.com/api-reference/customers/delete-payment-method.md): Delete a payment method associated with a customer.
- [List Customer Entitlements](https://docs.dodopayments.com/api-reference/customers/list-customer-entitlements.md): Get all entitlement grants that have been delivered to, or are still in flight for, a customer.
- [List Customer Credit Entitlements](https://docs.dodopayments.com/api-reference/customers/list-customer-credit-entitlements.md): Get all credit entitlements for a customer along with their current balances.

### Customer Wallets

- [List Customer Wallets](https://docs.dodopayments.com/api-reference/customers/get-customer-wallets.md): Retrieve monetary wallet balances associated with a specific customer. Wallets hold real funds in a supported currency (USD, EUR, or GBP) that can be applied to invoices and subscription payments.
- [List Customer Wallet Ledger Entries](https://docs.dodopayments.com/api-reference/customers/get-customer-wallets-ledger-entries.md): List wallet ledger entries (fund additions and deductions) for a specific customer. Supports pagination and currency filter.
- [Create Customer Wallet Ledger Entry](https://docs.dodopayments.com/api-reference/customers/post-customer-wallets-ledger-entries.md): Add or deduct monetary funds in a customer's wallet. Use entry_type 'credit' to add funds or 'debit' to deduct funds. Wallet balances are real money in a supported currency (USD, EUR, or GBP) that can be applied to subscription invoices.

### Products

- [List Products](https://docs.dodopayments.com/api-reference/products/get-products.md): Get a list of all products associated with your account.
- [Create Product](https://docs.dodopayments.com/api-reference/products/post-products.md): Create a new product.
- [Get Product Detail](https://docs.dodopayments.com/api-reference/products/get-products-1.md): Get detailed information about a specific product.
- [Update Product](https://docs.dodopayments.com/api-reference/products/patch-products.md): Update a product's details.
- [Update Product Image](https://docs.dodopayments.com/api-reference/products/put-products-images.md): Get a presigned S3 URL to upload an image for a product. Upload the image to the returned URL within 60 seconds.
- [Archive Product](https://docs.dodopayments.com/api-reference/products/archive-product.md): Archive a product associated with your account.
- [Unarchive Product](https://docs.dodopayments.com/api-reference/products/unarchive-product.md): Unarchive a product associated with your account.
- [Upload Product File](https://docs.dodopayments.com/api-reference/products/update-files.md): Get a presigned S3 URL to upload a single file for a product. Upload the file to the returned URL within 60 seconds.
- [List Short Links](https://docs.dodopayments.com/api-reference/products/get-products-short-links.md): Lists all short links created by the business. Short links provide shortened checkout URLs with custom slugs for your products.
- [Create Short Link](https://docs.dodopayments.com/api-reference/products/post-products-id-short-links.md): Creates a short checkout URL with a custom slug for a product. Uses a Static Checkout URL under the hood.

### Localized Pricing

- [List Localized Prices](https://docs.dodopayments.com/api-reference/products/get-products-localized-prices.md): List the active localized price rules for a product.
- [Create Localized Price](https://docs.dodopayments.com/api-reference/products/post-products-localized-prices.md): Create a localized price rule for a product, by currency or by country.
- [Get Localized Price](https://docs.dodopayments.com/api-reference/products/get-products-localized-prices-id.md): Retrieve a single localized price rule for a product.
- [Update Localized Price](https://docs.dodopayments.com/api-reference/products/patch-products-localized-prices.md): Update the amount of a localized price rule.
- [Archive Localized Price](https://docs.dodopayments.com/api-reference/products/delete-products-localized-prices.md): Archive a localized price rule. Idempotent soft-delete.

### Addons

- [Create Addon](https://docs.dodopayments.com/api-reference/addons/create-addon.md): Create a new addon product that can be attached to your main subscription products
- [List Addons](https://docs.dodopayments.com/api-reference/addons/list-addons.md): Retrieve a comprehensive list of all available addons
- [Get Addon](https://docs.dodopayments.com/api-reference/addons/get-addon.md): Retrieve detailed information about a specific addon using its unique identifier
- [Update Addon](https://docs.dodopayments.com/api-reference/addons/update-addon.md): Modify the details of an existing addon using its unique identifier
- [Update Addon Image](https://docs.dodopayments.com/api-reference/addons/update-addon-images.md): Get a presigned S3 URL to upload an image for an existing addon. Upload the image to the returned URL within 60 seconds.

### Credit Entitlements

- [List Credit Entitlements](https://docs.dodopayments.com/api-reference/credit-entitlements/list-credit-entitlements.md): Lists all credit entitlements for the authenticated business with pagination support
- [Create Credit Entitlement](https://docs.dodopayments.com/api-reference/credit-entitlements/create-credit-entitlement.md): Creates a new credit entitlement for the authenticated business
- [Get Credit Entitlement](https://docs.dodopayments.com/api-reference/credit-entitlements/get-credit-entitlement.md): Retrieves a specific credit entitlement by its ID
- [Update Credit Entitlement](https://docs.dodopayments.com/api-reference/credit-entitlements/update-credit-entitlement.md): Updates an existing credit entitlement with partial data
- [Delete Credit Entitlement](https://docs.dodopayments.com/api-reference/credit-entitlements/delete-credit-entitlement.md): Soft-deletes a credit entitlement by its ID
- [Undelete Credit Entitlement](https://docs.dodopayments.com/api-reference/credit-entitlements/undelete-credit-entitlement.md): Restores a previously deleted credit entitlement
- [List Balances](https://docs.dodopayments.com/api-reference/credit-entitlements/list-balances.md): Lists all customer balances for a specific credit entitlement
- [Get Customer Balance](https://docs.dodopayments.com/api-reference/credit-entitlements/get-customer-balance.md): Gets a specific customer's balance for a credit entitlement
- [List Customer Grants](https://docs.dodopayments.com/api-reference/credit-entitlements/list-customer-grants.md): Lists credit grants for a customer under a specific credit entitlement
- [List Customer Ledger](https://docs.dodopayments.com/api-reference/credit-entitlements/list-customer-ledger.md): Lists ledger entries for a customer under a specific credit entitlement
- [Create Ledger Entry](https://docs.dodopayments.com/api-reference/credit-entitlements/create-ledger-entry.md): Creates a ledger entry to credit or debit a customer's balance

### Meters

- [Create Meter](https://docs.dodopayments.com/api-reference/meters/create-meter.md): Create a new meter.
- [List Meters](https://docs.dodopayments.com/api-reference/meters/get-meters.md): Get a list of all meters.
- [Get Meter](https://docs.dodopayments.com/api-reference/meters/retrieve-meter.md): Retrieve a meter by its ID.
- [Archive Meter](https://docs.dodopayments.com/api-reference/meters/archive-meter.md): Archive a meter by its ID.
- [Unarchive Meter](https://docs.dodopayments.com/api-reference/meters/unarchive-meter.md): Unarchive a meter by its ID.

### Usage Events

- [Ingest Events](https://docs.dodopayments.com/api-reference/usage-events/ingest-events.md): Ingest events for usage-based billing.
- [Get Event](https://docs.dodopayments.com/api-reference/usage-events/get-event.md): Get an event by its ID.
- [List Events](https://docs.dodopayments.com/api-reference/usage-events/list-events.md): Get a list of all events.

### Refunds

- [List Refunds](https://docs.dodopayments.com/api-reference/refunds/get-refunds.md): Get a list of all refunds associated with your account.
- [Create Refund](https://docs.dodopayments.com/api-reference/refunds/post-refunds.md): Create a refund for a payment.
- [Get Refund Detail](https://docs.dodopayments.com/api-reference/refunds/get-refunds-1.md): Get detailed information about a specific refund.
- [Get Refund Receipt](https://docs.dodopayments.com/api-reference/refunds/get-refund-receipt.md): Get a refund receipt for a refund.

### Disputes

- [List Disputes](https://docs.dodopayments.com/api-reference/disputes/get-disputes.md): Get a list of all disputes associated with your account.
- [Get Dispute Detail](https://docs.dodopayments.com/api-reference/disputes/get-disputes-1.md): Get detailed information about a specific dispute.

### Payouts

- [List Payouts](https://docs.dodopayments.com/api-reference/payouts/get-payouts.md): Get a list of all payouts associated with your account.
- [Retrieve Payout Breakup](https://docs.dodopayments.com/api-reference/payouts/retrieve-breakup.md): Returns the breakdown of a payout by event type (payments, refunds, disputes, fees, etc.) in the payout's currency.
- [List Payout Breakup Details](https://docs.dodopayments.com/api-reference/payouts/list-breakup-details.md): Returns paginated individual balance ledger entries for a payout, with each entry's amount pro-rated into the payout's currency.
- [Download Payout Breakup CSV](https://docs.dodopayments.com/api-reference/payouts/download-breakup-csv.md): Downloads the complete payout breakup as a CSV file with columns for ledger ID, event type, amounts, and more.

### Balance Ledger

- [List Balance Ledger Entries](https://docs.dodopayments.com/api-reference/balance-ledger/list-ledger-entries.md): Retrieve a paginated list of balance ledger entries for your account. Use query parameters to filter by date range, event type, currency, or reference object.

### Brands

- [List Brands](https://docs.dodopayments.com/api-reference/brands/list-brands.md): List all brands.
- [Create Brand](https://docs.dodopayments.com/api-reference/brands/create-brand.md): Create a new brand.
- [Get Brand](https://docs.dodopayments.com/api-reference/brands/get-brand.md): Retrieve a specific brand by ID.
- [Update Brand](https://docs.dodopayments.com/api-reference/brands/update-brand.md): Update an existing brand's details.
- [Update Brand Image](https://docs.dodopayments.com/api-reference/brands/update-brand-images.md): Get a presigned S3 URL to upload an image for a brand. Upload the image to the returned URL within 60 seconds.
- [Archive Brand](https://docs.dodopayments.com/api-reference/brands/archive-brand.md): Archive a brand and move its products, live subscriptions, and product collections to another brand of the same business.

### Webhooks

- [List Webhooks](https://docs.dodopayments.com/api-reference/webhooks/list-webhooks.md): List all webhooks for a business.
- [Create Webhook](https://docs.dodopayments.com/api-reference/webhooks/create-webhook.md): Create a new webhook for a business.
- [Get Webhook Detail](https://docs.dodopayments.com/api-reference/webhooks/get-details.md): Get detailed information about a specific webhook.
- [Update Webhook](https://docs.dodopayments.com/api-reference/webhooks/update-webhook.md): Update a specific webhook.
- [Delete Webhook](https://docs.dodopayments.com/api-reference/webhooks/delete-webhook.md): Delete a specific webhook.
- [Get Webhook Headers](https://docs.dodopayments.com/api-reference/webhooks/get-webhook-headers.md): Get the headers for a specific webhook.
- [Update Webhook Headers](https://docs.dodopayments.com/api-reference/webhooks/update-webhook-headers.md): Update the headers for a specific webhook.
- [Get Webhook Signing Key](https://docs.dodopayments.com/api-reference/webhooks/get-webhook-signing-key.md): Get the signing key for a specific webhook.

### Miscellaneous

- [Supported Countries](https://docs.dodopayments.com/api-reference/misc/supported-countries.md): Retrieve a list of countries that are supported by the Dodo Payments for your customers.

### Product Collections

- [List Product Collections](https://docs.dodopayments.com/api-reference/product-collections/list-product-collections.md): Get a list of all product collections associated with your account.
- [Create Product Collection](https://docs.dodopayments.com/api-reference/product-collections/create-product-collection.md): Create a new product collection.
- [Get Product Collection](https://docs.dodopayments.com/api-reference/product-collections/get-product-collection.md): Get detailed information about a specific product collection.
- [Update Product Collection](https://docs.dodopayments.com/api-reference/product-collections/update-product-collection.md): Update a product collection's details.
- [Archive Product Collection](https://docs.dodopayments.com/api-reference/product-collections/archive-product-collection.md): Archive a product collection associated with your account.
- [Unarchive Product Collection](https://docs.dodopayments.com/api-reference/product-collections/unarchive-product-collection.md): Unarchive a product collection associated with your account.
- [Update Product Collection Image](https://docs.dodopayments.com/api-reference/product-collections/update-product-collection-images.md): Get a presigned S3 URL to upload an image for a product collection. Upload the image to the returned URL within 60 seconds.
- [Create Product Collection Group](https://docs.dodopayments.com/api-reference/product-collections/create-group.md): Add a new group to a product collection.
- [Update Product Collection Group](https://docs.dodopayments.com/api-reference/product-collections/update-group.md): Update a group within a product collection.
- [Delete Product Collection Group](https://docs.dodopayments.com/api-reference/product-collections/delete-group.md): Delete a group from a product collection.
- [Add Products to Group](https://docs.dodopayments.com/api-reference/product-collections/add-group-items.md): Add one or more products to a group within a product collection.
- [Update Group Item](https://docs.dodopayments.com/api-reference/product-collections/update-group-item.md): Update a product item within a product collection group.
- [Delete Group Item](https://docs.dodopayments.com/api-reference/product-collections/delete-group-item.md): Remove a product item from a product collection group.

## OpenAPI Specs

- [openapi.documented](/openapi/openapi.documented.yml)