API reference
Test mode. Use your secret key on your server; live processing is currently disabled.
https://api.knoxapi.comSend 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/promotion_codes
List all promotion codes
Returns a list of your promotion codes.
Request parameters
| Parameter | Location | Type | Description |
|---|---|---|---|
active | query | boolean | Filter promotion codes by whether they are active. |
code | query | string | Only return promotion codes that have this case-insensitive code. |
coupon | query | string | Only return promotion codes for this coupon. |
created | query | one of multiple schemas | A filter on the list, based on the object `created` field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with a number of different query options. |
customer | query | string | Only return promotion codes that are restricted to this customer. |
customer_account | query | string | Only return promotion codes that are restricted to 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 promotion_code | |
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/promotion_codes
Create a promotion code
A promotion code points to an underlying promotion. You can optionally restrict the code to a specific customer, redemption limit, and expiration date.
Request parameters
| Field | Type | Description |
|---|---|---|
active | boolean | Whether the promotion code is currently active. |
code | string | The customer-facing code. Regardless of case, this code must be unique across all active promotion codes for a specific customer. Valid characters are lower case letters (a-z), upper case letters (A-Z), digits (0-9), and dashes (-). If left blank, we will generate one automatically. |
customer | string | The customer who can use this promotion code. If not set, all customers can use the promotion code. |
customer_account | string | The account representing the customer who can use this promotion code. If not set, all customers can use the promotion code. |
expand | array of string | Specifies which fields in the response should be expanded. |
expires_at | integer | The timestamp at which this promotion code will expire. If the coupon has specified a `redeems_by`, then this value cannot be after the coupon's `redeems_by`. |
max_redemptions | integer | A positive integer specifying the number of times the promotion code can be redeemed. If the coupon has specified a `max_redemptions`, then this value cannot be greater than the coupon's `max_redemptions`. |
metadata | 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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. |
promotion required | object | The promotion referenced by this promotion code. |
restrictions | object | Settings that restrict the redemption of the promotion code. |
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|---|---|
active required | boolean | Whether the promotion code is currently active. A promotion code is only active if the coupon is also valid. |
code required | string | The customer-facing code. Regardless of case, this code must be unique across all active promotion codes for each customer. Valid characters are lower case letters (a-z), upper case letters (A-Z), digits (0-9), and dashes (-). |
created required | integer | Time at which the object was created. Measured in seconds since the Unix epoch. |
customer | one of multiple schemas | The customer who can use this promotion code. |
customer_account | string | The account representing the customer who can use this promotion code. |
expires_at | integer | Date at which the promotion code can no longer be redeemed. |
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`. |
max_redemptions | integer | Maximum number of times this promotion code can be redeemed. |
metadata | 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. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
promotion required | promotion_codes_resource_promotion | |
restrictions required | promotion_codes_resource_restrictions | |
times_redeemed required | integer | Number of times this promotion code has been used. |
HTTP default: Error response.
| Field | Type | Description |
|---|---|---|
error required | api_errors |
GET /v1/promotion_codes/{promotion_code}
Retrieve a promotion code
Retrieves the promotion code with the given ID. In order to retrieve a promotion code by the customer-facing code use list with the desired code.
Request parameters
| Parameter | Location | Type | Description |
|---|---|---|---|
expand | query | array of string | Specifies which fields in the response should be expanded. |
promotion_code | path | string |
object. See the OpenAPI specification for the complete schema.
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|---|---|
active required | boolean | Whether the promotion code is currently active. A promotion code is only active if the coupon is also valid. |
code required | string | The customer-facing code. Regardless of case, this code must be unique across all active promotion codes for each customer. Valid characters are lower case letters (a-z), upper case letters (A-Z), digits (0-9), and dashes (-). |
created required | integer | Time at which the object was created. Measured in seconds since the Unix epoch. |
customer | one of multiple schemas | The customer who can use this promotion code. |
customer_account | string | The account representing the customer who can use this promotion code. |
expires_at | integer | Date at which the promotion code can no longer be redeemed. |
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`. |
max_redemptions | integer | Maximum number of times this promotion code can be redeemed. |
metadata | 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. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
promotion required | promotion_codes_resource_promotion | |
restrictions required | promotion_codes_resource_restrictions | |
times_redeemed required | integer | Number of times this promotion code has been used. |
HTTP default: Error response.
| Field | Type | Description |
|---|---|---|
error required | api_errors |
POST /v1/promotion_codes/{promotion_code}
Update a promotion code
Updates the specified promotion code by setting the values of the parameters passed. Most fields are, by design, not editable.
Request parameters
| Parameter | Location | Type | Description |
|---|---|---|---|
promotion_code | path | string |
| Field | Type | Description |
|---|---|---|
active | boolean | Whether the promotion code is currently active. A promotion code can only be reactivated when the coupon is still valid and the promotion code is otherwise redeemable. |
expand | array of string | Specifies which fields in the response should be expanded. |
metadata | one of multiple schemas | 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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. |
restrictions | object | Settings that restrict the redemption of the promotion code. |
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|---|---|
active required | boolean | Whether the promotion code is currently active. A promotion code is only active if the coupon is also valid. |
code required | string | The customer-facing code. Regardless of case, this code must be unique across all active promotion codes for each customer. Valid characters are lower case letters (a-z), upper case letters (A-Z), digits (0-9), and dashes (-). |
created required | integer | Time at which the object was created. Measured in seconds since the Unix epoch. |
customer | one of multiple schemas | The customer who can use this promotion code. |
customer_account | string | The account representing the customer who can use this promotion code. |
expires_at | integer | Date at which the promotion code can no longer be redeemed. |
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`. |
max_redemptions | integer | Maximum number of times this promotion code can be redeemed. |
metadata | 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. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
promotion required | promotion_codes_resource_promotion | |
restrictions required | promotion_codes_resource_restrictions | |
times_redeemed required | integer | Number of times this promotion code has been used. |
HTTP default: Error response.
| Field | Type | Description |
|---|---|---|
error required | api_errors |