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}

Retrieve a credit grant

GET / v1 / billing / credit_grants /:id

Retrieves a credit grant.

Parameters

• id string Required Unique identifier for the object.

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}