Create a customer credit grant
Create a one-off cash credit grant held by a customer directly, outside any billing schedule. Its credit is issued after this request returns, so the response shows the grant as it stands at that moment: usually state.issuance PENDING with a zero availableBalance, becoming ISSUED with the full balance once funded. Retrying with the same Idempotency-Key returns the original grant without creating another. Keys never expire within your account, and a key reused with different terms is rejected.
Headers
Your API credentials. Eg. Basic {credentials}.
Unique ID for this request, at most 255 printable ASCII characters. Retrying with the same ID returns the original grant. IDs are never reusable within your account.
Use this header to select an API version
2024-07-30 Body
ID of the customer receiving the credit.
"61b083e0-1faa-47ca-9aeb-6205da8f6c47"
Currency of the credit. Must be a currency your account invoices in.
AED, ARS, AUD, BRL, BGN, CAD, CHF, CLP, CNY, COP, CZK, DKK, EGP, EUR, GBP, HKD, ILS, INR, ISK, JPY, KRW, MXN, NOK, NZD, PLN, SAR, SEK, SGD, THB, USD, UYU, ZAR "GBP"
Amount of credit granted, in the grant's currency. Must be positive, with at most 15 digits before the decimal point and 10 after it.
500
Amount the customer pays for the credit, in the grant's currency. Zero for free credit; cannot be negative or exceed the amount granted. At most 15 digits before the decimal point and 10 after it.
400
First day the credit can be used, inclusive, in UTC.
"2026-01-01"
Name of the credit grant, up to 256 characters. Defaults to "Credit grant" when omitted.
"Onboarding credit"
Last day the credit can be used, inclusive, in UTC. Cannot be before the effective date. Omit for credit that does not expire.
"2026-12-31"
Response
Created
Credit grant ID.
"0199ca8a-e7e8-73b3-bd69-a316a23231a0"
Sequence account ID.
"dce9ae85-d8d0-42b4-bcad-f221a64363c6"
ID of the customer receiving the credit.
"61b083e0-1faa-47ca-9aeb-6205da8f6c47"
Whether the grant is held by the customer directly (CUSTOMER) or belongs to one of their billing schedules (SCHEDULE).
CUSTOMER, SCHEDULE "SCHEDULE"
Name of the credit grant.
"Monthly usage credits"
Whether credit is measured in currency or usage-metric units.
CURRENCY, METRIC "CURRENCY"
The configured credit allowance. Available credit may exceed this amount after rollover. The difference between this amount and available credit does not represent usage.
100
Credit currently available for eligible prices. Never negative. Zero before the effective date, while awaiting issuance, when no credit remains, or after expiry. Usage awaiting processing is not yet deducted. Dates are evaluated in UTC and are inclusive.
79.35
Independent issuance and date-validity states. availableBalance reports the credit usable now.
When the credit grant was created.
"2026-01-01T10:00:00Z"
When the grant's configuration last changed. Changes to the available balance do not update this timestamp.
"2026-01-01T10:00:00Z"
How often the credit grant refreshes its balance.
NONE, MONTHLY, QUARTERLY, HALF_YEARLY, YEARLY "MONTHLY"
How often the customer is charged for the credit grant.
ONE_TIME, MONTHLY, QUARTERLY, HALF_YEARLY, YEARLY "MONTHLY"
Whether unused balance carries over when the grant refreshes.
NONE, ON_GRANT_REFRESH, ON_GRANT_REFRESH_AND_PHASE "NONE"
IDs of prices eligible to use this credit. Includes all prices in the phase when no restriction was specified. Empty for a customer grant.
Identifiers for this credit grant in external integrations.
ID of the billing schedule the grant belongs to. Absent for a customer grant.
"0199ca86-560e-7ac4-999f-bee364f7e4e7"
ID of the billing schedule phase the grant belongs to. Absent for a customer grant.
"0199ca87-6d80-7836-aa09-10386a08d761"
Currency the grant is denominated in. Null when creditUnitType is METRIC.
AED, ARS, AUD, BRL, BGN, CAD, CHF, CLP, CNY, COP, CZK, DKK, EGP, EUR, GBP, HKD, ILS, INR, ISK, JPY, KRW, MXN, NOK, NZD, PLN, SAR, SEK, SGD, THB, USD, UYU, ZAR "GBP"
ID of the usage metric the credit is measured in when creditUnitType is METRIC.
"f092246c-6b90-4106-bcca-304ccf06bf45"
The amount charged to the customer for the credit grant.
100
Tax rate ID for the credit grant.
"179d1ab3-cc96-48e2-9310-067b0b42d47c"
First day the credit can be used, inclusive, in UTC.
"2026-01-01"
Last day the credit can be used, inclusive, in UTC.
"2026-01-31"
ID of the grant whose unused credit was rolled over into this grant.
"0199ca8a-e7e8-73b3-bd69-a316a2323100"