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
Privacy
Webhooks

Create a promotion code 

Products
Promotion Code
Create a promotion code

A promotion code points to a coupon. You can optionally restrict the code to a specific customer, redemption limit, and expiration date.

Parameters

  • couponstringRequired

    The coupon for this promotion code.

  • codestring

    The customer-facing code. Regardless of case, this code must be unique across all active promotion codes for a specific customer. Valid characters are lower case letters (a-z), upper case letters (A-Z), and digits (0-9).

    If left blank, we will generate one automatically.

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

More parameters

  • activeboolean

    Whether the promotion code is currently active.

  • customerstring

    The customer that this promotion code can be used by. If not set, the promotion code can be used by all customers.

  • expires_attimestamp

    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.

  • max_redemptionsinteger

    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.

  • restrictionsobject

    Settings that restrict the redemption of the promotion code.

    • restrictions.currency_optionsobject

      Promotion codes defined in each available currency option. Each key must be a three-letter ISO currency code and a supported currency.

      • restrictions.currency_options.<currency>.minimum_amountinteger

        Minimum amount required to redeem this Promotion Code into a Coupon (e.g., a purchase must be $100 or more to work).

    • restrictions.first_time_transactionboolean

      A Boolean indicating if the Promotion Code should only be redeemed for Customers without any successful payments or invoices

    • restrictions.minimum_amountinteger

      Minimum amount required to redeem this Promotion Code into a Coupon (e.g., a purchase must be $100 or more to work).

    • restrictions.minimum_amount_currencyenum

      Three-letter ISO code for minimum_amount

Returns

Returns the promotion code object.

POST /v1/promotion_codes
curl https://api.stripe.com/v1/promotion_codes \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d coupon=nVJYDOag
Response
{
  "id": "promo_1MiM6KLkdIwHu7ixrIaX4wgn",
  "object": "promotion_code",
  "active": true,
  "code": "A1H1Q1MG",
  "coupon": {
    "id": "nVJYDOag",
    "object": "coupon",
    "amount_off": null,
    "created": 1678040164,
    "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
  },
  "created": 1678040164,
  "customer": null,
  "expires_at": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {},
  "restrictions": {
    "first_time_transaction": false,
    "minimum_amount": null,
    "minimum_amount_currency": null
  },
  "times_redeemed": 0
}