Skip to content
Salvo

Examples use fictional data. Every company, person, address and count in them is invented, and their domains use the reserved .example TLD.

Platform

Billing

Balances, the ledger behind them, and the two ways to add money. Every amount is an integer number of cents.

5 endpoints

GET/v1/billing/summary

Balances and period usage

Both balances, the current plan and what has been consumed since the period started. One call for a billing widget.

API key or sessionFree
curl "https://beamro.com/api/v1/billing/summary" \
  -H "x-api-key: $SALVO_API_KEY"
200 response
{
  "org": {
    "id": "org_4k1p8w2ne6ts0ybc7j",
    "name": "Harlow Meadow Events",
    "slug": "harlow-meadow-events",
    "plan": "growth",
    "credit_balance": 38420,
    "email_balance_cents": 4180,
    "trial_granted": true,
    "created_at": "2026-08-31T11:04:02.000Z"
  },
  "wallet_cents": 4180,
  "credit_balance": 38420,
  "plan": "growth",
  "usage": {
    "emails_sent": 1438,
    "credits_used": 11580,
    "period_start": "2026-08-01T00:00:00.000Z"
  }
}
GET/v1/billing/ledger

Read the ledger

Every movement in credits, newest first, with the balance after each one. This is the audit trail behind the summary.

API key or sessionFree

Query parameters

FieldTypeDescription
limitnumberRows to return. Default 25, maximum 100.
offsetnumberRows to skip.
curl "https://beamro.com/api/v1/billing/ledger?limit=25" \
  -H "x-api-key: $SALVO_API_KEY"
200 response
{
  "rows": [
    {
      "id": "led_ent_9x2k4v7m1q0b6t3n8w",
      "org_id": "org_4k1p8w2ne6ts0ybc7j",
      "delta": -250,
      "balance_after": 38420,
      "kind": "search",
      "ref_type": "search",
      "ref_id": "sch_5v8p2q0w7m1x4h6t9c",
      "note": "250 person rows",
      "created_at": "2026-08-31T09:41:12.000Z"
    },
    {
      "id": "led_ent_4b8n1k6v0m2q7x3t9w",
      "org_id": "org_4k1p8w2ne6ts0ybc7j",
      "delta": 40000,
      "balance_after": 38670,
      "kind": "subscription",
      "ref_type": "plan",
      "ref_id": "growth",
      "note": "Growth plan renewal",
      "created_at": "2026-08-01T00:00:04.000Z"
    }
  ],
  "total": 412,
  "limit": 25,
  "offset": 0
}
POST/v1/billing/topup

Top up the sending wallet

Returns a hosted checkout URL when a payment provider is configured. When it is not — a self-hosted instance, or a test run — the balance moves directly and checkout_url is null.

API key or sessionFree

Body parameters

FieldTypeDescription
amount_centsreqnumberAmount to add, in cents. Minimum 1000.
curl -X POST "https://beamro.com/api/v1/billing/topup" \
  -H "x-api-key: $SALVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "amount_cents": 5000
  }'
200 response
{
  "checkout_url": "https://checkout.example/session/cs_live_7m2k9v",
  "balance_cents": 4180
}
POST/v1/billing/subscribe

Change plan

Moves the workspace onto a plan and grants its credits. Downgrades take effect at the end of the current period.

API key or sessionFree

Body parameters

FieldTypeDescription
planreqstringfree, starter, growth, pro or enterprise.
curl -X POST "https://beamro.com/api/v1/billing/subscribe" \
  -H "x-api-key: $SALVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "plan": "growth"
  }'
200 response
{
  "checkout_url": "https://checkout.example/session/cs_live_1n8b4k",
  "plan": "growth"
}
GET/v1/billing/invoices

List invoices

Issued invoices with a hosted link to the PDF where the provider supplies one.

API key or sessionFree
curl "https://beamro.com/api/v1/billing/invoices" \
  -H "x-api-key: $SALVO_API_KEY"
200 response
{
  "rows": [
    {
      "id": "inv_2k7v0m4x9n1q6b3t8w",
      "amount_cents": 32900,
      "status": "paid",
      "created_at": "2026-08-01T00:00:04.000Z",
      "hosted_url": "https://billing.example/invoice/inv_2k7v0m"
    },
    {
      "id": "inv_9b3n6k1v4m0q2x7t5w",
      "amount_cents": 5000,
      "status": "paid",
      "created_at": "2026-08-14T15:22:31.000Z",
      "hosted_url": "https://billing.example/invoice/inv_9b3n6k"
    }
  ]
}