---
title: "Create on-demand top-up invoice"
method: POST
path: "/api/v1/billing/drawdown/topup"
tags: ["Billing"]
---

# Create on-demand top-up invoice

`POST /api/v1/billing/drawdown/topup`

Request an on-demand top-up invoice..
Requires drawdown billing to be enabled. Only one unpaid top-up invoice
is allowed at a time.

## Request body

- CreateTopUpParams
  - `chargeAutomatically` boolean — Override whether to automatically charge the invoice. Defaults to the developer's drawdown config value if not specified.
  - `amountSubunits` integer, required — Amount in smallest currency unit (e.g. cents).

## Response `201`

Created

- Invoice
  - `bankTransferDetails` BankTransferDetails, required — Vendor-agnostic bank transfer details for push-based payment
    - `routingNumber` string, required
    - `accountNumber` string, required
    - `bankName` string, required
    - `accountHolderName` string, required
  - `url` string, nullable, required
  - `amount` Money, required
    - `currencyCode` string, required
    - `amountSubunits` integer, required
  - `status` 'draft' | 'open' | 'paid' | 'uncollectible' | 'void' | 'unknown', required
  - `id` string, required

## Other responses

- `400`
- `401` — Authentication Failed
- `409`
- `422` — Validation Error
- `503`

## Changes

- **2026-06-08** `0b28c67737d3` — 1 info
  - the security scope `billing:write` was added to the endpoint's security scheme `bearerAuth`

[Change history](https://skmtc.dev/rye-com/apis/universal-checkout-api/changes/api/v1/billing/drawdown/topup/post.md)

---

[API](https://skmtc.dev/rye-com/apis/universal-checkout-api.md) · [All operations](https://skmtc.dev/rye-com/apis/universal-checkout-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/rye-com/universal-checkout-api/revisions/175c7f9e090e/schema)