---
title: "Top up wallet"
method: POST
path: "/wallets/{id}/top-up"
tags: ["Wallets"]
---

# Top up wallet

`POST /wallets/{id}/top-up`

Use when adding funds to a wallet (e.g. top-up, refund, or manual credit). Supports optional idempotency via reference.

## Path parameters

- `id` string, required

## Request body

- TopUpWalletRequest
  - `amount` string — amount is the amount in the currency of the wallet to be added NOTE: this is not the number of credits to add, but the amount in the currency amount = credits_to_add * conversion_rate if both amount and credits_to_add are provided, amount will be ignored ex if the wallet has a conversion_rate of 2 then adding an amount of 10 USD in the wallet wil add 5 credits in the wallet
  - `credits_to_add` string — credits_to_add is the number of credits to add to the wallet
  - `description` string — description to add any specific details about the transaction
  - `expiry_date_utc` string — expiry_date_utc is the expiry date in UTC timezone ex 2025-01-01 00:00:00 UTC
  - `idempotency_key` string — idempotency_key is a unique key for the transaction
  - `metadata` TypesMetadata
  - `priority` integer — priority is the priority of the transaction lower number means higher priority default is nil which means no priority at all
  - `transaction_reason` 'INVOICE_PAYMENT' | 'FREE_CREDIT_GRANT' | 'SUBSCRIPTION_CREDIT_GRANT' | 'PURCHASED_CREDIT_INVOICED' | 'PURCHASED_CREDIT_DIRECT' | 'CREDIT_NOTE' | 'CREDIT_EXPIRED' | 'WALLET_TERMINATION' | 'MANUAL_BALANCE_DEBIT' | 'CREDIT_ADJUSTMENT' | 'INVOICE_VOID_REFUND', required

## Response `200`

OK

