Skip to main content
PATCH
/
products
/
api
/
v1
/
products
/
{gtin}
Update a product
curl --request PATCH \
  --url https://www.closient.com/products/api/v1/products/{gtin} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "metadata": {},
  "product_name": "<string>",
  "brand": "<string>",
  "description": "<string>",
  "manufacturer": "<string>",
  "country_of_origin": "<string>",
  "net_content": "<string>",
  "usage_instructions": "<string>",
  "brand_product_page_url": "<string>",
  "primary_language": "<string>",
  "category_id": "<string>",
  "ingredients": "<string>"
}
'
{
  "id": "<string>",
  "gtin": "<string>",
  "product_name": "<string>",
  "is_claimed": true,
  "confidence_score": 0.5,
  "field_confidence": {},
  "date_label_compliance": {
    "ca_ab660": "<string>",
    "federal": "<string>",
    "notes": [
      "<string>"
    ]
  },
  "metadata": {},
  "brand": "",
  "manufacturer": "",
  "description": "",
  "image_url": "",
  "country_of_origin": "",
  "net_content": "",
  "net_content_value": 123,
  "owner_id": "<string>",
  "length": 123,
  "length_uom": "",
  "width": 123,
  "width_uom": "",
  "height": 123,
  "height_uom": "",
  "depth": 123,
  "depth_uom": "",
  "gross_weight": 123,
  "gross_weight_uom": "",
  "net_weight": 123,
  "net_weight_uom": "",
  "gpc_brick_code": "",
  "gpc_class_code": "",
  "gpc_family_code": "",
  "gpc_segment_code": ""
}

Authorizations

​
X-API-Key
string
header
required

Path Parameters

​
gtin
string
required

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

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. Use the Stripe-style metadata semantics from :class:apps.core.api.metadata.MetadataWriteMixin for the metadata map (empty-string values delete keys; {} clears everything).

​
metadata
Metadata · object

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
​
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
​
description
string | null

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

​
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
​
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
​
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
​
usage_instructions
string | null

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

​
brand_product_page_url
string | null

Absolute URL of the brand's canonical product page. Omit or send null to leave unchanged.

Maximum string length: 2048
​
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
​
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.

Response

OK

Canonical product record returned by the GTIN repository.

Combines the core trade-item 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.

​
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. See C-2892 for the rule; the response shape is stable so a future federal date-label rule can be reported in the federal slot.

Examples:
{
  "ca_ab660": "compliant",
  "federal": "unknown",
  "notes": []
}
{
  "ca_ab660": "non_compliant",
  "federal": "unknown",
  "notes": ["description: 'sell by'"]
}
​
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.

​
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})?$