Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Connect
Fraud
Issuing
Terminal
Treasury
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Webhooks

Create a credit grant 

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 values
    paid

    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

POST /v1/billing/credit_grants
curl https://api.stripe.com/v1/billing/credit_grants \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d name="Purchased Credits" \
  -d customer=cus_QrvQguzkIK8zTj \
  -d "amount[monetary][currency]"=usd \
  -d "amount[monetary][value]"=1000 \
  -d "amount[type]"=monetary \
  -d "applicability_config[scope][price_type]"=metered \
  -d category=paid
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",
  "test_clock": null,
  "updated": 1726620803
}

Update a credit grant 

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

POST /v1/billing/credit_grants/:id
curl https://api.stripe.com/v1/billing/credit_grants/credgr_test_61R9rpFu8SZkXPTkU41L6nFOS1ekDKoa \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d "metadata[cost_basis]"="0.9" \
  -d expires_at=1759302000
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",
  "test_clock": null,
  "updated": 1726688977,
  "voided_at": null
}

Retrieve a credit grant 

Retrieves a credit grant

Parameters

  • idstringRequired

    Unique identifier for the object.

Returns

Returns a credit grant

GET /v1/billing/credit_grants/:id
curl https://api.stripe.com/v1/billing/credit_grants/credgr_test_61R9a6NUWsRmOW3RM41L6nFOS1ekDGHo \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"
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",
  "test_clock": null,
  "updated": 1726620803
}

List credit grants 

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

GET /v1/billing/credit_grants
curl https://api.stripe.com/v1/billing/credit_grants \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"
Response
{
  "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"
}

Expire a credit grant 

Expires a credit grant

Parameters

  • idstringRequired

    Unique identifier for the object.

Returns

Returns the expired credit grant

POST /v1/billing/credit_grants/:id/expire
curl -X POST https://api.stripe.com/v1/billing/credit_grants/credgr_test_61R9rm9vto9SMMvt041L6nFOS1ekDCim/expire \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"
Response
{
  "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
}