API Reference

Credit Grants

A Credit Grant represents an amount of credit issued to a customer. These grants are used in credit-based billing models to cover usage costs for metered services. Each grant has properties such as its amount, currency, status, effective and expiration dates, and rules that determine its applicability.
This API allows you to create, retrieve, update, list, and manage credit grants for your customers. For more information on tracking usage, see the Meters API.
The Credit Grant Object#A CreditGrant object contains all the details about a specific issuance of credit to a customer.
{
  "id": "cg_xxxxxxxxxxxxxx",
  "object": "credit_grant",
  "amount": "10000",
  "remaining_amount": "7500",
  "currency_id": "usd_xxxxxxxxxxxxxx",
  "customer_id": "cus_xxxxxxxxxxxxxx",
  "name": "Promotional Credits for Q3",
  "category": "promotional",
  "priority": 50,
  "status": "granted",
  "effective_at": 1672531200,
  "expires_at": 1680307199,
  "granted_at": 1672531200,
  "applicability_config": {
    "scope": {
      "price_type": "metered",
      "prices": [
        "price_xxxxxxxxxxxxxx"
      ]
    }
  },
  "livemode": true,
  "metadata": {},
  "customer": {
    "id": "cus_xxxxxxxxxxxxxx",
    "name": "John Doe"
  },
  "paymentCurrency": {
    "id": "usd_xxxxxxxxxxxxxx",
    "name": "US Dollar"
  },
  "items": []
}Create a Credit Grant#Issues a new credit grant to a specified customer. This adds to the customer's credit balance, which can then be applied to future invoices.
Parameters
Name
Type
Description
amount
string
Required. The amount of credit to grant.
currency_id
string
Required. The ID of the currency for this grant.
customer_id
string
Required. The ID or DID of the customer to whom the credit is granted. If a customer with the specified DID does not exist, a new one will be created.
name
string
An optional name for the credit grant for internal reference.
category
'paid' | 'promotional'
Required. The category of the credit grant.
priority
number
An integer from 0 to 100 that determines the order of application. Lower numbers are applied first. Defaults to 50.
effective_at
number
The Unix timestamp at which the grant becomes active. If not provided, it becomes active immediately.
expires_at
number
The Unix timestamp at which the grant expires. Expired grants cannot be used.
applicability_config
object
An object that defines rules for where this credit grant can be applied. If not provided, it defaults to applying to all metered prices. See details below.
metadata
Record<string, any>
A set of key-value pairs that you can attach to an object.
applicability_config Object Properties
Name
Type
Description
scope
object
Defines the scope of prices to which this grant can apply.
scope Object Properties
Name
Type
Description
price_type
'metered'
Specifies that the grant applies to metered prices.
prices
string[]
An array of Price IDs, restricting the grant's use to only those specific prices.
Returns
Returns a TCreditGrantExpanded object if the call is successful.
Example
import payment from '@blocklet/payment-js';

async function createCreditGrant() {
  try {
    const creditGrant = await payment.creditGrants.create({
      customer_id: 'cus_xxxxxxxxxxxxxx',
      amount: '50.00',
      currency_id: 'usd_xxxxxxxxxxxxxx',
      name: 'Initial Promotional Credit',
      category: 'promotional',
      effective_at: Math.floor(Date.now() / 1000),
      expires_at: Math.floor(Date.now() / 1000) + (30 * 24 * 60 * 60), // 30 days from now
      applicability_config: {
        scope: {
          price_type: 'metered'
        }
      }
    });
    console.log('Credit grant created:', creditGrant);
  } catch (error) {
    console.error('Error creating credit grant:', error.message);
  }
}

