Skip to main content
A Product is returned as a JSON object with object: "product". Every field on every response is documented below.

​
Example

{
  "object": "product",
  "id": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "name": "Reserve Cabernet Sauvignon 2021",
  "gtin": "09300675024235",
  "description": "Single-vineyard reserve from the Yarra Valley.",
  "status": "active",
  "destination": {
    "type": "page",
    "chatbot": null,
    "page": "a1c2e4f6-8b0d-4e2a-9c1b-3d5e7f9a2c4e",
    "knowledge_base": null,
    "url": null
  },
  "metadata": { "vintage": 2021, "abv": 14.2 },
  "total_scans": 142,
  "last_scanned_at": "2026-05-22T14:08:31+00:00",
  "created_at": "2025-11-04T03:22:01+00:00",
  "updated_at": "2026-05-22T14:08:31+00:00"
}

​
Identifiers

​
object
string
required
Always "product". Lets you distinguish object types when piping mixed responses through generic handlers.
​
id
string (uuid)
required
Stable UUID. Generated by Awardee on POST. Use this for all subsequent reads, updates, and deletes.
​
name
string
required
Operator-facing product name. Free-form. Not required to be unique. Defaults to an empty string on POST if omitted — set one for any product you want to recognize in the dashboard.
​
gtin
string | null
GS1 Global Trade Item Number. Always GTIN-14, left-padded with zeros. On write, the input must be exactly 8, 12, 13, or 14 digits — GTIN-8, GTIN-12 (UPC-A), GTIN-13 (EAN-13), or GTIN-14. Any other length is rejected with 400 invalid_payload. Input is normalized to GTIN-14 before storage.
9300675024235  →  09300675024235
Pass null to clear, or omit on PATCH to leave untouched.
​
description
string | null
Free-form description. Operator-facing only — not rendered to scanning consumers.

​
Destination

​
destination
object
required
The routing target for GS1 scans of this product’s GTIN. Always present as an object; the inner fields are mutually exclusive — exactly one of chatbot, page, knowledge_base, or url is non-null when type is set.

​
Status

​
status
string
required
One of unconfigured, active, inactive, archived.
ValueMeaning
unconfiguredNo destination set. Default on create.
activeLive. GTIN scans route to the destination.
inactivePaused. Row remains, scans show a “paused” screen.
archivedSoft-deleted. Hidden from list views.

​
Metadata

​
metadata
object
required
Free-form JSON object (Record<string, unknown>). Returned verbatim. Use it for integration-owned fields that don’t deserve a column — vintage, ABV, internal SKU codes, feature flags, anything.Replaces wholesale on PATCH. Defaults to {} on create.

​
Stats

​
total_scans
integer
required
Lifetime count of resolved GS1 scans for this product. Increments on every product.scanned event. Read-only.
​
last_scanned_at
string (datetime) | null
ISO 8601 timestamp of the most recent resolved scan, or null if never scanned. Read-only.

​
Timestamps

​
created_at
string (datetime)
required
When the row was inserted. ISO 8601.
​
updated_at
string (datetime)
required
When the row last changed. ISO 8601. Updates on every PATCH and on internal mutations (e.g. scan stamps).

​
Properties

Products support a satellite key/value list — list with GET /products/{id}/properties, replace as a set with PUT /products/{id}/properties. Each property has its own shape: 
{
  "object": "product_property",
  "id": "c4d5e6f7-8a9b-4c0d-1e2f-3a4b5c6d7e8f",
  "key": "vintage",
  "value": "2021",
  "sort_order": 0,
  "created_at": "2025-11-04T03:22:01+00:00",
  "updated_at": "2025-11-04T03:22:01+00:00"
}
​
key
string
required
Property name. Free-form; case-sensitive. Operator-defined.
​
value
string
required
Property value, always serialized as a string. Convert client-side if you need typed values.
​
sort_order
integer
required
Display order. Awardee stores properties as a sorted list — PUT preserves the order you send.

​
Images

Images are documented in detail under Images on the overview. The wire shape: 
{
  "object": "product_image",
  "id": "d5e6f7a8-9b0c-4d1e-2f3a-4b5c6d7e8f9a",
  "product_id": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "file_url": "https://files.awardee.dev/orgs/3c1e.../library/9f/9f2a48b1c7e4d5...jpg",
  "file_name": "front.jpg",
  "media_type": "image/jpeg",
  "size_bytes": 184320,
  "sort_order": 0,
  "created_at": "2025-11-04T03:23:11+00:00"
}