Collapse Menu
Documentation
FastSpring App
Contact Support

/coupons

Overview

This article provides information about the /coupons endpoint of the FastSpring API. Use this endpoint to create, update, delete and get coupons.

This article provides information about the /coupons endpoint of the FastSpring API. Use this endpoint to create, update, delete, and get coupons.

 

Create a New Coupon or Edit an Existing One

POST /coupons
   
Request Example
{
    "coupon": "Black-Friday-2021",
    "discount": {
        "hasMultipleDiscounts": true,
        "discounts": [
            {
                "type": "flat",
                "amount": {
                    "USD": 10.0
                },
                "products": [
                    "saas-app-annual"
                ],
                "discountPeriodCount": null
            },
            {
                "type": "percent",
                "percent": 25.0,
                "products": [
                    "saas-app-monthly"
                ],
                "discountPeriodCount": 3
            }
        ]
    },
    "combine": false,
    "reason": {
        "en": "Black Friday Savings"
    },
    "limit": "",
    "available": {
        "start": "2021-11-24 ",
        "end": "2021-11-29 "
    },
    "codes": [
        "BF21",
        "BL21"
    ]
}
 
// 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 lists only the first duplicate code found. The API rejects the request, and any valid/non-duplicate codes included in the payload are not 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 permanently deletes ALL remaining coupon codes from the specified coupon. After you make this request, the coupon will not have any codes remaining available. Customers will not be able to use the coupon until you add new codes.