Coupons API
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.
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.
Note: To authenticate with the Weebly API, you need to use OAuth. This will allow you to access resources based on a particular user and site.
In this topic:
Fields
The following table shows all fields that exist for this API, those that are returned when you retrieve a list, and those that are changeable using PATCH. All fields are returned when you retrieve a single item
Name |
Description |
Type |
List |
Change- able |
Required |
user_id |
Unique ID of the user authenticated during the OAuth process |
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 |
X If type= shipping |
||
category_ids |
For categories criteria, an array of category IDs that the coupon is valid for. |
array |
X |
X If criteria= categories |
|
product_ids |
For products criteria, an array of product IDs that the coupon is valid for. |
array |
X |
X If criteria= products |
|
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:
|
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 |
X |
||
start_date |
The first date the coupon is valid |
Unix timestamp in GMT |
X |
X If type= shipping |
|
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:
|
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 |
|
X |
X If criteria= total_ over |
shipping_ rate_ids |
For free shipping coupons, an array of shipping_rate_ids that provide free shipping. |
array |
|||
created_date |
Date the coupon was first created |
Unix timestamp in GMT |
|||
updated_date |
Date the coupon was last updated |
Unix timestamp in GMT |
Note: Any fields returned that are not documented are currently unsupported and can be safely ignored.
Retrieve a List of Coupons for a Site
Endpoint URL
Returns all coupons created for this site.
Scope: read:store-catalog
Query Parameters
Parameter |
Description |
Type |
page |
Which page of results to return. Start is 1. Note: Only the first 25 results are returned by default. If the result set is expected to be over 25, you must implement pagination. |
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:
|
string |
Request
Example returning all coupons:
Example of filtered request
Response
Example response
Retrieve the Number of Coupons for a Site
Enpoint URL
Returns the number of coupons for a store that have not been deleted - active and expired coupons are returned.
Scope: read:store-catalog
Scope: read:store-catalog
Request
Example request
Response
Example response
Retrieve Details for a Coupon
Enpoint URL
Returns the details for a coupon.
Scope: read:store-catalog
Scope: read:store-catalog
Request
Example request
Response
See Fields table. All fields for the [[ ]] are returned.
Example response
Create a Coupon
Endpoint URL
Creates a new coupon for the given site.
Scope: write:store-catalog
Scope: write:store-catalog
Note: You cannot create free shipping coupons using the API.
POST body:
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:
|
string |
Required |
criteria |
The limiting criteria for applying a coupon. Valid values are:
|
string |
Required |
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 |
product_ids |
For products criteria, an array of product IDs that the coupon is valid for. |
array |
Required If criteria= products |
category_ids |
For categories criteria, an array of category IDs that the coupon is valid for. |
array |
Required If criteria= categories |
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 |
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 |
Request
Example request
Response
Example response
Update a Coupon
Endpoint URL
Updates the given coupon.
Scope: write:store-catalog
Scope: write:store-catalog
Updateable Fields
These fields can be updated.
Name |
Description |
Type |
Notes |
code |
The coupon code that the customer must enter to redeem the coupon |
string |
|
type |
The type of this coupon. Valid values are:
|
string |
Required |
criteria |
The limiting criteria for applying a coupon. Valid values are:
|
string |
Required |
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 |
product_ids |
For products criteria, an array of product IDs that the coupon is valid for. |
array |
Required if criteria= products |
category_ids |
For categories criteria, an array of category IDs that the coupon is valid for. |
array |
Required if criteria= categories |
shipping_rate_ids |
For free shipping coupons, an array of shipping_rate_ids that provide free shipping. |
array |
Required if type= shipping |
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 |
Required if type= shipping |
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 |
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 |
Request
Example request
Response
Example response
Delete a Coupon
Endpoint URL
Deletes the given coupon.
Scope: write:store-catalog
Scope: write:store-catalog
Request
Example request
Response
There is no response to a delete request.