POST
/
subscriptions
JavaScript
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);
{
  "addons": [
    {
      "addon_id": "<string>",
      "quantity": 123
    }
  ],
  "client_secret": "<string>",
  "customer": {
    "customer_id": "<string>",
    "email": "<string>",
    "name": "<string>"
  },
  "discount_id": "<string>",
  "expires_on": "2023-11-07T05:31:56Z",
  "metadata": {},
  "payment_id": "<string>",
  "payment_link": "<string>",
  "recurring_pre_tax_amount": 1,
  "subscription_id": "<string>"
}

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

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.

billing
object
required

Billing address information for the subscription

customer
object
required

Customer details for the subscription

product_id
string
required

Unique identifier of the product to subscribe to

quantity
integer
required

Number of units to subscribe for. Must be at least 1.

Required range: x >= 0
addons
Attach Addon Request · object[] | null

Attach addons to this subscription

allowed_payment_method_types
enum<string>[] | null

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).

billing_currency
enum<string> | null

Fix the currency in which the end customer is billed. If Dodo Payments cannot support that currency for this transaction, it will not proceed

Available options:
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
discount_code
string | null

Discount Code to apply to the subscription

metadata
object

Additional metadata for the subscription Defaults to empty if not specified

on_demand
object | null

If true, generates a payment link. Defaults to false if not specified.

return_url
string | null

Optional URL to redirect after successful subscription creation

show_saved_payment_methods
boolean

Display saved payment methods of a returning customer False by default

tax_id
string | null

Tax ID in case the payment is B2B. If tax id validation fails the payment creation will fail

trial_period_days
integer | null

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

Response

Subscription successfully initiated

addons
Addon Cart Response Item · object[]
required

Addons associated with this subscription

customer
object
required

Customer details associated with this subscription

metadata
object
required

Additional metadata associated with the subscription

payment_id
string
required

First payment id for the subscription

recurring_pre_tax_amount
integer
required

Tax will be added to the amount and charged to the customer on each billing cycle

Required range: x >= 0
subscription_id
string
required

Unique identifier for the subscription

client_secret
string | null

Client secret used to load Dodo checkout SDK NOTE : Dodo checkout SDK will be coming soon

discount_id
string | null

The discount id if discount is applied

expires_on
string<date-time> | null

Expiry timestamp of the payment link

URL to checkout page