Merchant offers

A store can discount its own products. Customers see the discounted price in the cart, and checkout re-checks it; how prices are computed is in Cart & checkout.

Offer endpoints are store-scoped: the owner and the store's staff can use them.

Creating an offer#

POST stores/{store}/offers, multipart when it carries an image:

Field	Rule
name[ar], name[en]	required
description[ar], description[en]	optional
type	percentage, fixed or buy_x_get_y
value	required for percentage (percent off) and fixed (SAR off each unit)
buy_quantity, get_quantity	required for buy_x_get_y: buy 2 get 1 is 2 and 1
starts_at, ends_at	when it runs; ends_at is optional (no end)
usage_limit	optional; the offer stops after this many orders
is_active	switch it off without deleting it
image	optional, 2 MB

Always send starts_at. An offer saved without it is accepted but never applies, because only offers that have started are used. Send the current time to start at once.

What an offer applies to#

Choose the products in one of two ways:

• product_ids[] — specific products. Each must already be linked to the store.
• category_ids[] and sub_category_ids[] — every product in those categories. A product matches when its own category is in the list, so to cover a parent category's sub-categories, send them in sub_category_ids[] too. A category with none of the store's products is refused.

An offer that lists products applies to those products only, even if it also lists categories.

Avoid overlapping offers: when two active offers could apply to the same product, which one is used is not defined.

Usage limits#

usage_limit counts orders, not units: an order using the offer on several lines counts once. When the limit is reached, the offer stops applying at once, and it disappears from the customer app's limited offers feed. A customer whose cart still shows the old price is told at checkout (prices_changed).

Listing and editing#

• offers, offers/active, offers/expired list the store's offers.
• offers/{offer} reads one; update takes the same fields (use POST when sending a new image); delete removes it.

Orders already placed keep the price they were charged; changing or deleting an offer never alters them.