A coupon contains information about a percent-off or amount-off discount you might want to apply to a customer. Coupons may be applied to subscriptions, invoices, checkout sessions, quotes, and more. Coupons do not work with conventional one-off charges or payment intents.
openapi: 3.0.0
info:
title: Stripe Coupons API
description: >-
A coupon contains information about a percent-off or amount-off discount you
might want to apply to a customer. Coupons may be applied to subscriptions,
invoices, checkout sessions, quotes, and more. Coupons do not work with
conventional one-off charges or payment intents.
contact:
email: [email protected]
name: Stripe Dev Platform Team
url: https://stripe.com
termsOfService: https://stripe.com/us/terms/
version: '2023-10-16'
x-stripeSpecFilename: spec3
security:
- basicAuth: []
- bearerAuth: []
servers:
- url: https://api.stripe.com/
paths:
/v1/coupons:
get:
description: <p>Returns a list of your coupons.</p>
operationId: getCoupons
parameters:
- 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: >-
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/GetCouponsRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/CouponsResourceCouponList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Coupons
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
PullTagsFromSummary: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Coupons
- Get
post:
description: >-
<p>You can create coupons easily via the <a
href="https://dashboard.stripe.com/coupons">coupon management</a> page
of the Stripe dashboard. Coupon creation is also accessible via the API
if you need to create coupons on the fly.</p>
<p>A coupon has either a <code>percent_off</code> or an
<code>amount_off</code> and <code>currency</code>. If you set an
<code>amount_off</code>, that amount will be subtracted from any
invoice’s subtotal. For example, an invoice with a subtotal of
<currency>100</currency> will have a final total of
<currency>0</currency> if a coupon with an <code>amount_off</code> of
<amount>200</amount> is applied to it and an invoice with a subtotal of
<currency>300</currency> will have a final total of
<currency>100</currency> if a coupon with an <code>amount_off</code> of
<amount>200</amount> is applied to it.</p>
operationId: postCoupons
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
applies_to:
explode: true
style: deepObject
currency_options:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostCouponsRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/coupon'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Coupons
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
PullTagsFromSummary: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Coupons
- Post
/v1/coupons/{coupon}:
delete:
description: >-
<p>You can delete coupons via the <a
href="https://dashboard.stripe.com/coupons">coupon management</a> page
of the Stripe dashboard. However, deleting a coupon does not affect any
customers who have already applied the coupon; it means that new
customers can’t redeem the coupon. You can also delete coupons via the
API.</p>
operationId: deleteCouponsCoupon
parameters:
- in: path
name: coupon
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/DeleteCouponsCouponRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/deleted_coupon'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Delete Coupons Coupon
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
PullTagsFromSummary: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Coupon
- Coupons
- Delete
get:
description: <p>Retrieves the coupon with the given ID.</p>
operationId: getCouponsCoupon
parameters:
- in: path
name: coupon
required: true
schema:
maxLength: 5000
type: string
style: simple
- 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
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetCouponsCouponRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/coupon'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Coupons Coupon
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
PullTagsFromSummary: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Coupon
- Coupons
- Get
post:
description: >-
<p>Updates the metadata of a coupon. Other coupon details (currency,
duration, amount_off) are, by design, not editable.</p>
operationId: postCouponsCoupon
parameters:
- in: path
name: coupon
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
currency_options:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostCouponsCouponRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/coupon'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Coupons Coupon
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
PullTagsFromSummary: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Coupon
- Coupons
- Post
components:
schemas:
error:
description: An error response from the Stripe API
properties:
error:
$ref: '#/components/schemas/api_errors'
required:
- error
type: object
coupon:
description: >-
A coupon contains information about a percent-off or amount-off discount
you
might want to apply to a customer. Coupons may be applied to
[subscriptions](https://stripe.com/docs/api#subscriptions),
[invoices](https://stripe.com/docs/api#invoices),
[checkout sessions](https://stripe.com/docs/api/checkout/sessions),
[quotes](https://stripe.com/docs/api#quotes), and more. Coupons do not
work with conventional one-off
[charges](https://stripe.com/docs/api#create_charge) or [payment
intents](https://stripe.com/docs/api/payment_intents).
properties:
amount_off:
description: >-
Amount (in the `currency` specified) that will be taken off the
subtotal of any invoices for this customer.
nullable: true
type: integer
applies_to:
$ref: '#/components/schemas/coupon_applies_to'
created:
description: >-
Time at which the object was created. Measured in seconds since the
Unix epoch.
format: unix-time
type: integer
currency:
description: >-
If `amount_off` has been set, the three-letter [ISO code for the
currency](https://stripe.com/docs/currencies) of the amount to take
off.
nullable: true
type: string
currency_options:
additionalProperties:
$ref: '#/components/schemas/coupon_currency_option'
description: >-
Coupons defined in each available currency option. Each key must be
a three-letter [ISO currency
code](https://www.iso.org/iso-4217-currency-codes.html) and a
[supported currency](https://stripe.com/docs/currencies).
type: object
duration:
description: >-
One of `forever`, `once`, and `repeating`. Describes how long a
customer who applies this coupon will get the discount.
enum:
- forever
- once
- repeating
type: string
x-stripeBypassValidation: true
duration_in_months:
description: >-
If `duration` is `repeating`, the number of months the coupon
applies. Null if coupon `duration` is `forever` or `once`.
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 coupon can be redeemed, in total,
across all customers, before it is no longer valid.
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
name:
description: >-
Name of the coupon displayed to customers on for instance invoices
or receipts.
maxLength: 5000
nullable: true
type: string
object:
description: >-
String representing the object's type. Objects of the same type
share the same value.
enum:
- coupon
type: string
percent_off:
description: >-
Percent that will be taken off the subtotal of any invoices for this
customer for the duration of the coupon. For example, a coupon with
percent_off of 50 will make a $ (or local equivalent)100 invoice $
(or local equivalent)50 instead.
nullable: true
type: number
redeem_by:
description: Date after which the coupon can no longer be redeemed.
format: unix-time
nullable: true
type: integer
times_redeemed:
description: Number of times this coupon has been applied to a customer.
type: integer
valid:
description: >-
Taking account of the above properties, whether this coupon can
still be applied to a customer.
type: boolean
required:
- created
- duration
- id
- livemode
- object
- times_redeemed
- valid
title: Coupon
type: object
x-expandableFields:
- applies_to
- currency_options
x-resourceId: coupon
deleted_coupon:
description: ''
properties:
deleted:
description: Always true for a deleted object
enum:
- true
type: boolean
id:
description: Unique identifier for the object.
maxLength: 5000
type: string
object:
description: >-
String representing the object's type. Objects of the same type
share the same value.
enum:
- coupon
type: string
required:
- deleted
- id
- object
title: DeletedCoupon
type: object
x-expandableFields: []
x-resourceId: deleted_coupon
GetCouponsRequest:
type: object
properties: {}
CouponsResourceCouponList:
type: object
required:
- data
- has_more
- object
- url
properties:
data:
items:
$ref: '#/components/schemas/coupon'
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/coupons
type: string
PostCouponsRequest:
type: object
properties:
amount_off:
description: >-
A positive integer representing the amount to subtract from an
invoice total (required if `percent_off` is not passed).
type: integer
applies_to:
description: >-
A hash containing directions for what this Coupon will apply
discounts to.
properties:
products:
items:
maxLength: 5000
type: string
type: array
title: applies_to_params
type: object
currency:
description: >-
Three-letter [ISO code for the
currency](https://stripe.com/docs/currencies) of the `amount_off`
parameter (required if `amount_off` is passed).
type: string
currency_options:
additionalProperties:
properties:
amount_off:
type: integer
required:
- amount_off
title: currency_option
type: object
description: >-
Coupons defined in each available currency option (only supported if
`amount_off` is passed). Each key must be a three-letter [ISO
currency code](https://www.iso.org/iso-4217-currency-codes.html) and
a [supported currency](https://stripe.com/docs/currencies).
type: object
duration:
description: >-
Specifies how long the discount will be in effect if used on a
subscription. Defaults to `once`.
enum:
- forever
- once
- repeating
type: string
x-stripeBypassValidation: true
duration_in_months:
description: >-
Required only if `duration` is `repeating`, in which case it must be
a positive integer that specifies the number of months the discount
will be in effect.
type: integer
expand:
description: Specifies which fields in the response should be expanded.
items:
maxLength: 5000
type: string
type: array
id:
description: >-
Unique string of your choice that will be used to identify this
coupon when applying it to a customer. If you don't want to specify
a particular code, you can leave the ID blank and we'll generate a
random code for you.
maxLength: 5000
type: string
max_redemptions:
description: >-
A positive integer specifying the number of times the coupon can be
redeemed before it's no longer valid. For example, you might have a
50% off coupon that the first 20 readers of your blog can use.
type: integer
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`.
name:
description: >-
Name of the coupon displayed to customers on, for instance invoices,
or receipts. By default the `id` is shown if `name` is not set.
maxLength: 40
type: string
percent_off:
description: >-
A positive float larger than 0, and smaller or equal to 100, that
represents the discount the coupon will apply (required if
`amount_off` is not passed).
type: number
redeem_by:
description: >-
Unix timestamp specifying the last time at which the coupon can be
redeemed. After the redeem_by date, the coupon can no longer be
applied to new customers.
format: unix-time
type: integer
DeleteCouponsCouponRequest:
type: object
properties: {}
GetCouponsCouponRequest:
type: object
properties: {}
PostCouponsCouponRequest:
type: object
properties:
currency_options:
additionalProperties:
properties:
amount_off:
type: integer
required:
- amount_off
title: currency_option
type: object
description: >-
Coupons defined in each available currency option (only supported if
the coupon is amount-based). Each key must be a three-letter [ISO
currency code](https://www.iso.org/iso-4217-currency-codes.html) and
a [supported currency](https://stripe.com/docs/currencies).
type: object
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`.
name:
description: >-
Name of the coupon displayed to customers on, for instance invoices,
or receipts. By default the `id` is shown if `name` is not set.
maxLength: 40
type: string
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
tags:
- name: Coupon
- name: Coupons
- name: Delete
- name: Get
- name: Post