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

Promotion Code 

A Promotion Code represents a customer-redeemable code for an underlying promotion. You can create multiple codes for a single promotion.

If you enable promotion codes in your customer portal configuration, then customers can redeem a code themselves when updating a subscription in the portal. Customers can also view the currently active promotion codes and coupons on each of their subscriptions in the portal.

Endpoints

The Promotion Code object 

Attributes

  • idstring

    Unique identifier for the object.

  • codestring

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

  • metadatanullable object

    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.

  • promotionobject

    The promotion referenced by this promotion code.

More attributes

  • objectstring

  • activeboolean

  • createdtimestamp

  • customernullable stringExpandable

  • customer_accountnullable string

  • expires_atnullable timestamp

  • livemodeboolean

  • max_redemptionsnullable integer

  • restrictionsobject

  • times_redeemedinteger

The Promotion Code object
{
  "id": "promo_1MiM6KLkdIwHu7ixrIaX4wgn",
  "object": "promotion_code",
  "active": true,
  "code": "A1H1Q1MG",
  "promotion": {
    "type": "coupon",
    "coupon": "nVJYDOag"
  },
  "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
}

Create a promotion code 

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

Parameters

  • promotionobjectRequired

    The promotion referenced by 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.

    The maximum length is 500 characters.

  • 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

  • customerstring

  • customer_accountstring

  • expires_attimestamp

  • max_redemptionsinteger

  • restrictionsobject

Returns

Returns the promotion code object.

POST /v1/promotion_codes
curl https://api.stripe.com/v1/promotion_codes \
  -u "sk_test_Gx4mWEg...4DYMUIqfIrszsk_test_Gx4mWEgHtCMr4DYMUIqfIrsz:" \
  -d "promotion[type]"=coupon \
  -d "promotion[coupon]"=nVJYDOag
Response
{
  "id": "promo_1MiM6KLkdIwHu7ixrIaX4wgn",
  "object": "promotion_code",
  "active": true,
  "code": "A1H1Q1MG",
  "promotion": {
    "type": "coupon",
    "coupon": "nVJYDOag"
  },
  "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
}

Update a promotion code 

Updates the specified promotion code by setting the values of the parameters passed. Most fields 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.

More parameters

  • activeboolean

  • restrictionsobject

Returns

The updated promotion code object is returned upon success. Otherwise, this call raises an error.

POST /v1/promotion_codes/:id
curl https://api.stripe.com/v1/promotion_codes/promo_1MiM6KLkdIwHu7ixrIaX4wgn \
  -u "sk_test_Gx4mWEg...4DYMUIqfIrszsk_test_Gx4mWEgHtCMr4DYMUIqfIrsz:" \
  -d "metadata[order_id]"=6735
Response
{
  "id": "promo_1MiM6KLkdIwHu7ixrIaX4wgn",
  "object": "promotion_code",
  "active": true,
  "code": "A1H1Q1MG",
  "promotion": {
    "type": "coupon",
    "coupon": "nVJYDOag"
  },
  "created": 1678040164,
  "customer": null,
  "expires_at": null,
  "livemode": false,
  "max_redemptions": null,
  "metadata": {
    "order_id": "6735"
  },
  "restrictions": {
    "first_time_transaction": false,
    "minimum_amount": null,
    "minimum_amount_currency": null
  },
  "times_redeemed": 0
}

Retrieve a promotion code 

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.

Parameters

No parameters.

Returns

Returns a promotion code if a valid promotion code ID was provided. Raises an error otherwise.

GET /v1/promotion_codes/:id
curl https://api.stripe.com/v1/promotion_codes/promo_1MiM6KLkdIwHu7ixrIaX4wgn \
  -u "sk_test_Gx4mWEg...4DYMUIqfIrszsk_test_Gx4mWEgHtCMr4DYMUIqfIrsz:"
Response
{
  "id": "promo_1MiM6KLkdIwHu7ixrIaX4wgn",
  "object": "promotion_code",
  "active": true,
  "code": "A1H1Q1MG",
  "promotion": {
    "type": "coupon",
    "coupon": "nVJYDOag"
  },
  "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
}