Creates a credit grant
Parameters
- amountobjectRequired
Amount of this credit grant.
- applicability_
configobjectRequired Configuration specifying what this credit grant applies to.
- categoryenumRequired
The category of this credit grant.
Possible enum valuespaid
The credit grant was purchased by the customer for some amount.
promotional
The credit grant was given to the customer for free.
- customerstringRequired
ID of the customer to whom the billing credits should be granted.
- effective_
attimestamp The time when the billing credits become effective i.e when they are eligible to be used. Defaults to the current timestamp if not specified.
- expires_
attimestamp The time when the billing credits will expire. If not specified, the billing credits will never expire.
- metadataobject
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object (ex: cost basis) in a structured format.
- namestring
A descriptive name shown in dashboard.
Returns
Returns a credit grant
{ "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", "test_clock": null, "updated": 1726620803}
Updates a credit grant
Parameters
- idstringRequired
Unique identifier for the object.
- expires_
attimestamp The time when the billing credits created by this credit grant will expire. If set to empty, the billing credits will never expire.
- metadataobject
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object (ex: cost basis) in a structured format.
Returns
Returns the updated credit grant
{ "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", "test_clock": null, "updated": 1726688977, "voided_at": null}
Retrieves a credit grant
Parameters
- idstringRequired
Unique identifier for the object.
Returns
Returns a credit grant
{ "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", "test_clock": null, "updated": 1726620803}
Retrieve a list of credit grants
Parameters
- customerstring
Only return credit grants for this customer.
More parameters
- ending_
beforestring - limitinteger
- starting_
afterstring
Returns
Returns a list of credit grants
{ "object": "list", "data": [ { "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", "test_clock": null, "updated": 1726620803, "voided_at": null } ], "has_more": false, "url": "/v1/billing/credit_grants"}
Expires a credit grant
Parameters
- idstringRequired
Unique identifier for the object.
Returns
Returns the expired credit grant
{ "id": "credgr_test_61R9rm9vto9SMMvt041L6nFOS1ekDCim", "object": "billing.credit_grant", "amount": { "monetary": { "currency": "usd", "value": 1000 }, "type": "monetary" }, "applicability_config": { "scope": { "price_type": "metered" } }, "category": "paid", "created": 1726688741, "customer": "cus_QsEHa3GKweMwih", "effective_at": 1726688741, "expires_at": 1726688796, "livemode": false, "metadata": {}, "name": "Purchased Credits", "test_clock": null, "updated": 1726688796, "voided_at": null}