coupon

Collection: coupons

Coupons are where you configure discounts for your customers to use for an entire order. Each coupon can have one or more coupon codes associated with the coupon resource. The syntax for creating coupon discount strings can be found in the FoxyCart documentation.

If you create custom attributes for a coupon, they will automatically be included in the response as embedded resources without having to zoom in on them.

Creating Multiple Coupon Codes: If you have a list of coupon codes you would like to add to this coupon, you can POST to the coupon_codes link relationship with an array of coupon codes like so:

{
    "coupon_codes": [
        "foo",
        "bar"
    ]
}

Or if you're using an XML Content Type:

<resource>
    <coupon_codes>foo</coupon_codes>
    <coupon_codes>bar</coupon_codes>
</resource>

Generating Coupon Codes: To generate multiple coupon code variations, POST to the generate_codes link relationship with the following values:

length: (optional) the length of the coupon code. Defaults to 6 characters.
number_of_codes: (optional) the number of coupon code variations you would like. Defaults to 10.
prefix: (optional) a prefix for all generated coupon codes. For example, if you would like all the coupon code variations to have a "summer_special" prefix, set that here.

Required Scopes

Full store_full_access

Read coupons_read

Write coupons_write

Actions

GET View a coupon

PATCH Update a coupon (send only the properties you want to modify)

PUT Replace a coupon (send the entire representation)

DELETE Delete a coupon

HEAD Get just the header response

OPTIONS Get a response explaining which HTTP methods are supported

Properties (23)

name String · Required · max 50

The name of this coupon. This will be for your own use and displayed to the customer.

start_date String (nullable) · Optional

If you want this coupon's usage to be limited by a time frame or start in the future, add a start date here. To clear it out, set an empty value or use 0000-00-00.

Format: YYYY-MM-DD

end_date String (nullable) · Optional

If you want this coupon's usage to be limited by a time frame or end in the future, add an end date here. To clear it out, set an empty value or use 0000-00-00.

Format: YYYY-MM-DD

number_of_uses_allowed Number

This is the total number of times this coupon is allowed to be used. This can be helpful for promotions that involve offering a discount to the first 100 customers, as an example, even though more than 100 coupon codes were given out. Leave as 0 to ignore this feature.

number_of_uses_to_date Number · Read-only

For informational purposes, this shows you how many times this coupon has already been used.

number_of_uses_allowed_per_customer Number

If each customer is only allowed to use this coupon once, enter 1 here. This is based off of the customer email address, not a payment method, ip address, shipping address or browser cookie. Leave as 0 to ignore this feature.

number_of_uses_allowed_per_code Number

If you want to limit the number of uses per individual coupon code, enter that number here. If you want each code to only be used once, enter 1 here. Leave as 0 to ignore this feature.

product_code_restrictions String · Optional · max 5000

This limits which products the coupon will apply to. Enter a comma separated list of product codes or partial product codes, optionally using * as a wild card at the beginning, end, or middle of the value. So `abc123, fun_*, *-small` would match `abc123`, `fun_` and `fun_times`, and `example-small`. It wouldn't match `abc12`, `abc1234`, `fun`, or `good-smalls`.

item_option_restrictions Object (nullable) · Optional · max 6000

This restricts the usage of a coupon code based on an item's item_option key and value. Valid input is a JSON object with the keys matching the item_option.name, and the value an array of comma-separated matching or partially matching strings, using * as a wild card at the beginning, end, or middle of the string. So `{"author": ["Agatha*", "*brown"]}` will match the item where item option "author" is "Agatha Christie" or "Dan Brown". It would not match an item with no "author" option, or with an "author" of "John Doe".

coupon_discount_type String · Required

This specifies what type of discount will be applied. Will it be a percentage discount or an amount discount based on either the product price or the product quantity?

quantity_amountquantity_percentageprice_amountprice_percentageexternally_controlled

coupon_discount_details String · Required · max 200

