# Data model

The domain model behind the business: entities, fields, relations. Only externally visible fields are listed. Machine-readable JSON-LD is at `/ontology`.

## Relations

| | | | |
| --- | --- | --- | --- |
| `Product` | hasMany | `Sku` | A style has several colour / size variants |
| `Sku` | hasStockIn | `Warehouse` | A SKU has stock in each warehouse (Stock) |
| `Stock` | refersTo | `Sku` | A stock row refers to one SKU |
| `Stock` | belongsTo | `Warehouse` | Every stock row carries its warehouse_code |
| `Channel` | hasAccessTo | `Warehouse` | Warehouses a channel may access (allowlist) |
| `Channel` | hasPriceFor | `Product` | A channel's own price for a style (Price) |
| `Order` | belongsTo | `Channel` | An order belongs to a channel (ownership check) |
| `DropshipOrder` | belongsTo | `Channel` | A drop-ship order belongs to a channel |
| `Shipment` | belongsTo | `Channel` | A shipment belongs to a channel |
| `Shipment` | belongsTo | `Order` | A shipment comes from a wholesale order (order_id) |
| `StockReservation` | belongsTo | `Order` | A reservation comes from a wholesale order (order_id); confirming an order creates the reservation, shipping creates the shipment |
| `StockReservation` | belongsTo | `Channel` | A reservation belongs to a channel |
| `Cart` | belongsTo | `Channel` | A cart (via account) belongs to a channel |
| `Transaction` | belongsTo | `Channel` | A transaction is booked against one channel account |
| `Transaction` | refersTo | `Order` | Most transactions carry an order number and a reservation number |

## Product (Product (style))

One style code, containing several colour / size variants (SKUs).

| Field | Type | Description |
| --- | --- | --- |
| `product_code` | string | Style code |
| `product_name` | string | Product name (English) |
| `product_name_zh` | string | Product name in Chinese (present only when set; not yet fed from upstream) |
| `brand` | string | Brand |
| `price_wholesale` | number | Wholesale price |
| `price_retail` | number | Retail price |
| `currency` | string | Currency (AUD / CNY) |
| `weight_grams` | integer | Weight in grams (present only when set; not yet fed from upstream) |
| `image_urls` | array | Product image URLs |
| `description` | string | Specification description |
| `skus` | array | Every variant of this style (Sku) |

## Sku (SKU (barcode / variant))

One specific barcode = style × colour × size.

| Field | Type | Description |
| --- | --- | --- |
| `sku` | string | SKU / barcode |
| `product_code` | string | Owning style code |
| `color_code` | string | Colour code |
| `color_name` | string | Colour name |
| `color_name_zh` | string | Colour name in Chinese (present only when set; not yet fed from upstream) |
| `size` | string | Size |

## Warehouse (Warehouse)

Where stock sits. warehouse_code is the single identifier used in paths, parameters and responses: AU = Australia (all warehouses) (100003); AUSYD2 = Sydney main warehouse (Rosehill) (AUSYD2); AUSYD1 = Sydney accessories warehouse (AUSYD1); CN = China (all warehouses) (500001); CHNZJ1 = Zhenjiang warehouse (CHNZJ1)

| Field | Type | Description |
| --- | --- | --- |
| `warehouse_code` | string | Warehouse code: AU / AUSYD2 / AUSYD1 / CN / CHNZJ1 |
| `name` | string | Warehouse name (English) |
| `name_zh` | string | Warehouse name (Chinese) |
| `country` | string | Country (AU / CN) |
| `company_code` | string | Owning company code (100003 Australia / 500001 China) |
| `type` | string | group = company-level aggregate view; physical = a real warehouse |
| `can_ship` | boolean | Whether it ships directly |
| `currency` | string | Currency |

## Stock (Stock)

Live stock for one SKU in one warehouse (with a price snapshot). Whole-warehouse, by-style, by-SKU and incremental queries all return this shape.

| Field | Type | Description |
| --- | --- | --- |
| `warehouse_code` | string | Warehouse (carried on every row) |
| `sku` | string | SKU |
| `product_code` | string | Style code |
| `product_name` | string | Product name |
| `color_code` | string | Colour code |
| `color_name` | string | Colour |
| `size` | string | Size |
| `brand` | string | Brand |
| `quantity_on_hand` | integer | Quantity on hand |
| `quantity_available` | integer | Available quantity (on hand − reserved) |
| `price_wholesale` | number | Wholesale price |
| `price_retail` | number | Retail price |
| `currency` | string | Currency |
| `expected_arrival_date` | string | Expected arrival date (only when something is in transit) |
| `quantity_incoming` | integer | Quantity in transit (only when something is in transit) |

## Channel (Channel (customer))

A wholesale customer. The token carries the channel code; what it may call is set by its roles and warehouse allowlist.

