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

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

  • coupondictionary

    Hash describing the coupon for this promotion code.

  • metadatanullable dictionary

    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

  • restrictionsdictionary

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

  • metadatadictionary

    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

  • restrictionsdictionary

Returns

Returns the promotion code object.

POST /v1/promotion_codes
import stripe
stripe.api_key = "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2"
promotion_code = stripe.PromotionCode.create(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

  • metadatadictionary

    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

  • restrictionsdictionary

Returns

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

POST /v1/promotion_codes/:id
import stripe
stripe.api_key = "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2"
promotion_code = stripe.PromotionCode.modify(
  "promo_1MiM6KLkdIwHu7ixrIaX4wgn",
  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
import stripe
stripe.api_key = "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2"
promotion_code = stripe.PromotionCode.retrieve("promo_1MiM6KLkdIwHu7ixrIaX4wgn")
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

  • createddictionary

  • 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
import stripe
stripe.api_key = "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2"
promotion_codes = stripe.PromotionCode.list(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
    }
  ]
}