API Reference

Credit Grants

Credit Grants are objects that represent a credit amount issued to a customer. These credits can be used to offset the cost of future invoices. This API allows you to create, retrieve, update, list, and summarize credit grants for your customers.
For a higher-level guide on implementing a credit-based system, see the Credit Billing guide. To view the history of credit usage, refer to the Credit Transactions API.
The Credit Grant Object#A Credit Grant object contains the full details of a credit issued to a customer. It includes information about the amount, status, and applicability.
Attribute
Type
Description
id
string
Unique identifier for the credit grant.
object
string
The type of object, always credit_grant.
amount
string
The total amount of the credit grant in the smallest currency unit.
remaining_amount
string
The amount of credit remaining.
currency_id
string
The ID of the currency for the credit.
customer_id
string
The ID of the customer who received the grant.
category
string
The category of the grant. Can be 'paid' or 'promotional'.
status
string
The current status of the grant. Can be 'pending', 'granted', 'depleted', 'expired', or 'voided'.
name
string
An optional internal name for the credit grant.
priority
number
A positive integer between 1 and 99999 that determines the order in which credits are applied. Lower numbers have higher priority.
effective_at
number
Unix timestamp indicating when the grant becomes active.
expires_at
number
Unix timestamp indicating when the grant expires.
applicability_config
object
Rules that specify where this credit grant can be applied.
livemode
boolean
true if the object exists in live mode, false if it exists in test mode.
metadata
object
A set of key-value pairs that you can attach to an object.
Create a Credit Grant#Issues a new credit grant to a customer.
Parameters
Name
Type
Description
amount
string
Required. The value of the credit grant, specified in the smallest currency unit.
currency_id
string
Required. The three-letter ISO currency code (or custom currency ID) for the grant.
customer_id
string
Required. The ID of the customer to receive the credit.
category
'paid' | 'promotional'
Required. Specifies whether the credit is from a paid source or a promotion.
name
string
An optional internal name for this credit grant.
priority
number
A positive integer (1-99999) indicating the application priority. Lower numbers are applied first.
effective_at
number
A Unix timestamp indicating when the credit grant becomes active. If not provided, it becomes active immediately.
expires_at
number
A Unix timestamp indicating when the credit grant expires.
applicability_config
object
An object defining the scope of the credit's applicability. Contains a scope object with properties prices (an array of price IDs) and/or price_type (e.g., 'metered').
metadata
object
A set of key-value pairs to store additional information.
Example
async function createCreditGrant() {
  try {
    const creditGrant = await payment.creditGrants.create({
      customer_id: 'cust_xxxxxxxxxxxxxx',
      amount: '5000',
      currency_id: 'usd',
      category: 'promotional',
      name: 'New User Welcome Bonus',
      expires_at: Math.floor(Date.now() / 1000) + (30 * 24 * 60 * 60) // 30 days from now
    });
    console.log('Credit Grant created:', creditGrant);
  } catch (error) {
    console.error('Error creating credit grant:', error.message);
  }
}

createCreditGrant();Example Response
{
  "id": "cgrant_1A2b3C4d5E6f7G8h",
  "object": "credit_grant",
  "amount": "5000",
  "currency_id": "usd",
  "applicability_config": null,
  "category": "promotional",
  "customer_id": "cust_xxxxxxxxxxxxxx",
  "effective_at": 1672531200,
  "expires_at": 1675123200,
  "livemode": false,
  "metadata": {},
  "name": "New User Welcome Bonus",
  "priority": 50000,
  "status": "granted",
  "remaining_amount": "5000",
  "created_via": "api",
  "created_at": "2023-01-01T00:00:00.000Z",
  "updated_at": "2023-01-01T00:00:00.000Z"
}Retrieve a Credit Grant#Fetches the details of a specific credit grant by its ID.
Parameters
Name
Type
Description
id
string
Required. The unique identifier of the credit grant to retrieve.
Example
async function retrieveCreditGrant(grantId) {
  try {
    const creditGrant = await payment.creditGrants.retrieve(grantId);
    console.log('Retrieved Credit Grant:', creditGrant);
  } catch (error) {
    console.error('Error retrieving credit grant:', error.message);
  }
}

retrieveCreditGrant('cgrant_1A2b3C4d5E6f7G8h');Example Response
{
  "id": "cgrant_1A2b3C4d5E6f7G8h",
  "object": "credit_grant",
  "amount": "5000",
  "currency_id": "usd",
  "category": "promotional",
  "customer_id": "cust_xxxxxxxxxxxxxx",
  "status": "granted",
  "remaining_amount": "5000",
  // ... other properties
}Update a Credit Grant#Updates the specified credit grant by setting the metadata parameter. Other properties of a credit grant cannot be updated.
Parameters
Name
Type
Description
id
string
Required. The identifier of the credit grant to update.
metadata
object
A set of key-value pairs to store with the credit grant.
Example
async function updateCreditGrant(grantId) {
  try {
    const result = await payment.creditGrants.update(grantId, {
      metadata: {
        internal_ref: 'promo-campaign-fall2023'
      }
    });
    console.log('Update successful:', result.success);
  } catch (error) {
    console.error('Error updating credit grant:', error.message);
  }
}

