Core Resources
Payment Methods
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 

Billing
Credit Grant
Create a credit grant

Creates a credit grant.

Parameters

  • amountobjectRequired

    Amount of this credit grant.

    • amount.typeenumRequired

      The type of this amount. We currently only support monetary billing credits.

      Possible enum values
      monetary

      The amount is a monetary amount.

    • amount.monetaryobject

      The monetary amount.

      • amount.monetary.currencyenumRequired

        Three-letter ISO code for the currency of the value parameter.

      • amount.monetary.valueintegerRequired

        A positive integer representing the amount of the 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.

    • applicability_config.scopeobjectRequired

      Specify the scope of this applicability config.

      • applicability_config.scope.billable_itemsarray of objectsPreview feature

        A list of billable items that the credit grant can apply to. We currently only support metered billable items. Cannot be used in combination with price_type or prices.

        • applicability_config.scope.billable_items.idstringRequired

          The billable item ID this credit grant should apply to.

      • applicability_config.scope.price_typeenum

        The price type that credit grants can apply to. We currently only support the metered price type. Cannot be used in combination with prices.

        Possible enum values
        metered

        Credit grants being created can only apply to metered prices.

      • applicability_config.scope.pricesarray of objectsPreview feature

        A list of prices that the credit grant can apply to. We currently only support the metered prices. Cannot be used in combination with price_type.

        • applicability_config.scope.prices.idstringRequired

          The price ID this credit grant should apply to.

  • customerstringRequired

    ID of the customer to receive the billing credits.

  • categoryenum

    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.

  • 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:" \
  -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
}