---
title: Top up your balance
description: Add dollars to your open.sume.com balance with your API key.
---
`POST` `/v1/open/top-ups`

**Host** `https://api.open.sume.com` · **Auth** your open.sume.com API key

Starts a top-up of the balance your key is billed to. It is the same top-up as **Add funds** on the Billing page: you get a Stripe Checkout link, the payment happens there, and the balance grows once it is paid. A team key tops up the team's balance.

Send an `Idempotency-Key`. A retry with the same key returns the same top-up and the same checkout link, so a dropped connection never leads to a second payment. Reusing a key for a different amount fails with `409 idempotency_conflict`.

## Request

### Headers

| Name | Required | Description |
|---|---|---|
| `Authorization` | Yes | `Bearer <your open.sume.com API key>` |
| `Idempotency-Key` | Recommended | Up to 255 characters. One key, one top-up. |

### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `amount_usd_cents` | integer | Yes | Dollars to add, in cents. `2000` is $20. From `500` ($5) to `1000000` ($10,000). |
| `success_url` | string | No | Where the payer lands after paying (https). Defaults to the Billing page. |
| `cancel_url` | string | No | Where the payer lands on cancel (https). Defaults to the Billing page. |

## Example

```bash
curl -X POST https://api.open.sume.com/v1/open/top-ups \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Idempotency-Key: topup-2026-10-16-001" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd_cents": 2000}'
```

Open `checkout_url` in a browser and pay. Then poll [Get a top-up](/docs/reference/billing/get-top-up) until `status` is `paid`.

## Response

`201 Created`, or `200 OK` for a retry with the same `Idempotency-Key`.

```json
{
  "data": {
    "id": "owc_5f2c9a1e0b7d4c3a8e6f1d2b4a9c7e01",
    "object": "open_top_up",
    "status": "pending",
    "amount_usd_cents": 2000,
    "currency": "USD",
    "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_…",
    "expires_at": "2026-10-17T02:15:00.000Z",
    "created_at": "2026-10-16T02:15:00.000Z",
    "paid_at": null
  }
}
```

| `status` | Meaning |
|---|---|
| `pending` | The checkout is open and not paid yet. |
| `paid` | Paid; the dollars are in your balance. |
| `failed` | The payment failed. Nothing was charged. |
| `expired` | The checkout closed unpaid. Start a new top-up with a new `Idempotency-Key`. |

## Errors

| Status | `code` | When |
|---|---|---|
| 400 | `invalid_amount` | The amount is under $5 or over $10,000, or not whole cents. |
| 400 | `invalid_request` | A return URL is not https, or the `Idempotency-Key` is not 1 to 255 printable characters. |
| 403 | `open_key_required` | The key is not an open.sume.com key. |
| 409 | `idempotency_conflict` | The `Idempotency-Key` was used for a different amount. |
| 502 | `stripe_error` | Stripe could not open the checkout. Retry with the same `Idempotency-Key`. |
| 503 | `stripe_not_configured` | Top-ups are not available in this environment. |

[All error codes](/docs/errors)

## Related

- [Get a top-up](/docs/reference/billing/get-top-up)
- [Billing](/docs/billing)
- [Idempotency](/docs/idempotency)