A Promotion Code represents a customer-redeemable code for a coupon. It can be used to create multiple codes for a single coupon.
Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/stripe-promotion-codes-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Stripe Promotion Codes API
description: Needs description.
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: Returns a list of your promotion codes.
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
summary: Get promotion codes
x-summary-source: derived
post:
description: A promotion code points to a coupon. You can optionally restrict the code to a specific customer, redemption limit, and expiration date.
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
summary: Post promotion codes
x-summary-source: derived
/v1/promotion_codes/{promotion_code}:
get:
description: 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.
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
summary: Get promotion codes promotion code
x-summary-source: derived
post:
description: Updates the specified promotion code by setting the values of the parameters passed. Most fields are, by design, not editable.
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
summary: Post promotion codes promotion code
x-summary-source: derived
components:
schemas:
error:
description: An error response from the Stripe API
properties:
error:
$ref: '#/components/schemas/api_errors'
required:
- error
type: object
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
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
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
GetPromotionCodesRequest:
type: object
properties: {}
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.
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
type:
- integer
- 'null'
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.
type:
- integer
- 'null'
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.
type:
- object
- 'null'
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
securitySchemes:
basicAuth:
description: 'Basic HTTP authentication. Allowed headers-- Authorization: Basic <api_key> | Authorization: Basic <base64 hash of `api_key:`>'
scheme: basic
type: http
bearerAuth:
bearerFormat: auth-scheme
description: 'Bearer HTTP authentication. Allowed headers-- Authorization: Bearer <api_key>'
scheme: bearer
type: http