- TopUpWalletResponse
  - `invoice_id` string — Invoice ID if an invoice was created (only for PURCHASED_CREDIT_INVOICED)
  - `wallet` WalletResponse
    - `alert_settings` TypesAlertSettings
      - `alert_enabled` boolean
      - `critical` TypesAlertThreshold
        - `condition` 'above' | 'below'
        - `threshold` number
      - `info` TypesAlertThreshold
        - `condition` 'above' | 'below'
        - `threshold` number
      - `warning` TypesAlertThreshold
        - `condition` 'above' | 'below'
        - `threshold` number
    - `alert_state` 'ok' | 'info' | 'warning' | 'in_alarm'
    - `auto_topup` TypesAutoTopup
      - `amount` number
      - `enabled` boolean
      - `invoicing` boolean
      - `threshold` number
    - `balance` string
    - `config` TypesWalletConfig
      - `allowed_price_types` TypesWalletConfigPriceType[] — AllowedPriceTypes is a list of price types that are allowed for the wallet nil means all price types are allowed
    - `conversion_rate` string — amount in the currency = number of credits * conversion_rate ex if conversion_rate is 1, then 1 USD = 1 credit ex if conversion_rate is 2, then 1 USD = 0.5 credits ex if conversion_rate is 0.5, then 1 USD = 2 credits
    - `created_at` string, date-time
    - `created_by` string
    - `credit_balance` string
    - `credits_available_breakdown` TypesCreditBreakdown
      - `free` string
      - `purchased` string
    - `currency` string
    - `customer_id` string
    - `description` string
    - `environment_id` string
    - `id` string
    - `metadata` TypesMetadata
    - `name` string
    - `status` 'published' | 'deleted' | 'archived'
    - `tenant_id` string
    - `topup_conversion_rate` string — topup_conversion_rate is the conversion rate for the topup to the currency ex if topup_conversion_rate is 1, then 1 USD = 1 credit ex if topup_conversion_rate is 2, then 1 USD = 0.5 credits ex if topup_conversion_rate is 0.5, then 1 USD = 2 credits
    - `updated_at` string, date-time
    - `updated_by` string
    - `wallet_status` 'active' | 'frozen' | 'closed'
    - `wallet_type` 'PRE_PAID' | 'POST_PAID'
  - `wallet_transaction` WalletTransactionResponse
    - `amount` string
    - `conversion_rate` string — conversion_rate is the conversion rate for the transaction to the currency
    - `created_at` string, date-time
    - `created_by` string
    - `created_by_user` UserResponse
      - `email` string — Empty for service accounts
      - `id` string
      - `metadata` object
      - `roles` string[]
      - `tenant` TenantResponse
        - `billing_details` TenantBillingDetails
          - `address` Address
            - `address_city` string
            - `address_country` string
            - `address_line1` string
            - `address_line2` string
            - `address_postal_code` string
            - `address_state` string
          - `email` string
          - `help_email` string
          - `phone` string
        - `created_at` string, date-time
        - `id` string
        - `metadata` TypesMetadata
        - `name` string
        - `status` string
        - `updated_at` string, date-time
      - `type` 'user' | 'service_account'
    - `credit_amount` string
    - `credit_balance_after` string
    - `credit_balance_before` string
    - `credits_available` string
    - `currency` string
    - `customer` CustomerResponse — Customer response object containing all customer information
      - `address_city` string — AddressCity is the city of the customer's address
      - `address_country` string — AddressCountry is the country of the customer's address (ISO 3166-1 alpha-2)
      - `address_line1` string — AddressLine1 is the first line of the customer's address
      - `address_line2` string — AddressLine2 is the second line of the customer's address
      - `address_postal_code` string — AddressPostalCode is the postal code of the customer's address
      - `address_state` string — AddressState is the state of the customer's address
      - `created_at` string, date-time
      - `created_by` string
      - `email` string — Email is the email of the customer
      - `environment_id` string — EnvironmentID is the environment identifier for the customer
      - `external_id` string — ExternalID is the external identifier for the customer
      - `id` string — ID is the unique identifier for the customer
      - `integrations` EntityIntegrationMappingResponse[]
        - `created_at` string, date-time
        - `created_by` string
        - `entity_id` string
        - `entity_type` 'customer' | 'plan' | 'invoice' | 'subscription' | 'payment' | 'credit_note' | 'addon' | 'item' | 'item_price' | 'price'
        - `environment_id` string
        - `id` string
        - `metadata` object
        - `provider_entity_id` string
        - `provider_type` string
        - `status` 'published' | 'deleted' | 'archived'
        - `tenant_id` string
        - `updated_at` string, date-time
        - `updated_by` string
      - `metadata` object — Metadata
      - `name` string — Name is the name of the customer
      - `status` 'published' | 'deleted' | 'archived'
      - `tenant_id` string
      - `updated_at` string, date-time
      - `updated_by` string
    - `customer_id` string
    - `description` string
    - `environment_id` string
    - `expiry_date` string, date-time
    - `id` string
    - `idempotency_key` string
    - `metadata` TypesMetadata
    - `priority` integer
    - `reference_id` string
    - `reference_type` 'PAYMENT' | 'EXTERNAL' | 'REQUEST' | 'INVOICE'
    - `status` 'published' | 'deleted' | 'archived'
    - `tenant_id` string
    - `topup_conversion_rate` string — topup_conversion_rate is the conversion rate for the topup to the currency
    - `transaction_reason` 'INVOICE_PAYMENT' | 'FREE_CREDIT_GRANT' | 'SUBSCRIPTION_CREDIT_GRANT' | 'PURCHASED_CREDIT_INVOICED' | 'PURCHASED_CREDIT_DIRECT' | 'CREDIT_NOTE' | 'CREDIT_EXPIRED' | 'WALLET_TERMINATION' | 'MANUAL_BALANCE_DEBIT' | 'CREDIT_ADJUSTMENT' | 'INVOICE_VOID_REFUND'
    - `transaction_status` 'pending' | 'completed' | 'failed'
    - `type` 'credit' | 'debit'
    - `updated_at` string, date-time
    - `updated_by` string
    - `wallet` WalletResponse
      - `alert_settings` TypesAlertSettings
        - `alert_enabled` boolean
        - `critical` TypesAlertThreshold
          - `condition` 'above' | 'below'
          - `threshold` number
        - `info` TypesAlertThreshold
          - `condition` 'above' | 'below'
          - `threshold` number
        - `warning` TypesAlertThreshold
          - `condition` 'above' | 'below'
          - `threshold` number
      - `alert_state` 'ok' | 'info' | 'warning' | 'in_alarm'
      - `auto_topup` TypesAutoTopup
        - `amount` number
        - `enabled` boolean
        - `invoicing` boolean
        - `threshold` number
      - `balance` string
      - `config` TypesWalletConfig
        - `allowed_price_types` TypesWalletConfigPriceType[] — AllowedPriceTypes is a list of price types that are allowed for the wallet nil means all price types are allowed
      - `conversion_rate` string — amount in the currency = number of credits * conversion_rate ex if conversion_rate is 1, then 1 USD = 1 credit ex if conversion_rate is 2, then 1 USD = 0.5 credits ex if conversion_rate is 0.5, then 1 USD = 2 credits
      - `created_at` string, date-time
      - `created_by` string
      - `credit_balance` string
      - `credits_available_breakdown` TypesCreditBreakdown
        - `free` string
        - `purchased` string
      - `currency` string
      - `customer_id` string
      - `description` string
      - `environment_id` string
      - `id` string
      - `metadata` TypesMetadata
      - `name` string
      - `status` 'published' | 'deleted' | 'archived'
      - `tenant_id` string
      - `topup_conversion_rate` string — topup_conversion_rate is the conversion rate for the topup to the currency ex if topup_conversion_rate is 1, then 1 USD = 1 credit ex if topup_conversion_rate is 2, then 1 USD = 0.5 credits ex if topup_conversion_rate is 0.5, then 1 USD = 2 credits
      - `updated_at` string, date-time
      - `updated_by` string
      - `wallet_status` 'active' | 'frozen' | 'closed'
      - `wallet_type` 'PRE_PAID' | 'POST_PAID'
    - `wallet_id` string

## Other responses

- `400` — Invalid request
- `404` — Resource not found
- `500` — Server error

## Changes

- **2026-06-03** `7adf4f33ea1a` — 2 info
  - added the optional property `wallet_transaction/created_by_user/metadata` to the response with the `200` status
  - added the optional property `wallet_transaction/customer/integrations/items/metadata` to the response with the `200` status
- **2026-05-18** `8ec2edea6b20` — 6 warning
  - removed the optional property `details` from the response with the `400` status
  - removed the optional property `details` from the response with the `404` status
  - removed the optional property `details` from the response with the `500` status
  - added the new `too_many_requests` enum value to the `code` response property for the response status `400`
  - …2 more
- **2026-04-06** `95af41a12111` — 8 warning, 12 info
  - removed the optional property `error` from the response with the `400` status
  - removed the optional property `error` from the response with the `404` status
  - removed the optional property `error` from the response with the `500` status
  - removed the optional property `success` from the response with the `400` status
  - …16 more
- **2026-04-04** `3d452eb9ebcc` — 1 info
  - added the optional property `wallet_transaction/customer/integrations` to the response with the `200` status
- …earlier changes not shown

[Full history](https://skmtc.dev/flexprice/apis/flexprice-api/changes/wallets/:id/top-up/post.md)

---

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