Collapse Menu
Docs Home
Extensibility Options
Contact Support

/coupons

Overview

This article provides information about coupons.Use this endpoint to create, update, delete and get coupons.

Overview

This article provides information about coupons.Use this endpoint to create, update, delete and get coupons.

 

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"; date and time must be supplied in UTC
     "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; date and time must be supplied in UTC
    "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, in UTC
    "end": "2018-12-25 22:59"		// end date when coupon will expire, in UTC
  },
  "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.

Try FastSpring

Get a free account and see why FastSpring is the ecommerce partner of choice for software providers around the world. Try our full-service ecommerce solution today to unlock revenue growth for your online company.