> ## Documentation Index > Fetch the complete documentation index at: https://docs.meteroid.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a top-up > Sells credit: CHARGE bills a saved payment method now, SEND_INVOICE grants it once paid. The credit is PAID and applies to ALL charges. Currency credit is sold one for one, untaxed, as its usage is taxed when invoiced. With `credit_unit`, sells credits of that unit at its selling price in the customer's currency, taxed at purchase under the unit's product; refused when the unit has no price in that currency or no product. Without a saved payment method, CHARGE returns a hosted `checkout_url` where the customer pays. ## OpenAPI ````yaml https://api.meteroid.com/api-docs/openapi.json post /api/v1/customers/{id_or_alias}/top-ups openapi: 3.1.0 info: title: meteroid description: '' license: name: LicenseRef-Proprietary identifier: LicenseRef-Proprietary version: 0.1.0 servers: [] security: [] tags: - name: Meteroid description: Meteroid API - name: Add-ons - name: Batch Jobs - name: Budgets description: >- Beta: may change before general availability. Spending limits on a customer's usage, or one subscription's, per currency, with alerts at percentages of the amount. x-beta: true - name: Checkout Sessions - name: Checks description: >- Beta: may change before general availability. Whether a customer may consume more of a feature right now. x-beta: true - name: Connect description: Manage connected accounts (Express & Standard) - name: Coupons - name: Credit Notes - name: Credit units description: >- Custom denominations, such as "credits", that usage can be priced in and credit granted or sold in, instead of money. - name: Credits description: >- Prepaid credit: a customer's wallets, credit grants, ledger and top-ups. Promotional credit applies before tax like a discount; paid credit applies after tax like a payment. - name: Custom Properties - name: Customers - name: Entitlements - name: Events - name: Features - name: Invoices - name: Licenses description: >- Licenses for your customers' self-hosted installations: signed tokens carrying their plan's entitlements, activated and refreshed by the installation over the public licensing endpoints. - name: Metrics - name: OAuth description: OAuth 2.0 token endpoints (public, client-credentials auth) - name: OAuth Apps description: Manage OAuth applications for Connect integrations - name: Plans - name: Product Families - name: Products - name: Subscriptions - name: Usage - name: Usage costs description: >- Beta: may change before general availability. A customer's or a subscription's usage events and usage over time, with what they cost. x-beta: true - name: Webhook Endpoints description: Manage outbound webhook endpoints and inspect their deliveries paths: /api/v1/customers/{id_or_alias}/top-ups: post: tags: - Credits summary: Create a top-up description: >- Sells credit: CHARGE bills a saved payment method now, SEND_INVOICE grants it once paid. The credit is PAID and applies to ALL charges. Currency credit is sold one for one, untaxed, as its usage is taxed when invoiced. With `credit_unit`, sells credits of that unit at its selling price in the customer's currency, taxed at purchase under the unit's product; refused when the unit has no price in that currency or no product. Without a saved payment method, CHARGE returns a hosted `checkout_url` where the customer pays. operationId: create_top_up parameters: - name: id_or_alias in: path description: Customer ID or alias required: true schema: type: string - name: Idempotency-Key in: header description: Required; reuse it only to retry the same request required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateTopUpRequest' required: true responses: '201': description: Top-up paid, settling, or awaiting the customer content: application/json: schema: $ref: '#/components/schemas/TopUpResponse' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '404': description: Customer or payment method not found content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '409': description: >- Idempotency-Key reused with another request or the charge was declined content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '429': description: Too many top-ups for this customer in a rolling day content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '500': description: Internal error content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' security: - bearer_auth: [] components: schemas: CreateTopUpRequest: type: object description: Credit sold to the customer, charged or invoiced. required: - amount properties: amount: type: integer format: int64 description: >- Credit to buy, positive, applying to ALL charges. In minor units of `currency`, charged one for one without tax: the usage it pays is taxed on the invoice that bills it. With `credit_unit`, in minor units of that unit (e.g. 500000 is 5,000.00 credits of a unit with precision 2), charged at the unit's price per credit in the customer's currency, plus tax under the unit's product. collection: $ref: '#/components/schemas/TopUpCollection' description: >- CHARGE (default) charges a saved payment method now; SEND_INVOICE issues an invoice and grants the credit once it is paid. credit_unit: type: - string - 'null' description: >- Buy credits of this credit unit (its code) instead of money; excludes `currency`. They are charged in the customer's currency at the customer's agreed price for the unit (the wallet's `unit_price`), else its list price, plus tax, under the unit's product. currency: oneOf: - $ref: '#/components/schemas/Currency' description: >- Defaults to the customer's currency. SEND_INVOICE sells only in the customer's currency. - type: 'null' expires_at: type: - string - 'null' format: date-time description: Absolute expiry of the purchased credit; unset never expires. payment_method_id: type: - string - 'null' description: CHARGE only; defaults to the customer's default payment method. unit_price: type: - string - 'null' description: >- With `credit_unit`: the negotiated price of one credit for this purchase, in major units of the customer's currency, as a decimal string (e.g. "0.0008"). Defaults to the wallet's `unit_price` when set, else the list price; the unit must still have a list price in that currency. additionalProperties: false TopUpResponse: type: object description: >- Where a top-up stands. Its credit is granted once it is paid; `wallet.funded` reports it. required: - status - amount - currency properties: amount: type: integer format: int64 description: >- Credit bought, in minor units of `currency`, or of `credit_unit` when set. charged_amount: type: - integer - 'null' format: int64 description: >- Charged to the payment method, tax included, in minor units of `currency`; absent until a charge is made. checkout_url: type: - string - 'null' description: >- Hosted page where the customer completes the payment; present while it awaits them. credit_unit: type: - string - 'null' description: >- Set when credits of this credit unit were bought: `amount` is in its minor units. currency: $ref: '#/components/schemas/Currency' description: The money the top-up is charged in. invoice_id: type: - string - 'null' description: The invoice documenting the purchase. payment_transaction_id: type: - string - 'null' description: >- The charge made on the payment method; absent until a charge is made. status: $ref: '#/components/schemas/TopUpStatus' description: SUCCEEDED once paid; otherwise what the payment is waiting for. RestErrorResponse: type: object required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string TopUpCollection: type: string description: >- How a top-up is paid: CHARGE a saved payment method now, or SEND_INVOICE and grant the credit once the invoice is paid. enum: - CHARGE - SEND_INVOICE Currency: type: string enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BRL - BSD - BTN - BWP - BYN - BZD - CAD - CDF - CHF - CLP - CNH - CNY - COP - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRU - MUR - MVR - MWK - MXN - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - UYU - UZS - VES - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW - ZWL examples: - EUR TopUpStatus: type: string enum: - SUCCEEDED - PENDING - REQUIRES_CUSTOMER_ACTION - AWAITING_PAYMENT ErrorCode: type: string enum: - BAD_REQUEST - NOT_FOUND - CONFLICT - FORBIDDEN - UNAUTHORIZED - TOKEN_EXPIRED - TOO_MANY_REQUESTS - INTERNAL_SERVER_ERROR securitySchemes: bearer_auth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.