Skip to main content
PATCH
/
certifications
/
api
/
v1
/
products
/
{gtin}
/
certifications
/
{certification_id}
Update certification assignment
curl --request PATCH \
  --url https://www.closient.com/certifications/api/v1/products/{gtin}/certifications/{certification_id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "metadata": {},
  "valid_from": "2023-12-25",
  "expiration_date": "2023-12-25",
  "certificate_number": "<string>",
  "issuing_body": "<string>",
  "verification_url": "<string>",
  "verification_status": "unverified",
  "scope": "<string>",
  "certification_value": "<string>",
  "audit_date": "2023-12-25",
  "initial_certification_date": "2023-12-25",
  "certificate_countries": [
    "<string>"
  ]
}
'
{
  "id": "<string>",
  "label": "<string>",
  "is_active": true,
  "metadata": {},
  "code": "",
  "description": "",
  "url": "",
  "logo_url": "<string>",
  "valid_from": "2023-12-25",
  "expiration_date": "2023-12-25",
  "certificate_number": "",
  "issuing_body": "",
  "expiry_date": "2023-12-25",
  "verification_url": "",
  "verification_status": "unverified",
  "scope": "",
  "certification_value": "",
  "audit_date": "2023-12-25",
  "initial_certification_date": "2023-12-25",
  "certificate_countries": [
    "<string>"
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.closient.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
X-API-Key
string
header
required

Path Parameters

​
gtin
string
required

GTIN-8, GTIN-12, GTIN-13, or GTIN-14 barcode digits (no spaces, no hyphens). Shorter forms are zero-left-padded to GTIN-14 server-side. Returns 404 if no product matches the normalized GTIN.

Required string length: 8 - 14
Pattern: ^\d{8,14}$
​
certification_id
string<shortuuid>
required

Short ID of the certification to update on this product.

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

Body

application/json

Request body for PATCH /products/{gtin}/certifications/{certification_id}.

All fields are optional; only fields present in the request body are updated. metadata follows the Stripe-style merge convention: keys with null values delete the key, keys with values upsert, omitted keys are preserved. See :func:apps.core.api.metadata.apply_metadata_update.

​
metadata
Metadata · object

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

​
valid_from
string<date> | null

Start of validity (ISO 8601). Send null to clear; omit to leave unchanged.

​
expiration_date
string<date> | null

End of validity (ISO 8601). Send null to clear; omit to leave unchanged.

​
certificate_number
string | null

Certificate identifier from the issuing body. Omit to leave unchanged.

Maximum string length: 100
​
issuing_body
string | null

Free-text issuing-organization name. Omit to leave unchanged.

Maximum string length: 255
​
verification_url
string | null

URL to verify this certificate online. Omit to leave unchanged.

​
verification_status
enum<string> | null

Lifecycle state of the certificate's verification. One of unverified, verified, expired. Omit to leave unchanged.

Available options:
unverified,
verified,
expired
​
scope
string | null

Free-text describing what the certification covers. Omit to leave unchanged.

​
certification_value
string | null

GS1 certificationValue — assessed level/result. Omit to leave unchanged.

Maximum string length: 255
​
audit_date
string<date> | null

Date of the certification audit (ISO 8601). Omit to leave unchanged.

​
initial_certification_date
string<date> | null

Date the certification was originally granted (ISO 8601). Omit to leave unchanged.

​
certificate_countries
string[] | null

ISO 3166-1 alpha-2 country codes for certificate jurisdictions. Omit to leave unchanged; pass [] to clear.

Response

OK

A certification assigned to a specific product, with certificate detail.

Mirrors :class:apps.certifications.models.CertificationAssignment. Most fields proxy through to the linked :class:Certification record (label, code, description, url, logo_url); the rest carry the per-instance certificate metadata (number, issuing body, validity dates, verification status, audit dates, scope, ...).

id and id are the certification's identifiers, not the assignment's — chosen so callers can deep-link to the certification record from a product's certification list.

​
id
string<shortuuid>
required

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}$
​
label
string
required

Display name of the underlying certification (e.g. USDA Organic).

Maximum string length: 255
​
is_active
boolean
required

Computed: true when today's date falls within [valid_from, expiration_date] (either bound being null is treated as open). Refreshes per request — do not cache.

​
metadata
Metadata · object

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

​
code
string
default:""

Stable code of the underlying certification (e.g. USDA_ORGANIC). Empty for unnamed.

Maximum string length: 50
​
description
string
default:""

Free-text summary from the underlying certification record. May be empty.

​
url
string
default:""

Canonical reference URL from the underlying certification record. May be empty.

​
logo_url
string | null

Absolute URL of the certification's logo. null when no logo is set.

​
valid_from
string<date> | null

Start of validity for this certificate (ISO 8601, YYYY-MM-DD). null when not recorded — treat as 'valid since unknown date'.

​
expiration_date
string<date> | null

End of validity for this certificate (ISO 8601, YYYY-MM-DD). null for certificates with no scheduled expiry. Drives the is_active computed field below.

​
certificate_number
string
default:""

Certificate identifier issued by the certification body (e.g. NOP-12345). Empty when not yet recorded.

Maximum string length: 100
​
issuing_body
string
default:""

Free-text name of the organization that issued this certificate. Distinct from the linked :class:CertificationBody record — kept separately because the brand may report a different name than the canonical body. Empty when not recorded.

Maximum string length: 255
​
expiry_date
string<date> | null

When this specific certificate expires (ISO 8601). Distinct from expiration_date: expiration_date is the policy/program validity window; expiry_date is the certificate document's own expiry as printed on it. Often equal in practice.

​
verification_url
string
default:""

URL to verify this certificate online via the issuing body's registry (e.g. USDA Organic Integrity Database). Empty when no public registry is exposed.

​
verification_status
enum<string>
default:unverified

Lifecycle state of the certificate's verification. unverified (default) means the brand-claimed certificate has not been audited by Closient; verified means it has been confirmed against the issuing body's registry; expired means the verification record lapsed. Maps to GS1 certificationStatus (ACTIVE / INACTIVE) in JSON-LD exports.

Available options:
unverified,
verified,
expired
​
scope
string
default:""

Free-text describing what the certification covers (e.g. Product, All organic dairy lines). Empty when not specified.

​
certification_value
string
default:""

GS1 certificationValue — the assessed level or result (e.g. Grade A, Level 3, 100% Organic). Empty when the program does not grade results.

Maximum string length: 255
​
audit_date
string<date> | null

Date the certification audit was performed (ISO 8601). null when not recorded.

​
initial_certification_date
string<date> | null

Date the certification was originally granted (ISO 8601). null when not recorded. Use to compute years-certified.

​
certificate_countries
string[]

ISO 3166-1 alpha-2 country codes (uppercase, e.g. ["US", "CA"]) indicating jurisdictions where this certificate is valid. Empty list when not recorded — does not imply 'valid everywhere'.