Assign a subscription, replacing any current one
POST
/v1/customers/{external_customer_id}/subscriptions
const url = 'https://api.seal0.app/v1/customers/example/subscriptions';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"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"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}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" }'Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”external_customer_id
required
string
Opaque customer ID; must match ^[A-Za-z0-9._:-]{1,255}$.
Header Parameters
Section titled “Header Parameters”Idempotency-Key
string
Optional; replays the stored response for 24 hours.
Request Bodyrequired
Section titled “Request Bodyrequired”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
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"}Responses
Section titled “Responses”The new current subscription.
Media typeapplication/json
object
cancel_at
required
string format: date-time
created_at
required
string format: date-time
current_period_end
required
string format: date-time
current_period_start
required
string format: date-time
customer_id
required
The customer’s external ID.
string
grace_ends_at
required
string format: date-time
id
required
string
is_current
required
boolean
plan
required
A pinned plan version.
object
key
required
Feature or plan key.
string
version
required
integer
replaced_at
required
string format: date-time
status
required
string
trial_ends_at
required
string format: date-time
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
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
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
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
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
message
required
string
request_id
required
string
Example generated
{ "error": { "code": "example", "field": "example", "message": "example", "request_id": "example" }}default
Section titled “default”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
message
required
string
request_id
required
string
Example generated
{ "error": { "code": "example", "field": "example", "message": "example", "request_id": "example" }}