NAV

Discount Coupons

Discount coupons allow customers to get discounts on their orders in the checkout process. For store owners it’s a great way to increase sales or make a temporary promotion.

Learn more about discount coupons in our Help Center.

Search coupons

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

Request

Request example

GET /api/v3/4870020/discount_coupons?discount_type=ABS%2CPERCENT&availability=ACTIVE%2CEXPIRED&token=123abcd HTTP/1.1
Host: app.ecwid.com
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/discount_coupons?code={code}&discount_type={discount_type}&availability={availability}&limit={limit}&offset={offset}&token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
offsetnumberOffset from the beginning of the returned items list (for paging)
limitnumberMaximum number of returned items in one batch. Maximum allowed value: 100. Default value: 10
codestringCoupon code
discount_typestringComma separated list of discount types. Supported values: ABS, PERCENT, SHIPPING, ABS_AND_SHIPPING, PERCENT_AND_SHIPPING
availabilitystringComma separated list of coupon states. Supported values: ACTIVE, PAUSED, EXPIRED, USEDUP
createdFromstringCoupon creation date/time (lower bound). Supported formats:
  • UNIX timestamp
  • yyyy-MM-dd HH:mm:ss Z
  • yyyy-MM-dd HH:mm:ss
  • yyyy-MM-dd
Examples:
  • 1447804800
  • 2015-04-22 18:48:38 -0500
  • 2015-04-22 (this is 2015-04-22 00:00:00 UTC)
createdTostringCoupon creation date/time (upper bound). Supported formats:
  • UNIX timestamp
  • yyyy-MM-dd HH:mm:ss Z
  • yyyy-MM-dd HH:mm:ss
  • yyyy-MM-dd
updatedFromstringCoupon last update date/time (lower bound). Supported formats:
  • UNIX timestamp
  • yyyy-MM-dd HH:mm:ss Z
  • yyyy-MM-dd HH:mm:ss
  • yyyy-MM-dd
updatedTostringCoupon last update date/time (upper bound). Supported formats:
  • UNIX timestamp
  • yyyy-MM-dd HH:mm:ss Z
  • yyyy-MM-dd HH:mm:ss
  • yyyy-MM-dd

Response

Response example (JSON)

{
    "total": 3,
    "count": 3,
    "limit": 10,
    "offset": 0,
    "items": [
        {
            "id": 1231421413,
            "name": "Coupon # 1",
            "code": "MOXQ3YCWXRXA",
            "discountType": "ABS",
            "status": "ACTIVE",
            "discount": 1,
            "launchDate": "2014-06-06 08:00:00 +0400",
            "usesLimit": "UNLIMITED",
            "repeatCustomerOnly": false,
            "creationDate": "2014-06-06 18:57:19 +0400",
            "updateDate": "2017-01-10 02:03:43 +0000",
            "orderCount": 0,
            "catalogLimit": {
                "products": [
                    37208342,
                    37208338
                ],
                "categories": []
            }
        },
        {
            "id": 12314211242,
            "name": "Coupon # 3",
            "code": "O3Q4AP5FKXJ1",
            "discountType": "PERCENT",
            "status": "PAUSED",
            "discount": 5,
            "launchDate": "2014-06-06 08:00:00 +0400",
            "usesLimit": "UNLIMITED",
            "repeatCustomerOnly": false,
            "creationDate": "2014-06-06 08:00:00 +0400",
            "updateDate": "2017-02-10 08:03:43 +0000",
            "orderCount": 0
        }
    ]
}

A JSON object of type ‘DiscountCouponSearchResults’ with the following fields:

DiscountCouponSearchResults

FieldTypeDescription
totalnumberThe total number of found items (might be more than the number of returned items)
countnumberThe number of returned items
offsetnumberOffset from the beginning of the returned items list (for paging)
limitnumberMaximum number of returned items. Maximum allowed value: 100. Default value: 10
itemsArray<CouponSearchEntry>The items list

CouponSearchEntry

FieldTypeDescription
idnumberInternal unique coupon ID
namestringCoupon title
codestringUnique coupon code
discountTypestringDiscount type: ABS, PERCENT, SHIPPING, ABS_AND_SHIPPING, PERCENT_AND_SHIPPING
statusstringDiscount coupon state: ACTIVE, PAUSED, EXPIRED or USEDUP
discountnumberDiscount amount
launchDatestringThe date of coupon launch
expirationDatestringCoupon expiration date, e.g. 2014-06-06 08:00:00 +0400
totalLimitnumberThe minimum order subtotal the coupon applies to
usesLimitstringNumber of uses limitation: UNLIMITED, ONCEPERCUSTOMER, SINGLE
repeatCustomerOnlybooleanCoupon usage limitation flag identifying whether the coupon works for all customers or only repeat customers
creationDatestringCoupon creation date. Format example: 2016-06-29 11:36:55 +0000
updateDatestringCoupon update date. Format example: 2016-06-29 11:36:55 +0000
orderCountnumberNumber of uses
catalogLimit<DiscountCouponCatalogLimit>The products and categories the coupon can be applied to

