Skip to content
Metronome Docs
  • Auto
  • Light
  • Dark
Talk to an expert

Create

API Reference
V1
Credit Grants
Create a credit grant
client.v1.creditGrants.create(CreditGrantCreateParamsbody, RequestOptionsoptions?): dataIDCreditGrantCreateResponse
post/v1/credits/createGrant

Create a new credit grant

Parameters
bodycustomer_idstringexpires_atstringgrant_amountGrantAmountnamestringpaid_amountPaidAmountprioritynumbercredit_grant_typestringcustom_fieldsRecord<string, string>effective_atstringinvoice_datestringproduct_idsarrayreasonstringrollover_settingsRolloverSettingsuniqueness_keystringCreditGrantCreateParams
Hide ParametersShow Parameters
customer_idstring

the Metronome ID of the customer

formatuuid
expires_atstring

The credit grant will only apply to usage or charges dated before this timestamp

formatdate-time
grant_amountGrantAmount

the amount of credits granted

Hide ParametersShow Parameters
amountnumber
credit_type_idstring

the ID of the pricing unit to be used. Defaults to USD (cents) if not passed.

formatuuid
namestring

the name of the credit grant as it will appear on invoices

prioritynumber
credit_grant_typestring
optional
custom_fieldsRecord<string, string>
optional

Custom fields to attach to the credit grant.

effective_atstring
optional

The credit grant will only apply to usage or charges dated on or after this timestamp

formatdate-time
invoice_datestring
optional

The date to issue an invoice for the paid_amount.

formatdate-time
product_idsarray
optional
Array<string>

The product(s) which these credits will be applied to. (If unspecified, the credits will be applied to charges for all products.). The array ordering specified here will be used to determine the order in which credits will be applied to invoice line items

reasonstring
optional
rollover_settingsRolloverSettings
optional

Configure a rollover for this credit grant so if it expires it rolls over a configured amount to a new credit grant. This feature is currently opt-in only. Contact Metronome to be added to the beta.

Hide ParametersShow Parameters
expires_atstring

The date to expire the rollover credits.

formatdate-time
prioritynumber

The priority to give the rollover credit grant that gets created when a rollover happens.

rollover_amountunion
type"MAX_PERCENTAGE"valuenumberRolloverAmountMaxPercentage | type"MAX_AMOUNT"valuenumberRolloverAmountMaxAmount

Specify how much to rollover to the rollover credit grant

Hide ParametersShow Parameters
type"MAX_PERCENTAGE"valuenumberRolloverAmountMaxPercentage
type"MAX_AMOUNT"valuenumberRolloverAmountMaxAmount
uniqueness_keystring
optional

Prevents the creation of duplicates. If a request to create a record is made with a previously used uniqueness key, a new record will not be created and the request will fail with a 409 error.

minLength1
maxLength128
Returns
CreditGrantCreateResponse
Hide ParametersShow Parameters
dataidstringID
import Metronome from '@metronome/sdk';

const client = new Metronome({
  bearerToken: 'My Bearer Token',
});

const creditGrant = await client.v1.creditGrants.create({
  customer_id: '9b85c1c1-5238-4f2a-a409-61412905e1e1',
  expires_at: '2022-04-01T00:00:00Z',
  grant_amount: { amount: 1000, credit_type_id: '5ae401dc-a648-4b49-9ac3-391bb5bc4d7b' },
  name: 'Acme Corp Promotional Credit Grant',
  paid_amount: { amount: 5000, credit_type_id: '2714e483-4ff1-48e4-9e25-ac732e8f24f2' },
  priority: 0.5,
  credit_grant_type: 'trial',
  effective_at: '2022-02-01T00:00:00Z',
  reason: 'Incentivize new customer',
});

console.log(creditGrant.data);
200 Example
{
  "data": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
  }
}