Sources and ownership

A source is a system that sends Summerbase data. A provider’s source, such as Stripe, fetches its data itself once it is connected. A custom source is one you write to, and every API key that writes is bound to one: everything the key writes is attributed to that source, and nothing in a request can choose another.

A subscription, its items and a plan each live in one source, named by owner_source_id. Only that source may change the record’s own fields — a subscription’s status, dates, currency and items, an item’s amounts, a plan’s name — and a write from any other source that tries is refused with 400 and the code not_the_owner. Any source may still write properties and identities on it.

Creating a subscription claims it for your source, so a create says so with "claim_ownership": true, and one without it is refused with 404. That stops a write meant to annotate a subscription another system has not reported yet from creating it under the wrong owner:

{
  "customer_id": "backend:acct_4821",
  "claim_ownership": true,
  "status": "active",
  "currency_code": "USD",
  "items": [
    {"id": "backend:item_9001", "price_id": "backend:growth-monthly", "quantity": "25", "unit_amount": "50.00", "interval": "month"}
  ]
}

A customer belongs to no one source. Its name, email, signed_up_at and country_code are properties every source may write, and the record takes each from the source with the lowest priority that has one.