Billing

A prepaid balance: connected accounts beyond the free ones are charged day by day and usage (X API, messages) as it happens. Topping it up happens in the dashboard.

Get the balance

GET/v1/billing

Balance, connected accounts and what they cost. With the balance used up, connecting beyond the free accounts, and publishing or sending from accounts beyond them or on X, answer 402.

Response 200

data

enabledbooleanrequired
False while billing is not available: nothing is charged or limited.
balancenumberrequired
Prepaid balance in cents (up to three decimals). Negative when charges outran it.
currencystringrequired
connectedAccountsintegerrequired
max 9,007,199,254,740,991
freeAccountsintegerrequired
max 9,007,199,254,740,991
monthlyEstimateintegerrequired
Monthly price of the accounts connected now, in cents. It is charged day by day.
max 9,007,199,254,740,991
dailyEstimatenumberrequired
What those accounts cost today, in cents (up to three decimals).
daysLeftinteger | nullrequired
Whole days the balance covers at that cost; null when nothing is charged daily.
linesobject[]required
lines
- fromintegerrequired
  max 9,007,199,254,740,991
- tointeger | nullrequired
- accountsintegerrequired
  max 9,007,199,254,740,991
- unitAmountintegerrequired
  Cents per account and month.
  max 9,007,199,254,740,991
- amountintegerrequired
  max 9,007,199,254,740,991
canConnectMorebooleanrequired
Whether one more account can be connected right now.
blockedbooleanrequired
The balance is used up: accounts beyond the free ones, and X accounts, cannot publish or send until it is topped up.
cardobject
The saved payment method, for automatic recharges.
card
- brandstringrequired
  Card brand (visa, mastercard…) or another saved method (link, sepa_debit).
- last4string
- expMonthinteger
  max 9,007,199,254,740,991
- expYearinteger
  max 9,007,199,254,740,991
autoRechargeobject
autoRecharge
- enabledbooleanrequired
- thresholdintegerrequired
  Recharge when the balance falls below this, in cents.
  max 9,007,199,254,740,991
- amountintegerrequired
  What each recharge adds, in cents.
  max 9,007,199,254,740,991
- monthlyLimitintegerrequired
  Most that automatic recharges add in a calendar month, in cents.
  max 9,007,199,254,740,991
autoRechargeErrorobject
Why the last automatic recharge failed; it switched itself off.
autoRechargeError
- atstring (date-time)required
- messagestringrequired
autoRechargedThisMonthintegerrequired
Added by automatic recharges this calendar month, in cents.
max 9,007,199,254,740,991
topUpobjectrequired
Allowed top-up amounts, in cents.
topUp
- minintegerrequired
  max 9,007,199,254,740,991
- maxintegerrequired
  max 9,007,199,254,740,991
hasPortalbooleanrequired
Whether the billing portal (invoices, payment method) is available.

curl "https://api.usecrier.com/v1/billing" \
  -H "Authorization: Bearer $CRIER_API_KEY"

