Skip to main content
POST
Create Subscription

Authorizations

Authorization
string
header
required

Service (M2M) access token issued by POST /auth/token using the client_credentials grant. Required scopes, where known, are listed on each operation below.

Headers

Idempotency-Key
string

Deduplicates retried requests with the same key and parameters instead of creating a second resource. Recommended: a deterministic, order-scoped value such as initial-subscription:{provider_customer_id}:{order_id} — a client that generates a fresh random value on retry defeats the deduplication and creates a second subscription. Mint a new key for a genuinely new attempt. Reusing a key replays the original response, so a retry after a 400 decline returns that same 400 instead of charging a replacement card, and changing items under an unchanged key is rejected as an idempotency conflict rather than retried. The replay window (roughly 24 hours) also outlives the subscription's own incomplete_expired deadline (roughly 20 hours), so once a prior attempt under a key has reached a terminal state, a genuinely new purchase needs a new key.

Body

application/json
provider_customer_id
string
required

Saved provider customer id (e.g. test_customer_id).

items
object[]
required

Non-empty. Carries both recurring and one-time prices — send every price in this one array. You do not say which is which: each provider_price_id is resolved with the provider, and a recurring price becomes a subscription item while a one-time price is billed once on the subscription's first invoice. Must include exactly one recurring price, with any number of one-time prices beside it: an items array of only one-time prices, or with two or more recurring prices, is rejected with a 400. Pause, resume and cancel act on the whole subscription, so create one subscription per recurring product. A one-time price is charged immediately even when trial_period_days is set: the trial defers the recurring charge, not the one-time item, which is what makes a "$1 first month then rebill" bundle a single call. Each entry has a required provider_price_id and optional quantity. A separate one_time_items array is not accepted — a request that still sends it is rejected with a 400 naming the field, so an upfront charge can never be silently skipped; move those entries into items. Invoice lines do not carry a coverage period.

provider_payment_method_id
string

Saved provider payment-method id (e.g. test_payment_method_id). When provided, set as the new subscription's default payment method. Charged off-session during the request by default, or used as the method the customer confirms when on_session: true. When omitted, the customer's default payment method is used. On the off-session posture a customer with no default is rejected with a 400; on the on-session posture the field may be omitted for a customer with no saved method at all — the browser confirmation collects it, which is what makes a first purchase possible.

discounts
object[]

Discounts applied at creation, so the discount reaches the first invoice — how long it keeps applying afterwards is the coupon's own duration, not this field's. Each entry must specify exactly one of coupon, promotion_code or discount; sending two of them as non-empty strings, or none of them, is a 400. A blank or non-string member is ignored rather than rejected, so {"coupon": "", "promotion_code": "test_promotion_code_id"} is accepted as a promotion-code discount. Ids are trimmed before use. An empty array is treated as absent — identical to omitting the field: the provider default applies, which inherits any discount already on the billing customer. Per-item discounts go on items[].discounts instead.

metadata
object

Free-form string key/value pairs attached to the subscription.

trial_period_days
integer

Starts the subscription on a trial of this many days, deferring the first recurring charge until the trial ends. Must be a positive integer. What happens when the trial ends is not configurable per request: OpenLoop sets the end behaviour to cancel, so a trial that ends with no payment method on file cancels the subscription rather than invoicing it. trial_settings is not a request field — a body that carries one is accepted and the field is ignored.

on_session
boolean

Opts into the on-session (customer-present) payment posture: the response then carries a payment_confirmation block whose client_secret your browser confirms while the customer is still present, which is what makes 3D Secure reachable and can reduce first-payment declines. Absent or false keeps the default off-session behavior unchanged, including the error on a declined card. Must be a boolean when supplied — a non-boolean value is rejected with a 400. If you set on_session: true and the response carries no payment_confirmation key, the posture was not honored — you are talking to a deployment that predates this field, and the first charge has already been attempted off-session. Do not proceed to browser confirmation in that case.

Response

Success.

data
object
required