Create a subscription (first charge confirmed by frontend)

POST

/api/v1/subscriptions

curl --request POST \
  --url https://example.com/api/v1/subscriptions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '{ "customerId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "planId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "trialPeriodDays": 14, "idempotencyKey": "example" }'

Authorizations

• x-api-key

Request Body^required

Media typeapplication/json

object

customerId

required

Local customer id (UUID)

string format: uuid

planId

required

Local plan id (UUID)

string format: uuid

trialPeriodDays

Free trial length in days — Stripe schedules the first charge

number

>= 1

Example

14

idempotencyKey

Pass the same key on retries to guarantee the subscription is created at most once

string

Responses

201

Media typeapplication/json

object

subscription

required

object

id

required

string

stripeSubscriptionId

required

string

customerId

required

string

planId

required

string

status

required

string

Allowed values: active canceled incomplete incomplete_expired trialing past_due unpaid

currentPeriodStart

required

string format: date-time

nullable

currentPeriodEnd

required

string format: date-time

nullable

trialEnd

required

string format: date-time

nullable

createdAt

required

string format: date-time

updatedAt

required

string format: date-time

clientSecret

required

string

nullable

Example

{
  "subscription": {
    "status": "active"
  }
}