updateCreditGrant('cgrant_1A2b3C4d5E6f7G8h');Example Response
{
  "success": true
}List all Credit Grants#Returns a paginated list of credit grants. You can filter the list based on various parameters.
Parameters
Name
Type
Description
customer_id
string
Filters the list to grants for a specific customer.
currency_id
string
Filters the list by currency.
status
string
Filters the list by status (e.g., 'granted', 'expired').
livemode
boolean
Filters by live or test mode.
q
string
A search query string that searches across multiple fields.
page
number
The page number for pagination.
pageSize
number
The number of items per page. Defaults to 20.
order
string | string[]
The order to sort the results.
Example
async function listCustomerCredits() {
  try {
    const creditGrants = await payment.creditGrants.list({
      customer_id: 'cust_xxxxxxxxxxxxxx',
      status: 'granted',
      pageSize: 5
    });
    console.log(`Found ${creditGrants.count} granted credits for customer.`);
    creditGrants.list.forEach(grant => {
      console.log(`- Grant ${grant.id}: ${grant.remaining_amount} ${grant.currency_id}`);
    });
  } catch (error) {
    console.error('Error listing credit grants:', error.message);
  }
}

listCustomerCredits();Example Response
{
  "count": 1,
  "list": [
    {
      "id": "cgrant_1A2b3C4d5E6f7G8h",
      "object": "credit_grant",
      "amount": "5000",
      "currency_id": "usd",
      "category": "promotional",
      "customer_id": "cust_xxxxxxxxxxxxxx",
      "status": "granted",
      "remaining_amount": "5000",
      // ... other properties
    }
  ]
}Retrieve a Credit Summary#Provides a summary of a customer's credit balances, grouped by currency.
Parameters
Name
Type
Description
customer_id
string
Required. The ID of the customer for whom to retrieve the summary.
subscription_id
string
An optional subscription ID to provide context for the credit summary, which may affect which applicable credits are returned.
Example
async function getCreditSummary(customerId) {
  try {
    const summary = await payment.creditGrants.summary({ customer_id: customerId });
    console.log('Customer Credit Summary:', summary);
  } catch (error) {
    console.error('Error retrieving credit summary:', error.message);
  }
}

getCreditSummary('cust_xxxxxxxxxxxxxx');Example Response
{
  "customer_id": "cust_xxxxxxxxxxxxxx",
  "total_balance": {
    "usd": {
      "currency_id": "usd",
      "total_amount": "15000",
      "available_amount": "7500",
      "pending_amount": "0",
      "currency": {
        "id": "usd",
        "symbol": "$",
        "decimal": 2
      }
    },
    "eur": {
      "currency_id": "eur",
      "total_amount": "10000",
      "available_amount": "10000",
      "pending_amount": "0",
      "currency": {
        "id": "eur",
        "symbol": "€",
        "decimal": 2
      }
    }
  }
}
This section detailed how to manage Credit Grants programmatically. After issuing credits, you will want to track how they are applied to invoices. Proceed to the Credit Transactions API to learn more.

Overview

Get Started

Core Concepts

Usage Guides

API Reference

TypeScript Support

Credit Grants

The Credit Grant Object#

Create a Credit Grant#

Retrieve a Credit Grant#

Update a Credit Grant#

List all Credit Grants#

Retrieve a Credit Summary#

Meter Events

Credit Transactions

Attribute	Type	Description
`id`	string	Unique identifier for the credit grant.
`object`	string	The type of object, always `credit_grant`.
`amount`	string	The total amount of the credit grant in the smallest currency unit.
`remaining_amount`	string	The amount of credit remaining.
`currency_id`	string	The ID of the currency for the credit.
`customer_id`	string	The ID of the customer who received the grant.
`category`	string	The category of the grant. Can be `'paid'` or `'promotional'`.
`status`	string	The current status of the grant. Can be `'pending'`, `'granted'`, `'depleted'`, `'expired'`, or `'voided'`.
`name`	string	An optional internal name for the credit grant.
`priority`	number	A positive integer between 1 and 99999 that determines the order in which credits are applied. Lower numbers have higher priority.
`effective_at`	number	Unix timestamp indicating when the grant becomes active.
`expires_at`	number	Unix timestamp indicating when the grant expires.
`applicability_config`	object	Rules that specify where this credit grant can be applied.
`livemode`	boolean	`true` if the object exists in live mode, `false` if it exists in test mode.
`metadata`	object	A set of key-value pairs that you can attach to an object.

Name	Type	Description
`amount`	string	Required. The value of the credit grant, specified in the smallest currency unit.
`currency_id`	string	Required. The three-letter ISO currency code (or custom currency ID) for the grant.
`customer_id`	string	Required. The ID of the customer to receive the credit.
`category`	'paid' \| 'promotional'	Required. Specifies whether the credit is from a paid source or a promotion.
`name`	string	An optional internal name for this credit grant.
`priority`	number	A positive integer (1-99999) indicating the application priority. Lower numbers are applied first.
`effective_at`	number	A Unix timestamp indicating when the credit grant becomes active. If not provided, it becomes active immediately.
`expires_at`	number	A Unix timestamp indicating when the credit grant expires.
`applicability_config`	object	An object defining the scope of the credit's applicability. Contains a `scope` object with properties `prices` (an array of price IDs) and/or `price_type` (e.g., `'metered'`).
`metadata`	object	A set of key-value pairs to store additional information.

Name	Type	Description
`id`	string	Required. The identifier of the credit grant to update.
`metadata`	object	A set of key-value pairs to store with the credit grant.

Name	Type	Description
`customer_id`	string	Filters the list to grants for a specific customer.
`currency_id`	string	Filters the list by currency.
`status`	string	Filters the list by status (e.g., `'granted'`, `'expired'`).
`livemode`	boolean	Filters by live or test mode.
`q`	string	A search query string that searches across multiple fields.
`page`	number	The page number for pagination.
`pageSize`	number	The number of items per page. Defaults to `20`.
`order`	string \| string[]	The order to sort the results.

Name	Type	Description
`customer_id`	string	Required. The ID of the customer for whom to retrieve the summary.
`subscription_id`	string	An optional subscription ID to provide context for the credit summary, which may affect which applicable credits are returned.