Developer : Coupons

Manage applications

The /coupons resource contains information about coupons that can be used for discounts at checkout. See Creating coupons for how to create coupons with the Goodsie API.

Resource URI

/api/v1/coupons

Method Scope Required
GET admin
POST admin

Properties

Property Methods Description
codes GET A list of coupon codes that can be used for the coupon. Codes can be multi_use or one_use
created GET Timestamp of when the coupon was created
currency GET (For flat_discount coupons) The flat discount is in this currency
free_ship GET, PUT, POST Default false, this is a boolean value for whether or not to include free shipping in addition to a flat-rate or percent discount. This field is not taken into consideration when using the free_shipping coupon type
end_date GET, PUT, POST Timestamp of when the coupon expires
flat_rate GET, PUT, POST (For flat_discount coupons) The discount amount as a formatted string
flat_rate_raw GET (For flat_discount coupons) The discount amount in float format
hits GET Number of times that a customer has attempted to use the coupon
id GET The unique id of the coupon
limit GET, PUT, POST Maximum number of times the coupon may be used. 0 indicates no limit
modified GET Timestamp of when the coupon was last modified
name GET, PUT, POST The coupon's name
percentage GET, PUT, POST (For percentage_off coupons) The percentage discount as a formatted string
percentage_raw GET (For percentage_off coupons) The percentage discount in float format
redeemed GET The number of times the coupon has been redeemed
start_date GET, PUT, POST Timestamp of when the coupon starts being valid
threshold GET, PUT, POST (For flat_discount coupons) The minimum purchase amount required to use the coupon as a formatted string
threshold_raw GET (For flat_discount coupons) The minimum purchase amount in float format
type GET, PUT, POST The coupon type. One of percentage_off, flat_discount, or free_shipping.

Subresources

Methods Path Description
GET, PUT, DELETE /api/v1/coupons/{id} A coupon

Example

curl -H "Authorization: Bearer ba125ac086" \
    https://goodsie.com/api/v1/coupons
[
    {
        "codes": [
            {
                "code": "123",
                "created": 1323950577,
                "active": true,
                "modified": 1323950577,
                "type": "multi_use"
            }
        ],
        "created": 1323950577,
        "end_date": 1326625200,
        "free_ship": false,
        "hits": 2,
        "id": 3,
        "limit": 0,
        "modified": 1323950812,
        "name": "Test",
        "percentage": "34% off",
        "percentage_raw": 34,
        "redeemed": 1,
        "start_date": 1323946800,
        "type": "percentage_off"
    },
    {
        "codes": [
            {
                "code": "dccb90",
                "created": 1323971202,
                "active": false,
                "modified": 1324405412,
                "type": "one_use"
            },
            {
                "code": "71a1ea",
                "created": 1324410295,
                "active": true,
                "modified": 1324410295,
                "type": "one_use"
            }
        ],
        "created": 1323971202,
        "currency": "USD",
        "end_date": 1326625200,
        "flat_rate": "$1.00 off",
        "flat_rate_raw": 1.0,
        "free_ship": false,
        "hits": 1,
        "id": 4,
        "limit": 1,
        "modified": 1324410295,
        "name": "A One-Time Use Coupon",
        "redeemed": 1,
        "start_date": 1324378800,
        "threshold": "$10.00",
        "threshold_raw": 10.0,
        "type": "flat_discount"
    }
]

Creating coupons

To create a coupon, you must specify a type, start_date, end_date (as UNIX timestamps), name, and limit. If you supply a code, Goodsie will create a multi-use coupon with that code. If you omit the code parameter, Goodsie will auto-generate n single-use coupons, where n is the limit you supplied.

curl -H "Authorization: Bearer 5b3d4a9a09" -X POST \
    -F 'name=mycoupon' \
    -F 'type=free_shipping' \
    -F 'limit=2' \
    -F 'start_date=1324378800' \
    -F 'end_date=1326625200' \
    -F 'code=abc123' \
    https://goodsie.com/api/v1/coupons
{
    "codes": [
        {
            "active": true, 
            "code": "abc123", 
            "created": 1326491901, 
            "modified": 1326491901, 
            "type": "multi_use"
        }
    ], 
    "created": 1326491901, 
    "end_date": 1326625200, 
    "hits": 0, 
    "id": 14, 
    "limit": 2, 
    "modified": 1326491901, 
    "name": "mycoupon", 
    "redeemed": 0, 
    "start_date": 1324378800, 
    "type": "free_shipping"
}
curl -H "Authorization: Bearer 5b3d4a9a09" -X POST \
    -F 'name=mycoupon' \
    -F 'type=free_shipping' \
    -F 'limit=2' \
    -F 'start_date=1324378800' \
    -F 'end_date=1326625200' \
    https://goodsie.com/api/v1/coupons
{
    "codes": [
        {
            "active": true, 
            "code": "ea5bb1", 
            "created": 1326492065, 
            "modified": 1326492065, 
            "type": "one_use"
        }, 
        {
            "active": true, 
            "code": "5a611b", 
            "created": 1326492065, 
            "modified": 1326492065, 
            "type": "one_use"
        }
    ], 
    "created": 1326492065, 
    "end_date": 1326625200, 
    "hits": 0, 
    "id": 15, 
    "limit": 2, 
    "modified": 1326492065, 
    "name": "mycoupon", 
    "redeemed": 0, 
    "start_date": 1324378800, 
    "type": "free_shipping"
}