Core Resources
Payment Methods
Money Management
Products
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury
Payment Records
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. We currently only support metered prices that have a Billing Meter attached to them.

  • 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.

  • customerstring

    ID of the customer to receive the billing credits.

  • customer_accountstringPreview feature

    ID of the account to receive the billing credits.

  • effective_attimestamp

    The time when the billing credits become effective-when they’re eligible for use. It defaults to the current timestamp if not specified.

  • expires_attimestamp

    The time when the billing credits expire. If not specified, the billing credits don’t expire.

  • metadataobject

    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.

  • namestring

    A descriptive name shown in the Dashboard.

  • priorityintegerPreview feature

    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.

POST /v1/billing/credit_grants
curl https://api.stripe.com/v1/billing/credit_grants \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -H "Stripe-Version: 2025-09-30.preview" \
  -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",
  "priority": null,
  "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 expire. If set to empty, the billing credits never expire.

  • metadataobject

    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.

POST /v1/billing/credit_grants/:id
curl https://api.stripe.com/v1/billing/credit_grants/credgr_test_61R9rpFu8SZkXPTkU41L6nFOS1ekDKoa \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -H "Stripe-Version: 2025-09-30.preview" \
  -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",
  "priority": 50,
  "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_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -H "Stripe-Version: 2025-09-30.preview"
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
}

List credit grants

Retrieve a list of credit grants.

Parameters

  • customerstring

    Only return credit grants for this customer.

  • customer_accountstringPreview feature

    Only return credit grants for this account.

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_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -H "Stripe-Version: 2025-09-30.preview"
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",
      "priority": 50,
      "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_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -H "Stripe-Version: 2025-09-30.preview"
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",
  "priority": 50,
  "test_clock": null,
  "updated": 1726688796,
  "voided_at": null
}