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

The Promotion Code object 

Products
Promotion Code
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.

    • promotion.couponnullable stringExpandable

      If promotion type is coupon, the coupon for this promotion.

    • promotion.typeenum

      The type of promotion.

      Possible enum values
      coupon

      Coupon promotion type.

More attributes

  • objectstring

    String representing the object’s type. Objects of the same type share the same value.

  • activeboolean

    Whether the promotion code is currently active. A promotion code is only active if the coupon is also valid.

  • createdtimestamp

    Time at which the object was created. Measured in seconds since the Unix epoch.

  • customernullable stringExpandable

    The customer that this promotion code can be used by.

  • expires_atnullable timestamp

    Date at which the promotion code can no longer be redeemed.

  • livemodeboolean

    Has the value true if the object exists in live mode or the value false if the object exists in test mode.

  • max_redemptionsnullable integer

    Maximum number of times this promotion code can be redeemed.

  • restrictionsobject

    Settings that restrict the redemption of the promotion code.

    • restrictions.currency_optionsnullable objectExpandable

      Promotion code restrictions 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_amountnullable integer

      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_currencynullable string

      Three-letter ISO code for minimum_amount

  • times_redeemedinteger

    Number of times this promotion code has been used.

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
}