Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Fraud
Issuing
Terminal
Treasury
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Webhooks

Create a coupon 

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_offinteger

    A positive integer representing the amount to subtract from an invoice total (required if percent_off is not passed).

  • currencyenum

    Three-letter ISO code for the currency of the amount_off parameter (required if amount_off is passed).

  • durationenum

    Specifies how long the discount will be in effect if used on a subscription. Defaults to once.

    Possible enum values
    forever

    Applies to all charges from a subscription with this coupon applied.

    once

    Applies to the first charge from a subscription with this coupon applied.

    repeating

    Applies to charges in the first duration_in_months months from a subscription with this coupon applied.

  • duration_in_monthsinteger

    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.

  • metadataobject

    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.

  • namestring

    Name of the coupon displayed to customers on, for instance invoices, or receipts. By default the id is shown if name is not set.

  • percent_offfloat

    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).

More parameters

  • applies_toobject

  • currency_optionsobject

  • idstring

  • max_redemptionsinteger

  • redeem_bytimestamp

Returns

Returns the coupon object.

POST /v1/coupons
curl https://api.stripe.com/v1/coupons \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d duration=repeating \
  -d duration_in_months=3 \
  -d percent_off="25.5"
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
}

Update a coupon 

Updates the metadata of a coupon. Other coupon details (currency, duration, amount_off) are, by design, not editable.

Parameters

  • metadataobject

    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.

  • namestring

    Name of the coupon displayed to customers on, for instance invoices, or receipts. By default the id is shown if name is not set.

More parameters

  • currency_optionsobject

Returns

The newly updated coupon object if the call succeeded. Otherwise, this call raises an error, such as if the coupon has been deleted.

POST /v1/coupons/:id
curl https://api.stripe.com/v1/coupons/jMT0WJUD \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d "metadata[order_id]"=6735
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 

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.

GET /v1/coupons/:id
curl https://api.stripe.com/v1/coupons/jMT0WJUD \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"
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
}

List all coupons 

Returns a list of your coupons.

Parameters

No parameters.

More parameters

  • createdobject

  • ending_beforestring

  • limitinteger

  • starting_afterstring

Returns

A dictionary with a data property that contains an array of up to limit coupons, starting after coupon starting_after. Each entry in the array is a separate coupon object. If no more coupons are available, the resulting array will be empty.

GET /v1/coupons
curl -G https://api.stripe.com/v1/coupons \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d limit=3
Response
{
  "object": "list",
  "url": "/v1/coupons",
  "has_more": false,
  "data": [
    {
      "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
    }
  ]
}

Delete a coupon 

You can delete coupons via the coupon management 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.

Parameters

No parameters.

Returns

An object with the deleted coupon’s ID and a deleted flag upon success. Otherwise, this call raises an error, such as if the coupon has already been deleted.

DELETE /v1/coupons/:id
curl -X DELETE https://api.stripe.com/v1/coupons/jMT0WJUD \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"
Response
{
  "id": "jMT0WJUD",
  "object": "coupon",
  "deleted": true
}