/coupons

Last modified December 7, 2018

This article applies to Contextual Commerce. (Looking for Classic Commerce documentation?)

Coupons and Coupon Codes 

Use this endpoint to create, update, delete and get coupons.  Read more about coupons at Coupons.

Create a New Coupon or Edit an Existing One

POST /coupons

Request Example
// For coupons with "amount off" discount
 
{
    "coupon": "coupon-id", // required, alphanumeric coupon ID
    "discount" {"type": "flat", "amount": {"USD": 8, "EUR": 10}}, // required - valid values for type are flat and percent. Flat expects object with amount off per currency.
    "combine": true, // corresponding to "combine discounts" in the interface. optional, default: false. If enabled will apply coupon discount in addition to the product discount.
    "reason": {"en": "Your Reason", "de": "Your Reason in German"}, //optional - discount reason visible to end users, object with all languages you want to enter it in.
    "limit": 10,  // optional - use limit for each coupon code
    "available": {"start":"2015-08-15", "end": "2015-09-15"},  // optional, also accepts timestamp in milliseconds and datetime string  e.g. "2015-09-01 08:00" to set "start time" or "end time"
     "codes": ["code1", "code2", ...] //optional, actual coupon codes which trigger this discount
    "products": ["product-id", "another-product-id"] // optional - array of product ids to which this discount applies. If not provided applies to all products.
}
 
// For coupons with "percentage off" discount
 
// Use the same syntax as above but different type for "discount":
"discount": {"type": "percent", "percent": 20},


Update Existing Coupon

POST /coupons

Request Example
{
    "coupon": "coupon-id", // required, ID of the coupon you are updating
    "discount": {"type": "percent", "percent": 20},  // optional
    "combine": true, // "combine discounts" in the interface, optional.
    "reason": {"en": "String", "de": "String"}, //optional - an empty object {} will clear the reason.
    "limit": 10,  // optional - 0 will disable use-limit
    "available": {"start":"2015-08-15", "end": "2015-09-15"},  // optional - an empty object {} will clear both start date and end date
    "codes": ["code1", "code2", ...]  //optional, an empty array [] will remove all existing coupon codes.
    "products": ["product-id", "another-product-id"] // optional - an empty array [] will remove all existing product conditions.
}


Add Coupon Codes to a Coupon

POST /coupons/{coupon-id}/codes

Request Example
{
 "codes": ["code1", "code2", ...]
}
Response Example
{
    "coupon": "holiday-2016",
    "codes": [
        "8675309"
    ],
    "result": "success"
}


// possible error response when trying to upload a duplicate code
{
    "coupon": "holiday-2016",
    "codes": [
        "0BXB6NMMCT",
        "0DCBKZN35L",
        "8675309"
    ],
    "result": "error",
    "error": "Coupon code 0BXB6NMMCT already exists."
}

Note

If your request payload includes a duplicate of an existing coupon code, the response will list only the first duplicate code it found; the request will be rejected and any valid / non-duplicate codes included in the payload will not be added to the coupon.


Retrieve Coupon Details

GET /coupons/{couponID}
Response example
{
  "coupon": "blackfriday",              // coupon ID
  "discount": {
    "type": "percent",			// or "amount"
    "percent": 20			// discount value
  },
  "combine": false,			// can coupon discount be combined with product discounts?
  "reason": {
    "en": "Holiday Savings!"
  },				        // optional customer-facing "Applied Discount Reason" text
  "limit": "1",				// number of uses allowed per code
  "available": {
    "start": "2018-11-01 00:00",	// start date when the coupon will become available
    "end": "2018-12-25 22:59"		// end date when coupon will expire
  },
  "codes": [
    "0793PE2TSK",
    "0BXB6NMMCT",
    ...					// all remaining coupon codes will be listed
  ],
  "products": []			// if discounted is restricted to specific products, product IDs will be listed here
}


Get Coupon Codes Assigned to a Coupon

GET /coupons/{coupon-id}/codes

Request Example
{
 "codes": ["code1", "code2", ...]
}
Response example
{
"coupon": "AXL", // coupon ID
"codes": ["AXL1"] // all coupon codes associated with the coupon ID, including both active and inactive codes
}

Delete ALL Coupon Codes from a Coupon

DELETE /coupons/{coupon-id}/codes

Warning

This request will permanently delete ALL remaining coupon codes from the specified coupon. After processing this request, the coupon will not have any codes remaining available. Customers will not be able to use the coupon until new codes are added.