Add subscription item
const url = 'http://localhost:8080/v1/subscriptions/example/items';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"plan_id":"example","quantity":1}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url http://localhost:8080/v1/subscriptions/example/items \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "plan_id": "example", "quantity": 1 }'Adds a plan to the subscription as a new item. The plan must use the same billing interval and currency as the other items, and must not share meters with the customer’s other live subscriptions.
On an active subscription, a plan whose base fee is billed in advance is charged for the rest of the current period, in the same transaction as the add. An item added on the first day of the period (in the tenant’s timezone) pays for the whole period. A plan billed in arrears is billed at the end of the period for the days it was on the subscription.
Sends the subscription.item.added webhook event.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Header Parameters
Section titled “Header Parameters”Makes the call safe to retry. Send a unique value (a UUID works) and
the same value on every retry. For 24 hours, a repeat with the same
key, method, path and body gets the first response again, with an
Idempotent-Replayed: true header, instead of running again. The
error cases are in docs/api-surface.md. The usage routes do not take
it: each usage event carries its own idempotency_key.
Request Bodyrequired
Section titled “Request Bodyrequired”object
Responses
Section titled “Responses”The new item.
One priced line of a subscription. It pairs a plan with a quantity.
object
The item’s stored metadata. Absent when empty.
object
Plan the item moves to at pending_plan_effective_at. Absent when no change is scheduled.
When the plan was last changed immediately. Absent until the first such change.
Example generated
{ "id": "example", "tenant_id": "example", "subscription_id": "example", "plan_id": "example", "quantity": 1, "metadata": {}, "pending_plan_id": "example", "pending_plan_effective_at": "2026-04-15T12:00:00Z", "plan_changed_at": "2026-04-15T12:00:00Z", "created_at": "2026-04-15T12:00:00Z", "updated_at": "2026-04-15T12:00:00Z"}The body is not valid JSON.
object
object
One of invalid_request_error, authentication_error,
rate_limit_error or api_error. Every error the API
answers has this shape, including an unknown path (404,
code route_not_found) and a method the path does not take
(405, code method_not_allowed, with an Allow header).
The few exceptions are listed in docs/api-surface.md.
The request field the error is about. Sent only when the error
names one. A request body may hold only the fields its
operation lists, spelled and cased as listed: any other
field, or one the server sets (such as id), is refused
with 422 and param naming it. An operation with no request body lists no fields: send
no body, {} or null. The Stripe and Postmark webhooks and
the LiteLLM callback take their sender’s body as it comes.
Example
{ "error": { "type": "invalid_request_error" }}Subscription not found.
object
object
One of invalid_request_error, authentication_error,
rate_limit_error or api_error. Every error the API
answers has this shape, including an unknown path (404,
code route_not_found) and a method the path does not take
(405, code method_not_allowed, with an Allow header).
The few exceptions are listed in docs/api-surface.md.
The request field the error is about. Sent only when the error
names one. A request body may hold only the fields its
operation lists, spelled and cased as listed: any other
field, or one the server sets (such as id), is refused
with 422 and param naming it. An operation with no request body lists no fields: send
no body, {} or null. The Stripe and Postmark webhooks and
the LiteLLM callback take their sender’s body as it comes.
Example
{ "error": { "type": "invalid_request_error" }}Code already_exists: the subscription already has an item for
this plan. Code invalid_state: the subscription is canceled;
the plan is archived; the plan’s meters (the meters it has a
price for) overlap another live subscription of the customer; or the plan’s
currency differs from the subscription’s. Code
unpaid_invoice_blocks_change: the invoice for the current
period is unpaid (a written-off invoice is unpaid); settle or
void it first. Code
unbilled_period: a billing period ended and could not be
invoiced; retry billing first.
object
object
One of invalid_request_error, authentication_error,
rate_limit_error or api_error. Every error the API
answers has this shape, including an unknown path (404,
code route_not_found) and a method the path does not take
(405, code method_not_allowed, with an Allow header).
The few exceptions are listed in docs/api-surface.md.
The request field the error is about. Sent only when the error
names one. A request body may hold only the fields its
operation lists, spelled and cased as listed: any other
field, or one the server sets (such as id), is refused
with 422 and param naming it. An operation with no request body lists no fields: send
no body, {} or null. The Stripe and Postmark webhooks and
the LiteLLM callback take their sender’s body as it comes.
Example
{ "error": { "type": "invalid_request_error" }}Code validation_error: plan_id is missing or not found,
quantity is less than 1, or the plan’s billing interval
differs from the other items’.
Also: the body has an unknown field (param names it; the body must use only the fields listed here).
object
object
One of invalid_request_error, authentication_error,
rate_limit_error or api_error. Every error the API
answers has this shape, including an unknown path (404,
code route_not_found) and a method the path does not take
(405, code method_not_allowed, with an Allow header).
The few exceptions are listed in docs/api-surface.md.
The request field the error is about. Sent only when the error
names one. A request body may hold only the fields its
operation lists, spelled and cased as listed: any other
field, or one the server sets (such as id), is refused
with 422 and param naming it. An operation with no request body lists no fields: send
no body, {} or null. The Stripe and Postmark webhooks and
the LiteLLM callback take their sender’s body as it comes.
Example
{ "error": { "type": "invalid_request_error" }}