DiscountCouponCatalogLimit

FieldTypeDescription
productsArray<number>The list of product IDs the coupon can be applied to
categoriesArray<number>The list of category IDs the coupon can be applied to

Errors

Error response example

HTTP/1.1 500 Server Error
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaning
400Request parameters are malformed
403Access token doesn’t have read_discount_coupons scope
415Unsupported content-type: expected application/json or text/json
500Cannot retrieve the coupon info because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Get coupon

Request

Request example

GET /api/v3/4870020/discount_coupons/MOXQ3YCWXRXA?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/discount_coupons/{couponIdentifier}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
couponIdentifiernumber/stringCoupon identifier in a store. It can be either unique internal coupon id OR a discount coupon code.
tokenstringoAuth token

Response

Response example (JSON)

{
    "id": 12314211242,
    "name": "Coupon # 1",
    "code": "MOXQ3YCWXRXA",
    "discountType": "ABS",
    "status": "ACTIVE",
    "discount": 1,
    "launchDate": "2014-06-06 08:00:00 +0400",
    "usesLimit": "UNLIMITED",
    "repeatCustomerOnly": false,
    "creationDate": "2014-06-06 18:57:19 +0400",
    "updateDate": "2017-02-10 08:03:43 +0000",
    "orderCount": 0,
    "catalogLimit": {
        "products": [
            37208342,
            37208338
        ],
        "categories": []
    }
}

A JSON object of type 'Coupon’ with the following fields:

Coupon

FieldTypeDescription
idnumberInternal unique coupon ID
namestringCoupon title
codestringUnique coupon code
discountTypestringDiscount type: ABS, PERCENT, SHIPPING, ABS_AND_SHIPPING, PERCENT_AND_SHIPPING
statusstringDiscount coupon state: ACTIVE, PAUSED, EXPIRED or USEDUP
discountnumberDiscount amount
launchDatestringThe date of coupon launch
expirationDatestringCoupon expliration date, e.g. 2014-06-06 08:00:00 +0400
totalLimitnumberThe minimum order subtotal the coupon applies to
usesLimitstringNumber of uses limitation: UNLIMITED, ONCEPERCUSTOMER, SINGLE
repeatCustomerOnlybooleanCoupon usage limitation flag identifying whether the coupon works for all customers or only repeat customers
creationDatestringCoupon creation date. Format example: 2016-06-29 11:36:55 +0000
updateDatestringCoupon update date. Format example: 2016-06-29 11:36:55 +0000
orderCountnumberNumber of uses
catalogLimit<DiscountCouponCatalogLimit>The products and categories the coupon can be applied to

DiscountCouponCatalogLimit

FieldTypeDescription
productsArray<number>The list of product IDs the coupon can be applied to
categoriesArray<number>The list of category IDs the coupon can be applied to

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaning
400Malformed request parameters
403Access token doesn’t have read_discount_coupons scope
404Coupon is not found
415Unsupported content-type: expected application/json or text/json

Create coupon

Create a new discount coupon in an Ecwid store.

Request

Request body

POST /api/v3/4870020/discount_coupons?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json
Cache-Control: no-cache

{
    "name": "Coupon # 1",
    "code": "MOXQ3YCWXRXA",
    "discountType": "ABS",
    "status": "ACTIVE",
    "discount": 1,
    "launchDate": "2014-06-06 08:00:00 +0400",
    "usesLimit": "UNLIMITED",
    "repeatCustomerOnly": false,
    "orderCount": 0,
    "catalogLimit": {
        "products": [
            37208342,
            37208338
        ],
        "categories": []
    }
}

POST https://app.ecwid.com/api/v3/{storeId}/discount_coupons?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token

Request body

A JSON object of type 'Coupon’ with the following fields:

Coupon

FieldTypeDescription
namestringCoupon title
codestringUnique coupon code, length limit is 128 characters.
discountTypestringDiscount type: ABS, PERCENT, SHIPPING, ABS_AND_SHIPPING, PERCENT_AND_SHIPPING . Default is ABS
statusstringDiscount coupon state: ACTIVE, PAUSED, EXPIRED or USEDUP . Default is ACTIVE
discountnumberDiscount amount . 0 is default
launchDatestringThe date of coupon launch
expirationDatestringCoupon expliration date, e.g. 2014-06-06 08:00:00 +0400
totalLimitnumberThe minimum order subtotal the coupon applies to
usesLimitstringNumber of uses limitation: UNLIMITED, ONCEPERCUSTOMER, SINGLE . UNLIMITED is default
repeatCustomerOnlybooleanCoupon usage limitation flag identifying whether the coupon works for all customers or only repeat customers. false is default
orderCountnumberNumber of uses
catalogLimit<DiscountCouponCatalogLimit>The products and categories the coupon can be applied to

DiscountCouponCatalogLimit

