Store owners can create coupons for use on their site. Coupons can be either an amount deducted from the order, a percentage off of an order, or free shipping. They can be restricted either by the order amount needing to meet a certain threshold, or they can be restricted to specific products. The owner can also limit the number of coupons available and the date range that they are valid for.

For free shipping coupons, the coupon can be for a specific rate or method that the store owner has already configured. You cannot create free shipping coupons using the API.

Use the Coupons API to manage a store’s coupons, including retrieving coupons, updating or deleting existing ones, and creating new ones.

Fields

The following table shows all fields that exist for this API, those that are returned when you retrieve a list, those that are required for PUT and POST, and those that are changeable using PATCH and PUT. All fields are returned when you retrieve a single item.

Name Description Type List Required Changeable
user_id The unique ID of the authenticated user string X
site_id ID of a Weebly site, unique to the currently authenticated user​ string X
availability Date range that the coupon is valid for. string
summary Calculated string that describes the coupon, based on the posted criteria. string X
num_available Total number of coupons available. integer X
num_used ​Number of coupons redeemed by the store's customers. integer
shipping_method_ids For free shipping coupons, an array of shipping_method_ids that provide free shipping. This must already be configured in the store. array of strings Required if type=​shipping X
shipping_rate_ids For free shipping coupons, an array of shipping_rate_ids that provide free shipping. This must already be configured in the store. array of strings Required if type=​shipping X
category_ids For categories criteria, an array of category IDs that the coupon is valid for. array of strings Required if criteria=categories X
product_ids For products criteria, an array of product IDs that the coupon is valid for. array of strings Required if criteria=products X
coupon_id ​Unique ID (within the store) of the coupon string X
code ​​The coupon code that the customer must enter to redeem the coupon string X X X
type The type of this coupon.
Valid values are:
  • percent: percentage amount off the total order
  • absolute: absolute amount off the total order
  • shipping: free shipping (only available if the store owner has configured shipping rates for their store)
string X X
amount The amount of the coupon, for example 5.00 for an absolute amount of $5.00. For percent types, use a percentage amount, for example 20.00 for 20%. decimal Required if type=absolute X
start_date ​​The first date the coupon is valid. ​Unix timestamp in GMT
X
end_date ​​​The last date the coupon is valid. ​​Unix timestamp in GMT
X
criteria The limiting criteria for applying a coupon.
Valid values are:
  • all: no limitations
  • total_over: only orders over X dollar amount
  • categories: only orders containing products from specific categories
  • products: only orders containing specific products
string X X
criteria_amount ​​For total_over criteria, the threshold amount an order must meet in order for the coupon to be valid. decimal Required If criteria= ​total_over X
created_date Date the coupon was created Unix GMT Timestamp

updated_date Date the coupon was last updated Unix GMT Timestamp

GET
Retrieve a List of Coupons

GET /v1/user/sites/{SITE_ID}/store/coupons

Returns all coupons for the given site. Only list fields are returned.


scope: read:store-catalog

Query Parameters

Returned values are paginated. You can further filter results using these parameters:

Parameter Description Type
page Which page of results to return. Start is 1. integer
limit Number of results per page to return. Default is 25.
Max is 200.
integer
filterby Field name to set a filter on. string
filterfor ​​​Value to search the filterby field for.
You can use the following URL encoded operators with your filterfor parameter:
  • ​<: use %3C
  • >: use %3E
  • <=: use %3C%3D
  • >=: use %3E%3D
string

Example CURL request returning all coupons:

curl --request GET \
--url https://api.weebly.com/v1/user/sites/987654321/store/coupons \
--header 'accept: application/vnd.weebly.v1+json' \
--header 'content-type: application/json' \
--header 'x-weebly-access-token: [YOUR_TOKEN]"

Example filtered request:

curl --request GET \
--url https://api.weebly.com/v1/user/sites/987654321/store/coupons?filterby=num_avail&filterfor=$3 \
--header 'accept: application/vnd.weebly.v1+json' \
--header 'content-type: application/json' \
--header 'x-weebly-access-token: [YOUR_TOKEN]"

Example response:

[
    {
        "user_id": "123456",
        "site_id": "987654321",
        "summary": "$10 off orders over $100",
        "coupon_id": "2",
        "code": "10OFF"
    },
    {
        "user_id": "123456",
        "site_id": "987654321",
        "summary": "$10 off select products",
        "coupon_id": "7",
        "code": "SPRINGTIME"
    },
    {
        "user_id": "123456",
        "site_id": "987654321",
        "summary": "$10 off select products",
        "coupon_id": "8",
        "code": "SPRINGFLING"
    }
]

GET
Retrieve the Number of Coupons for a Site

GET /v1/user/sites/{SITE_ID}/store/coupons/count

Returns the number of coupons.


scope: read:store-catalog

Example CURL request:

curl --request GET \
--url https://api.weebly.com/v1/user/sites/987654321/store/coupons/count \
--header 'accept: application/vnd.weebly.v1+json' \
--header 'content-type: application/json' \
--header 'x-weebly-access-token: [YOUR_TOKEN]"

