Skip to main content

Cart mutator

Overview​

The Cart Mutator is a powerful webhook used during the checkout process to modify an order before it's finalized. This section explains how to use the Cart Mutator, including its advantages, use cases, and a detailed example.

Cart Mutator overview​

Important

The Price Calculator webhook has been deprecated and replaced with the more versatile Cart Mutator endpoint, which allows for flexible modifications of an existing order.

The Cart Mutator webhook is executed just before the payment for an order during the checkout process. You can use the cart mutator to change the order before it's submitted to AiFi systems and sent back to you in the checkout webhook.

You can apply any logic based on date, time, customer information, product list, product quantities, and more to implement custom pricing, discounts, and taxes. For example, you can apply discounts based on the day, offer loyalty rewards, or implement buy-one-get-one-free deals.

The retailer is responsible for returning the total price and total tax. All calculations around taxes and prices are the retailer's responsibility, although you can choose to retain the price and tax information pre-computed by AiFi.

Additionally, you can add products to the receipt, such as deposit fees for bottles or placeholder products to convey messages like "DISCOUNT APPLIED." However, careless usage can result in inconsistencies, such as individual product prices not adding up to the total receipt amount. Use with caution.

info

The Cart Mutator webhook, like all webhooks, isn't available in the public sandbox. Test it in your environment and ensure your endpoint accepts and returns data in the proper format as described in the API reference. Your webhook should allow for unexpected fields in the future as AiFi may add additional metadata.

Cart Mutator in the checkout process​

Refer to the Checkout section and Appendix B for a comprehensive understanding of how the Cart Mutator is integrated into the checkout process.

Cart Mutator example​

Example payload​

# Example payload for the checkout webhook
# Note: Deprecated fields are omitted in this example
{
    "orderId": 1705,
    "sessionId": "some-unique-token",
    "status": "completed",  # The status field mentioned in the guide above
    "customer": {
        "id": "42",
        "externalId": "my-customer-94325",
        "role": "customer"
    },
    "storeId": 2,
    "storeExternalId": "mystore-0001",
    "cart": [
        {
            "id": "32462045249599",
            "productId": "32462045249599",
            "externalId": "my-external-id-coca-cola-2",
            "name": "coca-cola-2",
            "barcode": "001",
            "thumbnail": "https://example.com/some-picture.jpg",
            "price": 10,
            "subtotalPrice": "10.00",
            "totalTax": "0.99",
            "totalPrice": "10.99",
            "quantity": 1
        }
    ],
    "totalPrice": "10.99",
    "totalTax": "0.99",
    "subtotalPrice": "10.00",
    "payment": {
        "paymentProvider": "ADYEN",
        "paymentInstrument": {
            "type": "card",
            "cardBin": null,
            "cardLast4": "2137",
            "cardExpMonth": 12,
            "cardExpYear": 2025,
            "cardBrand": "visa"
        },
        "paymentStatus": "success"
    },
    "timeOfOrigin": "2023-05-09T07:11:18.331Z",
    "timeOfIssue": "2023-05-09T07:11:18.331Z"
}

Example response​

{
  "orderId": 1705,
  "cart": [
    {
      // The original product with modified prices
      "id": "32462045249599",
      "externalId": "my-internal-id-coca-cola-2",
      "subtotalPrice": "2.00",
      "totalTax": "0.50",
      "totalPrice": "2.50",
      "taxLines": [
        {
          "title": "VAT A", // Or, for example, Sales Tax Santa Clara County
          "rate": "0.25",
          "amount": "0.50"
        }
      ],
      "quantity": 1,
      "isDeposit": false
    },
    {
      // An additional item added
      "id": "32462045240999",
      "externalId": "pet-bottle-deposit",
      "subtotalPrice": "0.50",
      "totalTax": "0.00",
      "totalPrice": "0.50",
      "quantity": 1,
      "taxLines": [],
      "isDeposit": true
    },
    {
      // A discount applied
      "id": "32462045241234",
      "externalId": "generic-discount-product",
      "subtotalPrice": "-0.25",
      "totalTax": "0.00",
      "totalPrice": "-0.25",
      "quantity": 1,
      "taxLines": [],
      "isDeposit": false
    }
  ],
  "totalPrice": "2.75",
  "totalTax": "0.50",
  "subtotalPrice": "2.25"
}

In this example, the original order is modified to reflect the correct price for the product "coca-cola-2," with appropriate taxes specified. Additional products, such as a deposit fee and a discount, are added to the final checkout. The total price, total tax, and subtotal price for the receipt are updated accordingly.

If you only provide the id or externalId field on each product in the response, explicitly set the other field to null (for example if you only provide "externalId": "pet-bottle-deposit", then add "id": null to that line item).

For a complete example of a flow where the customer taps their credit card, processed by AiFi using an external payment provider, shops, and leaves the store, utilizing the Cart Mutator to calculate prices, taxes, and discounts, see Appendix B.

Checkout​

Refer to the Checkout section for an overview of the entire checkout flow at AiFi and details on the payloads sent.

If you have integrated the cart mutator, AiFi guarantees that the checkout webhook will include the original Cart Mutator webhook updated with all the values you provided. This means that all products and monetary amounts will be exactly as specified in your Cart Mutator response.