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.
Interact with this resource
To interact with this resource and see it in the context of the API, you can utilise Postman or your Terminal/Console to perform requests. If you have a Foxy store, you can also use the API browser in the admin to interact with resources connected to your store.
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.
Interact with this resource
To interact with this resource and see it in the context of the API, you can utilise Postman or your Terminal/Console to perform requests. If you have a Foxy store, you can also use the API browser in the admin to interact with resources connected to your store.
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 | This limits which products the coupon will apply to. Enter a comma separated listed 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. |
String | Optional. 5000 characters or less. |
| item_option_restrictions | 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". |
JSON | Optional. 6000 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, price_percentage or externally_controlled |
| 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 | 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.) |
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>