Example response:

{
    "count": 9
}

GET
Retrieve Details for a Coupon

GET /v1/user/sites/{SITE_ID}/store/coupons/{COUPON_ID}

Returns all fields for the given coupon.


scope: read:store-catalog

Example CURL request:

curl --request GET \
--url https://api.weebly.com/v1/user/sites/987654321/store/coupons/3 \
--header 'accept: application/vnd.weebly.v1+json' \
--header 'content-type: application/json' \
--header 'x-weebly-access-token: [YOUR_TOKEN]"

Example response:

See Fields table. All fields for the coupon are returned.

{
    "user_id": "123456",
    "site_id": "987654321",
    "availability": "3/1/2017 - 3/31/2017",
    "summary": "$10 off orders over $100",
    "num_available": 100,
    "num_used": 0,
    "shipping_method_ids": [],
    "category_ids": [],
    "product_ids": [],
    "coupon_id": "2",
    "code": "10OFF",
    "type": "absolute",
    "amount": 10,
    "start_date": 1488326400,
    "end_date": 1490918400,
    "criteria": "total_over",
    "criteria_amount": 100,
    "created_date": 1486166397,
    "updated_date": 1486166397,
    "shipping_rate_ids": []
}

POST
Create a Coupon

POST /v1/user/sites/{SITE_ID}/store/coupons

Creates a new coupon for the site’s store.


scope: write:store-catalog

These fields can be created:

Name Description Type Notes
code ​​The coupon code that the customer must enter to redeem the coupon string Required
type The type of this coupon.
Valid values are:
  • percent: percentage amount off the total order
  • absolute: absolute amount off the total order
  • shipping: free shipping (only available if the store owner has configured shipping rates for their store)
string Required
criteria The limiting criteria for applying a coupon.
Valid values are:
  • all: no limitations
  • total_over: only orders over X dollar amount
  • categories: only orders containing products from specific categories
  • products: only orders containing specific products
string Required
amount The amount of the coupon, for example 5.00 for an absolute amount of $5.00. For percent types, use a percentage amount, for example 20.00 for 20%. decimal Required if type=absolute
criteria_amount ​​For total_over criteria, the threshold amount an order must meet in order for the coupon to be valid. decimal Required if criteria=total_over
category_ids For categories criteria, an array of category IDs that the coupon is valid for. array of strings Required if criteria=categories
product_ids For products criteria, an array of product IDs that the coupon is valid for. array of strings Required if criteria=products
shipping_method_ids For free shipping coupons, an array of shipping_method_ids that provide free shipping. This must already be configured in the store. array of strings Required if type=shipping
shipping_rate_ids For free shipping coupons, an array of shipping_rate_ids that provide free shipping. This must already be configured in the store. array of strings Required if type=shipping
num_available Total number of coupons available. integer
start_date ​​The first date the coupon is valid. ​Unix timestamp in GMT
end_date ​​​The last date the coupon is valid. ​​Unix timestamp in GMT

Example CURL request:

curl --request POST \
--url https://api.weebly.com/v1/user/sites/987654321/store/coupons \
--header 'accept: application/vnd.weebly.v1+json' \
--header 'content-type: application/json' \
--header 'x-weebly-access-token: [YOUR_TOKEN]"
--data '{
            "code": "5-OFF",
            "type": "absolute",
            "amount": 5,
            "criteria": "total_over",
            "criteria_amount": "5.00",
            "num_available": 100,
            "start_date": 1493596800,
            "end_date": 1496275199
        }'

Example response:

{
    "user_id": "123456",
    "site_id": "987654321",
    "availability": "4/30/2017 - 5/31/2017",
    "summary": "$5 off orders over $5",
    "num_available": 100,
    "num_used": 0,
    "shipping_method_ids": [],
    "shipping_rate_ids": [],
    "category_ids": [],
    "product_ids": [],
    "coupon_id": "11",
    "code": "5-OFF",
    "type": "absolute",
    "amount": 5,
    "start_date": 1493596800,
    "end_date": 1496275199,
    "criteria": "total_over",
    "criteria_amount": 5,
    "created_date": 1486410889,
    "updated_date": 1486410889
}

PUT
Replace a Coupon

PUT /v1/user/sites/{SITE_ID}/store/coupons/{COUPON_ID}

Replaces the given coupon.


scope: write:store-catalog

These fields can be replaced:

Name Description Type Notes
code ​​The coupon code that the customer must enter to redeem the coupon string Required
type The type of this coupon.
Valid values are:
  • percent: percentage amount off the total order
  • absolute: absolute amount off the total order
  • shipping: free shipping (only available if the store owner has configured shipping rates for their store)
string Required
criteria The limiting criteria for applying a coupon.
Valid values are:
  • all: no limitations
  • total_over: only orders over X dollar amount
  • categories: only orders containing products from specific categories
  • products: only orders containing specific products
