Update a customer

PATCH

/v1/customers/:id

curl -X PATCH "https://api.summerbase.com/v1/customers/:id" \
  -H "Authorization: Bearer sb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "email": "billing@northwind.example.com",
      "name": "Northwind Labs",
      "seats": 25
    }
  }'

const response = await fetch("https://api.summerbase.com/v1/customers/:id", {
  method: "PATCH",
  headers: {
    Authorization: "Bearer sb_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "properties": {
      "email": "billing@northwind.example.com",
      "name": "Northwind Labs",
      "seats": 25
    }
  }),
})
const data = await response.json()

Record what you know about a customer. Only the keys you mention change; null clears one.

Properties are attributed to your own source, so they never overwrite what another source said. identities teaches us what other systems call this customer, which is how a backend sync links its own id to a provider’s.

A value you change or clear is kept in the customer’s history, which is what past figures are read from. To remove one for good, reimport the history without it or erase it.

Parameters

Path Parameters

required

string

The customer’s Summerbase id, or an identity ref: a source slug and that source’s own id for them, joined by a colon — stripe:cus_123.

Example

backend:acct_4821

Query Parameters

expand[]

Array<string>

<= 10 items

Allowed values: country erasures subscriptions

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

application/json

object

identities

What other sources call this customer, as source:id — ["stripe:cus_123"]. One that already identifies another customer merges that customer into this one, with a warning.

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

Array<string>

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

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

Example

{
  "properties": {
    "email": "billing@northwind.example.com",
    "name": "Northwind Labs",
    "seats": 25
  }
}

Response

Returns the customer object, with response_metadata about this request.

application/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

{
  "arr": "15000.00",
  "churned_at": null,
  "country_code": "US",
  "created_at": "2025-11-03T16:20:04Z",
  "email": "billing@northwind.example.com",
  "first_paying_at": "2025-12-01T10:04:00Z",
  "first_seen_at": "2025-11-03T16:20:00Z",
  "first_subscribed_at": "2025-11-17T10:04:00Z",
  "id": "0199a7c2-4e1b-7f38-b9d2-5a6c8e0f1d73",
  "identities": [
    "stripe:cus_QX7bN2kLp4Rt9v",
    "backend:acct_4821"
  ],
  "mrr": "1250.00",
  "name": "Northwind Labs",
  "object": "customer",
  "properties": {
    "seats": 25
  },
  "properties_by_source": {
    "backend": {
      "seats": 25
    },
    "stripe": {
      "email": "billing@northwind.example.com",
      "name": "Northwind Labs"
    }
  },
  "signed_up_at": "2025-11-03T16:20:00Z",
  "status": "paying"
}