FieldTypeDescription
productsArray<number>The list of product IDs the coupon can be applied to
categoriesArray<number>The list of category IDs the coupon can be applied to

Response

Response example

{
    "id": 21871001,
    "code": 9698215
}

A JSON object of type 'CreateStatus’ with the following fields:

CreateStatus

FieldTypeDescription
idnumberInternal unique coupon ID
codenumberCode of the created coupon

Errors

Error response example

HTTP/1.1 409 Conflict
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, a JSON-formatted body containing error description.

HTTP codes

HTTP StatusResponse JSONDescription
400Request parameters are malformed
403Access token doesn’t have create_discount_coupons scope
409The coupon with the given code already exists
415Unsupported content-type: expected application/json or text/json
500The creation request failed because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Update coupon

Update an existing discount coupon in an Ecwid store referring to its code or ID.

Request

Request body for discount coupon code

PUT /api/v3/4870020/discount_coupons/12MOXQ3YCWXRXA?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json
Cache-Control: no-cache

{
    "name": "Coupon # 1",
    "code": "MOXQ3YCWXRXA",
    "discountType": "ABS",
    "status": "ACTIVE",
    "discount": 1,
    "launchDate": "2014-06-06 08:00:00 +0400",
    "usesLimit": "UNLIMITED",
    "repeatCustomerOnly": false,
    "orderCount": 0,
    "catalogLimit": {
        "products": [
            37208342,
            37208338
        ],
        "categories": []
    }
}

Request body for discount coupon id

PUT /api/v3/4870020/discount_coupons/123213123?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json
Cache-Control: no-cache

{
    "name": "Coupon # 1",
    "code": "MOXQ3YCWXRXA",
    "discountType": "ABS",
    "status": "ACTIVE",
    "discount": 1,
    "launchDate": "2014-06-06 08:00:00 +0400",
    "usesLimit": "UNLIMITED",
    "repeatCustomerOnly": false,
    "orderCount": 0,
    "catalogLimit": {
        "products": [
            37208342,
            37208338
        ],
        "categories": []
    }
}

PUT https://app.ecwid.com/api/v3/{storeId}/discount_coupons/{couponIdentifier}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
couponIdentifiernumber/stringCoupon identifier in a store. It can be either unique internal coupon id OR a discount coupon code.

Request body

A JSON object of type 'Coupon’ with the following fields:

Coupon

FieldTypeDescription
namestringCoupon title
codestringUnique coupon code, length limit is 128 characters.
discountTypestringDiscount type: ABS, PERCENT, SHIPPING, ABS_AND_SHIPPING, PERCENT_AND_SHIPPING .
statusstringDiscount coupon state: ACTIVE, PAUSED, EXPIRED or USEDUP .
discountnumberDiscount amount .
launchDatestringThe date of coupon launch
expirationDatestringCoupon expliration date, e.g. 2014-06-06 08:00:00 +0400
totalLimitnumberThe minimum order subtotal the coupon applies to
usesLimitstringNumber of uses limitation: UNLIMITED, ONCEPERCUSTOMER, SINGLE .
repeatCustomerOnlybooleanCoupon usage limitation flag identifying whether the coupon works for all customers or only repeat customers.
orderCountnumberNumber of uses
catalogLimit<DiscountCouponCatalogLimit>The products and categories the coupon can be applied to

DiscountCouponCatalogLimit

FieldTypeDescription
productsArray<number>The list of product IDs the coupon can be applied to
categoriesArray<number>The list of category IDs the coupon can be applied to

Response

Response example

{
    "updateCount": 1
}

A JSON object of type 'UpdateStatus’ with the following fields:

UpdateStatus

FieldTypeDescription
updateCountnumberThe number of updated coupons (1 or 0 depending on whether the update was successful)

Errors

Error response example

HTTP/1.1 409 Conflict
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, a JSON-formatted body containing error description.

HTTP codes

HTTP StatusResponse JSONDescription
400Request parameters are malformed
403Access token doesn’t have update_discount_coupons scope
409The coupon with the given code already exists
415Unsupported content-type: expected application/json or text/json
500The request failed because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Delete coupon

Delete a specific coupon from an Ecwid store referring to its code or ID.

Request example

DELETE /api/v3/4870020/discount_coupons/MOXQ3Y222CWXRXA?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

DELETE https://app.ecwid.com/api/v3/{storeId}/discount_coupons/{couponIdentifier}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
couponIdentifiernumber/stringCoupon identifier in a store. It can be either unique internal coupon id OR a discount coupon code.
tokenstringoAuth token

Response

Response example

{
    "deleteCount": 1
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted coupons (1 or 0 depending on whether the request was successful). It returns 0 when the coupon with the given code is not found

Errors

Error response example

HTTP/1.1 500 Server Error
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description.

HTTP codes

HTTP StatusResponse JSONDescription
400Request parameters are malformed
403Access token doesn’t have update_discount_coupons scope
500The request failed because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message