SellOrchard
Start free trial

API reference

Discount codes

Discount codes (automatic discounts are managed in the admin).
On this page

List discount codes

get/discounts

Required scopes:read_discounts

Query parameters

NameTypeDescription
limitintegerPage size, 1–250 (default 50).

default 50 · min 1 · max 250

cursorstringnext_cursor from the previous page.
updated_sincestring<date-time>Only objects changed at or after this ISO-8601 time.
created_sincestring<date-time>Only objects created at or after this ISO-8601 time.
codestringThis code.

Example request

curl
curl "https://api.sellorchard.com/v1/discounts?limit=50" \
  -H "Authorization: Bearer $SELLORCHARD_API_KEY"

Response200Discount codes.

Show response schema
  • dataarray of Discountrequired
    Show item attributes
    • objectstringrequired
    • idintegerrequired

      Id.

    • codestringrequired

      The code (upper case).

    • titlestring | nullrequired

      Shown to shoppers.

    • typestringrequired

      Kind.

      One of:percentagefixedfree_shippingbuy_x_get_y

    • valuestringrequired

      Percent (percentage) or amount (fixed).

      pattern ^-?\d+\.\d{2}$

    • minimum_subtotalstring | nullrequired

      Minimum subtotal.

      pattern ^-?\d+\.\d{2}$

    • minimum_quantityinteger | nullrequired

      Minimum items.

    • applies_tostringrequired

      What it discounts.

      One of:allcategoriesproducts

    • product_idsarray of integerrequired

      Products (applies_to products).

    • category_idsarray of integerrequired

      Categories (applies_to categories).

    • once_per_customerbooleanrequired

      One use per customer.

    • usage_limitinteger | nullrequired

      Total uses allowed.

    • times_usedintegerrequired

      Uses so far.

    • starts_atstring<date-time> | nullrequired

      Starts.

    • ends_atstring<date-time> | nullrequired

      Ends.

    • is_activebooleanrequired

      Switched on.

    • statestringrequired

      Right now.

      One of:activescheduledexpiredused_updisabled

    • created_atstring<date-time>required

      Created.

    • updated_atstring<date-time>required

      Last changed.

  • has_morebooleanrequired

    More pages after this one.

  • next_cursorstring | nullrequired

    Pass as cursor for the next page; null on the last page.

