Skip to main content
POST
Create a customer credit grant

Headers

Authorization
string
required

Your API credentials. Eg. Basic {credentials}.

Idempotency-Key
string
required

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.

sequence-version
enum<string>

Use this header to select an API version

Available options:
2024-07-30

Body

application/json
customerId
string
required

ID of the customer receiving the credit.

Example:

"61b083e0-1faa-47ca-9aeb-6205da8f6c47"

currency
enum<string>
required

Currency of the credit. Must be a currency your account invoices in.

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

"GBP"

amount
number
required

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.

Example:

500

costOfCredit
number
required

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.

Example:

400

effectiveDate
string
required

First day the credit can be used, inclusive, in UTC.

Example:

"2026-01-01"

name
string | null

Name of the credit grant, up to 256 characters. Defaults to "Credit grant" when omitted.

Example:

"Onboarding credit"

expiryDate
string | null

Last day the credit can be used, inclusive, in UTC. Cannot be before the effective date. Omit for credit that does not expire.

Example:

"2026-12-31"

Response

Created

id
string
required

Credit grant ID.

Example:

"0199ca8a-e7e8-73b3-bd69-a316a23231a0"

sequenceAccountId
string
required

Sequence account ID.

Example:

"dce9ae85-d8d0-42b4-bcad-f221a64363c6"

customerId
string
required

ID of the customer receiving the credit.

Example:

"61b083e0-1faa-47ca-9aeb-6205da8f6c47"

scope
enum<string>
required

Whether the grant is held by the customer directly (CUSTOMER) or belongs to one of their billing schedules (SCHEDULE).

Available options:
CUSTOMER,
SCHEDULE
Example:

"SCHEDULE"

name
string
required

Name of the credit grant.

Example:

"Monthly usage credits"

creditUnitType
enum<string>
required

Whether credit is measured in currency or usage-metric units.

Available options:
CURRENCY,
METRIC
Example:

"CURRENCY"

amount
number
required

The configured credit allowance. Available credit may exceed this amount after rollover. The difference between this amount and available credit does not represent usage.

Example:

100

availableBalance
number
required

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.

Example:

79.35

state
object
required

Independent issuance and date-validity states. availableBalance reports the credit usable now.

Example:
createdAt
string
required

When the credit grant was created.

Example:

"2026-01-01T10:00:00Z"

updatedAt
string
required

When the grant's configuration last changed. Changes to the available balance do not update this timestamp.

Example:

"2026-01-01T10:00:00Z"

grantRefreshFrequency
enum<string>
required

How often the credit grant refreshes its balance.

Available options:
NONE,
MONTHLY,
QUARTERLY,
HALF_YEARLY,
YEARLY
Example:

"MONTHLY"

billingFrequency
enum<string>
required

How often the customer is charged for the credit grant.

Available options:
ONE_TIME,
MONTHLY,
QUARTERLY,
HALF_YEARLY,
YEARLY
Example:

"MONTHLY"

rolloverMode
enum<string>
required

Whether unused balance carries over when the grant refreshes.

Available options:
NONE,
ON_GRANT_REFRESH,
ON_GRANT_REFRESH_AND_PHASE
Example:

"NONE"

restrictToPrices
string[]
required

IDs of prices eligible to use this credit. Includes all prices in the phase when no restriction was specified. Empty for a customer grant.

Example:
integrationIds
object[]
required

Identifiers for this credit grant in external integrations.

Example:
billingScheduleId
string | null

ID of the billing schedule the grant belongs to. Absent for a customer grant.

Example:

"0199ca86-560e-7ac4-999f-bee364f7e4e7"

phaseId
string | null

ID of the billing schedule phase the grant belongs to. Absent for a customer grant.

Example:

"0199ca87-6d80-7836-aa09-10386a08d761"

currency
enum<string> | null

Currency the grant is denominated in. Null when creditUnitType is METRIC.

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

"GBP"

metricId
string | null

ID of the usage metric the credit is measured in when creditUnitType is METRIC.

Example:

"f092246c-6b90-4106-bcca-304ccf06bf45"

costOfCredit
number | null

The amount charged to the customer for the credit grant.

Example:

100

taxRateId
string | null

Tax rate ID for the credit grant.

Example:

"179d1ab3-cc96-48e2-9310-067b0b42d47c"

effectiveDate
string | null

First day the credit can be used, inclusive, in UTC.

Example:

"2026-01-01"

expiryDate
string | null

Last day the credit can be used, inclusive, in UTC.

Example:

"2026-01-31"

sourceGrantId
string | null

ID of the grant whose unused credit was rolled over into this grant.

Example:

"0199ca8a-e7e8-73b3-bd69-a316a2323100"