createCreditGrant();Example Response
{
  "id": "cg_xxxxxxxxxxxxxx",
  "object": "credit_grant",
  "amount": "5000",
  "remaining_amount": "5000",
  "currency_id": "usd_xxxxxxxxxxxxxx",
  "customer_id": "cus_xxxxxxxxxxxxxx",
  "name": "Initial Promotional Credit",
  "category": "promotional",
  "status": "granted",
  "effective_at": 1672531200,
  "expires_at": 1675209600,
  "livemode": true,
  "metadata": {},
  "customer": {
    "id": "cus_xxxxxxxxxxxxxx",
    "name": "John Doe"
  },
  "paymentCurrency": {
    "id": "usd_xxxxxxxxxxxxxx",
    "name": "US Dollar"
  }
}Retrieve a Credit Grant#Fetches the details of an existing credit grant by its unique ID.
Parameters
Name
Type
Description
id
string
Required. The unique identifier of the credit grant to retrieve.
Returns
Returns a TCreditGrantExpanded object, including an items array with expanded price details if applicable.
Example
import payment from '@blocklet/payment-js';

async function getCreditGrant(creditGrantId) {
  try {
    const creditGrant = await payment.creditGrants.retrieve(creditGrantId);
    console.log('Retrieved credit grant:', creditGrant);
  } catch (error) {
    console.error(`Error retrieving credit grant ${creditGrantId}:`, error.message);
  }
}

getCreditGrant('cg_xxxxxxxxxxxxxx');Example Response
{
  "id": "cg_xxxxxxxxxxxxxx",
  "object": "credit_grant",
  "amount": "5000",
  "remaining_amount": "5000",
  "currency_id": "usd_xxxxxxxxxxxxxx",
  "customer_id": "cus_xxxxxxxxxxxxxx",
  "name": "Initial Promotional Credit",
  "category": "promotional",
  "status": "granted",
  "effective_at": 1672531200,
  "expires_at": 1675209600,
  "livemode": true,
  "metadata": {},
  "customer": {
    "id": "cus_xxxxxxxxxxxxxx",
    "name": "John Doe"
  },
  "paymentCurrency": {
    "id": "usd_xxxxxxxxxxxxxx",
    "name": "US Dollar"
  },
  "items": []
}Update a Credit Grant#Updates the specified credit grant by setting the metadata parameter. Other properties of a credit grant cannot be changed after creation.
Parameters
Name
Type
Description
id
string
Required. The identifier of the credit grant to update.
metadata
Record<string, any>
A set of key-value pairs to store with the credit grant.
Returns
Returns an object with a success boolean indicating if the update was successful.
Example
import payment from '@blocklet/payment-js';

async function updateCreditGrant(creditGrantId) {
  try {
    const result = await payment.creditGrants.update(creditGrantId, {
      metadata: {
        internal_order_id: 'order_12345'
      }
    });
    console.log('Update successful:', result.success);
  } catch (error) {
    console.error(`Error updating credit grant ${creditGrantId}:`, error.message);
  }
}

updateCreditGrant('cg_xxxxxxxxxxxxxx');Example Response
{
  "success": true
}List 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
Filter grants by a specific customer ID or DID.
currency_id
string
Filter grants by currency ID.
status
string
Filter grants by status. Can be a comma-separated string of statuses (e.g., 'granted,pending').
livemode
boolean
Filter grants by their live mode status.
q
string
A general search query for filtering grants.
page
number
The page number for pagination. Defaults to 1.
pageSize
number
The number of items per page. Defaults to 20.
order
string
The sort order for the results (e.g., 'created_at:DESC'). Defaults to sorting by status in the order: granted, pending, depleted.
Returns
Returns a paginated list of TCreditGrantExpanded objects.
Example
import payment from '@blocklet/payment-js';

async function listCustomerGrants() {
  try {
    const creditGrants = await payment.creditGrants.list({
      customer_id: 'cus_xxxxxxxxxxxxxx',
      status: 'granted',
      pageSize: 5
    });
    console.log(`Found ${creditGrants.count} grants.`);
    creditGrants.list.forEach(grant => {
      console.log(`- ${grant.id} (${grant.name})`);
    });
  } catch (error) {
    console.error('Error listing credit grants:', error.message);
  }
}

