Search discount coupons

get https://app.ecwid.com/api/v3/{storeId}/discount_coupons

Search or filter discount coupons in an Ecwid store. Filters include: discount coupon code, type, availability.

Request and response example

Request:

curl --location 'https://app.ecwid.com/api/v3/1003/discount_coupons' \
--header 'Authorization: Bearer secret_ab***cd'

Response:

{
    "total": 2,
    "count": 2,
    "offset": 0,
    "limit": 100,
    "items": [
        {
            "id": 162428889,
            "name": "Summer Promo",
            "code": "DISC",
            "discountType": "ABS",
            "status": "ACTIVE",
            "discount": 10,
            "launchDate": "2022-07-28 23:00:00 +0000",
            "usesLimit": "UNLIMITED",
            "repeatCustomerOnly": false,
            "applicationLimit": "UNLIMITED",
            "creationDate": "2022-07-29 15:22:35 +0000",
            "updateDate": "2024-05-01 05:26:28 +0000",
            "orderCount": 1
        },
        {
            "id": 224219782,
            "name": "Test Coupon",
            "code": "DISC2",
            "discountType": "PERCENT",
            "status": "ACTIVE",
            "discount": 10,
            "launchDate": "2024-09-01 23:00:00 +0000",
            "usesLimit": "UNLIMITED",
            "repeatCustomerOnly": false,
            "applicationLimit": "UNLIMITED",
            "creationDate": "2024-09-02 07:55:21 +0000",
            "updateDate": "2024-09-02 08:33:26 +0000",
            "orderCount": 3
        }
    ]
}

Access scopes

Requires the following access scope: read_discount_coupons

Path params

Param	Type	Description
storeId	number	Ecwid store ID.

Query params

All query params are optional.

Name	Type	Description
offset	number	Offset from the beginning of the returned items list (for paging).
limit	number	Maximum number of returned items in one batch. Default value: `100`. Maximum allowed value: `100`.
code	string	Search term for the discount coupon code.
discount_type	string	Search term for the discount coupon type. Supported values: `ABS`, `PERCENT`, `SHIPPING`, `ABS_AND_SHIPPING`, `PERCENT_AND_SHIPPING`.
availability	string	Search term for the current state of the discount coupon. Supported values: `ACTIVE`, `PAUSED`, `EXPIRED`, `USEDUP`.
createdFrom	string	Coupon creation date/time (lower bound). Supported formats: UNIX timestamp, date/time. Examples: `1447804800`, `2023-01-15 19:27:50`.
createdTo	string	Coupon creation date/time (upper bound). Supported formats: UNIX timestamp, date/time. Examples: `1447804800`, `2023-01-15 19:27:50`.
updatedFrom	string	Coupon last update date/time (lower bound). Supported formats: UNIX timestamp, date/time. Examples: `1447804800`, `2023-01-15 19:27:50`.
updatedTo	string	Coupon last update date/time (upper bound). Supported formats: UNIX timestamp, date/time. Examples: `1447804800`, `2023-01-15 19:27:50`.
responseFields	string	Limit JSON response by specific fields. If specified, all missing fields will be removed from the response body. Example: `?responseFields=items(id,name,status)`

Example of using responseFields param:

curl --location 'https://app.ecwid.com/api/v3/1003/discount_coupons?responseFields=items(id,name,status)' \
--header 'Authorization: Bearer secret_ab***cd'

{
    "items": [
        {
            "id": 162428889,
            "name": "Summer Promo",
            "status": "ACTIVE"
        },
        {
            "id": 224219782,
            "name": "Test Coupon",
            "status": "ACTIVE"
        }
    ]
}

Headers

The Authorization header with a secret access token is required.

Header	Format	Description
Authorization	`Bearer secret_ab***cd`	Access token of the application.

Response

A JSON object with the following fields:

Field	Type	Description
total	number	The total number of found items (might be more than the number of returned items)
count	number	The number of returned items
offset	number	Offset from the beginning of the returned items list (for paging)
limit	number	Maximum number of returned items. Maximum allowed value: `100`. Default value: `100`
items	Array items	Detailed information about found discount coupons.

items

Field	Type	Description
id	number	Internal unique coupon ID.
name	string	Discount coupon name visible on the storefront.
code	string	Discount coupon code used for its activation at the checkout.
discountType	string	Discount type: `ABS`, `PERCENT`, `SHIPPING`, `ABS_AND_SHIPPING`, `PERCENT_AND_SHIPPING`
status	string	Discount coupon state: `ACTIVE`, `PAUSED`, `EXPIRED` or `USEDUP`
discount	number	Discount coupon value.
launchDate	string	The date of coupon launch, e.g. `2014-06-06 08:00:00 +0400`. Any date provided will be corrected to the UTC timezone
expirationDate	string	Coupon expiration date, e.g. `2014-06-06 08:00:00 +0400`. Any date provided will be corrected to the UTC timezone
totalLimit	number	Minimum order subtotal for the discount coupon to be applied.
usesLimit	string	Number of uses limitation: `UNLIMITED`, `ONCEPERCUSTOMER`, `SINGLE`
repeatCustomerOnly	boolean	DEPRECATED Use `applicationLimit` instead.
applicationLimit	string	User application limit for the discount coupon. Supported values: `"UNLIMITED"` - no user application limits. `"NEW_CUSTOMER_ONLY"` - discount coupon can be applied only by customers without placed orders. `"REPEAT_CUSTOMER_ONLY"` - discount coupon can be applied only by customers who placed orders in the store before.
creationDate	string	Coupon creation date. Format example: `2023-06-29 11:36:55 +0000`
updateDate	string	Coupon update date. Format example: `2023-06-29 11:36:55 +0000`
orderCount	number	Counter for the discount coupon uses.
catalogLimit	Object catalogLimit	Product and category limitations for the discount coupon. If empty, discount coupon can be applied to all products and categories available on the storefront.
shippingLimit	Object shippingLimit	Shipping method limitations for the discount coupon. If empty, discount coupon can be applied to any shipping method available at the checkout.

catalogLimit

Field	Type	Description
products	Array of numbers	List of product IDs the discount coupon can be applied to, e.g. `[123456,234567]`
categories	Array of numbers	List of category IDs the discount coupon can be applied to, e.g. `[0,87253552,765257901]`

shippingLimit

Field	Type	Description
shippingMethods	Array of strings	List of shipping method IDs the discount coupon can be applied to, e.g. `["18765-8651899366181"]`