Docs / API reference / Discounts

Discounts

Discount codes.

List discount codes#

GET/api/public/v1/discountsdiscounts:read

List discount codes, newest first. Lists discount codes of the shop.

Query parameters

limitinteger

Page size. Clamped to 1..200. Non-numeric values fall back to the default. Default: 50.

cursorstring (ISO 8601 timestamp)

Value of next_cursor from the previous page. Returns items with created_at strictly before this timestamp.

active"true" | "false"

Filter by active flag.

codestring

Exact code; upper-cased before matching (so case-insensitive for upper-case stored codes).

shop_iduuid

Only for OAuth tokens that cover several shops: the shop to query. Must be one of the token's shops (else 403 forbidden). Required when the token covers more than one shop (else 400 shop_required). Optional for API keys (a key belongs to exactly one shop; any other value returns 403).

Response fields

dataarray

Items of this page.

next_cursorstring|null

created_at of the last item when more items exist, otherwise null.

data[].iduuid

Discount id.

data[].codestring

Discount code (stored upper-case).

data[].titlestring|null

Internal title.

data[].typestring

percentage | fixed | free_shipping (values from the MCP manage_discount schema).

data[].value_centsinteger

For type=percentage: the percentage (e.g. 10). For fixed: amount in minor units. For free_shipping: unused.

data[].applies_tostring

all | products.

data[].product_idsuuid[]|null

Products the code applies to when applies_to=products.

data[].min_purchase_centsinteger|null

Minimum order value.

data[].min_quantityinteger|null

Minimum item quantity.

data[].usage_limit_totalinteger|null

Total redemption limit.

data[].usage_limit_per_customerinteger|null

Per-customer limit.

data[].combinableboolean|null

Whether combinable with other discounts.

data[].starts_attimestamp|null

Start of validity.

data[].ends_attimestamp|null

End of validity.

data[].activeboolean

Active flag.

data[].times_usedinteger

Redemptions so far.

data[].created_attimestamp

Creation time; pagination key.

data[].updated_attimestamp

Last update.

Errors

401unauthorized

Any endpoint. Response carries header WWW-Authenticate: Bearer resource_metadata="<origin>/.well-known/oauth-protected-resource".

403forbidden

Scope check per endpoint (and per body field on PATCH /orders/:id).

403forbidden

shop_id query parameter names a shop outside the credential's reach.

400shop_required

Multi-shop OAuth token without shop_id.

404not_found

Any endpoint when the resolved shop has active=false.

429rate_limited

Any endpoint. Header Retry-After (seconds until the next minute bucket).

500server_error

Any endpoint.

Try itNot authorized

Request

curl "https://api.ecomone.shop/api/public/v1/discounts?limit=10" \
  -H "X-Api-Key: $ECOMONE_API_KEY" \
  -H "X-Api-Secret: $ECOMONE_API_SECRET"