This is the string that determines the tiers and amounts that make up your discount. For example, 2-.50|10-3|50-5 means "between 2 and 9 is discounted by .5 per product, 10 and 49 by 3 per product and 50 and over by 5 per product". If you're doing a quantity discount, it will compare against the quantity of products in the order. If you're doing a price based discount, it will compare against the price of the products in the order. Please see the [documentation](https://wiki.foxycart.com/v/2.0/coupons_and_discounts) for more information.

combinable Boolean

If this coupon can be combined with other coupons, check this check box. If this box is unchecked, the coupon will not be added to the cart if another coupon is already in the cart. Similarly, if this coupon is added first, no other coupons will be able to be added to the cart.

shared_codes_allowed Boolean

Enables code sharing between coupons. If true, coupon codes from this coupon can also be used by other coupons that also have shared codes enabled.

multiple_codes_allowed Boolean

Set to true if you want to allow your customers to use multiple coupon codes from this coupon on the same order. If false, the customer will see an error if they try to add another coupon code if one for this coupon is already in the cart.

exclude_category_discounts Boolean

Set to true if you want to ensure category discounts are not applied for an order that uses this coupon.

exclude_line_item_discounts Boolean

Set to true if you want to ensure line item discounts are not applied to any products for an order that uses this coupon.

is_taxable Boolean

Set to true to apply taxes before this coupon's discount is applied. Check with your tax professional if you have questions about how you should calculate taxes.

customer_auto_apply Boolean

If this is true, the customer_* restrictions (below) will automatically apply on checkout when a customer authenticates. If false, customers must enter the coupon code themselves. In either case the customer_* restrictions must be met in order for the coupon to be applied.

customer_attribute_restrictions String · Optional · max 2000

A querystring-style filter for auto-applying based on customer attributes. For example, "attributes:name[auto_apply_coupons]=1" would auto-apply this coupon if the customer has a matching attribute.

customer_subscription_restrictions String · Optional · max 200

List of product codes, comma-separated. This keys off a customer's active subscription codes. Allows for wildcards like the product code restrictions. So "abc123,foo*" would match if the customer has an active subscription containing any products that have codes that match.

inclusive_tax_rate Number · Optional

This parameter is used for coupon calculation amount in tax inclusive mode.

Must be between 0 and 1.

date_created String (nullable) · Read-only

The date this resource was created.

date_modified String (nullable) · Read-only

The date this resource was last modified.

Link Relations (6)

self This Coupon

fx:attributes GET POST PATCH PUT Attributes for This Coupon

fx:store GET PATCH PUT DELETE This Store

fx:generate_codes Generate random Coupon Codes

fx:coupon_codes GET POST Coupon Codes

fx:coupon_item_categories GET POST Valid Item Categories for this Coupon

Zoomable Resources

Embed related resources using ?zoom=<resource>. Filter with ?resource:property=value.

coupon_codes coupon_item_categories

https://api.foxycart.com/coupons/{id}

Available via fx:coupon on applied_coupon_code·fx:coupon on coupon_code·fx:coupon on coupon_code_transaction·fx:coupon on coupon_detail·fx:coupon on coupon_item_category·fx:coupon on discount

Example Representation

Show _links

Zoom

{
  "_links": {
    "curies": [
      {
        "name": "fx",
        "href": "https://api.foxycart.com/rels/{rel}",
        "templated": true
      }
    ],
    "self": {
      "href": "https://api.foxycart.com/coupons/123",
      "title": "This Coupon"
    },
    "fx:attributes": {
      "href": "https://api.foxycart.com/coupons/123/attributes",
      "title": "Attributes for This Coupon"
    },
    "fx:store": {
      "href": "https://api.foxycart.com/stores/456",
      "title": "This Store"
    },
    "fx:generate_codes": {
      "href": "https://api.foxycart.com/coupons/123/generate_codes",
      "title": "Generate random Coupon Codes"
    },
    "fx:coupon_codes": {
      "href": "https://api.foxycart.com/coupons/123/codes",
      "title": "Coupon Codes"
    },
    "fx:coupon_item_categories": {
      "href": "https://api.foxycart.com/coupons/123/item_categories",
      "title": "Valid Item Categories for this Coupon"
    }
  },
  "name": "test",
  "start_date": null,
  "end_date": null,
  "number_of_uses_allowed": 0,
  "number_of_uses_to_date": 31,
  "number_of_uses_allowed_per_customer": 0,
  "number_of_uses_allowed_per_code": 0,
  "product_code_restrictions": "",
  "item_option_restrictions": null,
  "coupon_discount_type": "quantity_amount",
  "coupon_discount_details": "2-1",
  "combinable": true,
  "shared_codes_allowed": false,
  "multiple_codes_allowed": true,
  "exclude_category_discounts": false,
  "exclude_line_item_discounts": false,
  "is_taxable": true,
  "customer_auto_apply": false,
  "customer_attribute_restrictions": "",
  "customer_subscription_restrictions": "",
  "inclusive_tax_rate": 0,
  "date_created": "2014-04-21T13:40:45-0700",
  "date_modified": "2015-03-16T12:30:58-0700"
}