Update a subscription item

PATCH

/v1/subscription_items/:id

curl -X PATCH "https://api.summerbase.com/v1/subscription_items/:id" \
  -H "Authorization: Bearer sb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": "30",
    "subscription_id": "backend:sub_7731"
  }'

Change one item. Only the fields you mention change.

Its own fields — unit amount, quantity, interval — are the owning source’s. Any source may attach properties and identities.

A value you change or clear is kept in the item’s history. To remove one for good, reimport the subscription without it, or erase a property.

Parameters

Path Parameters

id

required

string

Its Summerbase id, or an identity ref: a source slug and that source’s own id for it, joined by a colon — stripe:si_123.

Example

backend:item_9001

Query Parameters

expand[]

Array<string>

<= 10 items

Allowed values: price subscription

Relationships to include in the response instead of fetching separately. A dotted path expands what an expanded record can expand in turn — at most 4 deep, 10 paths a request, and never back to a record already on the path.

Request Body^required

Media typeapplication/json

object

deleted

Whether the item has come off the subscription. When it did is the effective_at of the write that set this.

boolean

discount_amount

What comes off this item’s invoice, in the subscription’s currency, after every discount the source applies to it has been worked out: coupons at any level, stacked in the source’s order, restricted to the products they cover. The item is worth unit_amount × quantity less this, each interval. Zero is no discount.

string format: decimal

discount_ends_at

When the discount, or the earliest part of it, stops applying, if the source knows. Information for a reader: the discount comes off when the source writes a smaller discount_amount, not when this passes.

string format: date-time

identities

What other sources call this subscription item, as source:id — ["stripe:cus_123"]. One that already identifies another subscription item is refused.

What each source calls this record, as <source>:<id in that source>. Any entry addresses it — stripe:cus_123.

Array<string>

interval

The unit this item bills in.

string

Allowed values: day week month year

interval_count

How many intervals between charges.

integer

>= 1

on_warning

What to do about the parts of this write that cannot be applied as sent, or that would merge two records together.

warn applies everything it can and reports the rest in warnings, so one unusable property never costs you a subscription’s amounts. error applies none of it unless all of it applies: the write is rolled back and every warning comes back as an error instead.

Send error from a form, where somebody is waiting to be told what to fix, and where folding two customers together is a thing to confirm rather than to discover afterwards. Leave it alone in an ingest client, which wants the revenue to land either way.

string

Allowed values: warn error

price_id

The price this item is on, when a source named one.

string format: uuid

pricing_model

How the unit amount is arrived at.

string

Allowed values: fixed tiered metered

properties

Properties to record in your source.

Property keys and the values to set. Only the keys named here change; null clears one.

object

key

additional properties

Any of:

string

string

number

number

boolean

boolean

object

object

operation

What to do with the value. Defaults to setting it.

string

Allowed values: set increment set_once

type

What this value is. Given here, it is not inferred; omitted, the key’s existing definition decides, and a new key takes the type its first value looks like.

string

Allowed values: string number boolean datetime

value

The value, as a string. Parsed into the key’s type — which type states outright, or which the key’s existing definition decides. Null clears the key.

string

quantity

How many units at this unit amount. A decimal, because a unit is not always a whole seat: a billing system that meters usage sends 1.5 of something, and rounding it would misstate what the item is worth.

string format: decimal

subscription_id

required

The subscription to add it to — a Summerbase id, or a source identity.

string

unit_amount

What one unit costs per interval. Excludes tax and any discount.

string format: decimal

Example

{
  "quantity": "30",
  "subscription_id": "backend:sub_7731"
}

Response

Returns the deleted subscription item’s id, with deleted: true.

Media typeapplication/json

Example

{
  "created_at": "2025-11-17T10:04:03Z",
  "deleted": false,
  "discount_amount": "0",
  "discount_ends_at": null,
  "id": "0199a7c2-5b41-7c62-9d3e-6a1f8b2c4d97",
  "identities": [
    "stripe:si_QhT6vW8xY0zA3b"
  ],
  "interval": "month",
  "interval_count": 1,
  "net_amount": "1250.00",
  "object": "subscription_item",
  "plan_id": "0198f1a4-1d2e-7a40-9b31-5c6d7e8f9a0b",
  "plan_name": "Growth",
  "price_id": "0198f1a4-2e5f-7b80-a1c2-3d4e5f6a7b8c",
  "price_name": "Growth monthly",
  "pricing_model": "fixed",
  "properties": {
    "seat_type": "standard"
  },
  "properties_by_source": {
    "backend": {
      "seat_type": "standard"
    }
  },
  "quantity": "25",
  "subscription_id": "0199a7c2-5b3e-7a14-8c6d-2f9e4b7a1c05",
  "unit_amount": "50.00"
}