const res = await fetch("https://api.ecomone.shop/api/public/v1/discounts?limit=10", {
  method: "GET",
  headers: {
    "X-Api-Key": process.env.ECOMONE_API_KEY,
    "X-Api-Secret": process.env.ECOMONE_API_SECRET,
  },
});
if (!res.ok) throw new Error((await res.json()).message);
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.ecomone.shop/api/public/v1/discounts?limit=10",
    headers={
        "X-Api-Key": os.environ["ECOMONE_API_KEY"],
        "X-Api-Secret": os.environ["ECOMONE_API_SECRET"],
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()["data"]

200Response

{
  "data": [
    {
      "id": "a1b2c3d4-1111-4222-8333-444455556666",
      "code": "SUMMER10",
      "title": "Summer sale",
      "type": "percentage",
      "value_cents": 10,
      "applies_to": "all",
      "product_ids": [],
      "min_purchase_cents": 4900,
      "min_quantity": 0,
      "usage_limit_total": 500,
      "usage_limit_per_customer": 1,
      "combinable": false,
      "starts_at": "2026-06-01T00:00:00.000Z",
      "ends_at": "2026-09-01T00:00:00.000Z",
      "active": true,
      "times_used": 118,
      "created_at": "2026-05-28T12:00:00.000Z",
      "updated_at": "2026-05-28T12:00:00.000Z"
    }
  ],
  "next_cursor": null
}

Retrieve a discount code#

GET/api/public/v1/discounts/{id}discounts:read

Retrieve one discount by UUID or code. If :id is a UUID it is matched against id, otherwise exactly (case-sensitive, NOT upper-cased) against code.

Path parameters

iduuid | stringrequired

Discount UUID or code (use the exact stored case, normally upper-case).

Query parameters

shop_iduuid

Response fields

data.iduuid

Discount id.

data.codestring

Discount code (stored upper-case).

data.titlestring|null

Internal title.

data.typestring

percentage | fixed | free_shipping (values from the MCP manage_discount schema).

data.value_centsinteger

For type=percentage: the percentage (e.g. 10). For fixed: amount in minor units. For free_shipping: unused.

data.applies_tostring

all | products.

data.product_idsuuid[]|null

Products the code applies to when applies_to=products.

data.min_purchase_centsinteger|null

Minimum order value.

data.min_quantityinteger|null

Minimum item quantity.

data.usage_limit_totalinteger|null

Total redemption limit.

data.usage_limit_per_customerinteger|null

Per-customer limit.

data.combinableboolean|null

Whether combinable with other discounts.

data.starts_attimestamp|null

Start of validity.

data.ends_attimestamp|null

End of validity.

data.activeboolean

Active flag.

data.times_usedinteger

Redemptions so far.

data.created_attimestamp

Creation time; pagination key.

data.updated_attimestamp

Last update.

Errors

400bad_request

Detail endpoints and PATCH.

404not_found

Detail endpoints.

401unauthorized

Any endpoint. Response carries header WWW-Authenticate: Bearer resource_metadata="<origin>/.well-known/oauth-protected-resource".

403forbidden

Scope check per endpoint (and per body field on PATCH /orders/:id).

403forbidden

shop_id query parameter names a shop outside the credential's reach.

400shop_required

Multi-shop OAuth token without shop_id.

404not_found

Any endpoint when the resolved shop has active=false.

429rate_limited

Any endpoint. Header Retry-After (seconds until the next minute bucket).

500server_error

Any endpoint.

Try itNot authorized

Request

curl "https://api.ecomone.shop/api/public/v1/discounts/WINTER10" \
  -H "X-Api-Key: $ECOMONE_API_KEY" \
  -H "X-Api-Secret: $ECOMONE_API_SECRET"

const res = await fetch("https://api.ecomone.shop/api/public/v1/discounts/WINTER10", {
  method: "GET",
  headers: {
    "X-Api-Key": process.env.ECOMONE_API_KEY,
    "X-Api-Secret": process.env.ECOMONE_API_SECRET,
  },
});
if (!res.ok) throw new Error((await res.json()).message);
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.ecomone.shop/api/public/v1/discounts/WINTER10",
    headers={
        "X-Api-Key": os.environ["ECOMONE_API_KEY"],
        "X-Api-Secret": os.environ["ECOMONE_API_SECRET"],
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()["data"]

200Response

{
  "data": {
    "id": "a1b2c3d4-1111-4222-8333-444455556666",
    "code": "SUMMER10",
    "title": "Summer sale",
    "type": "percentage",
    "value_cents": 10,
    "applies_to": "all",
    "product_ids": [],
    "min_purchase_cents": 4900,
    "min_quantity": 0,
    "usage_limit_total": 500,
    "usage_limit_per_customer": 1,
    "combinable": false,
    "starts_at": "2026-06-01T00:00:00.000Z",
    "ends_at": "2026-09-01T00:00:00.000Z",
    "active": true,
    "times_used": 118,
    "created_at": "2026-05-28T12:00:00.000Z",
    "updated_at": "2026-05-28T12:00:00.000Z"
  }
}