Pre-1.0 · one maintainer · Stripe and cards only · no SDKs (client libraries) yet · no production users yet. Docs describe v0.9.1 (29 Oct 2026) · What’s new →

Remove subscription item

DELETE

/v1/subscriptions/{id}/items/{itemID}

const url = 'http://localhost:8080/v1/subscriptions/example/items/example';
const options = {method: 'DELETE', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request DELETE \
  --url http://localhost:8080/v1/subscriptions/example/items/example \
  --header 'Authorization: Bearer <token>'

Removes an item from the subscription. The last item of an active subscription cannot be removed; cancel the subscription instead.

On an active subscription, the unused part of a base fee billed in advance is credited in the same transaction. 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.removed webhook event.

Authorizations

BearerAuth

Parameters

Path Parameters

required

string

itemID

required

string

Responses

204

Item removed.

404

Subscription not found, or the item is not on this subscription.

application/json

object

error

object

type

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.

string

code

string

message

string

request_id

string

param

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.

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}

409

Code invalid_state: this is the last item of an active subscription. Code unbilled_period: a billing period ended and could not be invoiced; retry billing first.

application/json

object

error

object

type

string

code

string

message

string

request_id

string

param

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}