Skip to main content
PATCH
Update a product

Authorizations

X-API-Key
string
header
required

Path Parameters

gtin
string<gtin>
required

GTIN barcode (8, 12, 13, or 14 digits, with or without separators). Normalized to GTIN-14 for lookup.

Required string length: 8 - 14
Pattern: ^[0-9]{8}$|^[0-9]{12,14}$

Body

application/json

Partial-update payload for PATCH /products/{gtin}.

Every field is optional. Only fields explicitly set in the request are written; passing null leaves the existing value unchanged, except for metadata, which follows Stripe-style semantics: {} or null clears all metadata, an empty-string value deletes that key, other values set that key, and omitted keys are preserved.

metadata
Metadata · object | null

Developer-attached key/value data. Send {} or null to clear. Empty-string values delete that key. Omitted keys are preserved.

product_name
string | null

Display name as marketed on the packaging. Omit or send null to leave unchanged.

Maximum string length: 255
Pattern: ^[^\x00]{0,255}$
brand
string | null

Brand name. Looked up by name (case-insensitive) under the caller's organization; a new Brand is created when no match exists. Omit or send null to leave unchanged.

Maximum string length: 255
Pattern: ^[^\x00]{0,255}$
description
string | null

Long-form product description. Omit or send null to leave unchanged.

Maximum string length: 65536
Pattern: ^[^\x00]{0,}$
manufacturer
string | null

Manufacturer name. Looked up by name (case-insensitive); a new Manufacturer is created when no match exists. Omit or send null to leave unchanged.

Maximum string length: 255
Pattern: ^[^\x00]{0,255}$
country_of_origin
string | null

ISO 3166-1 alpha-2 country code where the product is made. Omit or send null to leave unchanged.

Maximum string length: 2
Pattern: ^[^\x00]{0,2}$
net_content
string | null

Free-text net content as printed on the package (e.g. 340g). Omit or send null to leave unchanged.

Maximum string length: 100
Pattern: ^[^\x00]{0,100}$
usage_instructions
string | null

Directions or instructions for use. Omit or send null to leave unchanged.

Maximum string length: 65536
Pattern: ^[^\x00]{0,}$
brand_product_page_url
string<http-url> | null

Absolute http(s) URL of the brand's canonical product page, up to 200 characters. An empty string clears it. Omit or send null to leave unchanged.

