Custom source

A custom source is how your own code sends data to Summerbase. It does one of two jobs:

• Add details to customers your billing source already has. Your billing is in Stripe, say, but your own system knows more: the plan tier in your product, the account manager, the industry. Your code adds that to the customers Stripe reported.
• Send your subscriptions. Your billing runs on a system Summerbase doesn’t connect to, or on your own. Your code sends customers and their subscriptions, and Summerbase works out your metrics from them.

Both start the same way.

Set up

1. Create the source. Go to Settings, then Sources, choose Add source, then Custom. Give it a name and a short slug, such as backend. The slug can’t be changed later, because your records are named with it: your customer acct_4821 becomes backend:acct_4821 in Summerbase.
2. Create an API key. On the source’s page, under API keys, choose New key. Copy the secret straight away: it’s shown only once. Keep it on your server.

Add details to customers from another source

Address the customer by your own id, and list the id your billing source uses for them under identities. That links the two, and your properties land on the same customer:

curl https://api.summerbase.com/v1/customers/backend:acct_4821 \
  -X PATCH \
  -H "Authorization: Bearer $SUMMERBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identities": ["stripe:cus_NfJG2nK3"],
    "properties": {
      "account_manager": "Dana Okafor",
      "industry": "Logistics"
    }
  }'

From then on, either id finds the customer. Your properties are kept separately from Stripe’s, so neither overwrites the other. See How your data fits together.

You can add properties to a subscription the same way, addressed by your billing source’s id for it:

curl https://api.summerbase.com/v1/subscriptions/stripe:sub_1QxR8t \
  -X PATCH \
  -H "Authorization: Bearer $SUMMERBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"properties": {"sales_channel": "partner"}}'

The subscription’s amounts, status and dates stay your billing source’s. If that source hasn’t reported the subscription yet, the request is refused; send it again later.

Send your subscriptions

1. Send a customer

Address each customer by your own id. Summerbase creates the customer the first time, and updates it after that.

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

2. Send your plans and prices

A subscription is on a price, and every price is on a plan, so both have to exist before a subscription names them. See Plans and prices.

First the plan, addressed by your own id for it. Summerbase creates it the first time, and updates it after that:

curl https://api.summerbase.com/v1/plans/backend:growth \
  -X PATCH \
  -H "Authorization: Bearer $SUMMERBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "name": "Growth",
      "archived": false
    }
  }'

Then each price on it, naming the plan with plan_id. A name and the price’s list terms are optional:

curl https://api.summerbase.com/v1/prices/backend:growth_monthly \
  -X PATCH \
  -H "Authorization: Bearer $SUMMERBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "backend:growth",
    "name": "Growth monthly",
    "currency_code": "USD",
    "interval": "month",
    "interval_count": 1,
    "pricing_model": "fixed",
    "unit_amount": "50.00"
  }'

An annual Growth price is a second price with the same plan_id.

3. Send a subscription

Each item names its price with price_id. The plan comes from the price.

curl https://api.summerbase.com/v1/subscriptions/backend:sub_311 \
  -X PATCH \
  -H "Authorization: Bearer $SUMMERBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "claim_ownership": true,
    "customer_id": "backend:acct_4821",
    "status": "active",
    "currency_code": "USD",
    "items": [
      {
        "id": "backend:item_9001",
        "price_id": "backend:growth_monthly",
        "unit_amount": "50.00",
        "quantity": "25",
        "interval": "month"
      }
    ]
  }'

claim_ownership: true is needed the first time you send a subscription. It confirms that your source is the one that bills it, and from then on only your source can change its amounts, status and dates.

The order matters: plans, then prices, then subscriptions. A subscription that names a price Summerbase doesn’t have yet is refused as a whole.

4. Keep it up to date

Whenever something changes, such as a move to another price, more seats or a cancellation, send the subscription again with what’s true now. A new price goes in before the first subscription on it. Sending the same thing twice is harmless.

To load the history you had before using Summerbase, see Reimport subscription.

Next

The API reference has every endpoint and field.