Create Subscription

Create a subscription without charging it yet. This is the first half of a two-step signup: your server creates the subscription and passes its client_secret to your checkout page, which collects the card and calls Confirm Subscription.

POST /subscriptions/create

The subscription starts in created status. Nothing is charged and no renewal is scheduled until it is confirmed. To create and charge in one call, use Create and Confirm Subscription.

Headers

Header	Type	Required	Description
`api-key`	string	Yes	Your secret API key.
`X-Profile-Id`	string	No	Business profile to create the subscription under, when `profile_id` is not in the body. Leave both out to use your default profile.

Body Parameters

Parameter	Type	Required	Description
`profile_id`	string	No	Business profile the subscription belongs to. It decides which connector charges the subscription and which webhook URL receives its events. If left out, the `X-Profile-Id` header is used, then your default profile, as on Create Payment. Send it if your account has no default profile.
`merchant_reference_id`	string	Yes	Your unique reference for this subscription, such as your order ID. A second create with the same reference is refused while the first subscription is not `failed`.
`customer_id`	string	Yes	ID of the customer. Must exist unless `customer` is also sent.
`customer`	object	No	Details for a customer that does not exist yet: `name`, `email`, `phone`, `phone_country_code`. The customer is created only when it does not exist; an existing customer is not changed.
`amount`	integer	Yes	Amount charged every period, in the smallest currency unit. Must be greater than zero.
`currency`	string	Yes	Three-letter ISO 4217 currency code.
`billing_interval`	string	Yes	`day`, `week`, `month` or `year`.
`interval_count`	integer	Yes	Number of `billing_interval` units in one period. At least `1`.
`total_billing_cycles`	integer	No	Total number of payments, including the first. Leave out to renew until cancelled.
`payment_details`	object	Yes	See Payment details.
`billing`	object	No	Billing address.
`shipping`	object	No	Shipping address.
`plan_id`	string	No	Your own plan label. Stored and returned; it does not change the price.
`item_price_id`	string	No	Your own price label. Stored and returned; it does not change the price.

Payment details

Field	Type	Required	Description
`return_url`	string	Yes	Where the customer is sent after a 3D Secure challenge during confirm.
`setup_future_usage`	string	Yes	Must be `off_session` so the card is saved for renewals.
`authentication_type`	string	No	`three_ds` or `no_three_ds`.

Request Example

curl -X POST 'https://api.moonlinkpay.com/subscriptions/create' \
  -H "Content-Type: application/json" \
  -H "api-key: snd_YOUR_API_KEY" \
  -d '{
  "profile_id": "pro_YOUR_PROFILE_ID",
  "merchant_reference_id": "order_1002",
  "customer_id": "cus_jane_42",
  "amount": 1500,
  "currency": "USD",
  "billing_interval": "month",
  "interval_count": 1,
  "payment_details": {
    "return_url": "https://example.com/return",
    "setup_future_usage": "off_session"
  }
}'

curl -X POST 'https://api.moonlinkpay.com/subscriptions/create' \  -H "Content-Type: application/json" \  -H "api-key: snd_YOUR_API_KEY" \  -d '{  "profile_id": "pro_YOUR_PROFILE_ID",  "merchant_reference_id": "order_1002",  "customer_id": "cus_jane_42",  "amount": 1500,  "currency": "USD",  "billing_interval": "month",  "interval_count": 1,  "payment_details": {    "return_url": "https://example.com/return",    "setup_future_usage": "off_session"  }}'

Response

{
"id": "sub_fOC8OiljkGOI59gaZJqL",
"merchant_reference_id": "order_1002",
"status": "created",
"client_secret": "sub_fOC8OiljkGOI59gaZJqL_secret_rGax6h0aEyu8owBeID6C",
"customer_id": "cus_jane_42",
"profile_id": "pro_YOUR_PROFILE_ID",
"amount": 1500,
"currency": "USD",
"total_billing_cycles": null,
"remaining_billing_cycles": null,
"billing_cycle_count": 0,
"next_billing_at": null,
"cancel_at_period_end": false,
"payment": {
  "payment_id": "sub_7515eafdcb30ed3ec6e1425c_0_0",
  "status": "requires_payment_method",
  "amount": 1500,
  "currency": "USD"
},
"invoice": {
  "id": "invoice_T4UTILxQleMKwGQGkATL",
  "status": "invoice_created",
  "amount": 1500,
  "currency": "USD",
  "billing_cycle_count": 0,
  "attempt_count": 0
}
}

{"id": "sub_fOC8OiljkGOI59gaZJqL","merchant_reference_id": "order_1002","status": "created","client_secret": "sub_fOC8OiljkGOI59gaZJqL_secret_rGax6h0aEyu8owBeID6C","customer_id": "cus_jane_42","profile_id": "pro_YOUR_PROFILE_ID","amount": 1500,"currency": "USD","total_billing_cycles": null,"remaining_billing_cycles": null,"billing_cycle_count": 0,"next_billing_at": null,"cancel_at_period_end": false,"payment": {  "payment_id": "sub_7515eafdcb30ed3ec6e1425c_0_0",  "status": "requires_payment_method",  "amount": 1500,  "currency": "USD"},"invoice": {  "id": "invoice_T4UTILxQleMKwGQGkATL",  "status": "invoice_created",  "amount": 1500,  "currency": "USD",  "billing_cycle_count": 0,  "attempt_count": 0}}

Pass only the subscription id and client_secret to the browser. Never expose your secret API key on a checkout page.

Errors

Code	When
`HE_01`	A subscription with this `merchant_reference_id` already exists.
`HE_02`	`customer_id` does not exist and no `customer` details were sent, or `profile_id` is not one of your business profiles.
`IR_04`	No profile was given and your account has no default profile.
`IR_06`	A field is missing or invalid, or `profile_id` and `X-Profile-Id` name different profiles.

Next step

Your checkout page collects the card and calls Confirm Subscription with the client_secret. It can show the price first with Get Subscription Price.

On this page