Skip to content
API referenceCore API

Update a discount

For AI assistants: the facts every SparkLayer API call needs
  • Base URLs: Live https://app.sparklayer.io, test https://test.app.sparklayer.io. Each environment has its own data and its own API keys.
  • Access: API access needs the Pro or Enterprise plan. Create credentials (Site ID, Client ID, Client Secret) in the SparkLayer Dashboard at Settings > API.
  • Access token: POST {base}/api/auth/token with a Site-Id header and a JSON body (not form-encoded): {"grant_type":"client_credentials","client_id":"…","client_secret":"…"}. It returns access_token, valid for 3,600 seconds. There is no refresh token: cache the token and request a new one shortly before it expires.
  • Every request: Authorization: Bearer <access_token> and Site-Id: <site id>, plus Content-Type: application/json when there is a body. Set a User-Agent that names your integration.
  • Errors: RFC 7807 problem details: title, status, detail and an optional errors[] of { code, message, property }. Some error responses have no body. Retry 5xx, 429 (honouring Retry-After) and concurrent-update 409s with exponential backoff; on 401, get a new token once and retry; don't retry other 4xx without changing the request.
  • Pagination: Most list endpoints return everything. GET /api/v2/price-lists pages with page and page_size (up to 250) until pagination.current_page equals total_pages. GET /api/v1/purchases uses limit (up to 500) and offset: stop when a page has fewer than limit results.
  • Ground rules: Use only endpoints, fields and SDK methods that the docs or OpenAPI specs define. Prefer GET /api/v2/price-lists over the deprecated v1. Products are matched by SKU. Keep credentials in environment variables or a secrets manager, never in code.
  • Read the docs as Markdown: Add .md to any page URL. Index of every page: docs.sparklayer.io/llms.txt. Every API operation, compactly: docs.sparklayer.io/llms-api.txt. The developer guides in full: docs.sparklayer.io/developers/llms.txt.
  • OpenAPI specs: core, ordering, pricing, purchasing, stock, files, sync-log: https://docs.sparklayer.io/openapi/<api>.yaml (also .json). Ignite: https://docs.sparklayer.io/openapi/ignite.yaml.
  • MCP: Search and read these docs from your assistant with the docs MCP server at https://docs.sparklayer.io/mcp.
Build with AI: ready-made prompts and MCP setup
PATCH
/api/v1/discounts/{id}

Replaces the discount with the object you send, so include every required field, not just the ones you're changing. internal_slug can't be changed and must match the existing value, otherwise you get a 400. The same currency, coupon code and size rules apply as when creating a discount, and an unknown ID returns 404.

Authorization

bearerAuth
AuthorizationBearer <token>