| Field | Type | Description |
| --- | --- | --- |
| `channel_code` | string | Channel code (customer identity) |
| `region` | string | Default region au / cn |
| `roles` | array | Roles ({ROLES}) |

## Price (Channel price)

One channel's price for one style (per-channel, not the single price carried in the stock rows).

| Field | Type | Description |
| --- | --- | --- |
| `warehouse_code` | string | Warehouse |
| `channel_code` | string | Channel |
| `product_code` | string | Style code |
| `price_wholesale` | number | This channel's wholesale price |
| `price_retail` | number | Retail price |
| `price_settlement` | number | Settlement price |

## Order (Wholesale order)

Wholesale ordering and lookup; belongs to one channel. What you send when ordering is what you get back when reading.

| Field | Type | Description |
| --- | --- | --- |
| `order_id` | string | Order id |
| `warehouse_code` | string | Warehouse |
| `lines` | array | Lines [{sku, quantity}] |
| `status` | string | Status: draft / confirmed / cancelled |
| `status_raw` | integer | Raw status code |
| `created_date` | string | Document date |
| `note` | string | Note |
| `channel_code` | string | Owning channel (ownership check: you only see your own) |

## DropshipOrder (Drop-ship order)

Drop-ship ordering and lookup; belongs to one channel, carries the recipient. One SKU per order.

| Field | Type | Description |
| --- | --- | --- |
| `dropship_order_id` | string | Drop-ship order id |
| `serial_number` | string | Serial number |
| `client_order_number` | string | Your own order number |
| `warehouse_code` | string | Warehouse |
| `sku` | string | SKU |
| `quantity` | integer | Quantity |
| `quantity_allocated` | integer | Quantity allocated |
| `quantity_shipped` | integer | Quantity shipped |
| `recipient` | object | Recipient {name, phone, address, country_code, state, city, postal_code} |
| `sender` | object | Sender {name, phone} |
| `shipping_method` | string | Shipping method normal / express / ems |
| `carrier` | string | Carrier |
| `tracking_number` | string | Tracking number |
| `shipped` | boolean | Shipped or not |
| `shipped_date` | string | Ship date |
| `status` | string | Status: pending / shipped / intercepted / cancelled |
| `status_raw` | integer | Raw status code |
| `paid` | boolean | Paid or not |
| `price_settlement` | number | Settlement price |
| `amount_shipping` | number | Shipping cost |
| `channel_code` | string | Owning channel |

## Shipment (Shipment)

A shipment; belongs to one channel. Tracking hangs under it.

| Field | Type | Description |
| --- | --- | --- |
| `shipment_id` | string | Shipment id |
| `order_id` | string | Source wholesale order id |
| `reservation_id` | string | Source reservation id |
| `warehouse_code` | string | Warehouse |
| `status` | string | Status: shipped |
| `tracking_number` | string | Tracking number |
| `lines` | array | Lines |
| `channel_code` | string | Owning channel |

## StockReservation (Stock reservation)

Stock locked for a channel; belongs to that channel.

| Field | Type | Description |
| --- | --- | --- |
| `reservation_id` | string | Reservation id |
| `order_id` | string | Source wholesale order id |
| `warehouse_code` | string | Warehouse |
| `status` | string | Status: reserved / cancelled / confirmed |
| `shipped` | boolean | Shipped or not |
| `lines` | array | Lines [{sku, quantity}] |
| `channel_code` | string | Owning channel |

## Cart (Cart)

A cart keyed by OMS account (the account belongs to a channel).

| Field | Type | Description |
| --- | --- | --- |
| `account` | string | OMS account |
| `lines` | array | Items [{sku, quantity}] |
| `channel_code` | string | Owning channel |

## Transaction (Account transaction)

One money movement on a channel account: top-up, payment or refund. The balance is their running total.

| Field | Type | Description |
| --- | --- | --- |
| `transaction_id` | string | Transaction number (14 digits — same shape as a dropship serial number, so identification returns candidates rather than guessing) |
| `transaction_type` | string | Type: recharge / payment / refund |
| `amount` | number | Amount (sign follows the type) |
| `currency` | string | Currency |
| `balance_after` | number | Balance after this entry — the chain of balances can be checked end to end |
| `order_id` | string | Related order number (present only when there is one) |
| `reservation_id` | string | Related reservation number (present only when there is one) |
| `created_at` | string | When upstream processed it — not when it happened: back-dated entries land on the day they were entered |
| `channel_code` | string | Owning channel (used for the ownership check: you only see your own) |

```bash
curl "https://connect.everugg.net.au/ontology" -H "Accept: application/ld+json"
curl "https://connect.everugg.net.au/ontology?format=plain"
```

`/ontology` returns JSON-LD (W3C standard) by default; `?format=plain` returns plain JSON, `?format=rdf` returns N-Quads.

---
Markdown source: https://connect.everugg.net.au/reference/ontology.md?lang=en · Web page: https://connect.everugg.net.au/reference?sec=ontology&lang=en