Core concepts
The terms used across the OneBasket APIs and how they relate to each other.
Store
A store is the unit of tenancy in OneBasket. Every request is made in the scope of one store, and the API key identifies the store.
An organisation can have one store or several. For example, a football club can have a single store, and a league can have one store per club.
Provider
A provider is an external vendor system that supplies part of what the organisation sells. Ticketing systems, retail platforms, and food and beverage systems are all providers. Each store is connected to one or more providers.
The provider system remains the source of truth for its own products, baskets and orders. OneBasket keeps a synchronised representation of them.
Contact
A contact is a customer of the organisation. A contact is linked to the organisation's single sign-on system, and gives one view of the customer across all provider systems.
Requests that act for a signed-in customer carry a bearer token that identifies the contact. See Authentication.
Catalogue and product
A catalogue groups products from one or more providers so that they can be searched and sold together. Products are synchronised from the provider systems into catalogues.
Products in a catalogue can be related to each other. A cross-sell offers one product when the customer views or adds another product, including a product from a different provider.
Basket and provider basket
A basket holds the products a customer intends to buy. It tracks line items, totals, customer details, delivery methods and vouchers.
A basket contains one provider basket for each provider that has a product in it. A provider basket represents the basket that exists in that provider's system.
A basket does not require a contact. A customer can check out as a guest, and you can assign a contact to the basket later with Assign contact.
Payment intent
A payment intent states that the customer is ready to pay for the basket. Creating a payment intent makes the basket immutable. Deleting the payment intent before payment arrives makes the basket mutable again.
A payment intent has one of these statuses: PreparingPayment, AwaitingPayment, Cancelled, PaymentComplete.
Order and provider order
When payment for a basket is confirmed, the basket becomes an order. The order has the same id as the basket that was checked out.
An order contains one provider order for each provider. OneBasket sends each provider order to its provider and tracks whether the provider confirmed or rejected it. See Checkout flow.
Notification
Some requests are processed asynchronously. They return a notificationId straight away. You poll the Notifications API with that id to learn whether the request completed or failed. See Asynchronous operations.
Subscription, membership and entitlement
A subscription is created when a contact buys a subscription product and the order is processed. It holds the status and the billing dates of what the contact bought. A membership is a subscription product that an organisation sells as a membership. The API has no separate membership resource.
An entitlement is a benefit that a subscription gives to the customer, such as access to video content. OneBasket grants entitlements when the subscription starts and removes them when it ends. See Subscriptions and memberships.