Checkout functions

​

Overview

​

Register the discount callback

curl -X PUT https://api.salesive.com/api/v1/checkout-extensions/discount \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://discounts.example.com/salesive/checkout", "name": "Loyalty discount" }'

​

The request

{
  "id": "7f3c2a9e-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
  "topic": "discount/request",
  "shopId": "64b1f0a3c2d4e5f6a7b8c9d0",
  "sentAt": "2026-11-07T10:00:00.000Z",
  "currency": "NGN",
  "shop": { "id": "64b1f0a3c2d4e5f6a7b8c9d0", "name": "Ada Shoes", "type": "ecommerce" },
  "cart": {
    "id": "64c1f0a3c2d4e5f6a7b8c9d1",
    "subtotal": 12500,
    "lines": [
      {
        "lineItemId": "64d1f0a3c2d4e5f6a7b8c9d2",
        "productId": "64e1f0a3c2d4e5f6a7b8c9d3",
        "variant": "64f1f0a3c2d4e5f6a7b8c9d4",
        "quantity": 2,
        "unitPrice": 5000,
        "subtotal": 10000
      }
    ]
  },
  "customer": { "id": "64a1f0a3c2d4e5f6a7b8c9d5", "guest": false }
}

• id, topic, shopId and sentAt are added by the platform. They are inside the signed body, so reject a replay by id or a stale request by sentAt.
• lineItemId is the stable handle to echo in a line level discount.
• productId is the catalog id of the line: a product, food, service or digital product. variant is the variant id, or null.
• unitPrice includes addons and is what the buyer pays per unit.
• customer is null when nobody is signed in. A guest account carries guest: true. No name, email, phone or address is sent.
• Amounts are JSON numbers in the shop currency, rounded to two decimals.

​

The response

{
  "discounts": [
    {
      "lineItemId": "64d1f0a3c2d4e5f6a7b8c9d2",
      "amount": 1000,
      "code": "SHOES10",
      "title": "10% off shoes"
    },
    { "amount": 500, "title": "Store welcome" }
  ]
}

​

How Salesive applies the discounts

1. Line level first. Discounts are applied in the order the apps were loaded (oldest registration first), then in the order they appear in the response. Each line has a remaining capacity equal to its subtotal. A discount takes the smaller of its amount and that capacity, so a line never goes negative and a second app cannot discount money the first already removed.
2. Order level next. These are applied in the same order, each capped at what is left of the cart subtotal.
3. The total is capped at the subtotal. A discount can never take the order total below zero.
4. A grant reduced to zero is not recorded.

{
  source: "app",
  app, installation, extension,
  title, code,
  level: "line" | "order",
  lineItemId,
  amount,
  requestedAmount
}

​

Timeouts and failures

• Each app has 2 seconds, and all apps are called in parallel. APP_DISCOUNT_TIMEOUT_MS overrides the deadline, and the client clamps it to 5 seconds. The deadline covers DNS, connect, headers and body.
• A timeout, a non 2xx answer, a redirect, a response over 64 KB, a body that is not a JSON object, a blocked URL, a missing signing secret or an internal error contributes no discount.
• The checkout never breaks. On any failure the resolved result is no discount, and order creation carries on. A store whose discount app is down still sells at the normal price.
• Failures are not shown to the buyer. They are logged with the app, installation, reason and duration.

​

Signing

X-Salesive-Signature: t=<unix seconds>,v1=<base64 HMAC-SHA256 of "<t>.<raw body>">

​

Releases

​

The other kinds

• Payment customization would run when the payment step is built, after the order exists. It would hide, rename or reorder payment methods, and add a short message next to one. It would never create a payment session or mark an order paid.
• Delivery customization would run at the shipping step. It would rename, reorder or hide the options the store already has, and add a short message. It would not change a price; a new price belongs to the shipping rates kind.

​

Next steps