Send Authorization: Bearer <access_token>, together with your Site-Id header, on every request. Get the token from POST /api/auth/token with your Site ID in the Site-Id header and a JSON body (not form-encoded, so standard OAuth 2.0 client libraries don't work): {"grant_type": "client_credentials", "client_id": "…", "client_secret": "…"}. Tokens are valid for 3,600 seconds and there is no refresh token: request a new one shortly before it expires. Create API credentials in the SparkLayer Dashboard under Settings > API. See Authentication.

In: header

Path Parameters

id*string

The discount's ID (a UUID).

Header Parameters

Site-Id*string

Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?string

A user friendly name for the discount

Lengthlength <= 256
internal_name*string
Lengthlength <= 45
internal_slug*string
Lengthlength <= 45
template?|

Discount template type. If not null allowed values are - 'order_level_get_amount_off', 'order_level_get_free_product', 'product_level_get_amount_off', 'order_level_get_shipping_reward', 'advanced_order_level_get_amount_off', 'order_level_requirement_amount_off', 'advanced_discount', 'advanced_free_products'

calculation_group*number

Dependency level = Calculation Group. All discounts with the same dependency level will share the same base, pre-discount totals. E.g. discount A (50% off) and discount B (50% off) will reward 100% off - not 75% off.

Range0 <= value <= 127
priority*number

The sequence to apply the discounts (within each discount 'dependency level')

Range0 <= value <= 10000
times_applicable_per_order*number

Per order application limits. If -1 allow unlimited applications, otherwise limited

Range-1 <= value <= 127
max_rewards?|

Used when rewardSelectionType is cheapest or expensive to determine the number of rewards available

Range1 <= value <= 127
Default1
groups*array<string>

Customer groups covered by this discount (use default to cover all groups)

excluded_customers?array<string>

Array of email address or accounting ids of customers to exclude from the discount

simultaneity?array<>|

Other discounts which can be applied simultaneous, if null no limitation

requirement_selection_type*string

Products which must be in the cart must match all or any one of the combo groups

Value in

  • "any"
  • "all"
reward_selection_type*string

Value in

  • "all"
  • "cheapest"
  • "expensive"
currency_code*|
Length3 <= length <= 3
start_date*|

Start Date

Formatdate-time
end_date*|

End Date

Formatdate-time
active*boolean
requirements*array<>
rewards?array<>
other_requirements*array<|||>

Response Body

application/json

application/problem+json

curl -X PATCH "https://app.sparklayer.io/api/v1/discounts/942651af-f950-4716-9916-16170fe0645f" \  -H "Authorization: Bearer <ACCESS_TOKEN>" \  -H "Site-Id: jones-climbing" \  -H "Content-Type: application/json" \  -d '{    "name": "<name>",    "internal_name": "<internal_name>",    "internal_slug": "<internal_slug>",    "template": "<template>",    "calculation_group": 0,    "priority": 0,    "times_applicable_per_order": -1,    "max_rewards": 1,    "groups": [      "default"    ],    "excluded_customers": [      "customer@b2b.com"    ],    "simultaneity": [      "default"    ],    "requirement_selection_type": "any",    "reward_selection_type": "all",    "currency_code": "gbp",    "start_date": "2026-01-31T09:00:00Z",    "end_date": "2026-01-31T09:00:00Z",    "active": true,    "requirements": [      {        "items": [          {            "restrictions": [              {                "type": "productSKU",                "ref": "<ref>",                "metadata_namespace": "erp",                "metadata_key": "vendor"              }            ],            "points_type": "line",            "points": 1,            "quantity": 0,            "selection_type": "minimum"          }        ],        "max_rewards": 0,        "min_spend": 0,        "max_spend": 0,        "spend_tax_type": "net",        "selection_type": "minimum",        "min_points": 0      }    ],    "rewards": [      {        "type": "requirements|all",        "amount_type": "percent",        "restriction_type": "equals",        "item_id": "<item_id>",        "metadata_namespace": "erp",        "metadata_key": "vendor",        "amount": 0      }    ],    "other_requirements": [      {        "requirement_type": "coupons",        "coupons": [          {            "code": "<code>"          }        ]      }    ]  }'
{  "id": "942651af-f950-4716-9916-16170fe0645f",  "created_at": "2019-08-24T14:15:22Z",  "deleted_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z",  "name": "string",  "internal_name": "string",  "internal_slug": "string",  "template": "string",  "calculation_group": 0,  "priority": 0,  "times_applicable_per_order": -1,  "max_rewards": 1,  "groups": [    "default"  ],  "excluded_customers": [    "customer@b2b.com"  ],  "simultaneity": [    "default"  ],  "requirement_selection_type": "any",  "reward_selection_type": "all",  "currency_code": "gbp",  "start_date": "2019-08-24T14:15:22Z",  "end_date": "2019-08-24T14:15:22Z",  "active": true,  "requirements": [    {      "items": [        {          "restrictions": [            {              "type": "productSKU",              "ref": "string",              "metadata_namespace": "erp",              "metadata_key": "vendor"            }          ],          "points_type": "line",          "points": 1,          "quantity": 0,          "selection_type": "minimum"        }      ],      "max_rewards": 0,      "min_spend": 0,      "max_spend": 0,      "spend_tax_type": "net",      "selection_type": "minimum",      "min_points": 0    }  ],  "rewards": [    {      "type": "requirements|all",      "amount_type": "percent",      "restriction_type": "equals",      "item_id": "string",      "metadata_namespace": "erp",      "metadata_key": "vendor",      "amount": 1000000000    }  ],  "other_requirements": [    {      "requirement_type": "coupons",      "coupons": [        {          "code": "string"        }      ]    }  ]}

DELDelete a discount

Deletes a discount so it no longer applies to carts or appears in the API, and returns `204`. Returns `404` if the discount doesn't exist.

GETList shipping methods

Returns every shipping method configured for the store, including its bands, as a single array. Methods aren't filtered by country, customer group or cart contents, and the list isn't paginated.