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.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Required; reuse it only to retry the same request
Path Parameters
Customer ID or alias
ISO 4217 currency code, or a credit unit code
Body
Partial update of a wallet's configuration: omit a field to leave it unchanged.
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.
Ascending, distinct, at most 5, non-negative. Omit to leave unchanged; an empty list clears every threshold.
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.
See Wallet.usage_at_zero. Omit to leave unchanged.
FOLLOW_PLAN, ALWAYS_PAUSE, NEVER_PAUSE Response
The wallet's configuration after the change
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.
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).
The part of credit_on_account that pays only usage charges.
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.
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.
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.
Credit granted that takes effect later.
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.
FOLLOW_PLAN, ALWAYS_PAUSE, NEVER_PAUSE 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.
Automatic top-up of the credit that applies to ALL charges; absent when never set.
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.
The credit unit (its code) the wallet holds; absent for a currency.
Decimal places of credit_unit: amounts are integers of 10^-precision credit.
x >= 0Absent for a credit unit wallet.
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 "EUR"
With subscription_id only: the part of balance that belongs to no subscription, which
the customer's other subscriptions can spend too.
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.
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.
The currency of unit_price: the customer's currency when it was set. Absent with it.
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 "EUR"