Sprii Developer docs

Appearance

Order tracking ​

Order tracking is what lets Sprii attribute a finalised webshop order back to the live show / Sprii checkout it came from. Without it, Sprii sees that a customer started a checkout from a live show but never learns whether (and for how much) they actually bought.

The flow ​

Sprii issues an orderNo (the Sprii order number) for every checkout that originates from the player or from a social-media checkout link. Connecting that orderNo to the customer's basket on your side — and reporting it back when the order is paid — is what closes the attribution loop.

The integration has two halves:

1. Connect Sprii's orderNo to the user's basket ​

The orderNo is delivered to your site as part of two SDK actions:

  • SOME_CHECKOUT — fired when a customer follows a social-media checkout link and lands on your site.
  • UPDATE_CART_CONTENTS — fired whenever the customer adds, changes or removes items in the in-player cart.

In both handlers, take payload.orderNo and persist it on the customer's basket / session so that it's still available when the customer eventually checks out. Anything that survives until order placement works: a basket meta field, a session cookie, a row in a sprii_basket_orderno table, etc.

js
const connectSpriiOrderNoToBasket = async (orderNo) => {
  if (!orderNo) return;
  // Persist orderNo against the current basket / session so it ends up
  // on the resulting webshop order.
  await fetch('/api/cart/sprii-order-no', {
    method: 'POST',
    body: JSON.stringify({ orderNo }),
  });
};

2. Report the completed order back to Sprii ​

When the customer finalises the order in your webshop (payment received / order placed), your backend should call Sprii's POST /processOrders endpoint and pass the stored orderNo as spriiOrderNumber. Sprii uses spriiOrderNumber to locate the matching Sprii checkout, reconcile reserved quantities against what was actually purchased, and mark the checkout as paid.

Minimum payload:

json
{
  "orders": [
    {
      "spriiOrderNumber": "<the orderNo you stored on the basket>",
      "id": "<your webshop's order id>",
      "orderTotal": 29.99,
      "items": [
        {
          "product_id": "PROD-12345",
          "sku": "SKU-ABC-001",
          "quantity": 1,
          "unitPrice": 29.99
        }
      ]
    }
  ]
}

See the full request schema and matching rules for variants, partial fulfilment, and multi-order batches.

Why both halves are needed ​

  • Without step 1, the order arrives at Sprii with no spriiOrderNumber and Sprii has no way to match it to a live-show checkout — the sale is not attributed.
  • Without step 2, Sprii never learns that the checkout converted — reservations are not released, totals are not reconciled, and conversion metrics stay incomplete.