const res = await fetch('https://api.usecrier.com/v1/billing', {
  headers: {
    Authorization: `Bearer ${process.env.CRIER_API_KEY}`,
  },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.usecrier.com/v1/billing",
    headers={"Authorization": f"Bearer {os.environ['CRIER_API_KEY']}"},
)
data = res.json()["data"]

List balance movements

GET/v1/billing/movements

Top-ups and charges, newest first.

Parameters

limitinteger
max 200

Response 200

data []

idstringrequired
kindstringrequired
Values: top_up · auto_recharge · accounts · usage · adjustment
amountnumberrequired
Cents (up to three decimals): positive adds, negative debits.
atstring (date-time)required
daystring
UTC day (YYYY-MM-DD) a charge covers.
accountsinteger
Accounts a day was charged for.
max 9,007,199,254,740,991
familystring
Usage family of a usage charge.
Values: xApi · messages

curl "https://api.usecrier.com/v1/billing/movements" \
  -H "Authorization: Bearer $CRIER_API_KEY"

const res = await fetch('https://api.usecrier.com/v1/billing/movements', {
  headers: {
    Authorization: `Bearer ${process.env.CRIER_API_KEY}`,
  },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.usecrier.com/v1/billing/movements",
    headers={"Authorization": f"Bearer {os.environ['CRIER_API_KEY']}"},
)
data = res.json()["data"]

Top up the balance

POST/v1/billing/top-upDashboard only

Opens a payment page. The balance grows once the payment succeeds; the card is saved for automatic recharges.

Body

amountintegerrequired
Balance to add, in cents (taxes, if any, on top). Limits come with GET /v1/billing.
max 9,007,199,254,740,991
successUrlstring (uri)required
Dashboard page to come back to after paying.
cancelUrlstring (uri)required
Dashboard page to come back to if the user leaves Checkout.

Response 200

data

urlstring (uri)required
Send the user here.

curl -X POST "https://api.usecrier.com/v1/billing/top-up" \
  -H "Authorization: Bearer $CRIER_API_KEY"

const res = await fetch('https://api.usecrier.com/v1/billing/top-up', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CRIER_API_KEY}`,
  },
});
const { data } = await res.json();

import os, requests

res = requests.post(
    "https://api.usecrier.com/v1/billing/top-up",
    headers={"Authorization": f"Bearer {os.environ['CRIER_API_KEY']}"},
)
data = res.json()["data"]

Set automatic recharges

PUT/v1/billing/auto-rechargeDashboard only

Tops up the saved card when the balance falls below the threshold, up to a monthly limit. Needs one top-up first.

Body

enabledbooleanrequired
thresholdintegerrequired
Recharge when the balance falls below this, in cents.
max 9,007,199,254,740,991
amountintegerrequired
What each recharge adds, in cents.
max 9,007,199,254,740,991
monthlyLimitintegerrequired
Most that automatic recharges may add in a calendar month, in cents.
max 9,007,199,254,740,991

Response 200

data

enabledbooleanrequired
False while billing is not available: nothing is charged or limited.
balancenumberrequired
Prepaid balance in cents (up to three decimals). Negative when charges outran it.
currencystringrequired
connectedAccountsintegerrequired
max 9,007,199,254,740,991
freeAccountsintegerrequired
max 9,007,199,254,740,991
monthlyEstimateintegerrequired
Monthly price of the accounts connected now, in cents. It is charged day by day.
max 9,007,199,254,740,991
dailyEstimatenumberrequired
What those accounts cost today, in cents (up to three decimals).
daysLeftinteger | nullrequired
Whole days the balance covers at that cost; null when nothing is charged daily.
linesobject[]required
lines
- fromintegerrequired
  max 9,007,199,254,740,991
- tointeger | nullrequired
- accountsintegerrequired
  max 9,007,199,254,740,991
- unitAmountintegerrequired
  Cents per account and month.
  max 9,007,199,254,740,991
- amountintegerrequired
  max 9,007,199,254,740,991
canConnectMorebooleanrequired
Whether one more account can be connected right now.
blockedbooleanrequired
The balance is used up: accounts beyond the free ones, and X accounts, cannot publish or send until it is topped up.
cardobject
The saved payment method, for automatic recharges.
card
- brandstringrequired
  Card brand (visa, mastercard…) or another saved method (link, sepa_debit).
- last4string
- expMonthinteger
  max 9,007,199,254,740,991
- expYearinteger
  max 9,007,199,254,740,991
autoRechargeobject
autoRecharge
- enabledbooleanrequired
- thresholdintegerrequired
  Recharge when the balance falls below this, in cents.
  max 9,007,199,254,740,991
- amountintegerrequired
  What each recharge adds, in cents.
  max 9,007,199,254,740,991
- monthlyLimitintegerrequired
  Most that automatic recharges add in a calendar month, in cents.
  max 9,007,199,254,740,991
autoRechargeErrorobject
Why the last automatic recharge failed; it switched itself off.
autoRechargeError
- atstring (date-time)required
- messagestringrequired
autoRechargedThisMonthintegerrequired
Added by automatic recharges this calendar month, in cents.
max 9,007,199,254,740,991
topUpobjectrequired
Allowed top-up amounts, in cents.
topUp
- minintegerrequired
  max 9,007,199,254,740,991
- maxintegerrequired
  max 9,007,199,254,740,991
hasPortalbooleanrequired
Whether the billing portal (invoices, payment method) is available.

curl -X PUT "https://api.usecrier.com/v1/billing/auto-recharge" \
  -H "Authorization: Bearer $CRIER_API_KEY"

const res = await fetch('https://api.usecrier.com/v1/billing/auto-recharge', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.CRIER_API_KEY}`,
  },
});
const { data } = await res.json();

import os, requests

res = requests.put(
    "https://api.usecrier.com/v1/billing/auto-recharge",
    headers={"Authorization": f"Bearer {os.environ['CRIER_API_KEY']}"},
)
data = res.json()["data"]

Open the billing portal

POST/v1/billing/portalDashboard only

Invoices and the saved payment method.

Body

returnUrlstring (uri)required
Dashboard page to come back to.

Response 200

data

urlstring (uri)required
Send the user here.

curl -X POST "https://api.usecrier.com/v1/billing/portal" \
  -H "Authorization: Bearer $CRIER_API_KEY"

const res = await fetch('https://api.usecrier.com/v1/billing/portal', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CRIER_API_KEY}`,
  },
});
const { data } = await res.json();

import os, requests

res = requests.post(
    "https://api.usecrier.com/v1/billing/portal",
    headers={"Authorization": f"Bearer {os.environ['CRIER_API_KEY']}"},
)
data = res.json()["data"]