Create a subscription

Error

A valid request URL is required to generate request examples

{
  "id": "<string>",
  "object": "subscription",
  "customer": "<string>",
  "status": "incomplete",
  "collection_method": "charge_automatically",
  "items": [
    {
      "id": "<string>",
      "price": "<string>",
      "quantity": 123,
      "metadata": {}
    }
  ],
  "current_period_start": 123,
  "current_period_end": 123,
  "billing_cycle_anchor": 123,
  "cancel_at_period_end": true,
  "metadata": {},
  "livemode": true,
  "created_at": 123,
  "updated_at": 123,
  "default_payment_method": "<string>",
  "trial_start": 123,
  "trial_end": 123,
  "canceled_at": 123,
  "ended_at": 123,
  "latest_invoice": "<string>"
}

{
  "error": {
    "code": "INVALID_DATA",
    "message": "invalid collection_method"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "CUSTOMER_NOT_FOUND",
    "message": "customer not found"
  }
}

{
  "error": {
    "code": "INVALID_SUBSCRIPTION_STATE",
    "message": "invalid subscription state for this operation"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

POST

subscriptions

Error

A valid request URL is required to generate request examples

{
  "id": "<string>",
  "object": "subscription",
  "customer": "<string>",
  "status": "incomplete",
  "collection_method": "charge_automatically",
  "items": [
    {
      "id": "<string>",
      "price": "<string>",
      "quantity": 123,
      "metadata": {}
    }
  ],
  "current_period_start": 123,
  "current_period_end": 123,
  "billing_cycle_anchor": 123,
  "cancel_at_period_end": true,
  "metadata": {},
  "livemode": true,
  "created_at": 123,
  "updated_at": 123,
  "default_payment_method": "<string>",
  "trial_start": 123,
  "trial_end": 123,
  "canceled_at": 123,
  "ended_at": 123,
  "latest_invoice": "<string>"
}

{
  "error": {
    "code": "INVALID_DATA",
    "message": "invalid collection_method"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "CUSTOMER_NOT_FOUND",
    "message": "customer not found"
  }
}

{
  "error": {
    "code": "INVALID_SUBSCRIPTION_STATE",
    "message": "invalid subscription state for this operation"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

Authorizations

Authorization

string

header

required

A merchant secret key (sk_…) sent as Authorization: Bearer <key>.

Headers

Idempotency-Key

string

A unique key that makes retries safe: the same key with the same request body returns the original response instead of repeating the operation.

Maximum string length: 255

Body

application/json

customer

string

required

Customer id (cus_…).

items

object[]

required

Show child attributes

collection_method

enum<string>

required

Available options:

charge_automatically,

send_invoice

default_payment_method

string | null

Payment method id (pm_…). Required for charge_automatically subscriptions that start with a trial.

trial_start

integer | null

Unix epoch seconds. Start of the trial period. Defaults to the creation time when trial_end is set.

trial_end

integer | null

Unix epoch seconds. End of the trial period. No initial invoice is issued while the subscription is trialing.

metadata

object

Show child attributes

Response

The created subscription.

string

required

object

enum<string>

required

Available options:

subscription

customer

string

required

Customer id (cus_…).

status

enum<string>

required

incomplete — created; first invoice not yet paid. trialing — in free trial; no invoice yet (or a zero-total one). active — most recent invoice paid; in good standing. past_due — most recent invoice payment failed; in dunning. unpaid — dunning exhausted; service stopped. Terminal. canceled — terminated (immediately or at period end). Terminal.

Available options:

incomplete,

trialing,

active,

past_due,

unpaid,

canceled

collection_method

enum<string>

required

Available options:

charge_automatically,

send_invoice

items

object[]

required

Show child attributes

current_period_start

integer

required

Unix epoch seconds. Start of the current billing period.

current_period_end

integer

required

Unix epoch seconds. End of the current billing period.

billing_cycle_anchor

integer

required

Unix epoch seconds. The reference point used to compute period boundaries.

cancel_at_period_end

boolean

required

True when the subscription is scheduled to cancel at the end of the current period.

metadata

object

required

Show child attributes

livemode

boolean

required

created_at

integer

required

Unix epoch seconds.

updated_at

integer

required

default_payment_method

string | null

The payment method used for automatic renewal charges (pm_…). Null when not set.

trial_start

integer | null

Unix epoch seconds. Start of the trial period. Null when the subscription was not created with a trial.

trial_end

integer | null

Unix epoch seconds. End of the trial period. Null when no trial.

canceled_at

integer | null

Unix epoch seconds. When the cancellation was requested. Null while not canceled.

ended_at

integer | null

Unix epoch seconds. When the subscription terminated. Null while active.

latest_invoice

string | null

Most recent invoice id (inv_…). Null before the first invoice is issued.

Start here

Checkout

Commerce

Checkout endpoints

Payment link endpoints

Catalog endpoints

Payments

Terminal locations

Terminal management

Terminal testing

Terminal payments

Invoices

Subscriptions

Setup intents

Credit notes

Webhook endpoints

Customer endpoints

API key endpoints

Payment method endpoints

Create a subscription

Authorizations

Headers

Body

Response