Maximum string length: 200
Pattern: ^([Hh][Tt][Tt][Pp][Ss]?://[^\x00-\x20\x7f/?#][^\x00-\x20\x7f]{0,191})?$
primary_language
string | null

ISO 639-1 language code identifying the product's primary language. Omit or send null to leave unchanged.

Maximum string length: 10
Pattern: ^[^\x00]{0,10}$
category_id
string<shortuuid> | null

URL-safe 22-character shortuuid encoding of the row's UUID primary key. Stable across the row's lifetime; suitable for sharing in URLs, log lines, and external SDK clients. Accepted on input as either the shortuuid form or the canonical UUID form (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).

Required string length: 22
Pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$
ingredients
string | null

Raw ingredient list text (the verbatim text from the package). When provided, the parser splits the text into spans and matches each span to a Substance record. Omit to skip ingredient parsing.

Pattern: ^[^\x00]{0,}$
length

Product length. Unit is given by length_uom. Omit or send null to leave unchanged.

Required range: x >= 0
length_uom
enum<string> | null

UN/CEFACT unit code for length (e.g. CMT, MMT, MTR, INH).

Available options:
MMT,
CMT,
MTR,
INH
width

Product width. Unit is given by width_uom. Omit or send null to leave unchanged.

Required range: x >= 0
width_uom
enum<string> | null

UN/CEFACT unit code for width (e.g. CMT, MMT, MTR, INH).

Available options:
MMT,
CMT,
MTR,
INH
height

Product height. Unit is given by height_uom. Omit or send null to leave unchanged.

Required range: x >= 0
height_uom
enum<string> | null

UN/CEFACT unit code for height (e.g. CMT, MMT, MTR, INH).

Available options:
MMT,
CMT,
MTR,
INH
depth

Product depth. Unit is given by depth_uom. Omit or send null to leave unchanged.

Required range: x >= 0
depth_uom
enum<string> | null

UN/CEFACT unit code for depth (e.g. CMT, MMT, MTR, INH).

Available options:
MMT,
CMT,
MTR,
INH
gross_weight

Gross weight including packaging. Unit is given by gross_weight_uom. Omit or send null to leave unchanged.

Required range: x >= 0
gross_weight_uom
enum<string> | null

UN/CEFACT unit code for gross weight (e.g. GRM, KGM, LBR, ONZ).

Available options:
GRM,
KGM,
ONZ,
LBR
net_weight

Net weight excluding packaging. Unit is given by net_weight_uom. Omit or send null to leave unchanged.

Required range: x >= 0
net_weight_uom
enum<string> | null

UN/CEFACT unit code for net weight (e.g. GRM, KGM, LBR, ONZ).

Available options:
GRM,
KGM,
ONZ,
LBR
gpc_segment_code
string | null

GPC segment code (top-level classification).

Maximum string length: 8
Pattern: ^[^\x00]{0,8}$
gpc_family_code
string | null

GPC family code (parent of class).

Maximum string length: 8
Pattern: ^[^\x00]{0,8}$
gpc_class_code
string | null

GPC class code (parent of brick).

Maximum string length: 8
Pattern: ^[^\x00]{0,8}$
gpc_brick_code
string | null

8-digit GS1 GPC brick code.

Maximum string length: 8
Pattern: ^[^\x00]{0,8}$

Response

OK

Canonical product record returned by the GTIN repository.

Combines the core product fields, GDSN dimension/weight pairs, GS1 Global Product Classification (GPC) codes, and the Stripe-style metadata map. Crowd-sourced contributions are folded into this shape only after they pass the confidence-promotion threshold.

id
string<shortuuid>
required

Internal product identifier (UUID). Stable for the lifetime of the GTIN.

Required string length: 22
Pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$
gtin
string
required

Normalized GTIN-14 (zero-padded). Stable across the catalog regardless of input format.

Required string length: 14
Pattern: ^\d{14}$
product_name
string
required

Display name of the product as marketed on the packaging.

The GS1 Digital Link URI to encode in this product's QR code; print it as-is rather than building one. Scanning it reaches the resolver, which sends the scan wherever the product's resolution rules and claim allow (its Closient-hosted page by default). The host is the owning organization's verified custom resolver hostname when it has one with an active certificate, otherwise the platform resolver domain. Scheme and host are uppercase because that keeps a QR in its denser alphanumeric mode; both are case-insensitive. Null only for a stored GTIN with no valid check digit, which has no Digital Link. GET /products/{gtin}/barcode currently encodes the platform resolver domain for every product, so for an organization with a custom hostname its image differs from this link.

Example:

"HTTPS://GTIN.ONE/01/00012345678905"

is_claimed
boolean
required

True when the GTIN has been claimed by a brand owner (i.e. the linked Brand belongs to an Organization).

data_source
enum<string>
required

Provenance of the canonical record (e.g. crowd_sourced, open_food_facts, claimed once a brand owner takes ownership).

Available options:
crowd_sourced,
claimed,
imported,
ai_extracted,
brand_site_crawl,
gtin1_authoritative,
external_api,
open_food_facts,
usda_fdc,
fda_ndc,
affiliate_feed,
datakick,
common_crawl_wdc
confidence_score
number
required

Aggregate confidence score across all canonical fields, derived from contribution agreement.

Required range: 0 <= x <= 1
field_confidence
Field Confidence · object
required

Per-field confidence map, e.g. {"product_name": 0.95, "brand": 0.9}. Each value is in the range 0.0 - 1.0.

date_label_compliance
DateLabelComplianceOut · object
required

California AB 660 readiness summary, computed on read by scanning the stored free-text fields (product_name, description, net_content, usage_instructions) for the same banned phrases the registration API rejects. The response shape is stable so a future federal date-label rule can be reported in the federal slot.

Examples:
metadata
Metadata · object

Developer-attached key/value data attached to this object. Up to 50 keys; key max 40 chars, value max 500 chars.

brand
string
default:""

Brand name resolved from the linked Brand record. Empty string when the GTIN is not yet associated with a brand.

manufacturer
string
default:""

Manufacturer name resolved from the linked Manufacturer record. Empty string when no manufacturer is on file.

description
string
default:""

Long-form description of the product. May be empty. This field holds HTML, and the API sanitizes it on the way out against an allow-list (paragraphs, line breaks, inline emphasis, lists, and links restricted to http, https and mailto). Plain text is returned byte-for-byte; text containing a < that does not open a tag is returned entity-encoded, which is its correct encoding for an HTML field; script, style, event handlers and javascript:/data: URLs are removed. Stored data is never modified.

image_url
string
default:""

Absolute URL of the primary product image. Empty string when the product has no hero image.

country_of_origin
string
default:""

ISO 3166-1 alpha-2 country code identifying where the product was made. Empty string when unknown.

Maximum string length: 2
net_content
string
default:""

Free-text net content as printed on the package (e.g. 340g, 12 x 330ml). Use net_content_value + net_content_uom for the structured pair.

net_content_value
number | null

Structured numeric net content (e.g. 340 for 340g). Null when no structured value has been parsed.

net_content_uom
enum<string> | null

UN/CEFACT unit code paired with net_content_value. Null when no structured value has been parsed; expect the empty string on legacy records pending a backfill.

Available options:
MLT,
CLT,
LTR,
GRM,
KGM,
ONZ,
LBR,
PTI,
QTI,
GLL,
EA
owner_id
string<shortuuid> | null

URL-safe 22-character shortuuid encoding of the row's UUID primary key. Stable across the row's lifetime; suitable for sharing in URLs, log lines, and external SDK clients. Accepted on input as either the shortuuid form or the canonical UUID form (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).

Required string length: 22
Pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$
claim_verification_status
enum<string> | null

Verification tier for the GTIN ownership claim. Null when the GTIN has never been claimed; set automatically to unverified on initial claim and upgraded by external verification signals.

Available options:
unverified,
prefix_matched,
verified,
disputed,
rejected
length
number | null

Product length in the unit specified by length_uom. Null when the dimension is unknown.

length_uom
string
default:""

UN/CEFACT recommendation 20/21 unit code for the paired dimension (e.g. CMT centimetre, MMT millimetre, MTR metre). Empty string when the dimension is unknown.

Maximum string length: 10
width
number | null

Product width in the unit specified by width_uom. Null when the dimension is unknown.

width_uom
string
default:""

UN/CEFACT recommendation 20/21 unit code for the paired dimension (e.g. CMT centimetre, MMT millimetre, MTR metre). Empty string when the dimension is unknown.

Maximum string length: 10
height
number | null

Product height in the unit specified by height_uom. Null when the dimension is unknown.

height_uom
string
default:""

UN/CEFACT recommendation 20/21 unit code for the paired dimension (e.g. CMT centimetre, MMT millimetre, MTR metre). Empty string when the dimension is unknown.

Maximum string length: 10
depth
number | null

Product depth in the unit specified by depth_uom. Null when the dimension is unknown.

depth_uom
string
default:""

UN/CEFACT recommendation 20/21 unit code for the paired dimension (e.g. CMT centimetre, MMT millimetre, MTR metre). Empty string when the dimension is unknown.

Maximum string length: 10
gross_weight
number | null

Gross weight (product + packaging) in the unit specified by gross_weight_uom. Null when unknown.

gross_weight_uom
string
default:""

UN/CEFACT recommendation 20/21 unit code for the paired weight (e.g. GRM gram, KGM kilogram, LBR pound, ONZ ounce). Empty string when the weight is unknown.

Maximum string length: 10
net_weight
number | null

Net weight (product only, excluding packaging) in the unit specified by net_weight_uom. Null when unknown.

net_weight_uom
string
default:""

UN/CEFACT recommendation 20/21 unit code for the paired weight (e.g. GRM gram, KGM kilogram, LBR pound, ONZ ounce). Empty string when the weight is unknown.

Maximum string length: 10
gpc_brick_code
string
default:""

GS1 Global Product Classification 8-digit brick code (the most specific level). Empty string when the product has not been classified.

Maximum string length: 8
Pattern: ^(\d{8})?$
gpc_class_code
string
default:""

GS1 Global Product Classification class code (parent of brick). Empty string when unclassified.

Maximum string length: 8
Pattern: ^(\d{8})?$
gpc_family_code
string
default:""

GS1 Global Product Classification family code (parent of class). Empty string when unclassified.

Maximum string length: 8
Pattern: ^(\d{8})?$
gpc_segment_code
string
default:""

GS1 Global Product Classification segment code (top-level category). Empty string when unclassified.

Maximum string length: 8
Pattern: ^(\d{8})?$
sensitivities
ProductSensitivityOut · object[]

AI-inferred dietary-sensitivity flags for this product (histamine, sulfites, FODMAP, etc.), derived from its ingredient list. Only SENSITIVITY-category traits appear here — regulated allergens are not duplicated. LOW-severity flags are excluded unless include_low=true. Informational only, not medical advice.