Appearance

Core Concepts ​

This page introduces the main resources in the Shopwave API and how they relate to each other. Understanding the data model will help you design your integration effectively.

Data model ​

mermaid
erDiagram
    Merchant ||--o{ Store : "has"
    Merchant ||--o{ Employee : "employs"
    Merchant ||--o{ Product : "sells"
    Merchant ||--o{ Category : "organises"
    Merchant ||--o{ Supplier : "sources from"
    Merchant ||--o{ Promotion : "runs"
    Merchant ||--o{ Application : "registers"

    Store ||--o{ Basket : "processes"
    Store ||--o{ Order : "fulfils"
    Store ||--o{ Invoice : "receives"

    Product ||--o{ ProductInstance : "has variants"
    Product ||--o{ ProductComponent : "has sub-items"
    Product }o--o{ Category : "belongs to"

    Basket ||--o{ BasketProduct : "contains"
    Basket ||--o{ Transaction : "paid by"
    Basket ||--o| Order : "generates"

    Supplier ||--o{ SupplierStore : "operates"
    Supplier ||--o{ Invoice : "issues"

    User ||--|| Employee : "is"
    User ||--|| Merchant : "owns"

Resources ​

Merchant ​

The top-level entity. A merchant represents a business on the Shopwave platform — including branding, company details, and configuration. Each authenticated user owns exactly one merchant.

Key fields: name, description, companyNumber, vatNumber, colours, imageIds

Merchant API Reference →

Store ​

A physical location belonging to a merchant. Stores have addresses, geo-coordinates, timezone settings, and optional sandbox mode for testing. Most operations (baskets, stock, orders) are scoped to a specific store.

Key fields: addressLine1, city, postcode, lat, lng, timezoneId, email

Store API Reference →

Product ​

An item the merchant sells. Products have a name, barcode, description, images, and belong to one or more categories. Each product has one or more instances (variants) that hold pricing and tax information.

Key fields: name, barcode, details, tags, images, categories, instances

Products and instances

A product is the thing you sell (e.g. "Classic Beef Burger"). An instance is a specific variant with its own price (e.g. a regular or large size). Instances are immutable for historical accuracy — to change a price, create a new instance and deactivate the old one.

Product API Reference →

Category ​

Categories organise products into hierarchical groups. A category can have a parentId to form a tree structure (e.g. "Drinks" > "Hot Drinks" > "Coffee").

Key fields: title, parentId, activeDate

Category API Reference →

Product Component ​

Sub-item groups that can be attached to a product — things like sizes, toppings, or extras. Each component group has minimum and maximum quantity constraints and contains its own set of products and instances.

Key fields: name, productId, minQuantity, maxQuantity, products

Product Component API Reference →

Basket ​

The central resource in a sale. A basket represents a customer's cart at a specific store, containing line items (basket products) with quantities and prices. Baskets follow a two-phase flow:

  1. Part 1 — Create or update the basket with products, store, and promotions
  2. Part 2 — Set completed: true to finalise. Once complete, no further changes are allowed.

Transactions are attached between Part 1 and Part 2.

Key fields: storeId, basketProducts, consumerId, completeDate

Basket API Reference →

Transaction ​

A payment against a basket. Transactions have a type (CASH, CARD, or SERVICE), an amount in pence, and an optional tip. Like baskets, transactions are created then completed in a separate step.

Key fields: basketId, type, amount, tip, completeDate

Transaction API Reference →

Order ​

A delivery order attached to a completed basket. Orders track fulfilment status and are scoped to a store.

Key fields: storeId, timestamp, completeDate

Order API Reference →

Promotion ​

A discount or offer that can be applied to baskets. Promotions have date ranges, day-of-week availability, and can be scoped to specific stores, categories, or products. Codes can be generated and optionally linked to a consumer.

Key fields: title, startDate, endDate, daysAvailable, automatic

Promotion API Reference →

Invoice ​

A purchase invoice from a supplier, recording stock receipts. Invoices contain line items with quantities, prices, and VAT. When items are linked to products, stock levels are recalculated automatically.

Key fields: storeId, supplierId, reference, invoiceItems, totalIncVat

Invoice API Reference →

Supplier ​

A supplier profile that your merchant sources stock from. Suppliers have their own store locations (/supplier/store) and are linked to invoices.

Key fields: name, description, companyNumber, vatNumber

Supplier API Reference →

Employee ​

A staff member of the merchant. Employees have roles, join/exit dates, and are linked to user accounts.

Key fields: firstName, lastName, email, roleId, joinedDate

Employee API Reference →

User ​

The authenticated user's profile. A user is tied to an employee record and a merchant.

Key fields: firstName, lastName, email, employee

User API Reference →

Application ​

An OAuth application registered by the merchant. Each application has an identifier (client ID) and secret (client secret) for the OAuth flow, plus redirect URLs for different environments.

Key fields: applicationName, identifier, secret, url, sandbox

Application API Reference →

Report ​

Aggregated data across baskets, transactions, and products. The Basket Report provides completed basket details within a timeframe. The SWQL (Shopwave Query Language) Report offers flexible querying with custom FROM, WHERE, SELECT, and GROUP clauses.

Report API Reference →

Log ​

General-purpose JSON data storage. Logs are tagged and keyed by object type and identifier for retrieval. Useful for storing custom data like stock take results.

Key fields: tag, object, identifier, value

Log API Reference →

API conventions ​

Response envelope ​

Every response includes an api object with structured messages and performance metadata:

json
{
  "api": {
    "message": {
      "success": { ... },
      "error": { ... }
    },
    "codeBaseVersion": "2.0",
    "executionTime_milliSeconds": 29
  }
}

Check api.message.error even on 200/201 responses — partial failures (e.g. one item in a batch failing validation) are reported here.

Resource maps, not arrays ​

Resources are returned as objects keyed by their ID, not as arrays:

json
{
  "products": {
    "135592": { "id": 135592, "name": "Classic Beef Burger" },
    "135593": { "id": 135593, "name": "Veggie Wrap" }
  }
}

Create and update via POST ​

POST endpoints handle both creation and updates. To update an existing resource, include its id in the request body. To create, omit the id.

Batch operations ​

Most POST endpoints accept multiple objects in a single request, keyed by an arbitrary reference string you choose:

json
{
  "products": {
    "new-burger": { "name": "Chicken Burger", ... },
    "update-existing": { "id": 135592, "name": "Classic Beef Burger (Updated)", ... }
  }
}

The response uses the same keys so you can match results to your original objects.

Versioning ​

Include the x-accept-version header with your requests:

x-accept-version: 2.0

This ensures consistent behaviour as the API evolves.