Stripe Promotion Codes API
A Promotion Code represents a customer-redeemable code for a coupon. It can be used to create multiple codes for a single coupon.
OpenAPI Specification
openapi: 3.0.0
info:
title: Stripe Accounts Account Promotion Codes API
description: This is an object representing a Stripe account. You can retrieve it to see properties on the account like its current requirements or if the account is enabled to make live charges or receive payouts.
contact:
email: dev-platform@stripe.com
name: Stripe Dev Platform Team
url: https://stripe.com
termsOfService: https://stripe.com/us/terms/
version: '2023-10-16'
x-stripeSpecFilename: spec3
servers:
- url: https://api.stripe.com/
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Promotion Codes
paths:
/v1/promotion_codes:
get:
description: <p>Returns a list of your promotion codes.</p>
operationId: GetPromotionCodes
parameters:
- description: Filter promotion codes by whether they are active.
in: query
name: active
required: false
schema:
type: boolean
style: form
- description: Only return promotion codes that have this case-insensitive code.
in: query
name: code
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Only return promotion codes for this coupon.
in: query
name: coupon
required: false
schema:
maxLength: 5000
type: string
style: form
- description: 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.
explode: true
in: query
name: created
required: false
schema:
anyOf:
- properties:
gt:
type: integer
gte:
type: integer
lt:
type: integer
lte:
type: integer
title: range_query_specs
type: object
- type: integer
style: deepObject
- description: Only return promotion codes that are restricted to this customer.
in: query
name: customer
required: false
schema:
maxLength: 5000
type: string
style: form
- description: 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.
in: query
name: ending_before
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- description: 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.
in: query
name: starting_after
required: false
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetPromotionCodesRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/PromotionCodesResourcePromotionCodeList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Promotion Codes
post:
description: <p>A promotion code points to a coupon. You can optionally restrict the code to a specific customer, redemption limit, and expiration date.</p>
operationId: PostPromotionCodes
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
restrictions:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostPromotionCodesRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/promotion_code'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Promotion Codes
/v1/promotion_codes/{promotion_code}:
get:
description: <p>Retrieves the promotion code with the given ID. In order to retrieve a promotion code by the customer-facing <code>code</code> use <a href="/docs/api/promotion_codes/list">list</a> with the desired <code>code</code>.</p>
operationId: GetPromotionCodesPromotionCode
parameters:
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- in: path
name: promotion_code
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetPromotionCodesPromotionCodeRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/promotion_code'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Promotion Codes
post:
description: <p>Updates the specified promotion code by setting the values of the parameters passed. Most fields are, by design, not editable.</p>
operationId: PostPromotionCodesPromotionCode
parameters:
- in: path
name: promotion_code
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
restrictions:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostPromotionCodesPromotionCodeRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/promotion_code'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Promotion Codes
components:
schemas:
GetPromotionCodesPromotionCodeRequest:
type: object
properties: {}
promotion_code:
description: 'A Promotion Code represents a customer-redeemable code for a [coupon](https://stripe.com/docs/api#coupons). It can be used to
create multiple codes for a single coupon.'
properties:
active:
description: Whether the promotion code is currently active. A promotion code is only active if the coupon is also valid.
type: boolean
code:
description: The customer-facing code. Regardless of case, this code must be unique across all active promotion codes for each customer.
maxLength: 5000
type: string
coupon:
$ref: '#/components/schemas/coupon'
created:
description: Time at which the object was created. Measured in seconds since the Unix epoch.
format: unix-time
type: integer
customer:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/customer'
- $ref: '#/components/schemas/deleted_customer'
description: The customer that this promotion code can be used by.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/customer'
- $ref: '#/components/schemas/deleted_customer'
expires_at:
description: Date at which the promotion code can no longer be redeemed.
format: unix-time
nullable: true
type: integer
id:
description: Unique identifier for the object.
maxLength: 5000
type: string
livemode:
description: Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.
type: boolean
max_redemptions:
description: Maximum number of times this promotion code can be redeemed.
nullable: true
type: integer
metadata:
additionalProperties:
maxLength: 500
type: string
description: Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
nullable: true
type: object
object:
description: String representing the object's type. Objects of the same type share the same value.
enum:
- promotion_code
type: string
restrictions:
$ref: '#/components/schemas/promotion_codes_resource_restrictions'
times_redeemed:
description: Number of times this promotion code has been used.
type: integer
required:
- active
- code
- coupon
- created
- id
- livemode
- object
- restrictions
- times_redeemed
title: PromotionCode
type: object
x-expandableFields:
- coupon
- customer
- restrictions
x-resourceId: promotion_code
error:
description: An error response from the Stripe API
properties:
error:
$ref: '#/components/schemas/api_errors'
required:
- error
type: object
PostPromotionCodesPromotionCodeRequest:
type: object
properties:
active:
description: 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.
type: boolean
expand:
description: Specifies which fields in the response should be expanded.
items:
maxLength: 5000
type: string
type: array
metadata:
anyOf:
- additionalProperties:
type: string
type: object
- enum:
- ''
type: string
description: Set of [key-value pairs](https://stripe.com/docs/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:
description: Settings that restrict the redemption of the promotion code.
properties:
currency_options:
additionalProperties:
properties:
minimum_amount:
type: integer
title: currency_option
type: object
type: object
title: restrictions_params
type: object
PromotionCodesResourcePromotionCodeList:
type: object
required:
- data
- has_more
- object
- url
properties:
data:
items:
$ref: '#/components/schemas/promotion_code'
type: array
has_more:
description: True if this list has another page of items after this one that can be fetched.
type: boolean
object:
description: String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
enum:
- list
type: string
url:
description: The URL where this list can be accessed.
maxLength: 5000
pattern: ^/v1/promotion_codes
type: string
GetPromotionCodesRequest:
type: object
properties: {}
PostPromotionCodesRequest:
type: object
required:
- coupon
properties:
active:
description: Whether the promotion code is currently active.
type: boolean
code:
description: The customer-facing code. Regardless of case, this code must be unique across all active promotion codes for a specific customer. If left blank, we will generate one automatically.
maxLength: 500
type: string
coupon:
description: The coupon for this promotion code.
maxLength: 5000
type: string
customer:
description: The customer that this promotion code can be used by. If not set, the promotion code can be used by all customers.
maxLength: 5000
type: string
expand:
description: Specifies which fields in the response should be expanded.
items:
maxLength: 5000
type: string
type: array
expires_at:
description: 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`.
format: unix-time
type: integer
max_redemptions:
description: 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`.
type: integer
metadata:
additionalProperties:
type: string
description: Set of [key-value pairs](https://stripe.com/docs/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`.
type: object
restrictions:
description: Settings that restrict the redemption of the promotion code.
properties:
currency_options:
additionalProperties:
properties:
minimum_amount:
type: integer
title: currency_option
type: object
type: object
first_time_transaction:
type: boolean
minimum_amount:
type: integer
minimum_amount_currency:
type: string
title: restrictions_params
type: object