Create a coupon
POST / v1 / coupons
You can create coupons easily via the coupon management page of the Stripe dashboard. Coupon creation is also accessible via the API if you need to create coupons on the fly.
A coupon has either a percent_off or an amount_off and currency. If you set an amount_off, that amount will be subtracted from any invoice’s subtotal. For example, an invoice with a subtotal of 100 USD will have a final total of 0 USD if a coupon with an amount_off of 20000 is applied to it and an invoice with a subtotal of 300 USD will have a final total of 100 USD if a coupon with an amount_off of 20000 is applied to it.
Parameters
- amount _ off integer A positive integer representing the amount to subtract from an invoice total (required if
percent_offis not passed). - currency enum Three-letter ISO code for the currency of the
amount_offparameter (required ifamount_offis passed). - duration enum Specifies how long the discount will be in effect if used on a subscription. Defaults to
once. Possible enum valuesforeverApplies to all charges from a subscription with this coupon applied.onceApplies to the first charge from a subscription with this coupon applied.repeatingApplies to charges in the firstduration_in_monthsmonths from a subscription with this coupon applied. - metadata map Set 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. - name string Name of the coupon displayed to customers on, for instance invoices, or receipts. By default the
idis shown ifnameis not set. The maximum length is 40 characters. - percent _ off number A positive float larger than 0, and smaller or equal to 100, that represents the discount the coupon will apply (required if
amount_offis not passed).
More parameters
- applies _ to object
- currency _ options map
- duration _ in _ months integer
- id string
- max _ redemptions integer
- redeem _ by timestamp
Returns
Returns the coupon object.
Response
{ "id": "jMT0WJUD", "object": "coupon", "amount_off": null, "created": 1678037688, "currency": null, "duration": "forever", "livemode": false, "max_redemptions": null, "metadata": {}, "name": null, "percent_off": 25.5, "redeem_by": null, "times_redeemed": 0, "valid": true}
Update a coupon
POST / v1 / coupons /:id
Updates the metadata of a coupon. Other coupon details (currency, duration, amount_off) are, by design, not editable.
Parameters
- metadata map Set 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. - name string Name of the coupon displayed to customers on, for instance invoices, or receipts. By default the
idis shown ifnameis not set. The maximum length is 40 characters.
More parameters
- currency _ options map
Returns
The newly updated coupon object if the call succeeded. Otherwise, this call raises an error, such as if the coupon has been deleted.
Response
{ "id": "jMT0WJUD", "object": "coupon", "amount_off": null, "created": 1678037688, "currency": null, "duration": "repeating", "duration_in_months": 3, "livemode": false, "max_redemptions": null, "metadata": { "order_id": "6735" }, "name": null, "percent_off": 25.5, "redeem_by": null, "times_redeemed": 0, "valid": true}
Retrieve a coupon
GET / v1 / coupons /:id
Retrieves the coupon with the given ID.
Parameters
No parameters.
Returns
Returns a coupon if a valid coupon ID was provided. Raises an error otherwise.
Response
{ "id": "jMT0WJUD", "object": "coupon", "amount_off": null, "created": 1678037688, "currency": null, "duration": "repeating", "duration_in_months": 3, "livemode": false, "max_redemptions": null, "metadata": {}, "name": null, "percent_off": 25.5, "redeem_by": null, "times_redeemed": 0, "valid": true}