> ## Documentation Index > Fetch the complete documentation index at: https://docs.withorb.com/llms.txt > Use this file to discover all available pages before exploring further. # Create top-up > 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. ## OpenAPI ````yaml /api-reference/orb-openapi.json post /customers/{customer_id}/credits/top_ups openapi: 3.1.0 info: title: API Reference description: >- Orb's API is built with the following principles in mind: 1. **Predictable developer experience**: Where applicable, the Orb API uses industry-standard patterns such as cursor-based pagination and standardized error output. To help with debugging in critical API actions, the API always strives to provide detailed and actionable error messages. Aliases such as external customer IDs aid in fast integration times. 2. **Reliably real time**: Orb's event-based APIs, such as event ingestion are designed to handle extremely high throughput and scale with concurrent load. Orb also provides a real-time event-level credits ledger and a highly performant webhooks architecture. 3. **Flexibility at the forefront**: Features like timezone localization and the ability to amend historical usage show the flexible nature of the platform. You can download the latest OpenAPI spec [here](https://api.withorb.com/spec.json) - pass `?version=3.0` for an OpenAPI 3.0-compatible spec. contact: name: Orb, Inc. url: https://www.withorb.com/ email: team@withorb.com version: '1.0' servers: - url: https://api.withorb.com/v1 description: Production server security: - APIKeyAuth: [] tags: - name: Alert description: >- [Alerts within Orb](/product-catalog/configuring-alerts) monitor spending, usage, or credit balance and trigger webhooks when a threshold is exceeded. Alerts created through the API can be scoped to either customers or subscriptions. - name: Availability - name: Coupon description: >- A coupon represents a reusable discount configuration that can be applied either as a fixed or percentage amount to an invoice or subscription. Coupons are activated using a redemption code, which applies the discount to a subscription or invoice. The duration of a coupon determines how long it remains available for use by end users. - name: Credit description: >- The [Credit Ledger Entry resource](/product-catalog/prepurchase) models prepaid credits within Orb. - name: Credit note description: >- The [Credit Note](/invoicing/credit-notes) resource represents a credit that has been applied to a particular invoice. - name: Customer description: >- A customer is a buyer of your products, and the other party to the billing relationship. In Orb, customers are assigned system generated identifiers automatically, but it's often desirable to have these match existing identifiers in your system. To avoid having to denormalize Orb ID information, you can pass in an `external_customer_id` with your own identifier. See [Customer ID Aliases](/events-and-metrics/customer-aliases) for further information about how these aliases work in Orb. In addition to having an identifier in your system, a customer may exist in a payment provider solution like Stripe. Use the `payment_provider_id` and the `payment_provider` enum field to express this mapping. A customer also has a timezone (from the standard [IANA timezone database](https://www.iana.org/time-zones)), which defaults to your account's timezone. See [Timezone localization](/essentials/timezones) for information on what this timezone parameter influences within Orb. - name: Dimensional Price Group - name: Event description: >- The [Event](/core-concepts#event) resource represents a usage event that has been created for a customer. Events are the core of Orb's usage-based billing model, and are used to calculate the usage charges for a given billing period. - name: Invoice description: >- An [`Invoice`](/core-concepts#invoice) is a fundamental billing entity, representing the request for payment for a single subscription. This includes a set of line items, which correspond to prices in the subscription's plan and can represent fixed recurring fees or usage-based fees. They are generated at the end of a billing period, or as the result of an action, such as a cancellation. - name: Item description: >- The Item resource represents a sellable product or good. Items are associated with all line items, billable metrics, and prices and are used for defining external sync behavior for invoices and tax calculation purposes. - name: License - name: LicenseType description: >- The LicenseType resource represents a type of license that can be assigned to users. License types are used during billing by grouping metrics on the configured grouping key. - name: Metric description: >- The Metric resource represents a calculation of a quantity based on events. Metrics are defined by the query that transforms raw usage events into meaningful values for your customers. - name: Plan description: >- The [Plan](/core-concepts#plan-and-price) resource represents a plan that can be subscribed to by a customer. Plans define the billing behavior of the subscription. You can see more about how to configure prices in the [Price resource](/reference/price). - name: Price description: >- The Price resource represents a price that can be billed on a subscription, resulting in a charge on an invoice in the form of an invoice line item. Prices take a quantity and determine an amount to bill. Orb supports a few different pricing models out of the box. Each of these models is serialized differently in a given Price object. The model_type field determines the key for the configuration object that is present. For more on the types of prices, see [the core concepts documentation](/core-concepts#plan-and-price) - name: Price interval description: >- The Price Interval resource represents a period of time for which a price will bill on a subscription. A subscription’s price intervals define its billing behavior. - name: Subscription description: >- A [subscription](/core-concepts#subscription) represents the purchase of a plan by a customer. By default, subscriptions begin on the day that they're created and renew automatically for each billing cycle at the cadence that's configured in the plan definition. Subscriptions also default to **beginning of month alignment**, which means the first invoice issued for the subscription will have pro-rated charges between the `start_date` and the first of the following month. Subsequent billing periods will always start and end on a month boundary (e.g. subsequent month starts for monthly billing). Depending on the plan configuration, any _flat_ recurring fees will be billed either at the beginning (in-advance) or end (in-arrears) of each billing cycle. Plans default to **in-advance billing**. Usage-based fees are billed in arrears as usage is accumulated. In the normal course of events, you can expect an invoice to contain usage-based charges for the previous period, and a recurring fee for the following period. - name: Subscription Change paths: /customers/{customer_id}/credits/top_ups: post: tags: - Credit summary: Create top-up description: >- 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. operationId: create-top-up parameters: - required: true style: simple schema: oneOf: - type: string - type: 'null' name: customer_id in: path requestBody: content: application/json: schema: $ref: '#/components/schemas/AddCreditTopUpRequestParams' required: true responses: '201': description: Created headers: {} content: application/json: schema: $ref: '#/components/schemas/TopUp' '400': description: Bad Request headers: {} content: application/json: schema: $ref: '#/components/schemas/400Error' '401': description: Unauthorized headers: {} content: application/json: schema: $ref: '#/components/schemas/401Error' '404': description: Not Found headers: {} content: application/json: schema: $ref: '#/components/schemas/404Error' '409': description: Conflict headers: {} content: application/json: schema: $ref: '#/components/schemas/409Error' '413': description: Content Too Large headers: {} content: application/json: schema: $ref: '#/components/schemas/413Error' '429': description: Too Many Requests headers: {} content: application/json: schema: $ref: '#/components/schemas/429Error' '500': description: Internal Server Error headers: {} content: application/json: schema: $ref: '#/components/schemas/500Error' components: schemas: AddCreditTopUpRequestParams: properties: currency: type: string title: Currency description: >- 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: type: string title: Threshold description: >- 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: type: string title: Amount description: The amount to increment when the threshold is reached. per_unit_cost_basis: type: string title: Per Unit Cost Basis description: How much, in the customer's currency, to charge for each unit. invoice_settings: $ref: '#/components/schemas/NewTopUpInvoiceSettings' description: Settings for invoices generated by triggered top-ups. expires_after: oneOf: - type: integer - type: 'null' title: Expires After description: >- The number of days or months after which the top-up expires. If unspecified, it does not expire. expires_after_unit: oneOf: - type: string enum: - day - month - type: 'null' title: Expires After Unit description: The unit of expires_after. active_from: oneOf: - type: string format: date-time - type: 'null' title: Active From description: >- 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. additionalProperties: false type: object required: - currency - threshold - amount - per_unit_cost_basis - invoice_settings title: AddCreditTopUpRequestParams TopUp: properties: id: type: string title: Id currency: type: string title: Currency description: >- 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: type: string title: Threshold description: >- 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: type: string title: Amount description: The amount to increment when the threshold is reached. per_unit_cost_basis: type: string title: Per Unit Cost Basis description: How much, in the customer's currency, to charge for each unit. invoice_settings: $ref: '#/components/schemas/TopUpInvoiceSettings' description: Settings for invoices generated by triggered top-ups. expires_after: oneOf: - type: integer - type: 'null' title: Expires After description: >- The number of days or months after which the top-up expires. If unspecified, it does not expire. expires_after_unit: oneOf: - type: string enum: - day - month - type: 'null' title: Expires After Unit description: The unit of expires_after. type: object required: - id - currency - threshold - amount - per_unit_cost_basis - invoice_settings title: TopUp 400Error: oneOf: - $ref: '#/components/schemas/ConstraintViolationError' - $ref: '#/components/schemas/DuplicateResourceCreationError' - $ref: '#/components/schemas/RequestValidationError' 401Error: $ref: '#/components/schemas/AuthorizationError' title: 401Error 404Error: oneOf: - $ref: '#/components/schemas/FeatureNotAvailableError' - $ref: '#/components/schemas/ResourceNotFoundError' - $ref: '#/components/schemas/URLNotFound' 409Error: $ref: '#/components/schemas/IdempotencyRequestMismatch' title: 409Error 413Error: oneOf: - $ref: '#/components/schemas/RequestTooLargeError' - $ref: '#/components/schemas/ResourceTooLargeError' - $ref: '#/components/schemas/TooManyResultsError' 429Error: $ref: '#/components/schemas/TooManyRequests' title: 429Error 500Error: $ref: '#/components/schemas/ServerError' title: 500Error NewTopUpInvoiceSettings: properties: auto_collection: type: boolean title: Auto Collection description: >- Whether the credits purchase invoice should auto collect with the customer's saved payment method. net_terms: type: integer title: Net Terms description: >- 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: oneOf: - type: string - type: 'null' title: Memo description: An optional memo to display on the invoice. require_successful_payment: type: boolean title: Require Successful Payment description: >- 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. default: false type: object required: - auto_collection - net_terms title: NewTopUpInvoiceSettings TopUpInvoiceSettings: properties: auto_collection: type: boolean title: Auto Collection description: >- Whether the credits purchase invoice should auto collect with the customer's saved payment method. net_terms: type: integer title: Net Terms description: >- 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: oneOf: - type: string - type: 'null' title: Memo description: An optional memo to display on the invoice. require_successful_payment: type: boolean title: Require Successful Payment description: >- 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. default: false type: object required: - auto_collection - net_terms title: TopUpInvoiceSettings ConstraintViolationError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#400-constraint-violation title: Type status: type: integer enum: - 400 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: ConstraintViolationError DuplicateResourceCreationError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#400-duplicate-resource-creation title: Type status: type: integer enum: - 400 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: DuplicateResourceCreationError RequestValidationError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#400-request-validation-errors title: Type status: type: integer enum: - 400 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title validation_errors: items: {} type: array title: Validation Errors type: object required: - type - status - validation_errors title: RequestValidationError AuthorizationError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#401-authentication-error title: Type status: type: integer enum: - 401 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: AuthorizationError FeatureNotAvailableError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#404-feature-not-available title: Type status: type: integer enum: - 400 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: FeatureNotAvailableError ResourceNotFoundError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#404-resource-not-found title: Type status: type: integer enum: - 404 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: type: string title: Title type: object required: - type - status - title title: ResourceNotFoundError URLNotFound: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#404-url-not-found title: Type status: type: integer enum: - 404 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: URLNotFound IdempotencyRequestMismatch: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#409-resource-conflict title: Type status: type: integer enum: - 409 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: IdempotencyRequestMismatch RequestTooLargeError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#413-request-too-large title: Type status: type: integer enum: - 413 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: RequestTooLargeError ResourceTooLargeError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#413-resource-too-large title: Type status: type: integer enum: - 413 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: ResourceTooLargeError TooManyResultsError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#413-too-many-results title: Type status: type: integer enum: - 413 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: TooManyResultsError TooManyRequests: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#429-too-many-requests title: Type status: type: integer enum: - 429 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: TooManyRequests ServerError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#500-internal-server-error title: Type status: type: integer title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: ServerError securitySchemes: APIKeyAuth: type: http description: API Keys can be issued in the Orb's web application. scheme: bearer ````