API reference
Promotion Codes
A Promotion Code represents a customer-redeemable code for an underlying promotion. You can create multiple codes for a single promotion. If you enable promotion codes in your customer portal configuration, then customers can redeem a code themselves when updating a subscription in the portal. Customers can also view the currently active promotion codes and coupons on each of their subscriptions in the portal.
https://api.knoxapi.comCreate a promotion code
POST/v1/promotion_codes
A promotion code points to an underlying promotion. You can optionally restrict the code to a specific customer, redemption limit, and expiration date.
Body parameters
promotionobjectRequiredThe promotion referenced by this promotion code.
Show 2 child parameters
typestringRequiredPossible valuescoupon
couponstring
activebooleanWhether the promotion code is currently active.
codestringThe 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.
customerstringThe customer who can use this promotion code. If not set, all customers can use the promotion code.
customer_accountstringThe account representing the customer who can use this promotion code. If not set, all customers can use the promotion code.
expandarray of stringsSpecifies which fields in the response should be expanded.
expires_atintegerThe timestamp at which this promotion code will expire. If the coupon has specified a
redeems_by, then this value cannot be after the coupon'sredeems_by.max_redemptionsintegerA 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'smax_redemptions.metadataobjectSet of key-value pairs 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.restrictionsobjectSettings that restrict the redemption of the promotion code.
Show 4 child parameters
currency_optionsobjectfirst_time_transactionbooleanminimum_amountintegerminimum_amount_currencystring
Returns
The promotion_code object.
curl https://api.knoxapi.com/v1/promotion_codes \
-H "Authorization: Bearer $KNOX_SECRET_KEY" \
-d "promotion[type]=coupon"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const promotionCode = await stripe.promotionCodes.create({
promotion: {
type: 'coupon',
},
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
promotion_code = client.v1.promotion_codes.create(params={
"promotion": {
"type": "coupon",
},
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
promotion_code = Stripe::PromotionCode.create({
promotion: {
type: 'coupon',
},
}){
"active": false,
"code": "FALL20",
"created": 1234567890,
"customer": null,
"expires_at": 1234567890,
"id": "promo_1Pgc79B7WZ01zgkWNy4mn5NX",
"livemode": false,
"max_redemptions": null,
"metadata": {},
"object": "promotion_code",
"restrictions": {
"first_time_transaction": false,
"minimum_amount": null,
"minimum_amount_currency": null
},
"times_redeemed": 0,
"promotion": {
"coupon": null,
"type": "coupon"
},
"customer_account": null
}List all promotion codes
GET/v1/promotion_codes
Returns a list of your promotion codes.
Query parameters
activebooleanFilter promotion codes by whether they are active.
codestringOnly return promotion codes that have this case-insensitive code.
couponstringOnly return promotion codes for this coupon.
createdobject | integerA filter on the list, based on the object
createdfield. The value can be a string with an integer Unix timestamp, or it can be a dictionary with a number of different query options.Show 4 child parameters
gtintegergteintegerltintegerlteinteger
customerstringOnly return promotion codes that are restricted to this customer.
customer_accountstringOnly return promotion codes that are restricted to this account representing the customer.
ending_beforestringA cursor for use in pagination.
ending_beforeis an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting withobj_bar, your subsequent call can includeending_before=obj_barin order to fetch the previous page of the list.expandarray of stringsSpecifies which fields in the response should be expanded.
limitintegerA limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
starting_afterstringA cursor for use in pagination.
starting_afteris an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending withobj_foo, your subsequent call can includestarting_after=obj_fooin order to fetch the next page of the list.
Returns
A list of promotion_code objects.
curl -G https://api.knoxapi.com/v1/promotion_codes \
-H "Authorization: Bearer $KNOX_SECRET_KEY" \
--data-urlencode limit=3const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const page = await stripe.promotionCodes.list({
limit: 3,
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
page = client.v1.promotion_codes.list(params={
"limit": 3,
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
page = Stripe::PromotionCode.list({
limit: 3,
}){
"object": "list",
"url": "/v1/promotion_codes",
"has_more": false,
"data": [
{
"active": false,
"code": "FALL20",
"created": 1234567890,
"customer": null,
"expires_at": 1234567890,
"id": "promo_1Pgc79B7WZ01zgkWNy4mn5NX",
"livemode": false,
"max_redemptions": null,
"metadata": {},
"object": "promotion_code",
"restrictions": {
"first_time_transaction": false,
"minimum_amount": null,
"minimum_amount_currency": null
},
"times_redeemed": 0,
"promotion": {
"coupon": null,
"type": "coupon"
},
"customer_account": null
}
]
}Update a promotion code
POST/v1/promotion_codes/{promotion_code}
Updates the specified promotion code by setting the values of the parameters passed. Most fields are, by design, not editable.
Path parameters
promotion_codestringRequired
Body parameters
activebooleanWhether 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.
expandarray of stringsSpecifies which fields in the response should be expanded.
metadataobjectSet of key-value pairs 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.restrictionsobjectSettings that restrict the redemption of the promotion code.
Show 1 child parameter
currency_optionsobject
Returns
The promotion_code object.
curl https://api.knoxapi.com/v1/promotion_codes/promo_1Pgc79B7WZ01zgkWNy4mn5NX \
-H "Authorization: Bearer $KNOX_SECRET_KEY" \
-d "metadata[order_id]=6735"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const promotionCode = await stripe.promotionCodes.update('promo_1Pgc79B7WZ01zgkWNy4mn5NX', {
metadata: {
order_id: '6735',
},
});import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
promotion_code = client.v1.promotion_codes.update("promo_1Pgc79B7WZ01zgkWNy4mn5NX", params={
"metadata": {
"order_id": "6735",
},
})require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
promotion_code = Stripe::PromotionCode.update('promo_1Pgc79B7WZ01zgkWNy4mn5NX', {
metadata: {
order_id: '6735',
},
}){
"active": false,
"code": "FALL20",
"created": 1234567890,
"customer": null,
"expires_at": 1234567890,
"id": "promo_1Pgc79B7WZ01zgkWNy4mn5NX",
"livemode": false,
"max_redemptions": null,
"metadata": {},
"object": "promotion_code",
"restrictions": {
"first_time_transaction": false,
"minimum_amount": null,
"minimum_amount_currency": null
},
"times_redeemed": 0,
"promotion": {
"coupon": null,
"type": "coupon"
},
"customer_account": null
}Retrieve a promotion code
GET/v1/promotion_codes/{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.
Path parameters
promotion_codestringRequired
Query parameters
expandarray of stringsSpecifies which fields in the response should be expanded.
Returns
The promotion_code object.
curl https://api.knoxapi.com/v1/promotion_codes/promo_1Pgc79B7WZ01zgkWNy4mn5NX \
-H "Authorization: Bearer $KNOX_SECRET_KEY"const Stripe = require('stripe');
const stripe = new Stripe(process.env.KNOX_SECRET_KEY, {host: 'api.knoxapi.com'});
const promotionCode = await stripe.promotionCodes.retrieve('promo_1Pgc79B7WZ01zgkWNy4mn5NX');import os
import stripe
client = stripe.StripeClient(
os.environ["KNOX_SECRET_KEY"],
base_addresses={"api": "https://api.knoxapi.com"},
)
promotion_code = client.v1.promotion_codes.retrieve("promo_1Pgc79B7WZ01zgkWNy4mn5NX")require 'stripe'
Stripe.api_key = ENV['KNOX_SECRET_KEY']
Stripe.api_base = 'https://api.knoxapi.com'
promotion_code = Stripe::PromotionCode.retrieve('promo_1Pgc79B7WZ01zgkWNy4mn5NX'){
"active": false,
"code": "FALL20",
"created": 1234567890,
"customer": null,
"expires_at": 1234567890,
"id": "promo_1Pgc79B7WZ01zgkWNy4mn5NX",
"livemode": false,
"max_redemptions": null,
"metadata": {},
"object": "promotion_code",
"restrictions": {
"first_time_transaction": false,
"minimum_amount": null,
"minimum_amount_currency": null
},
"times_redeemed": 0,
"promotion": {
"coupon": null,
"type": "coupon"
},
"customer_account": null
}Operations and schemas come from the pinned Stripe OpenAPI specification (MIT); response examples from its fixtures. Nested object definitions and enums are in the complete specification.