> ## 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. # Configure a wallet > Settings of a customer's wallet in one currency or credit unit: whether usage is refused once its credit is used up, the balances that fire `wallet.balance_low`, and its automatic top-up. Opens the wallet if it does not exist yet. Partial update: omit a field to leave it unchanged. ## OpenAPI ````yaml https://api.meteroid.com/api-docs/openapi.json patch /api/v1/customers/{id_or_alias}/wallets/{currency} 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}/wallets/{currency}: patch: tags: - Credits summary: Configure a wallet description: >- Settings of a customer's wallet in one currency or credit unit: whether usage is refused once its credit is used up, the balances that fire `wallet.balance_low`, and its automatic top-up. Opens the wallet if it does not exist yet. Partial update: omit a field to leave it unchanged. operationId: patch_wallet parameters: - name: id_or_alias in: path description: Customer ID or alias required: true schema: type: string - name: currency in: path description: ISO 4217 currency code, or a credit unit code 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/PatchWalletRequest' required: true responses: '200': description: The wallet's configuration after the change content: application/json: schema: $ref: '#/components/schemas/Wallet' '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 content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '429': description: Too many requests 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: PatchWalletRequest: type: object description: >- Partial update of a wallet's configuration: omit a field to leave it unchanged. properties: auto_top_up: oneOf: - $ref: '#/components/schemas/AutoTopUpWriteRequest' description: >- Omit to leave the automatic top-up unchanged; `null` turns it off and removes its terms and the customer's confirmation; an object replaces the terms. Sending the stored terms unchanged changes nothing: a stopped rule stays stopped. Terms the customer confirmed in their portal and that this request changes stop until the customer confirms them again. Terms you created run as sent, and changing them lifts a stop caused by failed or reversed payments; otherwise such a stop lifts when the customer confirms the terms in their portal. Terms sent after a `null` are yours: an earlier confirmation does not carry over. Terms that turn automatic top-up on, or change what it charges, without the customer's confirmation need `customer_consent_attested`. - type: 'null' low_balance_thresholds: type: - array - 'null' items: type: integer format: int64 description: >- Ascending, distinct, at most 5, non-negative. Omit to leave unchanged; an empty list clears every threshold. unit_price: type: - string - 'null' description: >- Credit unit wallets: the price this customer agreed for one credit, in major units of the customer's currency, as a decimal string (positive, at most 12 decimal places). Purchases and automatic top-ups default to it instead of the list price. Omit to leave it unchanged; `null` returns the customer to the list price. A change applies to purchases quoted after it. An automatic top-up keeps running at the new price when it is at or below the price its terms were authorized at, and stops until they are confirmed again when it is above. usage_at_zero: oneOf: - $ref: '#/components/schemas/UsageAtZero' description: See `Wallet.usage_at_zero`. Omit to leave unchanged. - type: 'null' additionalProperties: false Wallet: type: object description: >- A customer's credit in one currency or credit unit. Amounts are minor units of it. Read with `subscription_id`, every amount counts only the credit that subscription can use. required: - credit_on_account - credit_on_account_usage_only - subscription_credit - upcoming_credit - low_balance_thresholds - usage_at_zero - pauses_at_zero properties: as_of: type: - string - 'null' format: date-time description: >- When `balance` and `unbilled_usage` were computed. They follow usage within a few seconds while the balance is near zero or a threshold, and within a minute otherwise. auto_top_up: oneOf: - $ref: '#/components/schemas/AutoTopUp' description: >- Automatic top-up of the credit that applies to ALL charges; absent when never set. - type: 'null' balance: type: - integer - 'null' format: int64 description: >- What the customer has left: `credit_on_account` minus the part of `unbilled_usage` that credit will pay. Never negative: usage beyond the credit stays in `unbilled_usage`, to be invoiced. Low-balance alerts use it; automatic top-ups watch only its part that pays any charge (credit that belongs to no subscription and is not limited to usage or products). Absent, with `unbilled_usage` and `as_of`, until the customer's usage has been priced once. With `subscription_id`: the credit that subscription can spend once every subscription's unbilled usage is paid, minus its own unbilled usage no credit pays (negative then), as `GET /wallets/check` reads it. Credit restricted to products it is not charged for is left out. Credit that belongs to no subscription counts in the balance of every subscription that can use it (see `shared_balance`): never add subscriptions' balances up. credit_on_account: type: integer format: int64 description: >- The ledger total: credit granted and effective, not yet applied to an invoice or expired, whatever it applies to. Usage not invoiced yet is not deducted (see `balance`). credit_on_account_usage_only: type: integer format: int64 description: The part of `credit_on_account` that pays only usage charges. credit_unit: type: - string - 'null' description: The credit unit (its code) the wallet holds; absent for a currency. credit_unit_precision: type: - integer - 'null' format: int32 description: >- Decimal places of `credit_unit`: amounts are integers of 10^-precision credit. minimum: 0 currency: oneOf: - $ref: '#/components/schemas/Currency' description: Absent for a credit unit wallet. - type: 'null' low_balance_thresholds: type: array items: type: integer format: int64 description: >- Ascending, distinct, at most 5. `wallet.balance_low` fires once when `balance` falls below one; a drop below several at once fires once, for the lowest. All credit counts, including credit that belongs to a subscription or is limited to usage or products, which `wallet.depleted` leaves out: a wallet can be depleted without an alert firing. pauses_at_zero: type: boolean description: >- Usage stops as soon as the credit is used up, for at least one active subscription: by `usage_at_zero`, or by the plan of a subscription charging usage in this wallet. shared_balance: type: - integer - 'null' format: int64 description: >- With `subscription_id` only: the part of `balance` that belongs to no subscription, which the customer's other subscriptions can spend too. subscription_credit: type: array items: $ref: '#/components/schemas/SubscriptionCredit' description: >- The part of `credit_on_account` that belongs to a subscription, which only that subscription's charges can use, per subscription. The rest pays any subscription. unbilled_usage: type: - integer - 'null' format: int64 description: >- Usage recorded and priced but not invoiced yet, tax included, in minor units: what the next invoices will charge for it, paid from credit as far as the credit goes. With `subscription_id`, that subscription's usage only; other subscriptions' usage paid from shared credit still lowers `balance`. unit_price: type: - string - 'null' description: >- Credit unit wallets: the price this customer agreed for one credit, in major units of `unit_price_currency`, as a decimal string (e.g. "0.0008"). Purchases and automatic top-ups in that currency charge it instead of the list price, unless a purchase sets its own `unit_price`. Absent: the list price applies. unit_price_currency: oneOf: - $ref: '#/components/schemas/Currency' description: >- The currency of `unit_price`: the customer's currency when it was set. Absent with it. - type: 'null' upcoming_credit: type: integer format: int64 description: Credit granted that takes effect later. usage_at_zero: $ref: '#/components/schemas/UsageAtZero' description: >- What this customer's usage does once the credit a subscription can use for it is used up (its own credit, credit that belongs to no subscription, and credit limited to the product: the `balance` of `GET /wallets/check`). `FOLLOW_PLAN` applies the "when credit runs out" rule of each subscription's plan. RestErrorResponse: type: object required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string AutoTopUpWriteRequest: type: object description: >- An automatic top-up's terms, replaced as a whole. FIXED needs `amount` and no `target`; TO_TARGET needs `target` above `threshold` and no `amount`; amounts are positive. required: - method - threshold properties: amount: type: - integer - 'null' format: int64 description: 'FIXED only: credit bought each time, in minor units of the wallet.' at_current_price: type: boolean description: >- Credit unit wallets: authorize today's price per credit for these terms, which lifts a stop caused by a price increase. When false (the default) the terms keep the price they were authorized at, and a rule stopped by a price increase stays stopped. A price at or below the authorized one never stops the rule: top-ups charge it. customer_consent_attested: type: boolean description: >- Attests that the customer agreed to automatic charges on these terms; recorded with the API key and the time. Required (true) when the terms turn automatic top-up on, including one the customer turned off, or change what it charges. Not needed to resend the stored terms unchanged, nor to change terms the customer confirmed in their portal: those stop until the customer confirms the new ones. daily_cap: type: - integer - 'null' format: int64 description: >- Most charged in a rolling day, tax included. For a credit unit wallet caps are money, in minor units of the customer's currency. maximum: type: - integer - 'null' format: int64 description: Largest single charge, in the same money as `minimum`. method: $ref: '#/components/schemas/AutoTopUpMethod' description: FIXED buys `amount` each time; TO_TARGET buys back up to `target`. minimum: type: - integer - 'null' format: int64 description: >- Smallest single charge. For a credit unit wallet it is money (the price before tax, in minor units of the customer's currency), like the caps; the threshold, amount and target are credits. monthly_cap: type: - integer - 'null' format: int64 description: Most charged in a calendar month (UTC), tax included. payment_method_id: type: - string - 'null' description: >- Defaults to the customer's default payment method: the customer's agreement, and your attestation of it, then cover whichever method is their default at each top-up. target: type: - integer - 'null' format: int64 description: >- TO_TARGET only: the balance a top-up brings the wallet back to; must exceed `threshold`. threshold: type: integer format: int64 description: >- Tops up once the balance is at or below this, in minor units of the wallet. additionalProperties: false UsageAtZero: type: string description: >- What a customer's usage does once the credit it can use runs out: what the subscription's plan says (`FOLLOW_PLAN`), or always or never refused for this customer. enum: - FOLLOW_PLAN - ALWAYS_PAUSE - NEVER_PAUSE AutoTopUp: type: object description: >- Automatic top-up of the credit that applies to ALL charges: it charges the customer's payment method when the balance falls below `threshold`. required: - status - method - threshold properties: amount: type: - integer - 'null' format: int64 description: 'FIXED only: credit bought each time, in minor units of the wallet.' customer_consent_attested_at: type: - string - 'null' format: date-time description: >- When an operator attested that the customer agreed to automatic charges on exactly these terms. Absent when the customer confirmed them in their portal, or the terms changed since. daily_cap: type: - integer - 'null' format: int64 description: >- Most charged in a rolling day, tax included. For a credit unit wallet caps are money, in minor units of the customer's currency. last_error: type: - string - 'null' description: Why the last charge failed; may carry payment provider detail. last_succeeded_at: type: - string - 'null' format: date-time description: The last charge that succeeded. maximum: type: - integer - 'null' format: int64 description: Largest single charge, in the same money as `minimum`. method: $ref: '#/components/schemas/AutoTopUpMethod' description: FIXED buys `amount` each time; TO_TARGET buys back up to `target`. minimum: type: - integer - 'null' format: int64 description: >- Smallest single charge. For a credit unit wallet it is money (the price before tax, in minor units of the customer's currency), like the caps; the threshold, amount and target are credits. monthly_cap: type: - integer - 'null' format: int64 description: Most charged in a calendar month (UTC), tax included. payment_method_id: type: - string - 'null' description: Absent charges the customer's default payment method. status: $ref: '#/components/schemas/AutoTopUpStatus' description: >- ACTIVE, DISABLED (terms kept) or SUSPENDED after repeated failed charges. suspended_at: type: - string - 'null' format: date-time description: 'Set while SUSPENDED: since when.' target: type: - integer - 'null' format: int64 description: >- TO_TARGET only: the balance a top-up brings the wallet back to, in minor units. threshold: type: integer format: int64 description: >- Tops up once the balance is at or below this, in minor units of the wallet. 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 SubscriptionCredit: type: object description: Credit on account that only one subscription can use. required: - subscription_id - credit_on_account properties: credit_on_account: type: integer format: int64 description: In minor units of the wallet. subscription_id: type: string ErrorCode: type: string enum: - BAD_REQUEST - NOT_FOUND - CONFLICT - FORBIDDEN - UNAUTHORIZED - TOKEN_EXPIRED - TOO_MANY_REQUESTS - INTERNAL_SERVER_ERROR AutoTopUpMethod: type: string enum: - FIXED - TO_TARGET AutoTopUpStatus: type: string enum: - ACTIVE - DISABLED - SUSPENDED securitySchemes: bearer_auth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.