Zopping
Get a token

Offer engine

The advanced companion to Run promotions. Where coupons are simple codes, offers are automatic, rule-based promotions: BOGO, cart and shipping discounts, "buy X at this price", segment-targeted deals, and stacking.

Anatomy of an offer

An offer is type + rule + scope:

  • offerType — the promotion shape (see types below). Determines the rule format.
  • rule — a JSON payload with the conditions and the discount/benefit.
  • scope & limits — storeId, orderType, paymentType, validity dates, customerRedemptionLimit, totalRedemption, stackable, and userSet (segment eligibility).

Common offer types

TypeMeaning
SFXGCDShop for X → cart discount
SFXGSDShop for X → shipping discount
BXGYDBuy X, get Y discounted (BOGO family)
BMINBuy a minimum quantity → discount
BXATP / BANYATPBuy X / any N at this price
PWPPay-what-price (tag-based)

Discount values inside rule use t (PERCENT_OFF, FIXED, FREE) and v (the amount/percent). The rule schema depends on offerType — the formats are below.

Rule formats by offer type

SFXGCD — shop for X, get a cart discount

An array of thresholds; the highest matched one applies. Each has a cartPrice floor, the cartDiscount (t/v), an optional maxDiscount cap, and optional timeSlots.

[
  {
    "cartPrice": 500,
    "cartDiscount": {
      "t": "PERCENT_OFF",
      "v": 10
    },
    "maxDiscount": 200
  },
  {
    "cartPrice": 1000,
    "cartDiscount": {
      "t": "PERCENT_OFF",
      "v": 15
    },
    "maxDiscount": 400
  }
]

SFXGSD — shop for X, get a shipping discount

Same shape as SFXGCD, but the benefit waives/reduces shipping ("t": "FREE" for free delivery).

BXGYD — buy X, get Y discounted (BOGO family)

buy lists the qualifying items (by product id) and required quantity q; get lists what's discounted (with optional variantId); limit caps repetitions. "t": "FREE" makes the "get" item free.

{
  "buy": {
    "1001": {
      "q": 2,
      "t": "FIXED",
      "v": 0
    }
  },
  "get": {
    "1001": {
      "variantId": 1001,
      "q": 1,
      "t": "FREE",
      "v": null
    }
  },
  "limit": 3
}

BMIN — buy a minimum quantity from a set

Scope with entity (PRODUCT/CATEGORY/TAG) + entityIds; each elementGroups entry gives a minQuantity/minAmount threshold and its total discount with a maxDiscount cap.

{
  "entity": {
    "type": "CATEGORY"
  },
  "entityIds": [
    10,
    20
  ],
  "elementGroups": [
    {
      "minQuantity": 3,
      "minAmount": 0,
      "total": {
        "t": "PERCENT_OFF",
        "v": 20
      },
      "maxDiscount": 1000
    }
  ]
}

BXATP / BANYATP — buy X / any N at this price

Fixed-price-for-quantity deals — buy the specified items (or any N from a set) at a set price. The rule carries the qualifying items/entity and the target price.

Other types (PWP pay-what-price, SF shop-for, shipping variants) follow the same t/v discount convention with type-specific conditions. When in doubt, read an existing offer of that type via GET /api/offer-service/offer and mirror its rule.

Create a cart discount (20% over ₹500)

curl -X POST https://zopping.com/api/offer-service/offer \
  -H "Authorization: Bearer $ZOPPING_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "organizationId": "<org-id>", "storeId": "<store-id>", "status": "ACTIVE",
    "offerType": "SFXGCD",
    "offerValidFrom": "2026-06-22", "offerValidTill": "2026-12-31",
    "stackable": true, "orderType": ["DELIVERY"],
    "rule": { "cartPrice": 500, "cartDiscount": { "t": "PERCENT_OFF", "v": 20 }, "maxDiscount": 500 }
  }'

Create a BOGO (buy 2, get 1 free)

curl -X POST https://zopping.com/api/offer-service/offer \
  -H "Authorization: Bearer $ZOPPING_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "organizationId": "<org-id>", "storeId": "<store-id>", "status": "ACTIVE",
    "offerType": "BXGYD", "offerValidFrom": "2026-06-22", "offerValidTill": "2026-06-30",
    "rule": {
      "buy": { "1001": { "q": 2, "t": "FIXED", "v": 0 } },
      "get": { "1001": { "variantId": 1001, "q": 1, "t": "FREE", "v": null } },
      "limit": 3
    }
  }'

Evaluate offers against a cart

Send the cart and context; get back applicable offers and potential offers (what the shopper could unlock):

curl -X POST https://zopping.com/api/offer-service/cart-offers \
  -H "Authorization: Bearer $ZOPPING_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "organizationId": "<org-id>", "storeId": "<store-id>", "customerId": 7781,
    "orderType": "DELIVERY", "paymentType": "UPI",
    "data": [ { "id": 2268, "quantity": 10, "mrp": 100, "discount": 0, "categoryIds": [302] } ]
  }'

The response carries offerSets (applied: cartDiscount, shippingDiscount, appliedPromoCode) and potentialOffers.

Targeting & campaigns

  • userSet on an offer restricts it to a customer segment.
  • Campaigns (promo-service/campaign) tie offers/coupons to segments and schedule delivery (email/push) — see Customer segments & targeting.
  • stackable controls whether an offer can combine with others.

Going further

Reference: Promotions.