API reference

Test mode. Use your secret key on your server; live processing is currently disabled.

https://api.knoxapi.com

Send form-encoded requests with Authorization: Bearer sk_test_....

Complete OpenAPI specification · Integration guide

Operations and schemas are based on the pinned Stripe OpenAPI specification (MIT). Nested object definitions and enums are available in the complete specification.

GET /v1/billing/alerts

List billing alerts

Lists billing active and inactive alerts

Request parameters

Parameter	Location	Type	Description
`alert_type`	query	string	Filter results to only include this type of alert.
`ending_before`	query	string	A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`limit`	query	integer	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
`meter`	query	string	Filter results to only include alerts with the given meter.
`starting_after`	query	string	A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`data` required	array of billing.alert
`has_more` required	boolean	True if this list has another page of items after this one that can be fetched.
`object` required	string	String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
`url` required	string	The URL where this list can be accessed.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/billing/alerts

Create a billing alert

Creates a billing alert

Request parameters

Field	Type	Description
`alert_type` required	string	The type of alert to create.
`expand`	array of string	Specifies which fields in the response should be expanded.
`title` required	string	The title of the alert.
`usage_threshold`	object	The configuration of the usage threshold.

Responses

HTTP 200: Successful response.

Field	Type	Description
`alert_type` required	string	Defines the type of the alert.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`status`	string	Status of the alert. This can be active, inactive or archived.
`title` required	string	Title of the alert.
`usage_threshold`	one of multiple schemas	Encapsulates configuration of the alert to monitor usage on a specific [Billing Meter](https://docs.stripe.com/api/billing/meter).

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/billing/credit_balance_summary

Retrieve the credit balance summary for a customer

Retrieves the credit balance summary for a customer.

Request parameters

Parameter	Location	Type	Description
`customer`	query	string	The customer whose credit balance summary you're retrieving.
`customer_account`	query	string	The account representing the customer whose credit balance summary you're retrieving.
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`filter`	query	object	The filter criteria for the credit balance summary.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`balances` required	array of credit_balance	The billing credit balances. One entry per credit grant currency. If a customer only has credit grants in a single currency, then this will have a single balance entry.
`customer` required	one of multiple schemas	The customer the balance is for.
`customer_account`	string	The account the balance is for.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`object` required	string	String representing the object's type. Objects of the same type share the same value.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/billing/credit_balance_transactions

List credit balance transactions

Retrieve a list of credit balance transactions.

Request parameters

Parameter	Location	Type	Description
`credit_grant`	query	string	The credit grant for which to fetch credit balance transactions.
`customer`	query	string	The customer whose credit balance transactions you're retrieving.
`customer_account`	query	string	The account representing the customer whose credit balance transactions you're retrieving.
`ending_before`	query	string	A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`limit`	query	integer	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
`starting_after`	query	string	A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`data` required	array of billing.credit_balance_transaction
`has_more` required	boolean	True if this list has another page of items after this one that can be fetched.
`object` required	string	String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
`url` required	string	The URL where this list can be accessed.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/billing/credit_grants

List credit grants

Retrieve a list of credit grants.

Request parameters

Parameter	Location	Type	Description
`customer`	query	string	Only return credit grants for this customer.
`customer_account`	query	string	Only return credit grants for this account representing the customer.
`ending_before`	query	string	A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`limit`	query	integer	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
`starting_after`	query	string	A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`data` required	array of billing.credit_grant
`has_more` required	boolean	True if this list has another page of items after this one that can be fetched.
`object` required	string	String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
`url` required	string	The URL where this list can be accessed.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/billing/credit_grants

Create a credit grant

Creates a credit grant.

Request parameters

Field	Type	Description
`amount` required	object	Amount of this credit grant.
`applicability_config` required	object	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.
`category`	string	The category of this credit grant. It defaults to `paid` if not specified.
`customer`	string	ID of the customer receiving the billing credits.
`customer_account`	string	ID of the account representing the customer receiving the billing credits.
`effective_at`	integer	The time when the billing credits become effective-when they're eligible for use. It defaults to the current timestamp if not specified.
`expand`	array of string	Specifies which fields in the response should be expanded.
`expires_at`	integer	The time when the billing credits expire. If not specified, the billing credits don't expire.
`metadata`	object	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.
`name`	string	A descriptive name shown in the Dashboard.
`priority`	integer	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.

Responses

HTTP 200: Successful response.

Field	Type	Description
`amount` required	billing_credit_grants_resource_amount
`applicability_config` required	billing_credit_grants_resource_applicability_config
`category` required	string	The category of this credit grant. This is for tracking purposes and isn't displayed to the customer.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`customer` required	one of multiple schemas	ID of the customer receiving the billing credits.
`customer_account`	string	ID of the account representing the customer receiving the billing credits
`effective_at`	integer	The time when the billing credits become effective-when they're eligible for use.
`expires_at`	integer	The time when the billing credits expire. If not present, the billing credits don't expire.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata` required	object	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.
`name`	string	A descriptive name shown in dashboard.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`priority`	integer	The priority for applying this credit grant. The highest priority is 0 and the lowest is 100.
`test_clock`	one of multiple schemas	ID of the test clock this credit grant belongs to.
`updated` required	integer	Time at which the object was last updated. Measured in seconds since the Unix epoch.
`voided_at`	integer	The time when this credit grant was voided. If not present, the credit grant hasn't been voided.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/billing/feedback_options

Feedback Options List API Method

An API method for listing the feedback options model

Request parameters

Parameter	Location	Type	Description
`ending_before`	query	string	A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`limit`	query	integer	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
`starting_after`	query	string	A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.
`status`	query	string	Filter results to only include feedback options with the given status.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`data` required	array of billing.feedback_option
`has_more` required	boolean	True if this list has another page of items after this one that can be fetched.
`object` required	string	String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
`url` required	string	The URL where this list can be accessed.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/billing/feedback_options

Create a feedback option

Creates a new feedback option.

Request parameters

Field	Type	Description
`description` required	string
`expand`	array of string	Specifies which fields in the response should be expanded.

Responses

HTTP 200: Successful response.

Field	Type	Description
`description` required	string	An arbitrary string attached to the object. Often useful for displaying to users.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`status` required	string	The feedback option's status.
`status_transitions` required	feedback_options_status_transitions

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/billing/meter_event_adjustments

Create a billing meter event adjustment

Creates a billing meter event adjustment.

Request parameters

Field	Type	Description
`cancel`	object	Specifies which event to cancel.
`event_name` required	string	The name of the meter event. Corresponds with the `event_name` field on a meter.
`expand`	array of string	Specifies which fields in the response should be expanded.
`type` required	string	Specifies whether to cancel a single event or a range of events for a time period. Time period cancellation is not supported yet.

Responses

HTTP 200: Successful response.

Field	Type	Description
`cancel`	one of multiple schemas	Specifies which event to cancel.
`event_name` required	string	The name of the meter event. Corresponds with the `event_name` field on a meter.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`status` required	string	The meter event adjustment's status.
`type` required	string	Specifies whether to cancel a single event or a range of events for a time period. Time period cancellation is not supported yet.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/billing/meter_events

Create a billing meter event

Creates a billing meter event.

Request parameters

Field	Type	Description
`event_name` required	string	The name of the meter event. Corresponds with the `event_name` field on a meter.
`expand`	array of string	Specifies which fields in the response should be expanded.
`identifier`	string	A unique identifier for the event. If not provided, one is generated. We recommend using UUID-like identifiers. Stripe enforces uniqueness within a rolling period of at least 24 hours. The enforcement of uniqueness primarily addresses issues arising from accidental retries or other problems occurring within extremely brief time intervals. This approach helps prevent duplicate entries and ensures data integrity in high-frequency operations.
`payload` required	object	The payload of the event. This must contain the fields corresponding to a meter's `customer_mapping.event_payload_key` (default is `stripe_customer_id`) and `value_settings.event_payload_key` (default is `value`). Read more about the [payload](https://docs.stripe.com/billing/subscriptions/usage-based/meters/configure#meter-configuration-attributes).
`timestamp`	integer	The time of the event. Measured in seconds since the Unix epoch. Must be within the past 35 calendar days or up to 5 minutes in the future. Defaults to current timestamp if not specified.

Responses

HTTP 200: Successful response.

Field	Type	Description
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`event_name` required	string	The name of the meter event. Corresponds with the `event_name` field on a meter.
`identifier` required	string	A unique identifier for the event.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`payload` required	object	The payload of the event. This contains the fields corresponding to a meter's `customer_mapping.event_payload_key` (default is `stripe_customer_id`) and `value_settings.event_payload_key` (default is `value`). Read more about the [payload](https://docs.stripe.com/billing/subscriptions/usage-based/meters/configure#meter-configuration-attributes).
`timestamp` required	integer	The timestamp passed in when creating the event. Measured in seconds since the Unix epoch.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/billing/meters

List billing meters

Retrieve a list of billing meters.

Request parameters

Parameter	Location	Type	Description
`ending_before`	query	string	A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`limit`	query	integer	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
`starting_after`	query	string	A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.
`status`	query	string	Filter results to only include meters with the given status.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`data` required	array of billing.meter
`has_more` required	boolean	True if this list has another page of items after this one that can be fetched.
`object` required	string	String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
`url` required	string	The URL where this list can be accessed.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/billing/meters

Create a billing meter

Creates a billing meter.

Request parameters

Field	Type	Description
`customer_mapping`	object	Fields that specify how to map a meter event to a customer.
`default_aggregation` required	object	The default settings to aggregate a meter's events with.
`display_name` required	string	The meter’s name. Not visible to the customer.
`event_name` required	string	The name of the meter event to record usage for. Corresponds with the `event_name` field on meter events.
`event_time_window`	string	The time window which meter events have been pre-aggregated for, if any.
`expand`	array of string	Specifies which fields in the response should be expanded.
`value_settings`	object	Fields that specify how to calculate a meter event's value.

Responses

HTTP 200: Successful response.

Field	Type	Description
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`customer_mapping` required	billing_meter_resource_customer_mapping_settings
`default_aggregation` required	billing_meter_resource_aggregation_settings
`display_name` required	string	The meter's name.
`event_name` required	string	The name of the meter event to record usage for. Corresponds with the `event_name` field on meter events.
`event_time_window`	string	The time window which meter events have been pre-aggregated for, if any.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`status` required	string	The meter's status.
`status_transitions` required	billing_meter_resource_billing_meter_status_transitions
`updated` required	integer	Time at which the object was last updated. Measured in seconds since the Unix epoch.
`value_settings` required	billing_meter_resource_billing_meter_value

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/billing/alerts/{id}

Retrieve a billing alert

Retrieves a billing alert given an ID

Request parameters

Parameter	Location	Type	Description
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`id`	path	string

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`alert_type` required	string	Defines the type of the alert.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`status`	string	Status of the alert. This can be active, inactive or archived.
`title` required	string	Title of the alert.
`usage_threshold`	one of multiple schemas	Encapsulates configuration of the alert to monitor usage on a specific [Billing Meter](https://docs.stripe.com/api/billing/meter).

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/billing/alerts/{id}/activate

Activate a billing alert

Reactivates this alert, allowing it to trigger again.

Request parameters

Parameter	Location	Type	Description
`id`	path	string

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.

Responses

HTTP 200: Successful response.

Field	Type	Description
`alert_type` required	string	Defines the type of the alert.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`status`	string	Status of the alert. This can be active, inactive or archived.
`title` required	string	Title of the alert.
`usage_threshold`	one of multiple schemas	Encapsulates configuration of the alert to monitor usage on a specific [Billing Meter](https://docs.stripe.com/api/billing/meter).

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/billing/alerts/{id}/archive

Archive a billing alert

Archives this alert, removing it from the list view and APIs. This is non-reversible.

Request parameters

Parameter	Location	Type	Description
`id`	path	string

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.

Responses

HTTP 200: Successful response.

Field	Type	Description
`alert_type` required	string	Defines the type of the alert.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`status`	string	Status of the alert. This can be active, inactive or archived.
`title` required	string	Title of the alert.
`usage_threshold`	one of multiple schemas	Encapsulates configuration of the alert to monitor usage on a specific [Billing Meter](https://docs.stripe.com/api/billing/meter).

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/billing/alerts/{id}/deactivate

Deactivate a billing alert

Deactivates this alert, preventing it from triggering.

Request parameters

Parameter	Location	Type	Description
`id`	path	string

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.

Responses

HTTP 200: Successful response.

Field	Type	Description
`alert_type` required	string	Defines the type of the alert.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`status`	string	Status of the alert. This can be active, inactive or archived.
`title` required	string	Title of the alert.
`usage_threshold`	one of multiple schemas	Encapsulates configuration of the alert to monitor usage on a specific [Billing Meter](https://docs.stripe.com/api/billing/meter).

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/billing/credit_balance_transactions/{id}

Retrieve a credit balance transaction

Retrieves a credit balance transaction.

Request parameters

Parameter	Location	Type	Description
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`id`	path	string	Unique identifier for the object.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`credit`	one of multiple schemas	Credit details for this credit balance transaction. Only present if type is `credit`.
`credit_grant` required	one of multiple schemas	The credit grant associated with this credit balance transaction.
`debit`	one of multiple schemas	Debit details for this credit balance transaction. Only present if type is `debit`.
`effective_at` required	integer	The effective time of this credit balance transaction.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`test_clock`	one of multiple schemas	ID of the test clock this credit balance transaction belongs to.
`type`	string	The type of credit balance transaction (credit or debit).

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/billing/credit_grants/{id}

Retrieve a credit grant

Retrieves a credit grant.

Request parameters

Parameter	Location	Type	Description
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`id`	path	string	Unique identifier for the object.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`amount` required	billing_credit_grants_resource_amount
`applicability_config` required	billing_credit_grants_resource_applicability_config
`category` required	string	The category of this credit grant. This is for tracking purposes and isn't displayed to the customer.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`customer` required	one of multiple schemas	ID of the customer receiving the billing credits.
`customer_account`	string	ID of the account representing the customer receiving the billing credits
`effective_at`	integer	The time when the billing credits become effective-when they're eligible for use.
`expires_at`	integer	The time when the billing credits expire. If not present, the billing credits don't expire.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata` required	object	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.
`name`	string	A descriptive name shown in dashboard.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`priority`	integer	The priority for applying this credit grant. The highest priority is 0 and the lowest is 100.
`test_clock`	one of multiple schemas	ID of the test clock this credit grant belongs to.
`updated` required	integer	Time at which the object was last updated. Measured in seconds since the Unix epoch.
`voided_at`	integer	The time when this credit grant was voided. If not present, the credit grant hasn't been voided.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/billing/credit_grants/{id}

Update a credit grant

Updates a credit grant.

Request parameters

Parameter	Location	Type	Description
`id`	path	string	Unique identifier for the object.

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.
`expires_at`	one of multiple schemas	The time when the billing credits created by this credit grant expire. If set to empty, the billing credits never expire.
`metadata`	object	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.

Responses

HTTP 200: Successful response.

Field	Type	Description
`amount` required	billing_credit_grants_resource_amount
`applicability_config` required	billing_credit_grants_resource_applicability_config
`category` required	string	The category of this credit grant. This is for tracking purposes and isn't displayed to the customer.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`customer` required	one of multiple schemas	ID of the customer receiving the billing credits.
`customer_account`	string	ID of the account representing the customer receiving the billing credits
`effective_at`	integer	The time when the billing credits become effective-when they're eligible for use.
`expires_at`	integer	The time when the billing credits expire. If not present, the billing credits don't expire.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata` required	object	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.
`name`	string	A descriptive name shown in dashboard.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`priority`	integer	The priority for applying this credit grant. The highest priority is 0 and the lowest is 100.
`test_clock`	one of multiple schemas	ID of the test clock this credit grant belongs to.
`updated` required	integer	Time at which the object was last updated. Measured in seconds since the Unix epoch.
`voided_at`	integer	The time when this credit grant was voided. If not present, the credit grant hasn't been voided.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/billing/credit_grants/{id}/expire

Expire a credit grant

Expires a credit grant.

Request parameters

Parameter	Location	Type	Description
`id`	path	string	Unique identifier for the object.

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.

Responses

HTTP 200: Successful response.

Field	Type	Description
`amount` required	billing_credit_grants_resource_amount
`applicability_config` required	billing_credit_grants_resource_applicability_config
`category` required	string	The category of this credit grant. This is for tracking purposes and isn't displayed to the customer.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`customer` required	one of multiple schemas	ID of the customer receiving the billing credits.
`customer_account`	string	ID of the account representing the customer receiving the billing credits
`effective_at`	integer	The time when the billing credits become effective-when they're eligible for use.
`expires_at`	integer	The time when the billing credits expire. If not present, the billing credits don't expire.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata` required	object	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.
`name`	string	A descriptive name shown in dashboard.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`priority`	integer	The priority for applying this credit grant. The highest priority is 0 and the lowest is 100.
`test_clock`	one of multiple schemas	ID of the test clock this credit grant belongs to.
`updated` required	integer	Time at which the object was last updated. Measured in seconds since the Unix epoch.
`voided_at`	integer	The time when this credit grant was voided. If not present, the credit grant hasn't been voided.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/billing/credit_grants/{id}/void

Void a credit grant

Voids a credit grant.

Request parameters

Parameter	Location	Type	Description
`id`	path	string	Unique identifier for the object.

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.

Responses

HTTP 200: Successful response.

Field	Type	Description
`amount` required	billing_credit_grants_resource_amount
`applicability_config` required	billing_credit_grants_resource_applicability_config
`category` required	string	The category of this credit grant. This is for tracking purposes and isn't displayed to the customer.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`customer` required	one of multiple schemas	ID of the customer receiving the billing credits.
`customer_account`	string	ID of the account representing the customer receiving the billing credits
`effective_at`	integer	The time when the billing credits become effective-when they're eligible for use.
`expires_at`	integer	The time when the billing credits expire. If not present, the billing credits don't expire.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata` required	object	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.
`name`	string	A descriptive name shown in dashboard.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`priority`	integer	The priority for applying this credit grant. The highest priority is 0 and the lowest is 100.
`test_clock`	one of multiple schemas	ID of the test clock this credit grant belongs to.
`updated` required	integer	Time at which the object was last updated. Measured in seconds since the Unix epoch.
`voided_at`	integer	The time when this credit grant was voided. If not present, the credit grant hasn't been voided.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/billing/feedback_options/{id}

Retrieve a feedback option

Retrieves a feedback options object given an ID.

Request parameters

Parameter	Location	Type	Description
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`id`	path	string

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`description` required	string	An arbitrary string attached to the object. Often useful for displaying to users.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`status` required	string	The feedback option's status.
`status_transitions` required	feedback_options_status_transitions

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/billing/feedback_options/{id}

Update a feedback option

Updates the description of an existing feedback option.

Request parameters

Parameter	Location	Type	Description
`id`	path	string

Field	Type	Description
`description`	string
`expand`	array of string	Specifies which fields in the response should be expanded.

Responses

HTTP 200: Successful response.

Field	Type	Description
`description` required	string	An arbitrary string attached to the object. Often useful for displaying to users.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`status` required	string	The feedback option's status.
`status_transitions` required	feedback_options_status_transitions

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/billing/feedback_options/{id}/deactivate

Deactivate a feedback option

Deactivates a feedback option. Deactivated feedback options cannot be used in portal configurations.

Request parameters

Parameter	Location	Type	Description
`id`	path	string

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.

Responses

HTTP 200: Successful response.

Field	Type	Description
`description` required	string	An arbitrary string attached to the object. Often useful for displaying to users.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`status` required	string	The feedback option's status.
`status_transitions` required	feedback_options_status_transitions

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/billing/meters/{id}

Retrieve a billing meter

Retrieves a billing meter given an ID.

Request parameters

Parameter	Location	Type	Description
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`id`	path	string

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`customer_mapping` required	billing_meter_resource_customer_mapping_settings
`default_aggregation` required	billing_meter_resource_aggregation_settings
`display_name` required	string	The meter's name.
`event_name` required	string	The name of the meter event to record usage for. Corresponds with the `event_name` field on meter events.
`event_time_window`	string	The time window which meter events have been pre-aggregated for, if any.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`status` required	string	The meter's status.
`status_transitions` required	billing_meter_resource_billing_meter_status_transitions
`updated` required	integer	Time at which the object was last updated. Measured in seconds since the Unix epoch.
`value_settings` required	billing_meter_resource_billing_meter_value

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/billing/meters/{id}

Update a billing meter

Updates a billing meter.

Request parameters

Parameter	Location	Type	Description
`id`	path	string

Field	Type	Description
`display_name`	string	The meter’s name. Not visible to the customer.
`expand`	array of string	Specifies which fields in the response should be expanded.

Responses

HTTP 200: Successful response.

Field	Type	Description
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`customer_mapping` required	billing_meter_resource_customer_mapping_settings
`default_aggregation` required	billing_meter_resource_aggregation_settings
`display_name` required	string	The meter's name.
`event_name` required	string	The name of the meter event to record usage for. Corresponds with the `event_name` field on meter events.
`event_time_window`	string	The time window which meter events have been pre-aggregated for, if any.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`status` required	string	The meter's status.
`status_transitions` required	billing_meter_resource_billing_meter_status_transitions
`updated` required	integer	Time at which the object was last updated. Measured in seconds since the Unix epoch.
`value_settings` required	billing_meter_resource_billing_meter_value

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/billing/meters/{id}/deactivate

Deactivate a billing meter

When a meter is deactivated, no more meter events will be accepted for this meter. You can’t attach a deactivated meter to a price.

Request parameters

Parameter	Location	Type	Description
`id`	path	string

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.

Responses

HTTP 200: Successful response.

Field	Type	Description
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`customer_mapping` required	billing_meter_resource_customer_mapping_settings
`default_aggregation` required	billing_meter_resource_aggregation_settings
`display_name` required	string	The meter's name.
`event_name` required	string	The name of the meter event to record usage for. Corresponds with the `event_name` field on meter events.
`event_time_window`	string	The time window which meter events have been pre-aggregated for, if any.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`status` required	string	The meter's status.
`status_transitions` required	billing_meter_resource_billing_meter_status_transitions
`updated` required	integer	Time at which the object was last updated. Measured in seconds since the Unix epoch.
`value_settings` required	billing_meter_resource_billing_meter_value

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/billing/meters/{id}/event_summaries

List billing meter event summaries

Retrieve a list of billing meter event summaries.

Request parameters

Parameter	Location	Type	Description
`customer`	query	string	The customer for which to fetch event summaries.
`end_time`	query	integer	The timestamp from when to stop aggregating meter events (exclusive). Must be aligned with minute boundaries.
`ending_before`	query	string	A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`id`	path	string	Unique identifier for the object.
`limit`	query	integer	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
`start_time`	query	integer	The timestamp from when to start aggregating meter events (inclusive). Must be aligned with minute boundaries.
`starting_after`	query	string	A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.
`value_grouping_window`	query	string	Specifies what granularity to use when generating event summaries. If not specified, a single event summary would be returned for the specified time range. For hourly granularity, start and end times must align with hour boundaries (e.g., 00:00, 01:00, ..., 23:00). For daily granularity, start and end times must align with UTC day boundaries (00:00 UTC).

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`data` required	array of billing.meter_event_summary
`has_more` required	boolean	True if this list has another page of items after this one that can be fetched.
`object` required	string	String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
`url` required	string	The URL where this list can be accessed.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/billing/meters/{id}/reactivate

Reactivate a billing meter

When a meter is reactivated, events for this meter can be accepted and you can attach the meter to a price.

Request parameters

Parameter	Location	Type	Description
`id`	path	string

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.

Responses

HTTP 200: Successful response.

Field	Type	Description
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`customer_mapping` required	billing_meter_resource_customer_mapping_settings
`default_aggregation` required	billing_meter_resource_aggregation_settings
`display_name` required	string	The meter's name.
`event_name` required	string	The name of the meter event to record usage for. Corresponds with the `event_name` field on meter events.
`event_time_window`	string	The time window which meter events have been pre-aggregated for, if any.
`id` required	string	Unique identifier for the object.
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`status` required	string	The meter's status.
`status_transitions` required	billing_meter_resource_billing_meter_status_transitions
`updated` required	integer	Time at which the object was last updated. Measured in seconds since the Unix epoch.
`value_settings` required	billing_meter_resource_billing_meter_value

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors