Skip to content

Assign a subscription, replacing any current one

POST
/v1/customers/{external_customer_id}/subscriptions
curl --request POST \
--url https://api.seal0.app/v1/customers/example/subscriptions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "cancel_at": "2026-04-15T12:00:00Z", "current_period_end": "2026-04-15T12:00:00Z", "current_period_start": "2026-04-15T12:00:00Z", "grace_ends_at": "2026-04-15T12:00:00Z", "plan": { "key": "example", "version": 1 }, "status": "example", "trial_ends_at": "2026-04-15T12:00:00Z" }'
external_customer_id
required
string

Opaque customer ID; must match ^[A-Za-z0-9._:-]{1,255}$.

Idempotency-Key
string
>= 1 characters <= 255 characters

Optional; replays the stored response for 24 hours.

Media typeapplication/json
object
cancel_at
string format: date-time
current_period_end
string format: date-time
current_period_start
string format: date-time
grace_ends_at
string format: date-time
plan
required

A plan version to pin; version omitted = latest published at request time.

object
key
required
string
version
integer
>= 1
status
required
string
trial_ends_at
string format: date-time

Example generated

{
"cancel_at": "2026-04-15T12:00:00Z",
"current_period_end": "2026-04-15T12:00:00Z",
"current_period_start": "2026-04-15T12:00:00Z",
"grace_ends_at": "2026-04-15T12:00:00Z",
"plan": {
"key": "example",
"version": 1
},
"status": "example",
"trial_ends_at": "2026-04-15T12:00:00Z"
}

The new current subscription.

Media typeapplication/json
object
cancel_at
required
string format: date-time
nullable
created_at
required
string format: date-time
current_period_end
required
string format: date-time
nullable
current_period_start
required
string format: date-time
nullable
customer_id
required

The customer’s external ID.

string
grace_ends_at
required
string format: date-time
nullable
id
required
string
is_current
required
boolean
plan
required

A pinned plan version.

object
key
required

Feature or plan key.

string
/^[a-z][a-z0-9_]{0,63}$/
version
required
integer
>= 1
replaced_at
required
string format: date-time
nullable
status
required
string
trial_ends_at
required
string format: date-time
nullable
updated_at
required
string format: date-time

Example generated

{
"cancel_at": "2026-04-15T12:00:00Z",
"created_at": "2026-04-15T12:00:00Z",
"current_period_end": "2026-04-15T12:00:00Z",
"current_period_start": "2026-04-15T12:00:00Z",
"customer_id": "example",
"grace_ends_at": "2026-04-15T12:00:00Z",
"id": "example",
"is_current": true,
"plan": {
"key": "example",
"version": 1
},
"replaced_at": "2026-04-15T12:00:00Z",
"status": "example",
"trial_ends_at": "2026-04-15T12:00:00Z",
"updated_at": "2026-04-15T12:00:00Z"
}

Error envelope.

Media typeapplication/json
object
error
required
object
code
required

Stable snake_case error code.

string
field
required

Offending input field, when known.

string
nullable
message
required
string
request_id
required
string

Example generated

{
"error": {
"code": "example",
"field": "example",
"message": "example",
"request_id": "example"
}
}

Error envelope.

Media typeapplication/json
object
error
required
object
code
required

Stable snake_case error code.

string
field
required

Offending input field, when known.

string
nullable
message
required
string
request_id
required
string

Example generated

{
"error": {
"code": "example",
"field": "example",
"message": "example",
"request_id": "example"
}
}

Error envelope.

Media typeapplication/json
object
error
required
object
code
required

Stable snake_case error code.

string
field
required

Offending input field, when known.

string
nullable
message
required
string
request_id
required
string

Example generated

{
"error": {
"code": "example",
"field": "example",
"message": "example",
"request_id": "example"
}
}

Error envelope.

Media typeapplication/json
object
error
required
object
code
required

Stable snake_case error code.

string
field
required

Offending input field, when known.

string
nullable
message
required
string
request_id
required
string

Example generated

{
"error": {
"code": "example",
"field": "example",
"message": "example",
"request_id": "example"
}
}

Error envelope.

Media typeapplication/json
object
error
required
object
code
required

Stable snake_case error code.

string
field
required

Offending input field, when known.

string
nullable
message
required
string
request_id
required
string

Example generated

{
"error": {
"code": "example",
"field": "example",
"message": "example",
"request_id": "example"
}
}

Error envelope.

Media typeapplication/json
object
error
required
object
code
required

Stable snake_case error code.

string
field
required

Offending input field, when known.

string
nullable
message
required
string
request_id
required
string

Example generated

{
"error": {
"code": "example",
"field": "example",
"message": "example",
"request_id": "example"
}
}