string Required
amount The amount of the coupon, for example 5.00 for an absolute amount of $5.00. For percent types, use a percentage amount, for example 20.00 for 20%. decimal Required if type=absolute
criteria_amount ​​For total_over criteria, the threshold amount an order must meet in order for the coupon to be valid. decimal Required if criteria=total_over
category_ids For categories criteria, an array of category IDs that the coupon is valid for. array of strings Required if criteria=categories
product_ids For products criteria, an array of product IDs that the coupon is valid for. array of strings Required if criteria=products
shipping_method_ids For free shipping coupons, an array of shipping_method_ids that provide free shipping. This must already be configured in the store. array of strings Required if type=shipping
shipping_rate_ids For free shipping coupons, an array of shipping_rate_ids that provide free shipping. This must already be configured in the store. array of strings Required if type=shipping
num_available Total number of coupons available. integer
start_date ​​The first date the coupon is valid. ​Unix timestamp in GMT
end_date ​​​The last date the coupon is valid. ​​Unix timestamp in GMT

Example CURL request:

curl --request PUT \
--url https://api.weebly.com/v1/user/sites/987654321/store/coupons/3 \
--header 'accept: application/vnd.weebly.v1+json' \
--header 'content-type: application/json' \
--header 'x-weebly-access-token: [YOUR_TOKEN]"
--data '{
            "code": "VIP",
            "type": "absolute",
            "amount": "100",
            "criteria": "all",
            "criteria_amount": "1",
            "product_ids": "[]",
            "category_ids": "[]",
            "shipping_rate_ids": "[]"
        }'

Example response:

{
    "user_id": "123456",
    "site_id": "987654321",
    "availability": "Never expires",
    "summary": "10% off all orders",
    "num_available": null,
    "num_used": 0,
    "shipping_rate_ids": [ ],
    "category_ids": [ ],
    "product_ids": [ ],
    "coupon_id": "3",
    "code": "VIP",
    "type": "absolute",
    "amount": 100,
    "start_date": null,
    "end_date": null,
    "criteria": "all",
    "criteria_amount": 1,
    "created_date": 1458873551,
    "updated_date": 1461024564
}

PATCH
Update a Coupon

PATCH /v1/user/sites/{SITE_ID}/store/coupons/{COUPON_ID}

Updates the given coupon.


scope: write:store-catalog

These fields can be updated:

Name Description Type
code ​​The coupon code that the customer must enter to redeem the coupon string
type The type of this coupon.
Valid values are:
  • percent: percentage amount off the total order
  • absolute: absolute amount off the total order
  • shipping: free shipping (only available if the store owner has configured shipping rates for their store)
string
criteria The limiting criteria for applying a coupon.
Valid values are:
  • all: no limitations
  • total_over: only orders over X dollar amount
  • categories: only orders containing products from specific categories
  • products: only orders containing specific products
string
amount The amount of the coupon, for example 5.00 for an absolute amount of $5.00. For percent types, use a percentage amount, for example 20.00 for 20%. decimal
criteria_amount ​​For total_over criteria, the threshold amount an order must meet in order for the coupon to be valid. decimal
category_ids For categories criteria, an array of category IDs that the coupon is valid for. array of strings
product_ids For products criteria, an array of product IDs that the coupon is valid for. array of strings
shipping_method_ids For free shipping coupons, an array of shipping_method_ids that provide free shipping. This must already be configured in the store. array of strings
shipping_rate_ids For free shipping coupons, an array of shipping_rate_ids that provide free shipping. This must already be configured in the store. array of strings
num_available Total number of coupons available. integer
start_date ​​The first date the coupon is valid. ​Unix timestamp in GMT
end_date ​​​The last date the coupon is valid. ​​Unix timestamp in GMT

Example CURL request:

curl --request PATCH \
--url https://api.weebly.com/v1/user/sites/987654321/store/coupons/2 \
--header 'accept: application/vnd.weebly.v1+json' \
--header 'content-type: application/json' \
--header 'x-weebly-access-token: [YOUR_TOKEN]"
--data '{
            "num_available": 90
            "amount": 10
        }'

Example response:

{
    "user_id": "123456",
    "site_id": "987654321",
    "availability": "2/28/2017 - 3/30/2017",
    "summary": "$10 off all orders",
    "num_available": 90,
    "num_used": 10,
    "shipping_method_ids": [],
    "category_ids": [],
    "product_ids": [],
    "coupon_id": "2",
    "code": "10OFF",
    "type": "absolute",
    "amount": 10,
    "start_date": 1488326400,
    "end_date": 1490918400,
    "criteria": "all",
    "criteria_amount": 10,
    "created_date": 1486166397,
    "updated_date": 1486415167
}

DELETE
Delete a Coupon

DELETE /v1/user/sites/{SITE_ID}/store/coupons/{COUPON_ID}

Deletes the given coupon.


scope: write:store-catalog

Example CURL request:

curl --request DELETE \
--url https://api.weebly.com/v1/user/sites/987654321/store/coupons/3 \
--header 'accept: application/vnd.weebly.v1+json' \
--header 'content-type: application/json' \
--header 'x-weebly-access-token: [YOUR_TOKEN]"

Response There is no response to a delete request.


Help make these docs better!









Tags: