---
title: "Create top-up"
method: POST
path: "/customers/{customer_id}/credits/top_ups"
tags: ["Credit"]
---

# Create top-up

`POST /customers/{customer_id}/credits/top_ups`

This endpoint allows you to create a new top-up for a specified customer's balance.
While this top-up is active, the customer's balance will added in increments of
the specified amount whenever the balance reaches the specified threshold.

If a top-up already exists for this customer in the same currency,
the existing top-up will be replaced.

## Path parameters

- `customer_id` string, nullable, required

## Request body

- AddCreditTopUpRequestParams
  - `currency` string, required — The currency or custom pricing unit to use for this top-up. If this is a real-world currency, it must match the customer's invoicing currency.
  - `threshold` string, required — The threshold at which to trigger the top-up. If the balance is at or below this threshold, the top-up will be triggered.
  - `amount` string, required — The amount to increment when the threshold is reached.
  - `per_unit_cost_basis` string, required — How much, in the customer's currency, to charge for each unit.
  - `invoice_settings` NewTopUpInvoiceSettings, required
    - `auto_collection` boolean, required — Whether the credits purchase invoice should auto collect with the customer's saved payment method.
    - `net_terms` integer, required — The net terms determines the difference between the invoice date and the issue date for the invoice. If you intend the invoice to be due on issue, set this to 0.
    - `memo` string, nullable — An optional memo to display on the invoice.
    - `require_successful_payment` boolean — When true, credit blocks created by this top-up will require that the corresponding invoice is paid before they are drawn down from. If any topup block is pending payment, further automatic top-ups will be paused until the invoice is paid or voided.
  - `expires_after` integer, nullable — The number of days or months after which the top-up expires. If unspecified, it does not expire.
  - `expires_after_unit` 'day' | 'month', nullable — The unit of expires_after.
  - `active_from` string, date-time, nullable — The date from which the top-up is active. If unspecified, the top-up is active immediately. This should not be more than 10 days in the past.

## Response `201`

Created

- TopUp
  - `id` string, required
  - `currency` string, required — The currency or custom pricing unit to use for this top-up. If this is a real-world currency, it must match the customer's invoicing currency.
  - `threshold` string, required — The threshold at which to trigger the top-up. If the balance is at or below this threshold, the top-up will be triggered.
  - `amount` string, required — The amount to increment when the threshold is reached.
  - `per_unit_cost_basis` string, required — How much, in the customer's currency, to charge for each unit.
  - `invoice_settings` TopUpInvoiceSettings, required
    - `auto_collection` boolean, required — Whether the credits purchase invoice should auto collect with the customer's saved payment method.
    - `net_terms` integer, required — The net terms determines the difference between the invoice date and the issue date for the invoice. If you intend the invoice to be due on issue, set this to 0.
    - `memo` string, nullable — An optional memo to display on the invoice.
    - `require_successful_payment` boolean — When true, credit blocks created by this top-up will require that the corresponding invoice is paid before they are drawn down from. If any topup block is pending payment, further automatic top-ups will be paused until the invoice is paid or voided.
  - `expires_after` integer, nullable — The number of days or months after which the top-up expires. If unspecified, it does not expire.
  - `expires_after_unit` 'day' | 'month', nullable — The unit of expires_after.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `404` — Not Found
- `409` — Conflict
- `413` — Content Too Large
- `429` — Too Many Requests
- `500` — Internal Server Error

---

[API](https://skmtc.dev/withorb/apis/api-reference.md) · [All operations](https://skmtc.dev/withorb/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/withorb/api-reference/revisions/816dfe734e2e/schema)