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

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

  • couponobject

    Hash describing the coupon for this promotion code.

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

More attributes

  • objectstring

  • activeboolean

  • createdtimestamp

  • customernullable stringExpandable

  • expires_atnullable timestamp

  • livemodeboolean

  • max_redemptionsnullable integer

  • restrictionsobject

  • times_redeemedinteger

The Promotion Code object
{
  "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
}

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

  • customerstring

  • 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_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -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
}

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_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d "metadata[order_id]"=6735
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": {
    "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_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"
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
}

List all promotion codes 

Returns a list of your promotion codes.

Parameters

No parameters.

More parameters

  • activeboolean

  • codestring

  • couponstring

  • createdobject

  • customerstring

  • ending_beforestring

  • limitinteger

  • starting_afterstring

Returns

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

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