listCustomerGrants();Example Response
{
  "count": 1,
  "list": [
    {
      "id": "cg_xxxxxxxxxxxxxx",
      "object": "credit_grant",
      "amount": "5000",
      "remaining_amount": "5000",
      "currency_id": "usd_xxxxxxxxxxxxxx",
      "customer_id": "cus_xxxxxxxxxxxxxx",
      "name": "Initial Promotional Credit",
      "status": "granted",
      "livemode": true
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 5
  }
}Get Credit Summary#Retrieves a summary of a customer's effective credit balances, grouped by currency. This is useful for displaying the total available credit to a customer. You can optionally scope the summary to a specific subscription to see credits applicable to it.
Parameters
Name
Type
Description
customer_id
string
Required. The ID or DID of the customer whose credit summary is being requested.
subscription_id
string
An optional subscription ID to scope the credit summary. Only grants applicable to the metered prices in this subscription will be included.
Returns
Returns a CreditSummary object, where each key is a currency ID and the value contains the credit summary for that currency.
Example
import payment from '@blocklet/payment-js';

async function getCustomerCreditSummary(customerId) {
  try {
    const summary = await payment.creditGrants.summary({ customer_id: customerId });
    console.log('Customer Credit Summary:', summary);
  } catch (error) {
    console.error('Error getting credit summary:', error.message);
  }
}

getCustomerCreditSummary('cus_xxxxxxxxxxxxxx');Example Response
{
  "usd_xxxxxxxxxxxxxx": {
    "paymentCurrency": {
      "id": "usd_xxxxxxxxxxxxxx",
      "name": "US Dollar",
      "symbol": "$",
      "decimal": 2
    },
    "totalAmount": "15000",
    "remainingAmount": "8500",
    "grantCount": 3
  }
}This guide covers the management of Credit Grants. For details on how credit is consumed, see the Credit Transactions API.

Name	Type	Description
`amount`	`string`	Required. The amount of credit to grant.
`currency_id`	`string`	Required. The ID of the currency for this grant.
`customer_id`	`string`	Required. The ID or DID of the customer to whom the credit is granted. If a customer with the specified DID does not exist, a new one will be created.
`name`	`string`	An optional name for the credit grant for internal reference.
`category`	`'paid' \| 'promotional'`	Required. The category of the credit grant.
`priority`	`number`	An integer from 0 to 100 that determines the order of application. Lower numbers are applied first. Defaults to 50.
`effective_at`	`number`	The Unix timestamp at which the grant becomes active. If not provided, it becomes active immediately.
`expires_at`	`number`	The Unix timestamp at which the grant expires. Expired grants cannot be used.
`applicability_config`	`object`	An object that defines rules for where this credit grant can be applied. If not provided, it defaults to applying to all metered prices. See details below.
`metadata`	`Record<string, any>`	A set of key-value pairs that you can attach to an object.

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

Name	Type	Description
`customer_id`	`string`	Filter grants by a specific customer ID or DID.
`currency_id`	`string`	Filter grants by currency ID.
`status`	`string`	Filter grants by status. Can be a comma-separated string of statuses (e.g., `'granted,pending'`).
`livemode`	`boolean`	Filter grants by their live mode status.
`q`	`string`	A general search query for filtering grants.
`page`	`number`	The page number for pagination. Defaults to 1.
`pageSize`	`number`	The number of items per page. Defaults to 20.
`order`	`string`	The sort order for the results (e.g., `'created_at:DESC'`). Defaults to sorting by status in the order: `granted`, `pending`, `depleted`.

Name	Type	Description
`customer_id`	`string`	Required. The ID or DID of the customer whose credit summary is being requested.
`subscription_id`	`string`	An optional subscription ID to scope the credit summary. Only grants applicable to the metered prices in this subscription will be included.

Overview

Getting Started

SDK Structure

Environments

Core Concepts

API Reference

Credit Grants

The Credit Grant Object#

Create a Credit Grant#

Retrieve a Credit Grant#

Update a Credit Grant#

List Credit Grants#

Get Credit Summary#

Meter Events

Credit Transactions

Name	Type	Description
`price_type`	`'metered'`	Specifies that the grant applies to metered prices.
`prices`	`string[]`	An array of Price IDs, restricting the grant's use to only those specific prices.