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.

  Hide child attributes

  • coupon.idstring

    Unique identifier for the object.

  • coupon.objectstring

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

  • coupon.amount_offnullable integer

    Amount (in the currency specified) that will be taken off the subtotal of any invoices for this customer.

  • coupon.applies_tonullable objectExpandable

    Contains information about what this coupon applies to.

    Hide child attributes

    • coupon.applies_to.productsarray of strings

      A list of product IDs this coupon applies to

  • coupon.createdtimestamp

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

  • coupon.currencynullable enum

    If amount_off has been set, the three-letter ISO code for the currency of the amount to take off.

  • coupon.currency_optionsnullable objectExpandable

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

    Hide child attributes

    • coupon.currency_options.<currency>.amount_offinteger

      Amount (in the currency specified) that will be taken off the subtotal of any invoices for this customer.

  • coupon.durationenum

    One of forever, once, or repeating. Describes how long a customer who applies this coupon will get the discount.

    Possible enum values

    forever Applies to all charges from a subscription with this coupon applied.

    once Applies to the first charge from a subscription with this coupon applied.

    repeating Applies to charges in the first duration_in_months months from a subscription with this coupon applied. This value is deprecated and will be replaced in future versions of the API.

  • coupon.duration_in_monthsnullable integerDeprecated

    If duration is repeating, the number of months the coupon applies. Null if coupon duration is forever or once.

  • coupon.livemodeboolean

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

  • coupon.max_redemptionsnullable integer

    Maximum number of times this coupon can be redeemed, in total, across all customers, before it is no longer valid.

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

  • coupon.namenullable string

    Name of the coupon displayed to customers on for instance invoices or receipts.

  • coupon.percent_offnullable float

    Percent that will be taken off the subtotal of any invoices for this customer for the duration of the coupon. For example, a coupon with percent_off of 50 will make a $100 invoice $50 instead.

  • coupon.redeem_bynullable timestamp

    Date after which the coupon can no longer be redeemed.

  • coupon.times_redeemedinteger

    Number of times this coupon has been applied to a customer.

  • coupon.validboolean

    Taking account of the above properties, whether this coupon can still be applied to a customer.

• 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

Collapse all

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

  Hide child attributes

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

    Hide child attributes

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