coupon

Description

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

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) the number of coupon code variations you would like to generate. For example, if you would like all the coupon code variations to have a "summer_special" prefix, set that here.

Sandbox Example

You can interact with this resource and run actions against the sandbox API via our HAL Brower.

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

Property Description Type Constraints
name The name of this coupon. This will be for your own use and displayed to the customer. String Required. 50 characters or less.
start_date 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. Date Optional. YYYY-MM-DD
end_date 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. Date Optional. YYYY-MM-DD
number_of_uses_allowed 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. Integer Optional
number_of_uses_to_date For informational purposes, this shows you how many times this coupon has already been used. Integer Read Only
number_of_uses_allowed_per_customer 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. Integer Optional
number_of_uses_allowed_per_code 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. Integer Optional
product_code_restrictions If you want to limit which products can use this coupon, you can enter a comma separated listed of product codes or partial product codes using * as a wild card at the beginning or end 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. String Optional. 500 characters or less.
coupon_discount_type 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? String Required. quantity_amount, quantity_percentage, price_amount, or price_percentage
coupon_discount_details 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 for more information: Coupons and Discounts String Required. 200 characters or less.
combinable 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. Boolean Optional
multiple_codes_allowed 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. Boolean Optional
exclude_category_discounts Set to true if you want to ensure category discounts are not applied for an order that uses this coupon. Boolean Optional
exclude_line_item_discounts Set to true if you want to ensure line item discounts are not applied to any products for an order that uses this coupon. Boolean Optional
is_taxable 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. Boolean Optional
date_created The date this resource was created. Date Read only
date_modified The date this resource was last modified. Date Read only

Example Representation

{
    "_links": {
        "curies": [
            {
                "name": "fx",
                "href": "https://api.foxycart.com/rels/{rel}",
                "templated": true
            }
        ],
        "self": {
            "href": "https://api.foxycart.com/coupons/244",
            "title": "test"
        },
        "fx:store": {
            "href": "https://api.foxycart.com/stores/66",
            "title": "This Store"
        },
        "fx:generate_codes": {
            "href": "https://api.foxycart.com/coupons/244/generate_codes",
            "title": "Generate random Coupon Codes"
        },
        "fx:coupon_codes": {
            "href": "https://api.foxycart.com/coupons/244/codes",
            "title": "Coupon Codes"
        },
        "fx:coupon_item_categories": {
            "href": "https://api.foxycart.com/coupons/244/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_code": 0,
    "coupon_discount_type": "quantity_amount",
    "coupon_discount_details": "2-1",
    "combinable": true,
    "multiple_codes_allowed": true,
    "exclude_category_discounts": false,
    "exclude_line_item_discounts": false,
    "is_taxable": true,
    "date_created": "2014-04-21T13:40:45-0700",
    "date_modified": "2015-03-16T12:30:58-0700"
}
<?xml version="1.0" encoding="UTF-8"?>
<resource href="https://api.foxycart.com/coupons/244" rel="https://api.foxycart.com/rels/coupon">
  <link rel="self" href="https://api.foxycart.com/coupons/244" title="test"/>
  <link rel="https://api.foxycart.com/rels/store" href="https://api.foxycart.com/stores/66" title="This Store"/>
  <link rel="https://api.foxycart.com/rels/generate_codes" href="https://api.foxycart.com/coupons/244/generate_codes" title="Generate random Coupon Codes"/>
  <link rel="https://api.foxycart.com/rels/coupon_codes" href="https://api.foxycart.com/coupons/244/codes" title="Coupon Codes"/>
  <link rel="https://api.foxycart.com/rels/coupon_item_categories" href="https://api.foxycart.com/coupons/244/item_categories" title="Valid Item Categories for this Coupon"/>
  <name>test</name>
  <start_date></start_date>
  <end_date></end_date>
  <number_of_uses_allowed>0</number_of_uses_allowed>
  <number_of_uses_to_date>31</number_of_uses_to_date>
  <number_of_uses_allowed_per_code>0</number_of_uses_allowed_per_code>
  <coupon_discount_type>quantity_amount</coupon_discount_type>
  <coupon_discount_details>2-1</coupon_discount_details>
  <combinable>true</combinable>
  <multiple_codes_allowed>true</multiple_codes_allowed>
  <exclude_category_discounts>false</exclude_category_discounts>
  <exclude_line_item_discounts>false</exclude_line_item_discounts>
  <is_taxable>true</is_taxable>
  <date_created>2014-04-21T13:40:45-0700</date_created>
  <date_modified>2015-03-16T12:30:58-0700</date_modified>
</resource>
{
    "class": [
        "coupon"
    ],
    "properties": {
        "name": "test",
        "start_date": null,
        "end_date": null,
        "number_of_uses_allowed": 0,
        "number_of_uses_to_date": 31,
        "number_of_uses_allowed_per_code": 0,
        "coupon_discount_type": "quantity_amount",
        "coupon_discount_details": "2-1",
        "combinable": true,
        "multiple_codes_allowed": true,
        "exclude_category_discounts": false,
        "exclude_line_item_discounts": false,
        "is_taxable": true,
        "date_created": "2014-04-21T13:40:45-0700",
        "date_modified": "2015-03-16T12:30:58-0700"
    },
    "links": [
        {
            "rel": [
                "self"
            ],
            "href": "https://api.foxycart.com/coupons/244"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/store"
            ],
            "href": "https://api.foxycart.com/stores/66"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/generate_codes"
            ],
            "href": "https://api.foxycart.com/coupons/244/generate_codes"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/coupon_codes"
            ],
            "href": "https://api.foxycart.com/coupons/244/codes"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/coupon_item_categories"
            ],
            "href": "https://api.foxycart.com/coupons/244/item_categories"
        }
    ]
}

Zoomable Resources

The following related resources can be embedded within this resource by including a ?zoom=<child_resource> parameter. You can also filter by child resources by ?child_resource:property=<property_value>

coupon_codes
coupon_item_categories