Update a subscription

PATCH

/v1/subscriptions/:id

curl -X PATCH "https://api.summerbase.com/v1/subscriptions/:id" \
  -H "Authorization: Bearer sb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "claim_ownership": true,
    "currency_code": "USD",
    "current_period_ends_at": "2026-11-01T10:04:00Z",
    "customer_id": "backend:acct_4821",
    "items": [
      {
        "id": "backend:item_9001",
        "interval": "month",
        "price_id": "backend:growth-monthly",
        "quantity": "25",
        "unit_amount": "50.00"
      }
    ],
    "status": "active"
  }'

Report what you know about a subscription. Only the fields you mention change; null clears one, and items replaces the whole set.

Its own fields are the owning source’s. Anyone may attach properties and identities; only the source that owns it may move its status, dates or items.

A value you change or clear is kept in the subscription’s history, which is what past figures are read from. To remove one for good, reimport the history 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:sub_123.

Example

backend:sub_7731

Query Parameters

expand[]

Array<string>

<= 10 items

Allowed values: currency customer items owner_source

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

cancels_at

A cancellation already booked. It is still in service until then, and the source says so with status: canceled when it stops.

string format: date-time

claim_ownership

Say true to create this subscription as the source it lives in — the only one that may write its status, its dates and its items from then on. A subscription is never created without it, so a write meant to annotate one that does not exist yet is refused rather than creating it under the wrong owner. On an existing subscription it changes nothing for the owner and is refused for anyone else.

boolean

currency_code

The currency it bills in, by its ISO 4217 code.

string

>= 3 characters <= 3 characters

current_period_ends_at

When the current billing period ends. The next charge is due then, unless a cancellation is booked for it.

string format: date-time

customer_id

required

Who is subscribed. A Summerbase id, or any source identity for them like stripe:cus_123, which creates the customer if it is new.

string

ended_at

When service stopped, beside status: canceled. Clear it, with status back to active, to resume a subscription; the same id may be brought back as often as the source does so.

string format: date-time

identities

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

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

Array<string>

items

Every item of the subscription. Sending this replaces the set.

Array<object>

object

discount_amount

What comes off this item’s invoice, as a decimal string, every coupon on it worked out. 0 is no discount, and clears one.

string format: decimal

discount_ends_at

When the discount, or the earliest part of it, stops applying, if known. Read with discount_amount: sent without it, an amount has no known end.

string format: date-time

id

required

This item’s id — a Summerbase id, or a source identity like stripe:si_123.

string

>= 1 characters <= 320 characters

identities

What other sources call this item, as source:id.

Array<string>

interval

The unit the item bills in.

string

Allowed values: day week month year

interval_count

How many intervals between charges. Two months is month with a count of 2.

integer

>= 1

price_id

The price this item is on — a Summerbase id, or a source identity like stripe:price_123. It has to exist: create it first, with PATCH /v1/prices/{id}. The item’s plan is the price’s.

string

<= 320 characters

pricing_model

How the unit amount is arrived at. fixed unless said otherwise.

string

Allowed values: fixed tiered metered

properties

Properties to record for this item, in your source.

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 string; 1.5 is allowed.

string format: decimal

unit_amount

What one unit costs per interval, as a decimal string. Excludes tax and discounts.

string format: decimal

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

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

status

Where it is in its life. Not whether it has been paid for.

string

Allowed values: pending trialing active paused canceled

trial_ends_at

When the trial ends, or ended. A subscription that trials starts trialing, so when it began is started_at and its status history.

string format: date-time

Example

{
  "claim_ownership": true,
  "currency_code": "USD",
  "current_period_ends_at": "2026-11-01T10:04:00Z",
  "customer_id": "backend:acct_4821",
  "items": [
    {
      "id": "backend:item_9001",
      "interval": "month",
      "price_id": "backend:growth-monthly",
      "quantity": "25",
      "unit_amount": "50.00"
    }
  ],
  "status": "active"
}

Response

Returns the subscription object, with response_metadata about this request.

Media typeapplication/json

object

response_metadata

About this request rather than about the record. Absent when there is nothing to say.

object

warnings

Parts of this write that were skipped — a property whose value did not fit its type — and things it did that were worth saying, like merging two customers. The rest of the write landed. Absent when there is nothing to report.

Send on_warning: "error" to have these refuse the write instead, and come back as error.errors with the same codes.

Array<object>

object

code

required

What kind of thing was skipped, for a client to branch on.

string

field

The input it came from, like properties.seats.

string

message

required

What was skipped and why, in a sentence.

string

Example

{
  "annual_amount": "15000.00",
  "billing_amounts": [
    {
      "interval": "month",
      "interval_count": 1,
      "net_amount": "1250.00"
    }
  ],
  "cancels_at": null,
  "currency_code": "USD",
  "current_period_ends_at": "2026-11-01T10:04:00Z",
  "customer_id": "0199a7c2-4e1b-7f38-b9d2-5a6c8e0f1d73",
  "ended_at": null,
  "id": "0199a7c2-5b3e-7a14-8c6d-2f9e4b7a1c05",
  "identities": [
    "stripe:sub_1QhT5uV7wX9yZ2aB"
  ],
  "monthly_amount": "1250.00",
  "object": "subscription",
  "owner_source_id": "0198f1a3-0b7c-7e25-9f41-6a2d8c3e5b19",
  "properties": {
    "account_manager": "Priya Shah"
  },
  "properties_by_source": {
    "backend": {
      "account_manager": "Priya Shah"
    },
    "stripe": {
      "contract_id": "C-2025-118"
    }
  },
  "recorded_at": "2025-11-17T10:04:03Z",
  "started_at": "2025-11-17T10:04:00Z",
  "status": "active",
  "trial_ends_at": "2025-12-01T10:04:00Z"
}