Subscription items

One price within a subscription, with a quantity. Add, change and remove items with proration.

The subscription item object

idstring

Prefixed si_.

objectstring

subscription_item

subscriptionstring

pricestring

quantityinteger

Seats or units for licensed prices.

credit_rolloverboolean

Carry unused included units into the next period.

included_unitsinteger | null

Overrides the price's included units.

trial_included_unitsinteger | null

Included units while the subscription is trialing; null means the regular allowance.

metadataobject

created_attimestamp

updated_attimestamp

Proration follows the arrears model: the invoice at period end bills each item at its quantity then, for the whole period. An increase or a new item therefore adds nothing mid-period; a decrease or a removed item charges the dropped amount for the part of the period already used. Nothing is adjusted during a trial. In a first period prepaid at checkout, the rest of the period is prorated instead. proration_behavior: create_prorations (default) adds the adjustment to the next invoice, always_invoice bills it immediately, none skips it.

Create a subscription item

POST/v1/subscription_itemsSecret key

Body

subscriptionstringrequired

pricestringrequired

Must match the subscription's interval and currency.

quantityintegerdefault: 1

proration_behaviorenumdefault: create_prorations

create_prorations, always_invoice or none.

credit_rolloverboolean

included_unitsinteger

trial_included_unitsinteger

Included units during the trial instead of included_units.

metadataobject

curl https://api.borga.is/v1/subscription_items \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "subscription": "sub_9Qw1Er3Ty5Ui7Op9As1Df3Gh",
    "price": "price_7Kl9Mn1Op3Qr5St7Uv9Wx1Yz",
    "quantity": 1
  }'

Retrieve a subscription item

GET/v1/subscription_items/:idSecret key

Update a subscription item

POST/v1/subscription_items/:idSecret key

Body

quantityinteger

proration_behaviorenumdefault: create_prorations

credit_rolloverboolean

included_unitsinteger

trial_included_unitsinteger

Included units during the trial instead of included_units.

metadataobject

Remove a subscription item

DELETE/v1/subscription_items/:idSecret key

Query parameters

proration_behaviorenumdefault: create_prorations

Whether to charge the item for the part of the period already used.

Returns { "deleted": true, "id": "si_…" }. A subscription must keep at least one recurring item.