Wallets

Top up wallet

Changed on

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

post/wallets/{id}/top-up

Request

  • Base URL
    https://us.api.flexprice.io/v1
  • URL
    https://us.api.flexprice.io/v1/wallets/{id}/top-up
  • Auth
    API key in header x-api-key

Path parameters

idstring required

Wallet ID

Request body

amountstring

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

bonus_credits_expiry_date_utcstring

bonus_credits_expiry_date_utc is the expiry (UTC, full precision) applied to the bonus credits transaction. Independent of expiry_date_utc, which governs the purchase credits. Only honored when bonus credits are actually granted (explicit BonusCreditsToAdd or slab).

bonus_credits_to_addstring

bonus_credits_to_add is an explicit override for the bonus credits granted alongside this purchase. When nil/omitted, the bonus is resolved from the tenant's bonus_credits_topup_config slabs (if enabled). When set, it must be greater than 0 and is used as-is, skipping slab resolution. To grant no bonus, omit this field entirely.

credits_to_addstring

credits_to_add is the number of credits to add to the wallet

descriptionstring

description to add any specific details about the transaction

effective_datestring date-time

effective_date is stored as the credit transaction's created_at. Omit to use the current time. Must not be in the future.

expiry_date_utcstring

expiry_date_utc is the expiry date in UTC timezone ex 2025-01-01 00:00:00 UTC

force_sync_invoiceboolean
idempotency_keystring

idempotency_key is a unique key for the transaction

metadataTypesMetadata
priorityinteger

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' | 'PURCHASED_CREDIT_BONUS' required

Response

OK

invoice_idstring

Invoice ID if an invoice was created (only for PURCHASED_CREDIT_INVOICED)

Changes