Before you start
- API authentication must be working for your platform’s backend. Every call on this page is server-to-server.
- The customer is signed in, so your backend has their
memberId. There is no check-in online, and an anonymous order gets no coupons and no bonus. See Customers and loyalty cards. - Your web shop is a store in Lobyco, with a
storeIdof its own or one it shares with a chain. Coupons, payments and purchases all name the store. See Import chains and stores. - Marketers limit an offer to checkout types in Nexus. An offer limited to the POS never applies online; an offer with no checkout types applies everywhere. Agree with them which offers the web shop should carry.
- Decide who applies the discounts, below. It decides which of the two middle sections you follow.
Choose who applies the discounts
Both routes end the same way: the order is recorded as a purchase, and that redeems the coupons.
Show the customer’s coupons
Whichever route applies the discounts, the customer sees their coupons in the web shop the way they see them in the app.1
Get the coupons
GET /v3/customers/{customerId}/couponsPass the web shop’sstoreId, or its chainId, so that only the coupons valid there come back. Ask for includedRelations Discount to show what each coupon is worth. The response is every coupon the customer has that is valid here: assigned, not expired, not yet used. What to show on a coupon, and how, is on Show offers in your app.2
Activate a coupon
POST /v3/customers/{customerId}/coupons/{couponId}/activateA coupon whose offer is pre-activated is ready at once. Every other coupon needs the customer to activate it, so put an action on the coupon that makes this call. Activation is what makes the coupon available at checkout, online and in store alike.3
Check the coupon is ready
GET /v3/customers/{customerId}/coupons/{couponId}Read the coupon back. An activated coupon carries itsactivationTime, and from then on the checkout calls below find it.Let Lobyco apply the discounts
This is the Discount integration of the POS, with the web shop as the store andOnline as the checkout type. Your platform sends the basket; Lobyco returns it priced.
1
Price the basket
POST /v1/discounted-purchasesSend the basket in the shape of a purchase:receiptId, the id your order will carry.storeId, the web shop.memberId, the signed-in customer.products, with their prices.checkoutType, set toOnline.
skipReservation=true: the basket page should not block their coupons. At checkout, call it again without the flag, so Lobyco reserves the coupons that granted a discount.2
Apply the response
The response repeats the order with the discounts applied.totalAmount and each product’s price are reduced, and discounts lists each discount with the couponIds that granted it. Show them in the basket and keep the coupon ids for the order. The shape is described step by step on Discount integration.3
Hold the coupons through the checkout
POST /api/v1/customers/{customerId}/coupons/reserveThe reservation Lobyco made while pricing lasts 1 minute, which suits a till and not an online checkout with a payment page. Reserve the coupons yourself for the time your checkout takes:couponIds, from the priced response.reservedBy, a value that names your platform.reservedUntil, far enough ahead to cover your payment page. A till reserves for 1 to 5 minutes; an online checkout takes longer.
4
Send the order as a purchase
POST /v1/purchasesWhen the order is placed, send it as a purchase, with thecouponIds from the priced response in its discounts. Lobyco redeems the coupons when it loads the purchase, and they drop out of the customer’s list. The payload is under Record the order.5
[Optional] Redeem the coupons at once
POST /v2/customers/{customerId}/coupons/redeemThe purchase redeems the coupons only when Lobyco loads it. If your platform sends purchases later, in a batch or at fulfilment, redeem the coupons when the order is placed. Send the order’sreceiptId as the Idempotency-Key header, and the purchase under the same receiptId redeems nothing twice. The rules are on Coupon redemption at POS.Apply the discounts yourself
When your platform must price the basket itself, it needs two things from Lobyco. The first is a copy of the offers, synced on a schedule. The second is the list of coupons the customer can use, read at checkout.1
Sync the offers
GET /v3/offersPull the offers on a schedule. Ask for the relations the pricing needs inincludedRelations:Discount, the discount rules.Affiliations, the product and category ids each rule applies to.StoresAndChains, where the offer is valid.
OfferDisplayStatus Active and Scheduled. Page with limit at 100 or less and offset, until a page comes back short. Keep an offer when its storeIds or chainIds cover the web shop. Keep it only when its discount’s checkoutTypes is empty or contains Online. An empty list means the offer applies at every checkout. Each discount type and its rules are on Offer and discount types. A filter on the date an offer last changed is planned, so that a later sync carries only the changes. Until then, sync the full set.2
Get the coupons to apply
GET /v2/customers/{customerId}/couponsAt checkout, call the Coupon API with the web shop’sstoreId. It returns the coupons the customer can use now: activated, valid in this store, not yet used. Lobyco has already applied the store and chain filter, so do not filter again. A coupon another system has reserved is listed with reservedBy and reservedUntil; skip it. Set includeOfferData=true to get each coupon’s current discount with it, and price from that where it differs from your synced copy. Match the rest by offerId to the synced offers, and apply the discounts in stacking priority; see Stacking of coupons.This list is not the list from the first section. The customer-facing call returns every coupon the customer has, to show; the Coupon API returns the ones to apply, to price. The two are not interchangeable.3
Reserve the coupons
POST /api/v1/customers/{customerId}/coupons/reserveReserve the coupons you applied for the time the checkout takes, withreservedBy naming your platform and reservedUntil 10 to 15 minutes ahead. A reserved coupon cannot be used in a store meanwhile.4
Send the order as a purchase
POST /v1/purchasesWhen the order is placed, send it as a purchase, with thecouponIds you applied in its discounts. Lobyco redeems the coupons when it loads the purchase, and the next call for the coupons to apply no longer lists them. The payload is under Record the order.5
[Optional] Redeem the coupons at once
POST /v2/customers/{customerId}/coupons/redeemThe purchase redeems the coupons only when Lobyco loads it. If your platform sends purchases later, in a batch or at fulfilment, redeem the coupons when the order is placed. Send the order’sreceiptId as the Idempotency-Key header, the storeId, each coupon’s value and the basketValue. The purchase under the same receiptId redeems nothing twice. The rules are on Coupon redemption at POS.Pay with bonus
A customer can pay part or all of an order with their bonus balance. Lobyco’s Payment Coordinator takes the bonus part; your own payment provider takes the rest.1
Read the balance
GET /v1/members/{memberId}/accountsSendincludeBalance=true and read the availableBalance of the active account. Show it at checkout and let the customer choose how much to apply, up to that balance and up to the order total.2
Create the payment
POST /v2/paymentsSend:type, set toEcommerce.storeId, the web shop.receiptId, the order’s id.memberId, the signed-in customer.amount, the bonus part of the order.operationId, unique per attempt. Reuse it only when retrying the same attempt, so a retry cannot create a second payment.requestMemberConfirmation,false.
paymentId, and the payment starts in WaitingPosCapture. The amount is reserved on the customer’s balance, and nothing has moved yet.3
Capture when the order is fulfilled
POST /v2/payments/{paymentId}/captureCapture when the goods are shipped or collected, with the finalamount and an operationId. A smaller amount than reserved is a partial capture, and Lobyco cancels the remainder. Use it when an item was out of stock and the order total fell. The state becomes Captured.Capture before the nightly job runs. It cancels every payment still in WaitingPosCapture 3 hours after it was created. If fulfilment takes longer than that, capture the full amount when the order is placed. A refund is of the whole payment, so settle a partly shipped order with a refund and a new payment for the part that shipped. The job is described under How the purchase checks the payment.The purchase can capture for you. When Lobyco loads a purchase whose LoyaltyApp amount equals a payment still in WaitingPosCapture, it captures the payment. A different amount leaves the payment as it is, so capture it yourself. The rules are under How the purchase checks the payment.4
Check the state
GET /v2/payments/{paymentId}Read the payment back:Captured means the bonus has moved. If the order is cancelled before capture, cancel the payment with POST /v1/payments/{paymentId}/cancel, and the reservation is released. The states, and what each allows, are on Payments.Record the order
POST /v1/purchases When the order is placed, send it as a purchase, whichever route priced it. It carries:receiptId, the order’s id, the same one the bonus payment and any explicit redeem call carry.storeId, the web shop.memberId, the signed-in customer.checkoutType, set toOnline.products, with their prices before and after discount.discounts, with thecouponIdsthat granted each one. Lobyco redeems these coupons when it loads the purchase, unless an explicit redeem call under the samereceiptIdalready did.paymentMethods, one per method. The bonus payment is one entry withpaymentTypeLoyaltyAppand the captured amount. Lobyco checks it against the payment under the samereceiptId, and cancels or refunds a payment recorded another way. See How the purchase checks the payment.
Failure and edge cases
If a coupon does not apply, a payment does not complete, or an order changes after it was placed, it is one of these.- A coupon was used in a store meanwhile. Lobyco still accepts the redemption, even past the coupon’s redemption limit. The order goes through as priced. The reservation is what stops the in-store use, so keep it live until the order is placed.
- The checkout outlives the reservation. Reserve for the time your checkout really takes. If the customer stalls on the payment page, reserve the coupons again with the same
reservedByand a laterreservedUntil. Lobyco refuses a reservation only when another holder’s reservation is still live. - The order is cancelled. Before the purchase is sent, release the coupons with the cancel-reservation call. After it, give them back with the cancel-redeem call under the order’s
receiptId. Both are on Coupon redemption at POS. Cancel the bonus payment before capture, and refund it after capture with POST /v1/payments/{paymentId}/refund. - The order is partly fulfilled. Capture the bonus payment for the final amount. If the purchase is not sent yet, send it with the products that shipped. If it was sent when the order was placed, record the unshipped items as a return with negative prices. Give back their coupons with the cancel-redeem call.
- The customer returns an item. Record the return as a purchase with negative prices, as on Transaction data. Give back the coupons, and refund the bonus payment.
- Fulfilment takes longer than a day. The nightly job cancels a bonus payment still waiting for capture, and the customer’s balance is released. Capture when the order is placed instead. If part of the order does not ship, refund the payment and create a new one for the part that shipped.
- The purchase’s bonus amount differs from the payment. Lobyco logs the mismatch and leaves the payment as it is. Capture or cancel it yourself. Send the purchase with the amount you captured, so the two agree.
- The offers in your copy are stale. An offer changes in Nexus between two syncs. The
discounton each coupon from the Coupon API is current, so price from it when it differs from your copy, and sync again. - Lobyco is unreachable at checkout. Pricing and the coupon list have no offline mode. Complete the order without loyalty discounts and without bonus rather than block it, and still record the purchase.
- The customer is not signed in. No coupons, no bonus. Record the purchase without a
memberId, so the sale is still counted.
API reference
Endpoint documentation: Coupons (Web & Mobile) V3, Coupons (POS), Discounts, Offers V3, Payment Coordinator, Bonus accounting and Purchases.Related
- Show offers in your app — rendering the coupons, and what each type should show.
- Discount integration — the pricing Lobyco does, step by step, with the stacking order.
- Direct coupon service integration — the POS version of applying the discounts yourself.
- Coupon redemption at POS — the explicit redeem call, reservations, redemption through the purchase, and returns.
- Payments — the Payment Coordinator’s states, methods and providers.
- Transaction data — the purchase payload and its validation.
- Offer and discount types — the discount rules your platform implements when it prices the basket itself.