Discount Integration - Lobyco Help center

API purpose

In a Discount integration, Lobyco receives the user basket, evaluates the products, and applies the coupons based on the rules and basket content. Lobyco can return to the POS the coupons to be applied and their definition, or it can return the price calculation and final price as well. This approach is best when you want Lobyco to own the discount logic rather than replicating offer definitions in the POS.

The Discount API is not a replacement for the Purchase API

The Discount API only calculates discounts for a basket during checkout. It does not store the transaction, capture payment, or trigger bonus, digital receipts, or challenges.After the sale is finalized you must still send it to the Purchase API (POST /v1/purchases) — see Transaction Data. See Integration building blocks for how the two APIs fit together.

Not sure which approach to choose?

See Applying discounts: two options for how this compares with the Direct Coupon Service Integration, where the POS decides which coupons to apply.

Flow

In this integration approach, Lobyco receives the user basket, evaluates the products, and applies the coupons based on the rules and basket content. Lobyco can return to the POS the coupons to be applied and their definition, or it can return also the price calculation and final price.

Send the purchase

Send the purchase to POST v1/discounted-purchases. Only purchases with a customer should be sent. No discounts are applied to anonymous purchases.

Confirm coupon redemption

POST v2/customers/{customerId}/coupons/redeem — POS confirms that the purchase was finished and coupons were used. Coupons can be also redeemed based on coupon ids sent along with transaction data. Include store id and total basket value for better reporting.

Cancel coupon reservation (optional)

POST /v1/customers/{customerId}/coupons/cancel-reservation — notify that the purchase was canceled and coupons should be available again on other POSes.

The redeem / cancel-reservation mechanics used in steps 2-3 are shared with the direct Coupon integration and are described in detail in Coupon Redemption at POS.

How to apply the response from `Discount API` Purchase endpoint

Tip 💡: Before making any API calls directly to your assigned integration layer, make sure you have created at least one offer in the Lobyco Admin Portal and that you have activated that offer for the customer you are testing your API calls with. We suggest you set up an offer with redemption limit 999. In this way you’ll be able to retest with the same offer for a longer time period.

The Discount API response will contain several important aspects to analyze:

Most of the fields from the request will be replicated in the response.
The totalAmount will be decreased by the total discount amount applied to products in the basket.
Product’s price will be decreased by the total discount amount applied to that product.
The response discounts collection will be filled in with applied discounts.

{
  ...
  "discounts": [
    {
      "name": "Discount_1",
      "totalDiscountAmount": 2.0,
      "couponIds": [
        "Coupon_1", "Coupon_2"  // Used coupons in order to apply the discount
      ],
      "appliedProducts": [ // List of products' SequenceNumber for which discount was applied
        1
      ]
    }
  ]
}

Tip 💡: The appliedProducts property will only be populated for product-level discounts. For basket-level discounts, it will be empty.

How to apply the response from Legacy `Discount API` Basket endpoint

The Discount API response will contain several important aspects for POS to analyze:

It will replicate the basketId from the request, for ease of identification.
It will contain a field called finalTotal, containing the total amount of the basket after discount application.

"total": 4000,
"finalTotal": 3967.0

Tip 💡: Notice that the discountCalculationAPI also replicates the basket total before discount application under the total field.

It will contain a list of line items, where the discountCalculationAPI will replicate most of the product information (from the request) and will add:

A finalTotalSalePrice containing the line item total sale price after discount application.

{
  "finalTotalSalePrice": 198.0,
  "id": "71360d70-7880-4433-a639-d066bdcb5b68",
  "barcode": "5700123969094",
  "quantity": 2,
  "sequenceNumber": 1,
  "totalSalePrice": 200,
  "product": {
    "id": "1000000",
    "displayName": "Banana",
    "categoryId": "1",
    "category": "Fruits",
    "taxCode": "A",
    "salePrice": 100,
    "unitOfMeasure": "Piece",
    "units": 1
}

A discounts field containing the discounts applicable to the respective line item (including the calculated discount amount value after each discount application).

"discounts": [
  {
    "id": "4ccec898-1e0e-4a52-affe-44f66416a180",
    "description": "Discount_1",
    "value": 2.0,
    "couponIds": [
      "Coupon_2"
    ],
  }
]

A coupons field containing all the used coupons required to apply the discounts on the current line item.

"coupons": [
  {
    "couponId": "Coupon_1",
    "barcode": "12345678",
    "sequenceNumber": 1,
    "campaignId": "4ccec898-1e0e-4a52-affe-44f66416a180"
  },
  {
    "couponId": "Coupon_2",
    "barcode": "23456789",
    "sequenceNumber": 2,
    "campaignId": "0f23c3e9-ecd9-4ca1-87c1-f2b6ef73e4b6"
  }
]

Besides line item discounts and coupons, the response may also contain basket-level discounts and coupons with a similar structure to those at line item level.

Tip 💡 The finalTotal field described above is calculated by taking into consideration all applied discounts regardless of whether they were applied at line item level or at basket level.

Compatibility and feature flags

Lobyco treats the Discount API response contract as stable and backward compatible. The meaning of existing response fields does not change, and the service does not start returning additional data that would change how an existing integration should interpret the result. While new fields can be introduced, they will be returned as null be default. Any large new feature that changes calculation behaviour or response content is rolled out behind a feature flag and is off by default, so existing integrations are unaffected until you explicitly opt in. Where a flag is available it can be overridden per request via a query parameter, so you can validate the new behaviour in a controlled way (for example, against a test customer) before enabling it more broadly.

Stacking of coupons

The stacking priority of promotions in a basket is determined by the priority set in the Lobyco Promotion Platform Admin. Marketeers can set priorities from 1-10, where priority 1 is the highest. Conflicting offers will be applied according to the priority settings. If two promotions are eligible for a basket—one being product-based and another being basket-based—the application order is determined by the priority order. For promotions with equal priority, the offer with the sooner-expiring coupon takes precedence.

Offline behaviour

Currently Lobyco Coupon and Discount do not support offline flows. If either POS is offline or Lobyco services are not reachable within a specific time, POS should be able to process the purchase without applying loyalty offers. One exception to this is coupon redemption itself, which supports an offline path — see Coupon Redemption at POS.

​API purpose

​The Discount API is not a replacement for the Purchase API

​Not sure which approach to choose?

​Flow

​Send the purchase

​Confirm coupon redemption

​Cancel coupon reservation (optional)

​How to apply the response from Discount API Purchase endpoint

​How to apply the response from Legacy Discount API Basket endpoint

​Compatibility and feature flags

​Stacking of coupons

​Offline behaviour