Skip to main content
POST
/
api
/
v1
/
subscriptions
Create subscription
curl --request POST \
  --url https://api.example.com/api/v1/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "activation_condition": "ON_START",
  "customer_id_or_alias": "<string>",
  "plan_id": "<string>",
  "start_date": "2023-12-25",
  "add_ons": [
    {
      "add_on_id": "<string>",
      "customization": {
        "price_entry": {},
        "name": "<string>"
      },
      "quantity": 1
    }
  ],
  "auto_advance_invoices": true,
  "billing_day_anchor": 16384,
  "charge_automatically": true,
  "coupon_codes": [
    "<string>"
  ],
  "end_date": "2023-12-25",
  "invoice_memo": "<string>",
  "net_terms": 1,
  "payment_methods_config": {
    "type": "online",
    "config": {
      "card": {
        "enabled": true
      },
      "direct_debit": {
        "enabled": true
      }
    }
  },
  "price_components": {
    "extra_components": [
      {
        "name": "<string>",
        "price_entry": {},
        "product_ref": {}
      }
    ],
    "overridden_components": [
      {
        "component_id": "<string>",
        "name": "<string>",
        "price_entry": {}
      }
    ],
    "parameterized_components": [
      {
        "component_id": "<string>",
        "parameters": {
          "billing_period": "MONTHLY",
          "committed_capacity": 1,
          "initial_slot_count": 1
        }
      }
    ],
    "remove_components": [
      "<string>"
    ]
  },
  "purchase_order": "<string>",
  "skip_past_invoices": true,
  "trial_days": 1,
  "version": 123
}
'
{
  "add_ons": [
    {
      "fee": {
        "rate": "<string>"
      },
      "name": "<string>",
      "period": "ONE_TIME",
      "quantity": 1,
      "add_on_id": "<string>",
      "id": "<string>"
    }
  ],
  "applied_coupons": [
    {
      "applied_coupon": {
        "coupon_id": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "id": "<string>",
        "is_active": true,
        "applied_amount": "<string>",
        "applied_count": 123,
        "last_applied_at": "2023-11-07T05:31:56Z"
      },
      "coupon": {
        "code": "<string>",
        "description": "<string>",
        "disabled": true,
        "discount": {
          "percentage": "<string>"
        },
        "id": "<string>",
        "reusable": true,
        "expires_at": "2023-11-07T05:31:56Z",
        "recurring_value": 123,
        "redemption_limit": 123
      }
    }
  ],
  "auto_advance_invoices": true,
  "billing_day_anchor": 123,
  "charge_automatically": true,
  "components": [
    {
      "fee": {
        "rate": "<string>"
      },
      "name": "<string>",
      "period": "ONE_TIME",
      "price_component_id": "price_7n42DGM5Tflk9n8mt7Fhc7",
      "product_id": "prd_7n42DGM5Tflk9n8mt7Fhc7"
    }
  ],
  "created_at": "2023-11-07T05:31:56Z",
  "currency": "AED",
  "current_period_start": "2023-12-25",
  "customer_id": "<string>",
  "customer_name": "<string>",
  "id": "<string>",
  "mrr_cents": 1,
  "net_terms": 1,
  "period": "MONTHLY",
  "plan_id": "<string>",
  "plan_name": "<string>",
  "plan_version": 1,
  "plan_version_id": "<string>",
  "start_date": "2023-12-25",
  "status": "PENDING_ACTIVATION",
  "activated_at": "2023-11-07T05:31:56Z",
  "billing_start_date": "2023-12-25",
  "checkout_url": "<string>",
  "current_period_end": "2023-12-25",
  "customer_alias": "<string>",
  "end_date": "2023-12-25",
  "invoice_memo": "<string>",
  "payment_methods_config": {
    "type": "online",
    "config": {
      "card": {
        "enabled": true
      },
      "direct_debit": {
        "enabled": true
      }
    }
  },
  "purchase_order": "<string>",
  "trial_duration": 1
}

Authorizations

​
Authorization
string
header
required

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

Body

application/json
​
activation_condition
enum<string>
required
Available options:
ON_START,
ON_CHECKOUT,
MANUAL
​
customer_id_or_alias
string<CustomerId or customer alias>
required
​
plan_id
string<MeteroidId>
required
Example:

"plan_7n42DGM5Tflk9n8mt7Fhc7"

​
start_date
string<date>
required
Example:

"2024-11-01"

