Create a credit grant
Grants credit without charging or invoicing: PROMOTIONAL credit for free, or PAID credit the
customer paid for outside Meteroid (“Paid outside Meteroid”). A PAID currency grant whose
cost is below its amount is split into a PAID grant for the cost and a PROMOTIONAL bonus
grant for the rest, returned as bonus_grant_id; a cost above the amount is refused.
For a customer of a French invoicing entity, PAID credit that cost more than zero needs a
reference to the invoice or receipt of its payment. Sell credit through Meteroid with a
top-up.
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
Body
Credit granted without charging or invoicing.
Credit granted, in minor units of currency, or of credit_unit when set (e.g. 500000
is 5,000.00 credits of a unit with precision 2). Positive.
PROMOTIONAL gives credit for free (a goodwill or marketing grant). PAID records credit the customer paid for outside of Meteroid: nothing is charged or invoiced, and the grant is shown as "Paid outside Meteroid". Usage paid with PAID currency credit is taxed on the invoice that bills it, so do not charge tax on the external sale of currency credit, or the customer is taxed twice. Credit in a credit unit is the exception: its usage is billed in credits, untaxed, so tax its sale as you would any other. Use a top-up to sell credit through Meteroid.
PAID, PROMOTIONAL Restricts the credit to charges of these products; absent applies to every product.
Combined with applies_to. Not available for credit units.
ALL pays any charge on an invoice; USAGE only usage charges.
ALL, USAGE What the customer paid for the credit, net of tax. Required for PAID credit in a credit
unit; defaults to zero for PROMOTIONAL credit and to amount for PAID currency credit.
PAID currency credit cannot cost more than amount. When it costs less, the cost is
granted as PAID credit and the rest as a separate PROMOTIONAL bonus grant with the same
expiry, which applies before tax; PAID credit that cost nothing is granted as PROMOTIONAL.
Grants in this credit unit (its code) instead of a currency; excludes currency. Credit in
a credit unit pays the usage priced in that unit, so applies_to must stay ALL.
Defaults to the customer's currency.
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"
When unspent credit lapses; absent never expires.
Lower values are drawn first among grants of the same type that pay the same charges; defaults to 100.
Shown on the credit ledger.
Your own reference, e.g. a contract or support ticket. Required for PAID credit that cost more than zero when the customer's invoicing entity is in France: the number of the invoice or receipt for the payment, as French law requires a supporting document for every accounting entry. Refused with 400 when missing.
The customer's subscription (sub_…) the credit belongs to: it pays only that
subscription's charges and lapses when the subscription ends. It must not have ended,
and its currency must be the grant's. Absent pays any of the customer's subscriptions.
Response
Credit granted
A lot of credit given to or bought by a customer. An invoice applies promotional currency
credit before tax and paid credit after it. Within each, it draws the grants that belong to
the invoiced subscription first, then grants restricted to products (the fewest products
first), then usage-only grants, then the others; then by lowest priority, then the soonest
to lapse.
Amount granted, in minor units of currency or credit_unit.
The products whose charges the credit pays, combined with applies_to; empty when it
applies to every product.
ALL pays any charge on an invoice; USAGE only usage charges.
ALL, USAGE When the grant was recorded.
When the credit became spendable.
The grant's id (cgr_…).
The group the grant is shown in: INCLUDED, PREPAID, BONUS or ACCOUNT_BALANCE.
INCLUDED, PREPAID, BONUS, ACCOUNT_BALANCE The group's name as Meteroid shows it: "Included with ", "Purchased credit", "Free credit" or "Account balance".
Lower values are drawn first among grants of the same type that pay the same charges; 100 by default.
Shown on the credit ledger.
Not spent yet, in the same minor units.
Where the credit came from.
MANUAL, PURCHASE, PLAN, CREDIT_NOTE, ADJUSTMENT, MIGRATED, ROLLOVER, COUPON, OVERPAYMENT PENDING until effective_at, then ACTIVE, DEPLETED once spent, or EXPIRED.
PENDING, ACTIVE, DEPLETED, EXPIRED PAID or PROMOTIONAL: whether it applies after or before tax.
PAID, PROMOTIONAL Only on the response that created a PAID currency grant whose cost was below its
amount: the PROMOTIONAL "Bonus credit" grant created beside it for the difference, with
the same expiry, scope and priority.
What the whole grant was paid, net of tax: zero for promotional or included credit. A PAID grant created through the API without an invoice ("Paid outside Meteroid") carries the cost it was given. Absent for credit granted before costs were recorded.
cost per one major unit of credit, in major units of the cost currency (e.g. "0.008"),
rounded to 12 decimal places, for display only.
The credit note that gave the credit back.
The credit unit (its code) the amounts are in; absent for a currency.
Decimal places of credit_unit: amounts are integers of 10^-precision credit.
x >= 0Absent when the grant is in a credit unit.
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"
When the subscription the grant belongs to ended, if it ended. Unspent credit lapses then
(status EXPIRED), even before expires_at.
Lost to expiry; present only on an expired grant.
When unspent credit lapses; absent never expires.
The invoice that sold the credit, or whose void or negative total gave it back.
Your own reference, e.g. a contract or support ticket.
The subscription the grant belongs to (sub_…): it pays only that subscription's
charges, and lapses when the subscription ends. Null when it pays any of the customer's
subscriptions.