The Credit Grant object

Attributes

id string Unique identifier for the object.
object string, value is "billing.credit_grant" String representing the object’s type. Objects of the same type share the same value.
amount object Amount of this credit grant.
applicability _ config object Configuration specifying what this credit grant applies to. We currently only support metered prices that have a Billing Meter attached to them.
category enum The category of this credit grant. This is for tracking purposes and isn’t displayed to the customer. Possible enum values paid The credit grant was purchased by the customer for some amount. promotional The credit grant was given to the customer for free.
created timestamp Time at which the object was created. Measured in seconds since the Unix epoch.
customer string Expandable ID of the customer receiving the billing credits.
customer _ account nullable string ID of the account representing the customer receiving the billing credits
effective _ at nullable timestamp The time when the billing credits become effective-when they’re eligible for use.
expires _ at nullable timestamp The time when the billing credits expire. If not present, the billing credits don’t expire.
livemode boolean If the object exists in live mode, the value is true. If the object exists in test mode, the value is false.
metadata map Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
name nullable string A descriptive name shown in dashboard.
priority nullable integer The priority for applying this credit grant. The highest priority is 0 and the lowest is 100.
test _ clock nullable string Expandable ID of the test clock this credit grant belongs to.
updated timestamp Time at which the object was last updated. Measured in seconds since the Unix epoch.
voided _ at nullable timestamp The time when this credit grant was voided. If not present, the credit grant hasn’t been voided.

{ "id": "credgr_test_61R9a6NUWsRmOW3RM41L6nFOS1ekDGHo", "object": "billing.credit_grant", "amount": { "monetary": { "currency": "usd", "value": 1000 }, "type": "monetary" }, "applicability_config": { "scope": { "price_type": "metered" } }, "category": "paid", "created": 1726620803, "customer": "cus_QrvQguzkIK8zTj", "effective_at": 1729297860, "expires_at": null, "livemode": false, "metadata": {}, "name": "Purchased Credits", "priority": 50, "test_clock": null, "updated": 1726620803, "voided_at": null}

Create a credit grant

POST / v1 / billing / credit_grants

Creates a credit grant.

Parameters

amount object Required Amount of this credit grant.
applicability _ config object Required Configuration specifying what this credit grant applies to. We currently only support metered prices that have a Billing Meter attached to them.
category enum The category of this credit grant. It defaults to paid if not specified. Possible enum values paid The credit grant was purchased by the customer for some amount. promotional The credit grant was given to the customer for free.
customer string ID of the customer receiving the billing credits.
customer _ account string ID of the account representing the customer receiving the billing credits.
effective _ at timestamp The time when the billing credits become effective-when they’re eligible for use. It defaults to the current timestamp if not specified.
expires _ at timestamp The time when the billing credits expire. If not specified, the billing credits don’t expire.
metadata map Set of key-value pairs that you can attach to an object. You can use this to store additional information about the object (for example, cost basis) in a structured format.
name string A descriptive name shown in the Dashboard. The maximum length is 100 characters.
priority integer The desired priority for applying this credit grant. If not specified, it will be set to the default value of 50. The highest priority is 0 and the lowest is 100.

Returns

Returns a credit grant.

Response

{ "id": "credgr_test_61R9a6NUWsRmOW3RM41L6nFOS1ekDGHo", "object": "billing.credit_grant", "amount": { "monetary": { "currency": "usd", "value": 1000 }, "type": "monetary" }, "applicability_config": { "scope": { "price_type": "metered" } }, "category": "paid", "created": 1726620803, "customer": "cus_QrvQguzkIK8zTj", "effective_at": 1729297860, "expires_at": null, "livemode": false, "metadata": {}, "name": "Purchased Credits", "priority": 50, "test_clock": null, "updated": 1726620803}

Update a credit grant

POST / v1 / billing / credit_grants /:id

Updates a credit grant.

Parameters

id string Required Unique identifier for the object.
expires _ at timestamp The time when the billing credits created by this credit grant expire. If set to empty, the billing credits never expire.
metadata map Set of key-value pairs you can attach to an object. You can use this to store additional information about the object (for example, cost basis) in a structured format.

Returns

Returns the updated credit grant.

Response

{ "id": "credgr_test_61R9rpFu8SZkXPTkU41L6nFOS1ekDKoa", "object": "billing.credit_grant", "amount": { "monetary": { "currency": "usd", "value": 1000 }, "type": "monetary" }, "applicability_config": { "scope": { "price_type": "metered" } }, "category": "paid", "created": 1726688933, "customer": "cus_QsEHa3GKweMwih", "effective_at": 1726688933, "expires_at": 1759302000, "livemode": false, "metadata": { "cost_basis": "0.9" }, "name": "Purchased Credits", "priority": 50, "test_clock": null, "updated": 1726688977, "voided_at": null}