Stripe: Create a credit grant
Stripe billing.postBillingCreditGrants: arguments, response, policy and SDK examples.
← Billing operations · Get started
Operation stripe.postbillingcreditgrants
Provider route: POST /v1/billing/credit_grants. Alter supplies the connection’s credentials and routing.
Call through Alter
Section titled “Call through Alter”Install @alter-ai/sdk @alter-ai/stripe with npm, or alter-sdk-stripe with pip. Supply your connected customer’s grant ID and the arguments described below.
import { App } from "@alter-ai/sdk";import { StripeIntegration } from "@alter-ai/stripe";
async function execute(input: Parameters<StripeIntegration["billing"]["postBillingCreditGrants"]>[0]) { const app = new App({ apiKey: process.env.ALTER_API_KEY! }); try { const provider = new StripeIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! }); const call = await provider.billing.postBillingCreditGrants(input); const result = await call.wait(); return result.bodyJson(); } finally { await app.close(); }}import osfrom alter_sdk import Appfrom alter_sdk_stripe import StripeIntegration
async def execute(arguments): async with App(api_key=os.environ["ALTER_API_KEY"]) as app: provider = StripeIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]}) call = await provider.billing.post_billing_credit_grants(arguments) result = await call.wait() return result.body_json()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
headers | object | Optional | Additional keys: not allowed |
headers.Idempotency-Key | string | Optional | Minimum length: 1 Maximum length: 255 |
body | object | Required within parent | Additional keys: not allowed |
body.amount | object | Required within parent | Amount of this credit grant. |
body.amount.monetary | object | Optional | |
body.amount.monetary.currency | string | Required within parent | Format: currency |
body.amount.monetary.value | integer | Required within parent | |
body.amount.type | string | Required within parent | One of: monetary |
body.applicability_config | object | Required within parent | Configuration specifying what this credit grant applies to. We currently only support `metered` prices that have a [Billing Meter](https://docs.stripe.com/api/billing/meter) attached to them. |
body.applicability_config.scope | object | Required within parent | |
body.applicability_config.scope.price_type | string | Optional | One of: metered |
body.applicability_config.scope.prices | array | Optional | |
body.applicability_config.scope.prices[] | object | Each item | |
body.applicability_config.scope.prices[].id | string | Required within parent | Maximum length: 5000 |
body.category | string | Optional | The category of this credit grant. It defaults to `paid` if not specified. One of: paid, promotional |
body.customer | string | Optional | ID of the customer receiving the billing credits. Maximum length: 5000 |
body.customer_account | string | Optional | ID of the account representing the customer receiving the billing credits. Maximum length: 5000 |
body.effective_at | integer | Optional | The time when the billing credits become effective-when they’re eligible for use. It defaults to the current timestamp if not specified. Format: unix-time |
body.expand | array | Optional | Specifies which fields in the response should be expanded. |
body.expand[] | string | Each item | Maximum length: 5000 |
body.expires_at | integer | Optional | The time when the billing credits expire. If not specified, the billing credits don’t expire. Format: unix-time |
body.metadata | object | Optional | 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. Additional keys: see wildcard field |
body.metadata.* | string | Additional keys | |
body.name | string | Optional | A descriptive name shown in the Dashboard. Maximum length: 100 |
body.priority | integer | Optional | 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. |
Response
Section titled “Response”Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | Model | Root | Expand Void a credit grant — response body |
Referenced models: Void a credit grant — response body
Schemas
Section titled “Schemas”704 more schemas are linked from the tables above, on the schema pages.
Void a credit grant — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A credit grant is an API resource that documents the allocation of some billing credits to a customer. Related guide: [Billing credits](https://docs.stripe.com/billing/subscriptions/usage-based/billing-credits) |
amount | Model | Required within parent | Expand Void a credit grant — response body — amount |
applicability_config | Model | Required within parent | Expand Void a credit grant — response body — applicability config |
category | string | Required within parent | The category of this credit grant. This is for tracking purposes and isn't displayed to the customer. Known values: paid, promotional |
created | JSON | Required within parent | |
created (anyOf 1) | integer | Alternative | Time at which the object was created. Measured in seconds since the Unix epoch. Format: unix-time |
created (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
customer | JSON | Required within parent | ID of the customer receiving the billing credits. |
customer (anyOf 1) | string | Alternative | Maximum length: 5000 |
customer (anyOf 2) | Model | Alternative | Expand Create a customer — response body |
customer (anyOf 3) | Model | Alternative | Expand Delete a customer — response body |
customer_account | JSON | Optional | |
customer_account (anyOf 1) | string | Alternative | ID of the account representing the customer receiving the billing credits Maximum length: 5000 |
customer_account (anyOf 2) | null | Alternative | |
effective_at | JSON | Optional | |
effective_at (anyOf 1) | JSON | Alternative | |
effective_at (anyOf 1) (anyOf 1) | integer | Alternative | The time when the billing credits become effective-when they're eligible for use. Format: unix-time |
effective_at (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
effective_at (anyOf 2) | null | Alternative | |
expires_at | JSON | Optional | |
expires_at (anyOf 1) | JSON | Alternative | |
expires_at (anyOf 1) (anyOf 1) | integer | Alternative | The time when the billing credits expire. If not present, the billing credits don't expire. Format: unix-time |
expires_at (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
expires_at (anyOf 2) | null | Alternative | |
id | string | Required within parent | Unique identifier for the object. Maximum length: 5000 |
livemode | boolean | Required within parent | If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`. |
metadata | object | Required within parent | Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Additional keys: see wildcard field |
metadata.* | string | Additional keys | Maximum length: 500 |
name | JSON | Optional | |
name (anyOf 1) | string | Alternative | A descriptive name shown in dashboard. Maximum length: 5000 |
name (anyOf 2) | null | Alternative | |
object | string | Required within parent | String representing the object's type. Objects of the same type share the same value. Known values: billing.credit_grant |
priority | JSON | Optional | |
priority (anyOf 1) | JSON | Alternative | |
priority (anyOf 1) (anyOf 1) | integer | Alternative | The priority for applying this credit grant. The highest priority is 0 and the lowest is 100. |
priority (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
priority (anyOf 2) | null | Alternative | |
test_clock | JSON | Optional | |
test_clock (anyOf 1) | JSON | Alternative | ID of the test clock this credit grant belongs to. |
test_clock (anyOf 1) (anyOf 1) | string | Alternative | Maximum length: 5000 |
test_clock (anyOf 1) (anyOf 2) | Model | Alternative | Expand Create a test clock — response body |
test_clock (anyOf 2) | null | Alternative | |
updated | JSON | Required within parent | |
updated (anyOf 1) | integer | Alternative | Time at which the object was last updated. Measured in seconds since the Unix epoch. Format: unix-time |
updated (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
voided_at | JSON | Optional | |
voided_at (anyOf 1) | JSON | Alternative | |
voided_at (anyOf 1) (anyOf 1) | integer | Alternative | The time when this credit grant was voided. If not present, the credit grant hasn't been voided. Format: unix-time |
voided_at (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
voided_at (anyOf 2) | null | Alternative |
Referenced models: Void a credit grant — response body — amount, Void a credit grant — response body — applicability config, Create a customer — response body, Delete a customer — response body, Create a test clock — response body
Void a credit grant — response body — amount
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
monetary | JSON | Optional | |
monetary (anyOf 1) | JSON | Alternative | The monetary amount. |
monetary (anyOf 1) (anyOf 1) | Model | Alternative | Expand Void a credit grant — response body — amount monetary The monetary amount currency, value |
monetary (anyOf 2) | null | Alternative | |
type | string | Required within parent | The type of this amount. We currently only support `monetary` billing credits. Known values: monetary |
Referenced models: Void a credit grant — response body — amount monetary The monetary amount currency, value
Void a credit grant — response body — applicability config
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
scope | Model | Required within parent | Expand Void a credit grant — response body — applicability config scope |
Referenced models: Void a credit grant — response body — applicability config scope
Delete a customer — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
deleted | boolean | Required within parent | Always true for a deleted object Known values: True |
id | string | Required within parent | Unique identifier for the object. Maximum length: 5000 |
object | string | Required within parent | String representing the object's type. Objects of the same type share the same value. Known values: customer |
Create a test clock — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A test clock enables deterministic control over objects in testmode. With a test clock, you can create objects at a frozen time in the past or future, and advance to a specific future time to observe webhooks and state changes. After the clock advances, you can either validate the current state of your scenario (and test your assumptions), change the current state of your scenario (and test more complex scenarios), or keep advancing forward in time. |
created | JSON | Required within parent | |
created (anyOf 1) | integer | Alternative | Time at which the object was created. Measured in seconds since the Unix epoch. Format: unix-time |
created (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
deletes_after | JSON | Required within parent | |
deletes_after (anyOf 1) | integer | Alternative | Time at which this clock is scheduled to auto delete. Format: unix-time |
deletes_after (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
frozen_time | JSON | Required within parent | |
frozen_time (anyOf 1) | integer | Alternative | Time at which all objects belonging to this clock are frozen. Format: unix-time |
frozen_time (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
id | string | Required within parent | Unique identifier for the object. Maximum length: 5000 |
livemode | boolean | Required within parent | If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`. |
name | JSON | Optional | |
name (anyOf 1) | string | Alternative | The custom name supplied at creation. Maximum length: 5000 |
name (anyOf 2) | null | Alternative | |
object | string | Required within parent | String representing the object's type. Objects of the same type share the same value. Known values: test_helpers.test_clock |
status | string | Required within parent | The status of the Test Clock. Known values: advancing, internal_failure, ready |
status_details | Model | Required within parent | Expand Create a test clock — response body — status details |
Referenced models: Create a test clock — response body — status details
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: stripe.postbillingcreditgrants. Catalog operation: PostBillingCreditGrants. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.
Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.
Pinned headers: {"Stripe-Version": "2026-09-30.endive"}