Coupons Offers Cashback Lottery

Coupons, Offers, Cashback and Lottery

Selldone shops can run several incentive programs: coupons, product offers ("buy X, get Y"), cashback programs and a lottery. The Storefront SDK gives you read access to each of them, so you can show what a customer is eligible for on product pages, in the cart and in the account area. All of these calls are promise based and support the cache helpers.

Namespace	Method	Endpoint (XAPI)	Response
coupon	fetchAvailableCoupons(currency)	GET /shops/@{shop}/coupons	{ coupons: Partial<Coupon>[] }
offer	fetchOffers(currency)	GET /shops/@{shop}/offers	{ offers: Partial<Offer>[] }
cashback	get(currency, amount)	GET /shops/@{shop}/cashback	{ cashback: Partial<Cashback>[] }
lottery	fetchLotteryPrizes({ limit = 10 })	GET /shops/@{shop}/lottery/wins	{ prizes: Partial<Lottery>[] }

The Coupon, Offer, Cashback and Lottery models come from Selldone Core (@selldone/core-js/models/shop/incentives/…). Programs are currency-specific, so pass the customer's selected currency and reload them when it changes.

Coupons

const currency = window.$storefront.currency.code;

window.$storefront.coupon
  .fetchAvailableCoupons(currency)
  .then(({ coupons }) => {
    // coupons[i]: id, code, title, description, percent, limit, charge, currency,
    //             min_purchase, only_first_buy, start, end, color, …
  });

The call returns the coupons the customer qualifies for, plus coupons whose codes they entered before. Entered codes are kept in the SDK's local database and sent automatically as codes:

// Remember a code the customer typed, then reload the list
window.$storefront.database.coupon.addCouponCode("WELCOME10");
const { coupons } = await window.$storefront.coupon.fetchAvailableCoupons(currency);

// Forget it
window.$storefront.database.coupon.removeCouponCode("WELCOME10");

To look up a single code or apply a coupon to the basket, use the XAPI URL builders (see Basket and Checkout):

Action	URL builder	Endpoint
Find a coupon by code	GET_COUPONS_BY_CODE(shop, code)	GET /shops/@{shop}/coupons/{coupon_code}
Apply a coupon to the basket	PUT_SET_BASKET_COUPON(shop)	PUT /shops/@{shop}/coupon
Apply a discount code	PUT_DISCOUNT_CODE(shop)	PUT /shops/@{shop}/discount-code

Offers

Offers are automatic promotions such as "buy these products, get those at a discount".

const { offers } = await window.$storefront.offer.fetchOffers(window.$storefront.currency.code);
// offers[i]: id, title, description, percent, min_quantity, min_purchase,
//            buy_products, get_products, start, end, currency, color, …

Show them on product pages and in the cart. The server applies qualifying offers to the basket bill.

Cashback

Cashback programs return part of the purchase amount to the customer. Ask which programs apply to a given amount, for example the current product price or the basket total:

const { cashback } = await window.$storefront.cashback.get(
  window.$storefront.currency.code,
  129.99, // amount
);
// cashback[i]: title, percent, limit, min_purchase, only_first_buy, boosted, start, end, …

Lottery prizes

Customers who play the shop's lottery can win prizes and redeem one during checkout. A prize can carry a discount, a product variant or a gift card type. fetchLotteryPrizes() returns the prizes the signed-in customer has won, so call it after login:

const { prizes } = await window.$storefront.lottery.fetchLotteryPrizes({ limit: 10 });
// prizes[i]: id, title, description, image, color, amount, currency,
//            discount, discount_limit, product_id, variant_id, card_type_id, …

Related URL builders for the lottery game itself:

Action	URL builder	Endpoint
List the shop's lottery items	GET_FETCH_LOTTERIES(shop)	GET /shops/@{shop}/lottery
Play	POST_FETCH_LOTTERIES(shop)	POST /shops/@{shop}/lottery/play
Use a prize in the basket	PUT_SET_BASKET_LOTTERY(shop)	PUT /shops/@{shop}/lottery

Gift cards

Gift cards are not wrapped by the SDK yet. Use GET_MY_GIFT_CARDS(shop) / POST_ADD_GIFT_CARDS(shop) (/shops/@{shop}/giftcards) with window.axios.

A typical setup

The official Storefront loads incentives right after it knows who the customer is, and again when the currency changes:

function loadIncentives() {
  const currency = window.$storefront.currency.code;

  window.$storefront.coupon.fetchAvailableCoupons(currency).then(({ coupons }) => (state.coupons = coupons));
  window.$storefront.offer.fetchOffers(currency).then(({ offers }) => (state.offers = offers));

  if (window.$storefront.USER) {
    window.$storefront.lottery.fetchLotteryPrizes().then(({ prizes }) => (state.prizes = prizes));
  }
}

window.$storefront.user.fetchMyInfo(() => loadIncentives());

Next steps

• Basket and Checkout
• Customer Account: currency and local database.
• API Reference