/coupons

Last modified June 23, 2017

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 the 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

Request example
curl --verbose --user {username}:{password} -X GET https://api.fastspring.com/coupons/{couponID}
Response example
{
  "coupon": "holiday-2016",		// 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": "2016-11-01 00:00",	// start date when the coupon will become available
    "end": "2016-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 the coupon

GET /coupons/{coupon-id}/codes

Request Example
{
 "codes": ["code1", "code2", ...]
}
Response example
{
"coupon": "AXL", // coupon ID
"codes": ["AXL1"] // all the active codes in the coupon ID
}

Delete coupon codes from the coupon

DELETE /coupons/{coupon-id}/codes

Request Example
{
 "codes": ["code1", "code2", ...]
}