Skip to main content
PATCH
Configure a wallet

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key
string
required

Required; reuse it only to retry the same request

Path Parameters

id_or_alias
string
required

Customer ID or alias

currency
string
required

ISO 4217 currency code, or a credit unit code

Body

application/json

Partial update of a wallet's configuration: omit a field to leave it unchanged.

auto_top_up
object | null

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.

low_balance_thresholds
integer<int64>[] | null

Ascending, distinct, at most 5, non-negative. Omit to leave unchanged; an empty list clears every threshold.

unit_price
string | null

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
enum<string> | null

See Wallet.usage_at_zero. Omit to leave unchanged.

Available options:
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.

credit_on_account
integer<int64>
required

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
integer<int64>
required

The part of credit_on_account that pays only usage charges.

low_balance_thresholds
integer<int64>[]
required

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
boolean
required

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.

subscription_credit
object[]
required

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.

upcoming_credit
integer<int64>
required

Credit granted that takes effect later.

usage_at_zero
enum<string>
required

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.

Available options:
FOLLOW_PLAN,
ALWAYS_PAUSE,
NEVER_PAUSE
as_of
string<date-time> | null

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
object | null

Automatic top-up of the credit that applies to ALL charges; absent when never set.

balance
integer<int64> | null

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_unit
string | null

The credit unit (its code) the wallet holds; absent for a currency.

credit_unit_precision
integer<int32> | null

Decimal places of credit_unit: amounts are integers of 10^-precision credit.

Required range: x >= 0
currency
enum<string> | null

Absent for a credit unit wallet.

Available options:
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
Example:

"EUR"

shared_balance
integer<int64> | null

With subscription_id only: the part of balance that belongs to no subscription, which the customer's other subscriptions can spend too.

unbilled_usage
integer<int64> | null

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
string | null

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
enum<string> | null

The currency of unit_price: the customer's currency when it was set. Absent with it.

Available options:
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
Example:

"EUR"