200 response
{
  "data": [
    {
      "object": "discount",
      "id": 31,
      "code": "WELCOME10",
      "title": "Welcome 10% off",
      "type": "percentage",
      "value": "10.00",
      "minimum_subtotal": null,
      "minimum_quantity": null,
      "applies_to": "all",
      "product_ids": [],
      "category_ids": [],
      "once_per_customer": true,
      "usage_limit": null,
      "times_used": 12,
      "starts_at": null,
      "ends_at": null,
      "is_active": true,
      "state": "active",
      "created_at": "2026-11-02T15:00:00Z",
      "updated_at": "2026-11-03T09:30:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Error responses

  • 400invalid_requestMalformed request (e.g. a bad cursor).
  • 401authenticationMissing, invalid, expired or revoked API key.
  • 403permissionThe key lacks the scope, or the store's plan doesn't include the API.
  • 422invalid_requestInvalid parameters; errors lists each field.
  • 429rate_limitedToo many requests.
  • 500serverSomething went wrong on our side; safe to retry with the same Idempotency-Key.

Create a discount code

post/discounts

Fires discount.created.

Required scopes:write_discounts

Headers

NameTypeDescription
Idempotency-KeystringAny unique string (e.g. a UUID, up to 255 characters). A retry with the same key and body within 24 hours gets the first response again (Idempotent-Replayed: true); the same key with a different body is a 409 conflict.

Request body

  • codestring

    Letters, numbers, - and _ (required on create; stored upper case).

  • titlestring | null

    Shown to shoppers.

  • typestring

    Required on create.

    One of:percentagefixedfree_shipping

  • valuestring | number | null

    Percent (≤ 100) or amount; required for percentage and fixed.

  • minimum_subtotalstring | number | null
  • minimum_quantityinteger | null

    Minimum items.

  • applies_tostring

    Default all.

    One of:allcategoriesproducts

  • product_idsarray of integer

    With applies_to products.

  • category_idsarray of integer

    With applies_to categories.

  • once_per_customerboolean

    One use per customer.

  • usage_limitinteger | null

    Total uses.

  • starts_atstring<date-time> | null

    Start.

  • ends_atstring<date-time> | null

    End (after the start).

  • is_activeboolean

    Default true.

Example request

curl
curl -X POST "https://api.sellorchard.com/v1/discounts" \
  -H "Authorization: Bearer $SELLORCHARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "WELCOME10",
  "type": "percentage",
  "value": "10",
  "once_per_customer": true
}'

Response201A discount code.

Show response schema
  • dataDiscountrequired
    Show child attributes
    • objectstringrequired
    • idintegerrequired

      Id.

    • codestringrequired

      The code (upper case).

    • titlestring | nullrequired

      Shown to shoppers.

    • typestringrequired

      Kind.

      One of:percentagefixedfree_shippingbuy_x_get_y

    • valuestringrequired

      Percent (percentage) or amount (fixed).

      pattern ^-?\d+\.\d{2}$

    • minimum_subtotalstring | nullrequired

      Minimum subtotal.

      pattern ^-?\d+\.\d{2}$

    • minimum_quantityinteger | nullrequired

      Minimum items.

    • applies_tostringrequired

      What it discounts.

      One of:allcategoriesproducts

    • product_idsarray of integerrequired

      Products (applies_to products).

    • category_idsarray of integerrequired

      Categories (applies_to categories).

    • once_per_customerbooleanrequired

      One use per customer.

    • usage_limitinteger | nullrequired

      Total uses allowed.

    • times_usedintegerrequired

      Uses so far.

    • starts_atstring<date-time> | nullrequired

      Starts.

    • ends_atstring<date-time> | nullrequired

      Ends.

    • is_activebooleanrequired

      Switched on.

    • statestringrequired

      Right now.

      One of:activescheduledexpiredused_updisabled

    • created_atstring<date-time>required

      Created.

    • updated_atstring<date-time>required

      Last changed.

201 response
{
  "data": {
    "object": "discount",
    "id": 31,
    "code": "WELCOME10",
    "title": "Welcome 10% off",
    "type": "percentage",
    "value": "10.00",
    "minimum_subtotal": null,
    "minimum_quantity": null,
    "applies_to": "all",
    "product_ids": [],
    "category_ids": [],
    "once_per_customer": true,
    "usage_limit": null,
    "times_used": 12,
    "starts_at": null,
    "ends_at": null,
    "is_active": true,
    "state": "active",
    "created_at": "2026-11-02T15:00:00Z",
    "updated_at": "2026-11-03T09:30:00Z"
  }
}

Error responses

  • 401authenticationMissing, invalid, expired or revoked API key.
  • 403permissionThe key lacks the scope, or the store's plan doesn't include the API.
  • 409conflictThe Idempotency-Key was used with a different request, or that request is still running.
  • 422invalid_requestInvalid parameters; errors lists each field.
  • 429rate_limitedToo many requests.
  • 500serverSomething went wrong on our side; safe to retry with the same Idempotency-Key.

Get a discount code

get/discounts/{id}

Required scopes:read_discounts

Path parameters

NameTypeDescription
idrequiredintegerThe object id.

Example request

curl
curl "https://api.sellorchard.com/v1/discounts/120" \
  -H "Authorization: Bearer $SELLORCHARD_API_KEY"

Response200A discount code.

Show response schema
  • dataDiscountrequired
    Show child attributes
    • objectstringrequired
    • idintegerrequired

      Id.

    • codestringrequired

      The code (upper case).

    • titlestring | nullrequired

      Shown to shoppers.

    • typestringrequired

      Kind.

      One of:percentagefixedfree_shippingbuy_x_get_y

    • valuestringrequired

      Percent (percentage) or amount (fixed).

      pattern ^-?\d+\.\d{2}$

    • minimum_subtotalstring | nullrequired

      Minimum subtotal.

      pattern ^-?\d+\.\d{2}$

    • minimum_quantityinteger | nullrequired

      Minimum items.

    • applies_tostringrequired

      What it discounts.

      One of:allcategoriesproducts

    • product_idsarray of integerrequired

      Products (applies_to products).

    • category_idsarray of integerrequired

      Categories (applies_to categories).

    • once_per_customerbooleanrequired

      One use per customer.

    • usage_limitinteger | nullrequired

      Total uses allowed.

    • times_usedintegerrequired

      Uses so far.

    • starts_atstring<date-time> | nullrequired

      Starts.

    • ends_atstring<date-time> | nullrequired

      Ends.

    • is_activebooleanrequired

      Switched on.

    • statestringrequired

      Right now.

      One of:activescheduledexpiredused_updisabled

    • created_atstring<date-time>required

      Created.

    • updated_atstring<date-time>required

      Last changed.

200 response
{
  "data": {
    "object": "discount",
    "id": 31,
    "code": "WELCOME10",
    "title": "Welcome 10% off",
    "type": "percentage",
    "value": "10.00",
    "minimum_subtotal": null,
    "minimum_quantity": null,
    "applies_to": "all",
    "product_ids": [],
    "category_ids": [],
    "once_per_customer": true,
    "usage_limit": null,
    "times_used": 12,
    "starts_at": null,
    "ends_at": null,
    "is_active": true,
    "state": "active",
    "created_at": "2026-11-02T15:00:00Z",
    "updated_at": "2026-11-03T09:30:00Z"
  }
}

Error responses

  • 401authenticationMissing, invalid, expired or revoked API key.
  • 403permissionThe key lacks the scope, or the store's plan doesn't include the API.
  • 404not_foundNo such object in this store.
  • 429rate_limitedToo many requests.
  • 500serverSomething went wrong on our side; safe to retry with the same Idempotency-Key.

Update a discount code

patch/discounts/{id}

Required scopes:write_discounts

Path parameters

NameTypeDescription
idrequiredintegerThe object id.

Request body

  • codestring

    Letters, numbers, - and _ (required on create; stored upper case).

  • titlestring | null

    Shown to shoppers.

  • typestring

    Required on create.

    One of:percentagefixedfree_shipping

  • valuestring | number | null

    Percent (≤ 100) or amount; required for percentage and fixed.

  • minimum_subtotalstring | number | null
  • minimum_quantityinteger | null

    Minimum items.

  • applies_tostring

    Default all.

    One of:allcategoriesproducts

  • product_idsarray of integer

    With applies_to products.

  • category_idsarray of integer

    With applies_to categories.

  • once_per_customerboolean

    One use per customer.

  • usage_limitinteger | null

    Total uses.

  • starts_atstring<date-time> | null

    Start.

  • ends_atstring<date-time> | null

    End (after the start).

  • is_activeboolean

    Default true.

Example request

curl
curl -X PATCH "https://api.sellorchard.com/v1/discounts/120" \
  -H "Authorization: Bearer $SELLORCHARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "WELCOME10",
  "type": "percentage",
  "value": "10",
  "once_per_customer": true
}'

Response200A discount code.

Show response schema
  • dataDiscountrequired
    Show child attributes
    • objectstringrequired
    • idintegerrequired

      Id.

    • codestringrequired

      The code (upper case).

    • titlestring | nullrequired

      Shown to shoppers.

    • typestringrequired

      Kind.

      One of:percentagefixedfree_shippingbuy_x_get_y

    • valuestringrequired

      Percent (percentage) or amount (fixed).

      pattern ^-?\d+\.\d{2}$

    • minimum_subtotalstring | nullrequired

      Minimum subtotal.

      pattern ^-?\d+\.\d{2}$

    • minimum_quantityinteger | nullrequired

      Minimum items.

    • applies_tostringrequired

      What it discounts.

      One of:allcategoriesproducts

    • product_idsarray of integerrequired

      Products (applies_to products).

    • category_idsarray of integerrequired

      Categories (applies_to categories).

    • once_per_customerbooleanrequired

      One use per customer.

    • usage_limitinteger | nullrequired

      Total uses allowed.

    • times_usedintegerrequired

      Uses so far.

    • starts_atstring<date-time> | nullrequired

      Starts.

    • ends_atstring<date-time> | nullrequired

      Ends.

    • is_activebooleanrequired

      Switched on.

    • statestringrequired

      Right now.

      One of:activescheduledexpiredused_updisabled

    • created_atstring<date-time>required

      Created.

    • updated_atstring<date-time>required

      Last changed.

200 response
{
  "data": {
    "object": "discount",
    "id": 31,
    "code": "WELCOME10",
    "title": "Welcome 10% off",
    "type": "percentage",
    "value": "10.00",
    "minimum_subtotal": null,
    "minimum_quantity": null,
    "applies_to": "all",
    "product_ids": [],
    "category_ids": [],
    "once_per_customer": true,
    "usage_limit": null,
    "times_used": 12,
    "starts_at": null,
    "ends_at": null,
    "is_active": true,
    "state": "active",
    "created_at": "2026-11-02T15:00:00Z",
    "updated_at": "2026-11-03T09:30:00Z"
  }
}

Error responses

  • 401authenticationMissing, invalid, expired or revoked API key.
  • 403permissionThe key lacks the scope, or the store's plan doesn't include the API.
  • 404not_foundNo such object in this store.
  • 422invalid_requestInvalid parameters; errors lists each field.
  • 429rate_limitedToo many requests.
  • 500serverSomething went wrong on our side; safe to retry with the same Idempotency-Key.

Delete a discount code

delete/discounts/{id}

A code already used on orders is switched off instead (deleted: false).

Required scopes:write_discounts

Path parameters

NameTypeDescription
idrequiredintegerThe object id.

Example request

curl
curl -X DELETE "https://api.sellorchard.com/v1/discounts/120" \
  -H "Authorization: Bearer $SELLORCHARD_API_KEY"

Response200Deleted.

Show response schema
  • dataDeletedrequired
    Show child attributes
    • objectstringrequired

      Object type.

    • idintegerrequired

      Id.

    • deletedbooleanrequired

      true: deleted. Discounts used on orders are switched off instead (deleted false, is_active false).

200 response
{
  "data": {
    "object": "product",
    "id": 120,
    "deleted": true
  }
}

Error responses

  • 401authenticationMissing, invalid, expired or revoked API key.
  • 403permissionThe key lacks the scope, or the store's plan doesn't include the API.
  • 404not_foundNo such object in this store.
  • 429rate_limitedToo many requests.
  • 500serverSomething went wrong on our side; safe to retry with the same Idempotency-Key.