coupons

Description

This link relationship returns a collection of resources. You can easily paginate through this collection using the hypermedia links provided and the link relationships of first, prev, next, and last. Scroll down to view a representation of a single resource embedded within this collection.

Sandbox Example

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

Actions

GET
View a list of coupons
POST
Create a new coupon
HEAD
Get just the header response
OPTIONS
Get a response explaining which HTTP methods are supported

Example Representation

{
  "_links": {
    "curies": [
      {
        "name": "fx",
        "href": "https://api.foxycart.com/rels/{rel}",
        "templated": true
      }
    ],
    "self": {
      "href": "...",
      "title": "This Collection"
    },
    "first": {
      "href": "...?offset=0",
      "title": "First Page of this Collection"
    },
    "prev": {
      "href": "...?offset=0",
      "title": "Previous Page of this Collection"
    },
    "next": {
      "href": "...?offset=0",
      "title": "Next Page of this Collection"
    },
    "last": {
      "href": "...?offset=0",
      "title": "Last Page of this Collection"
    }
  },
  "_embedded": {
    "fx:coupons": [...]
  },
  "total_items": "5",
  "returned_items": 5,
  "limit": 20,
  "offset": 0
}
<?xml version="1.0" encoding="UTF-8"?>
<resource href="...">
  <link rel="self" href="..." title="This Collection"/>
  <link rel="first" href="...?offset=0" title="First Page of this Collection"/>
  <link rel="prev" href="...?offset=0" title="Previous Page of this Collection"/>
  <link rel="next" href="...?offset=0" title="Next Page of this Collection"/>
  <link rel="last" href="...?offset=0" title="Last Page of this Collection"/>
  <resource href="..." rel="https://api.foxycart.com/rels/coupon">
  ...
  </resource>
  <total_items>5</total_items>
  <returned_items>5</returned_items>
  <limit>20</limit>
  <offset>0</offset>
</resource>
{
    "properties": {
        "total_items": "5",
        "returned_items": 5,
        "limit": 20,
        "offset": 0
    },
    "entities": [...],
    "links": [
        {
            "rel": [
                "self"
            ],
            "href": "..."
        },
        {
            "rel": [
                "first"
            ],
            "href": "...?offset=0"
        },
        {
            "rel": [
                "prev"
            ],
            "href": "...?offset=0"
        },
        {
            "rel": [
                "next"
            ],
            "href": "...?offset=0"
        },
        {
            "rel": [
                "last"
            ],
            "href": "...?offset=0"
        }
    ],
    "actions": [
    ]
}

Embedded Resource: 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.

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) 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. 5000 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
customer_auto_apply Set to true if you want to mark this coupon like a auto apply. Boolean Optional
customer_attribute_restrictions Here can be querystring for our default filtering(Cheat-sheet link). If by this filter we can find customer coupon will be applyed. For example "attributes:name[auto_apply_coupons]=1" String Optional. 2000 characters or less.
customer_subscription_restrictions List of product codes comma-separated. It'd key off a a customer's active subscriptions codes. Allow 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 String Optional. 200 characters or less.
inclusive_tax_rate This param is using for coupon calculation amount for tax inclusive mode Decimal Optional. [0..1].
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:attributes": {
            "href": "https://api.foxycart.test/coupons/244/attributes",
            "title": "Attributes for This Coupon"
        },
        "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