​
add_ons
object[]
​
auto_advance_invoices
boolean
​
billing_day_anchor
integer<int32> | null
Required range: 1 <= x <= 32767
​
charge_automatically
boolean
​
coupon_codes
string[]
​
end_date
string<date>
Example:

"2025-11-01"

​
invoice_memo
string
​
net_terms
integer<int32>
Required range: x >= 0
​
payment_methods_config
object

Payment methods configuration. If not specified, inherits from the invoicing entity.

​
price_components
object
​
purchase_order
string | null
​
skip_past_invoices
boolean

Migration mode: when true with a past start_date, skip creating invoices for past cycles. The subscription will be set to the current billing period with correct cycle_index.

​
trial_days
integer<int32>
Required range: x >= 0
​
version
integer<int32>

Response

Subscription successfully created

​
add_ons
object[]
required
​
applied_coupons
object[]
required
​
auto_advance_invoices
boolean
required
​
billing_day_anchor
integer<int32>
required
​
charge_automatically
boolean
required
​
components
object[]
required
​
created_at
string<date-time>
required

When the subscription was created

​
currency
enum<string>
required
Available options:
AED,
AFN,
ALL,
AMD,
ANG,
AOA,
ARS,
AUD,
AWG,
AZN,
BAM,
BBD,
BDT,
BGN,
BHD,
BIF,
BMD,
BND,
BOB,
BRL,
BSD,
BTN,
BWP,
BYN,
BZD,
CAD,
CDF,
CHF,
CLP,
CNH,
CNY,
COP,
CRC,
CUC,
CUP,
CVE,
CZK,
DJF,
DKK,
DOP,
DZD,
EGP,
ERN,
ETB,
EUR,
FJD,
FKP,
GBP,
GEL,
GHS,
GIP,
GMD,
GNF,
GTQ,
GYD,
HKD,
HNL,
HRK,
HTG,
HUF,
IDR,
ILS,
INR,
IQD,
IRR,
ISK,
JMD,
JOD,
JPY,
KES,
KGS,
KHR,
KMF,
KPW,
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,
SDG,
SEK,
SGD,
SHP,
SLL,
SOS,
SRD,
SSP,
STD,
STN,
SVC,
SYP,
SZL,
THB,
TJS,
TMT,
TND,
TOP,
TRY,
TTD,
TWD,
TZS,
UAH,
UGX,
USD,
UYU,
UZS,
VES,
VND,
VUV,
WST,
XAF,
XCD,
XOF,
XPF,
YER,
ZAR,
ZMW,
ZWL
Example:

"EUR"

​
current_period_start
string<date>
required

Current billing period start date

​
customer_id
string<MeteroidId>
required
Example:

"cus_7n42DGM5Tflk9n8mt7Fhc7"

​
customer_name
string
required
​
id
string<MeteroidId>
required
Example:

"sub_7n42DGM5Tflk9n8mt7Fhc7"

​
mrr_cents
integer<int64>
required

Monthly recurring revenue in cents

Required range: x >= 0
​
net_terms
integer<int32>
required

Payment terms in days (0 = due on issue)

Required range: x >= 0
​
period
enum<string>
required

Billing period (monthly, annual, etc.)

Available options:
MONTHLY,
QUARTERLY,
SEMIANNUAL,
ANNUAL
​
plan_id
string<MeteroidId>
required
Example:

"plan_7n42DGM5Tflk9n8mt7Fhc7"

​
plan_name
string
required
​
plan_version
integer<int32>
required
Required range: x >= 0
​
plan_version_id
string<MeteroidId>
required
Example:

"plv_7n42DGM5Tflk9n8mt7Fhc7"

​
start_date
string<date>
required

When the subscription contract starts (benefits apply from this date)

​
status
enum<string>
required
Available options:
PENDING_ACTIVATION,
PENDING_CHARGE,
TRIAL_ACTIVE,
ACTIVE,
TRIAL_EXPIRED,
PAUSED,
SUSPENDED,
CANCELLED,
COMPLETED,
SUPERSEDED,
ERRORED
​
activated_at
string<date-time> | null

When the subscription was activated (first payment or activation condition met)

​
billing_start_date
string<date> | null

When billing started (after any trial period)

​
checkout_url
string | null
​
current_period_end
string<date> | null

Current billing period end date

​
customer_alias
string | null
​
end_date
string<date> | null

When the subscription ends (if set)

​
invoice_memo
string | null

Default memo for invoices

​
payment_methods_config
object

Online (card/direct debit), BankTransfer, or External.

​
purchase_order
string | null
​
trial_duration
integer<int32> | null

Trial duration in days

Required range: x >= 0