Broadleaf Microservices
  • v1.0.0-latest-prod

Understanding Offers Applied to the Cart

When offers are applied, the offer details and the adjustments are stored on the Cart, CartItems, FulfillmentGroups, and/or FulfillmentItems, depending on the offer types. See Offer Adjustment Mappings for more details.

Offer Application Flow

The offer application flow is typically triggered when a cart is priced, either from actions such as adding an item to the cart, removing item from the cart, or manually pricing the cart via the PriceCart API. For more details about cart pricing flow, please review the CartPricingService Docs.

After receiving the response from OfferServices, the offer adjustments are added to the Cart, CartItems, FulfillmentGroups, and/or FulfillmentItems accordingly. For more details about the response from OfferServices, review the OfferEngine’s Apply Offers OpenAPI Docs.

Offer Adjustment

Each offer adjustment, regardless of the offer type, has the following payload:

{
    "offerRef": { // (1)
      "id": "offer-id",
      "name": "offer",
      "description": "description",
      "cartLabel": "label",
      "prorationType": "TARGET_AND_QUALIFIER",
      "attributes": {}
    },
    "amount": { "amount": 5.99 }, // (2)
    "appliedToSalePrice": false,
    "quantityPerUsage": 1, // (3)
    "offerUses": 1, // (4)
    "qualifierDetails": [{ // (5)
        "offerId": "offerId",
        "itemId": "itemX", // (6)
        "quantityPerUsage": 1, // (7)
        "offerUses": 1,
        "fulfillmentItemDetail": false // (8)
    }]
}

  1. A reference to the offer

  2. The discounted amount from this offer

  3. The quantity targeted by each usage of the offer

  4. How many times this offer is applied

  5. A collection of details about its offer qualifier items

  6. The CartItem#id of the offer qualifier item

  7. The quantity used as a qualifier for each usage of the offer

  8. Whether this qualifier detail represents a fulfillment item

Note
 For details on offer adjustments payload from OfferServices, refer to Offer Adjustment Docs in OfferServices

Offer Qualifier and Target Details

For OrderItem and FulfillmentItem typed offers, there are offer qualifier and target items. Offer qualifier items are the items serve as qualifiers for the applied offers, while the offer target items are the items that are discounted from the applied offers.

Only offer target items have the adjustment payload stored, which has the relevant properties to help determine how the offers are applied.

Example Payloads

These are examples of the adjustment payload for different kinds of offer applied to the cart.

Buy 1X Get 1Y

ItemX

{
    "quantity": 1,
    "itemAdjustments": []
}

ItemY

{
    "quantity": 1,
    "itemAdjustments": [{
        "offerRef": {},
        "amount": { "amount": 5.99 },
        "appliedToSalePrice": false,
        "quantityPerUsage": 1,
        "offerUses": 1,
        "qualifierDetails": [
          {
            "offerId": "offerId",
            "itemId": "itemX",
            "quantityPerUsage": 1,
            "offerUses": 1,
            "fulfillmentItemDetail": false
          }
        ]
    }]
}
Buy 1X Get 1Y Applied Twice

ItemX

{
    "quantity": 2,
    "itemAdjustments": []
}

ItemY

{
    "quantity": 1,
    "itemAdjustments": [{
        "offerRef": {},
        "amount": { "amount": 5.99 },
        "appliedToSalePrice": false,
        "quantityPerUsage": 1,
        "offerUses": 2, // note the offer uses are 2
        "qualifierDetails": [
          {
            "offerId": "offerId",
            "itemId": "itemX",
            "quantityPerUsage": 1,
            "offerUses": 2,
            "fulfillmentItemDetail": false
          }
        ]
    }]
}
Buy One Get One

BogoItem

{
    "quantity": 2,
    "itemAdjustments": [{
        "offerRef": {},
        "amount": { "amount": 5.99 },
        "appliedToSalePrice": false,
        "quantityPerUsage": 1,
        "offerUses": 1,
        "qualifierDetails": [
          {
            "offerId": "offerId",
            "itemId": "BogoItem",
            "quantityPerUsage": 1,
            "offerUses": 1,
            "fulfillmentItemDetail": false
          }
        ]
    }]
}
Buy One Get One Applied Twice

BogoItem

{
    "quantity": 4,
    "itemAdjustments": [{
        "offerRef": {},
        "amount": { "amount": 5.99 },
        "appliedToSalePrice": false,
        "quantityPerUsage": 1,
        "offerUses": 2,
        "qualifierDetails": [
          {
            "offerId": "offerId",
            "itemId": "BogoItem",
            "quantityPerUsage": 1,
            "offerUses": 2,
            "fulfillmentItemDetail": false
          }
        ]
    }]
}
Buy 2X Get 1Y

ItemX

{
    "quantity": 2,
    "itemAdjustments": []
}

ItemY

{
    "quantity": 1,
    "itemAdjustments": [{
        "offerRef": {},
        "amount": { "amount": 5.99 },
        "appliedToSalePrice": false,
        "quantityPerUsage": 1,
        "offerUses": 1,
        "qualifierDetails": [
          {
            "offerId": "offerId",
            "itemId": "itemX",
            "quantityPerUsage": 2,
            "offerUses": 1,
            "fulfillmentItemDetail": false
          }
        ]
    }]
}

Offer Adjustment Mappings

The adjustment is added to different entities, based on each offer’s type:

  • Order-typed offers > Cart#adjustments

  • OrderItem-typed offers > CartItem#itemAdjustments

  • FulfillmentGroup-typed offers > FulfillmentGroup#adjustments

  • FulfillmentItem-typed offers > FulfillmentItem#fulfillmentAdjustments

Vouchers

When a cart is qualified for vouchers, they’re stored in Cart#vouchers for post-checkout processing.

Free Gift Items

When a Free Gift offer is applied, a free gift item is automatically added to cart. A free gift item is the same as a regular CartItem, except it has its unique management behaviors and can be identified by the IS_FREE_GIFT_ITEM attribute in the CartItem#internalAttributes map.

Behaviors Specific to Free Gift Items

Free gift items have the following behaviors that are only relevant to free gifts:

  • Free gift items are automatically added/removed based on the OfferServices response

  • The quantity of the free gift items should not be changed by the user, as it should only be updated by the system

  • When a free gift item is removed manually by the user, then that free gift offer will not be applied again, which is tracked using the OFFER_IDS_TO_IGNORE attribute from Cart#internalAttributes