> ## Documentation Index > Fetch the complete documentation index at: https://dodopayments-mintlify-external-integration-datafast-autosen.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Create Subscription > Create a subscription for a customer. **Deprecated API**: This API will be deprecated soon. We recommend using [Checkout Sessions](/api-reference/checkout-sessions/create) instead, which provides a more powerful and customizable API to create payment links for one-time payments and subscriptions. ## OpenAPI ````yaml post /subscriptions openapi: 3.1.0 info: title: public description: '' license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0 version: 1.61.5 servers: - url: https://test.dodopayments.com/ description: Test Mode Server Host - url: https://live.dodopayments.com/ description: Live Mode Server Host security: [] tags: - name: Products - name: Payments - name: Subscriptions - name: Addons - name: Customers - name: Refunds - name: Disputes - name: Events - name: License Keys - name: Licenses - name: Discounts - name: Meters - name: Outgoing Webhooks - name: Checkout - name: Webhook Events paths: /subscriptions: post: tags: - Subscriptions operationId: create_subscription_handler requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateSubscriptionRequest' required: true responses: '200': description: Subscription successfully initiated content: application/json: schema: $ref: '#/components/schemas/CreateSubscriptionResponse' '422': description: Invalid Request Object or Parameters '500': description: Something went wrong :( security: - API_KEY: [] x-codeSamples: - lang: JavaScript source: |- import DodoPayments from 'dodopayments'; const client = new DodoPayments({ bearerToken: 'My Bearer Token', }); const subscription = await client.subscriptions.create({ billing: { city: 'city', country: 'AF', state: 'state', street: 'street', zipcode: 'zipcode' }, customer: { customer_id: 'customer_id' }, product_id: 'product_id', quantity: 0, }); console.log(subscription.payment_id); - lang: Python source: |- from dodopayments import DodoPayments client = DodoPayments( bearer_token="My Bearer Token", ) subscription = client.subscriptions.create( billing={ "city": "city", "country": "AF", "state": "state", "street": "street", "zipcode": "zipcode", }, customer={ "customer_id": "customer_id" }, product_id="product_id", quantity=0, ) print(subscription.payment_id) - lang: Go source: | package main import ( "context" "fmt" "github.com/dodopayments/dodopayments-go" "github.com/dodopayments/dodopayments-go/option" ) func main() { client := dodopayments.NewClient( option.WithBearerToken("My Bearer Token"), ) subscription, err := client.Subscriptions.New(context.TODO(), dodopayments.SubscriptionNewParams{ Billing: dodopayments.F(dodopayments.BillingAddressParam{ City: dodopayments.F("city"), Country: dodopayments.F(dodopayments.CountryCodeAf), State: dodopayments.F("state"), Street: dodopayments.F("street"), Zipcode: dodopayments.F("zipcode"), }), Customer: dodopayments.F[dodopayments.CustomerRequestUnionParam](dodopayments.AttachExistingCustomerParam{ CustomerID: dodopayments.F("customer_id"), }), ProductID: dodopayments.F("product_id"), Quantity: dodopayments.F(int64(0)), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", subscription.PaymentID) } - lang: Java source: >- package com.dodopayments.api.example; import com.dodopayments.api.client.DodoPaymentsClient; import com.dodopayments.api.client.okhttp.DodoPaymentsOkHttpClient; import com.dodopayments.api.models.misc.CountryCode; import com.dodopayments.api.models.payments.AttachExistingCustomer; import com.dodopayments.api.models.payments.BillingAddress; import com.dodopayments.api.models.subscriptions.SubscriptionCreateParams; import com.dodopayments.api.models.subscriptions.SubscriptionCreateResponse; public final class Main { private Main() {} public static void main(String[] args) { DodoPaymentsClient client = DodoPaymentsOkHttpClient.fromEnv(); SubscriptionCreateParams params = SubscriptionCreateParams.builder() .billing(BillingAddress.builder() .city("city") .country(CountryCode.AF) .state("state") .street("street") .zipcode("zipcode") .build()) .customer(AttachExistingCustomer.builder() .customerId("customer_id") .build()) .productId("product_id") .quantity(0) .build(); SubscriptionCreateResponse subscription = client.subscriptions().create(params); } } - lang: Kotlin source: >- package com.dodopayments.api.example import com.dodopayments.api.client.DodoPaymentsClient import com.dodopayments.api.client.okhttp.DodoPaymentsOkHttpClient import com.dodopayments.api.models.misc.CountryCode import com.dodopayments.api.models.payments.AttachExistingCustomer import com.dodopayments.api.models.payments.BillingAddress import com.dodopayments.api.models.subscriptions.SubscriptionCreateParams import com.dodopayments.api.models.subscriptions.SubscriptionCreateResponse fun main() { val client: DodoPaymentsClient = DodoPaymentsOkHttpClient.fromEnv() val params: SubscriptionCreateParams = SubscriptionCreateParams.builder() .billing(BillingAddress.builder() .city("city") .country(CountryCode.AF) .state("state") .street("street") .zipcode("zipcode") .build()) .customer(AttachExistingCustomer.builder() .customerId("customer_id") .build()) .productId("product_id") .quantity(0) .build() val subscription: SubscriptionCreateResponse = client.subscriptions().create(params) } - lang: Ruby source: |- require "dodopayments" dodo_payments = Dodopayments::Client.new( bearer_token: "My Bearer Token", environment: "test_mode" # defaults to "live_mode" ) subscription = dodo_payments.subscriptions.create( billing: {city: "city", country: :AF, state: "state", street: "street", zipcode: "zipcode"}, customer: {customer_id: "customer_id"}, product_id: "product_id", quantity: 0 ) puts(subscription) components: schemas: CreateSubscriptionRequest: type: object description: >- Request payload for creating a new subscription This struct represents the data required to create a new subscription in the system. It includes details about the product, quantity, customer information, and billing details. required: - product_id - quantity - customer - billing properties: addons: type: - array - 'null' items: $ref: '#/components/schemas/AttachAddonReq' description: Attach addons to this subscription allowed_payment_method_types: type: - array - 'null' items: $ref: '#/components/schemas/PaymentMethodTypes' description: >- List of payment methods allowed during checkout. Customers will **never** see payment methods that are **not** in this list. However, adding a method here **does not guarantee** customers will see it. Availability still depends on other factors (e.g., customer location, merchant settings). uniqueItems: true billing: $ref: '#/components/schemas/BillingAddress' description: Billing address information for the subscription billing_currency: oneOf: - type: 'null' - $ref: '#/components/schemas/Currency' description: >- Fix the currency in which the end customer is billed. If Dodo Payments cannot support that currency for this transaction, it will not proceed customer: $ref: '#/components/schemas/CustomerRequest' description: Customer details for the subscription discount_code: type: - string - 'null' description: Discount Code to apply to the subscription force_3ds: type: - boolean - 'null' description: Override merchant default 3DS behaviour for this subscription metadata: $ref: '#/components/schemas/Metadata' description: |- Additional metadata for the subscription Defaults to empty if not specified on_demand: oneOf: - type: 'null' - $ref: '#/components/schemas/OnDemandSubscriptionReq' payment_link: type: - boolean - 'null' description: |- If true, generates a payment link. Defaults to false if not specified. product_id: type: string description: Unique identifier of the product to subscribe to quantity: type: integer format: int32 description: Number of units to subscribe for. Must be at least 1. minimum: 0 return_url: type: - string - 'null' description: Optional URL to redirect after successful subscription creation show_saved_payment_methods: type: boolean description: |- Display saved payment methods of a returning customer False by default tax_id: type: - string - 'null' description: >- Tax ID in case the payment is B2B. If tax id validation fails the payment creation will fail trial_period_days: type: - integer - 'null' format: int32 description: >- Optional trial period in days If specified, this value overrides the trial period set in the product's price Must be between 0 and 10000 days CreateSubscriptionResponse: type: object required: - subscription_id - recurring_pre_tax_amount - customer - metadata - addons - payment_id properties: addons: type: array items: $ref: '#/components/schemas/AddonCartResponseItem' description: Addons associated with this subscription client_secret: type: - string - 'null' description: |- Client secret used to load Dodo checkout SDK NOTE : Dodo checkout SDK will be coming soon customer: $ref: '#/components/schemas/CustomerLimitedDetailsResponse' description: Customer details associated with this subscription discount_id: type: - string - 'null' description: The discount id if discount is applied expires_on: type: - string - 'null' format: date-time description: Expiry timestamp of the payment link metadata: $ref: '#/components/schemas/Metadata' description: Additional metadata associated with the subscription payment_id: type: string description: First payment id for the subscription payment_link: type: - string - 'null' description: URL to checkout page recurring_pre_tax_amount: type: integer format: int32 description: >- Tax will be added to the amount and charged to the customer on each billing cycle minimum: 0 subscription_id: type: string description: Unique identifier for the subscription AttachAddonReq: type: object title: Attach Addon Request required: - addon_id - quantity properties: addon_id: type: string quantity: type: integer format: int32 minimum: 0 PaymentMethodTypes: type: string enum: - credit - debit - upi_collect - upi_intent - apple_pay - cashapp - google_pay - multibanco - bancontact_card - eps - ideal - przelewy24 - paypal - affirm - klarna - sepa - ach - amazon_pay - afterpay_clearpay BillingAddress: type: object required: - country - state - city - street - zipcode properties: city: type: string description: City name country: $ref: '#/components/schemas/CountryCodeAlpha2' description: Two-letter ISO country code (ISO 3166-1 alpha-2) state: type: string description: State or province name street: type: string description: >- Street address including house number and unit/apartment if applicable zipcode: type: string description: Postal code or ZIP code Currency: type: string enum: - AED - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BRL - BSD - BWP - BYN - BZD - CAD - CHF - CLP - CNY - COP - CRC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - JMD - JOD - JPY - KES - KGS - KHR - KMF - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRU - MUR - MVR - MWK - MXN - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SEK - SGD - SHP - SLE - SLL - SOS - SRD - SSP - STN - SVC - SZL - THB - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - UYU - UZS - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW CustomerRequest: oneOf: - $ref: '#/components/schemas/AttachExistingCustomer' - $ref: '#/components/schemas/NewCustomer' title: Customer Request Metadata: type: object additionalProperties: type: string propertyNames: type: string OnDemandSubscriptionReq: type: object title: On Demand Subscription Request required: - mandate_only properties: adaptive_currency_fees_inclusive: type: - boolean - 'null' description: >- Whether adaptive currency fees should be included in the product_price (true) or added on top (false). This field is ignored if adaptive pricing is not enabled for the business. mandate_only: type: boolean description: >- If set as True, does not perform any charge and only authorizes payment method details for future use. product_currency: oneOf: - type: 'null' - $ref: '#/components/schemas/Currency' description: >- Optional currency of the product price. If not specified, defaults to the currency of the product. product_description: type: - string - 'null' description: >- Optional product description override for billing and line items. If not specified, the stored description of the product will be used. product_price: type: - integer - 'null' format: int32 description: >- Product price for the initial charge to customer If not specified the stored price of the product will be used Represented in the lowest denomination of the currency (e.g., cents for USD). For example, to charge $1.00, pass `100`. AddonCartResponseItem: type: object title: Addon Cart Response Item description: Response struct representing subscription details required: - addon_id - quantity properties: addon_id: type: string quantity: type: integer format: int32 CustomerLimitedDetailsResponse: type: object required: - customer_id - name - email properties: customer_id: type: string description: Unique identifier for the customer email: type: string description: Email address of the customer metadata: $ref: '#/components/schemas/Metadata' description: Additional metadata associated with the customer name: type: string description: Full name of the customer phone_number: type: - string - 'null' description: Phone number of the customer CountryCodeAlpha2: type: string description: ISO country code alpha2 variant enum: - AF - AX - AL - DZ - AS - AD - AO - AI - AQ - AG - AR - AM - AW - AU - AT - AZ - BS - BH - BD - BB - BY - BE - BZ - BJ - BM - BT - BO - BQ - BA - BW - BV - BR - IO - BN - BG - BF - BI - KH - CM - CA - CV - KY - CF - TD - CL - CN - CX - CC - CO - KM - CG - CD - CK - CR - CI - HR - CU - CW - CY - CZ - DK - DJ - DM - DO - EC - EG - SV - GQ - ER - EE - ET - FK - FO - FJ - FI - FR - GF - PF - TF - GA - GM - GE - DE - GH - GI - GR - GL - GD - GP - GU - GT - GG - GN - GW - GY - HT - HM - VA - HN - HK - HU - IS - IN - ID - IR - IQ - IE - IM - IL - IT - JM - JP - JE - JO - KZ - KE - KI - KP - KR - KW - KG - LA - LV - LB - LS - LR - LY - LI - LT - LU - MO - MK - MG - MW - MY - MV - ML - MT - MH - MQ - MR - MU - YT - MX - FM - MD - MC - MN - ME - MS - MA - MZ - MM - NA - NR - NP - NL - NC - NZ - NI - NE - NG - NU - NF - MP - 'NO' - OM - PK - PW - PS - PA - PG - PY - PE - PH - PN - PL - PT - PR - QA - RE - RO - RU - RW - BL - SH - KN - LC - MF - PM - VC - WS - SM - ST - SA - SN - RS - SC - SL - SG - SX - SK - SI - SB - SO - ZA - GS - SS - ES - LK - SD - SR - SJ - SZ - SE - CH - SY - TW - TJ - TZ - TH - TL - TG - TK - TO - TT - TN - TR - TM - TC - TV - UG - UA - AE - GB - UM - US - UY - UZ - VU - VE - VN - VG - VI - WF - EH - YE - ZM - ZW AttachExistingCustomer: type: object title: Attach Existing Customer required: - customer_id properties: customer_id: type: string NewCustomer: type: object title: New Customer required: - email properties: email: type: string description: Email is required for creating a new customer name: type: - string - 'null' description: >- Optional full name of the customer. If provided during session creation, it is persisted and becomes immutable for the session. If omitted here, it can be provided later via the confirm API. phone_number: type: - string - 'null' securitySchemes: API_KEY: type: http scheme: bearer ````