One Basket Per Customer

Pre-release documentation

This is still in development and is not enabled for any clients yet. Nothing described below will affect your integration today. We're publishing this ahead of release so you can plan for it.

We plan to release this behavior for the Sales Interface and iframes throughout August. We tentatively plan to release the System Owner Mode changes in October 2026. Please get in touch with us as soon as possible if you have any concerns about these changes or timelines.

Once released, this feature will mean a Spektrix system will only permit a customer to have one open basket at a time. When it's turned on, the API will check for other open baskets belonging to the customer at the moment a customer is set on a basket — for example when they sign in, or when a basket is created or patched with a customer attached.

Creating a basket with no customer attached will not be affected. The rule will only apply once a customer is being linked to a basket.

We'd recommend reviewing the sections below against your current integration now, so you know what (if anything) you'll need to change ahead of release.

Which baskets will be automatically cancelled?

An existing open basket will only be cancelled automatically to resolve a conflict if both of the following are true:

It was started via iframes or Web Mode API
It has no payments on it yet

Any other open basket will be treated as blocked and will never be cancelled automatically. This will include:

Baskets started via the Sales Interface (in-person, over the phone, etc.)
A Web basket that already has a payment against it

If a customer has a blocked basket, it will always take priority over any other conflict — the request will stop and direct the integration to the box office, regardless of what other open baskets exist.

The basket currently being worked with will never count as a conflict with itself — only the customer's other open baskets will be considered.

Planned behaviour by API mode

Mode	What will happen when you set a customer	Other open, cancellable baskets	A blocked basket exists
Agent	Normal Agent basket creation assigns the Agent's own individual customer record — you can't attach an arbitrary customer this way.	Not applicable: Agent-owned baskets will be excluded.	Not applicable.
Web	The signed-in customer is attached to the current basket.	Automatically cancelled so the current basket can continue. No warning will be shown in the response — see Web mode below.	Request stops with a `409` and a customizable message.
System Owner	A System Owner user attaches a customer to a basket.	Request stops with a `409`, listing every conflicting basket so you can choose which to keep — see System Owner mode below.	Request stops with a `409` and a customizable message.

Web mode

This check isn't limited to calls where your code explicitly sets a customer on a basket. It will also apply when API v3 automatically creates a new basket for the session and attaches the signed-in customer to it, which can happen without any explicit "set customer" call from your integration. If you rely on implicit/automatic basket creation anywhere in your flow, it's worth reviewing those paths now, since they'll be in scope too.

If a signed-in customer starts or returns to a basket while they already have another cancellable basket open, that other basket will be cancelled automatically and the current one will continue. This will happen within the same request — there won't be anything extra for your integration to call, and the response will look like a normal success.

Because there won't be a warning in the API response, once this is live you'll want your site to tell customers that signing in (or continuing to checkout) may discard the contents of another basket they had open elsewhere.

warning

Cancellation and customer assignment will happen together. If cancelling a conflicting basket fails for any reason, none of it will be applied — the current basket will be left untouched and a 409 will be returned instead.

Client-side web integrations will not need to (and should not) call the resolve-conflict endpoint described below — that will only be for System Owner requests. If a request fails, only retry it where the failure looks transient; a 409 conflict response isn't something a retry will resolve — show the customer an appropriate recovery path or direct them to the box office instead.

Conflicting Basket Cancellation Failed

An HTTP 409 response will be returned when a conflict can't be resolved automatically — most commonly because one of the customer's other open baskets is blocked (started at the box office/phone, or already has a payment on it).

{
  "errorCode": 57,
  "message": "Unable to continue, please contact the box office."
}

info

This message will be configurable per client, so exact wording may differ from system to system once released.

How you'll be expected to handle this:

Show the customer the message returned in the response.
Direct them to the box office — this won't be fixable by retrying the same request.
No basket will have been cancelled when this error is returned; the customer's baskets are left as they were.

System Owner mode

Unlike Web mode, System Owner requests will never be resolved automatically. If the customer has other open, cancellable baskets, the request will stop and you'll be asked to choose which basket to keep.

Conflicting Baskets

The API will return an HTTP response with code 409 and a body with the baskets to be resolved.

{
  "errorCode": 63,
  "message": "The customer already has one or more open baskets that must be resolved before continuing",
  "conflictingBaskets": [
    {
      "id": "<session-id>",
      "createdDate": "2026-01-01T10:00:00Z",
      "isCurrent": false,
      "basket": {
        "id": "<basket-api-id>"
      }
    },
    {
      "id": "<current-session-id>",
      "createdDate": null,
      "isCurrent": true,
      "basket": {
        "id": "<current-basket-api-id>"
      }
    }
  ]
}

Field	Description
`id`	The session ID for that basket. You'll need this to call `resolve-conflict`.
`createdDate`	When the conflicting basket was created. The basket you were trying to attach the customer to (`isCurrent: true`) won't have a date here.
`isCurrent`	`true` for the basket you were trying to attach the customer to; `false` for the customer's other open baskets.
`basket`	The full basket contents, so you can show the customer what's in each basket and help them decide.

How you'll be expected to handle this:

Decide which basket to keep — typically by showing the customer the contents of each and letting them choose.
To keep the current basket, find the item in conflictingBaskets where isCurrent is true and take its id.
Call the resolution endpoint with that ID:

Request
Response

POST
https://system.spektrix.com/{{clientname}}/api/v3/baskets/{current-session-id}/resolve-conflict

HTTP 200
{
  "customer": "<customer-api-id>"
}

This endpoint will check that the customer owns the basket you're resolving to, cancel every other open basket for that customer, then set the customer on the basket you kept. These steps will happen atomically — if any part fails, nothing will be cancelled and a 409 will be returned again.

Allowing multiple baskets for specific System Owner accounts

If your System Owner API account will need to manage more than one open basket per customer at a time, you can ask your Spektrix client to enable an Allow multiple active baskets per customer setting on your API account. Accounts with this setting will bypass the one-basket check entirely.

warning

Enabling this setting comes with strict limitations: Offers with customer-based limits (such as per Customer or per Membership period), account credit, and gift voucher spend will not be supported in any Baskets when this is enabled.

Error reference

HTTP Status	Code	API Mode	When it will occur	Action
`409`	`63` – `ConflictingBaskets`	System Owner	A request tries to set a customer who has other cancellable open baskets.	Inspect `conflictingBaskets`, choose a basket to keep, then call `resolve-conflict`.
`409`	`57` – `ConflictingBasketCancellationFailed`	System Owner, Web	At least one conflicting basket is blocked (box office/phone, or has a payment), or a cancellation can't complete safely.	Show the returned message and direct the customer to the box office. Don't assume anything was cancelled.

What to do now

Nothing needs to change in your integration today — this feature is not yet enabled anywhere.
If you build integrations in System Owner mode, plan for handling the 409 responses above, including a UI path for choosing which basket to keep.
If you build Web integrations, plan messaging that tells customers a previous basket may be discarded when they sign in.
Contact support if you want to be notified when this is enabled for a specific client, if you think your integration will need the multiple-baskets opt-out, or if you would like this change turned on ahead of schedule in a client’s system.

Which baskets will be automatically cancelled?​

Planned behaviour by API mode​

Web mode​

Conflicting Basket Cancellation Failed​

System Owner mode​

Conflicting Baskets​

Allowing multiple baskets for specific System Owner accounts​

Error reference​

What to do now​