> ## 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. # Update certification assignment > Partially update an existing certification assignment. Only fields present in the request body are applied; omitted fields are left unchanged. ``metadata`` follows Stripe-style merge semantics. Returns ``404`` when the GTIN or certification does not match an existing assignment. ## OpenAPI ````yaml /openapi/openapi-certifications.json patch /certifications/api/v1/products/{gtin}/certifications/{certification_id} openapi: 3.1.0 info: title: Certifications API version: 1.0.0 description: > Product certifications and claims: organic, fair trade, non-GMO, and more. ## Authentication All endpoints require an API key passed via the `X-API-Key` HTTP header, unless otherwise noted. ``` X-API-Key: csb__ ``` Generate API keys in **Settings > API Keys** in your dashboard, or via the Account API. Session-based (cookie) authentication is also accepted for browser-based access. ## Rate Limits | Tier | Requests / minute | Requests / day | |-------------|-------------------|----------------| | Default | 300 | 10,000 | | Custom | Contact us | Contact us | Rate-limit headers are included on every response so callers can self-throttle without hitting our 429s ("informed governor"): - `RateLimit-Policy` — every active window, e.g. `300;w=60, 10000;w=86400` - `RateLimit-Limit` — quota for the **most-restrictive** currently-active window - `RateLimit-Remaining` — requests left in that window - `RateLimit-Reset` — seconds until that window resets (relative; clock-skew safe) Legacy `X-RateLimit-*` aliases are also emitted for back-compat. `X-RateLimit-Reset` keeps the absolute Unix-timestamp shape to avoid breaking existing consumers. When rate-limited, you receive `429 Too Many Requests` with a `retry_after_seconds` field in the error envelope and a `Retry-After` header. ## Pagination List endpoints return paginated results in this envelope: ```json { "data": [...], "pagination": { "page": 1, "page_size": 25, "total_count": 342, "total_pages": 14, "has_next": true, "has_previous": false } } ``` Use `?page=2&page_size=50` query parameters. Maximum page size is 100. ## Error Responses All errors conform to [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457) with `Content-Type: application/problem+json`: ```json { "type": "https://closient.com/docs/errors/not_found", "title": "Not Found", "status": 404, "detail": "The requested resource was not found.", "error_code": "not_found", "retryable": false, "timestamp": "2026-03-31T12:00:00+00:00" } ``` Common error codes: `unauthorized` (401), `forbidden` (403), `not_found` (404), `validation_error` (422), `rate_limited` (429), `internal_error` (500). termsOfService: https://www.closient.com/terms/ servers: - url: https://www.closient.com security: [] tags: - name: Certification Bodies description: Certification issuing organizations. - name: Certifications description: Certification definitions. - name: Claims description: Product claim definitions. - name: Assignments description: Product certification and claim assignments. externalDocs: description: Closient Documentation url: https://docs.closient.com paths: /certifications/api/v1/products/{gtin}/certifications/{certification_id}: patch: tags: - Assignments summary: Update certification assignment description: >- Partially update an existing certification assignment. Only fields present in the request body are applied; omitted fields are left unchanged. ``metadata`` follows Stripe-style merge semantics. Returns ``404`` when the GTIN or certification does not match an existing assignment. operationId: apps_certifications_api_update_product_certification parameters: - in: path name: gtin schema: description: >- 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. maxLength: 14 minLength: 8 pattern: ^\d{8,14}$ title: Gtin type: string required: true description: >- 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. - in: path name: certification_id schema: description: Short ID of the certification to update on this product. format: shortuuid maxLength: 22 minLength: 22 pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$ title: Certification Id type: string required: true description: Short ID of the certification to update on this product. requestBody: content: application/json: schema: $ref: '#/components/schemas/CertificationAssignmentUpdateIn' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CertificationAssignmentOut' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorOut' security: - APIKeyHeaderAuth: [] - OAuthTokenAuth: [] - SessionAuth: [] components: schemas: CertificationAssignmentUpdateIn: description: >- 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`. examples: - certificate_number: NOP-12345-UPDATED metadata: order_id: '6735' verification_status: verified properties: metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' description: >- Developer-attached key/value data. Send {} or null to clear. Empty-string values delete that key. Omitted keys are preserved. title: Metadata valid_from: anyOf: - format: date type: string - type: 'null' description: >- Start of validity (ISO 8601). Send ``null`` to clear; omit to leave unchanged. title: Valid From expiration_date: anyOf: - format: date type: string - type: 'null' description: >- End of validity (ISO 8601). Send ``null`` to clear; omit to leave unchanged. title: Expiration Date certificate_number: anyOf: - maxLength: 100 type: string - type: 'null' description: >- Certificate identifier from the issuing body. Omit to leave unchanged. title: Certificate Number issuing_body: anyOf: - maxLength: 255 type: string - type: 'null' description: Free-text issuing-organization name. Omit to leave unchanged. title: Issuing Body verification_url: anyOf: - type: string - type: 'null' description: URL to verify this certificate online. Omit to leave unchanged. title: Verification Url verification_status: anyOf: - $ref: '#/components/schemas/VerificationStatusEnum' - type: 'null' description: >- Lifecycle state of the certificate's verification. One of ``unverified``, ``verified``, ``expired``. Omit to leave unchanged. scope: anyOf: - type: string - type: 'null' description: >- Free-text describing what the certification covers. Omit to leave unchanged. title: Scope certification_value: anyOf: - maxLength: 255 type: string - type: 'null' description: >- GS1 ``certificationValue`` — assessed level/result. Omit to leave unchanged. title: Certification Value audit_date: anyOf: - format: date type: string - type: 'null' description: Date of the certification audit (ISO 8601). Omit to leave unchanged. title: Audit Date initial_certification_date: anyOf: - format: date type: string - type: 'null' description: >- Date the certification was originally granted (ISO 8601). Omit to leave unchanged. title: Initial Certification Date certificate_countries: anyOf: - items: type: string type: array - type: 'null' description: >- ISO 3166-1 alpha-2 country codes for certificate jurisdictions. Omit to leave unchanged; pass ``[]`` to clear. title: Certificate Countries title: CertificationAssignmentUpdateIn type: object CertificationAssignmentOut: description: |- 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. examples: - audit_date: '2024-01-10' certificate_countries: - US - CA certificate_number: NOP-12345 certification_value: 100% Organic code: USDA_ORGANIC description: USDA NOP. expiration_date: '2025-01-15' expiry_date: '2025-01-15' id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 initial_certification_date: '2020-03-01' is_active: true issuing_body: Oregon Tilth label: USDA Organic metadata: order_id: '6735' scope: Product url: https://www.usda.gov/topics/organic valid_from: '2024-01-15' verification_status: verified verification_url: https://organic.ams.usda.gov/integrity/ properties: metadata: additionalProperties: type: string description: >- Developer-attached key/value data attached to this object. Up to 50 keys; key max 40 chars, value max 500 chars. title: Metadata type: object id: description: >- 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``). format: shortuuid maxLength: 22 minLength: 22 pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$ title: Id type: string label: description: >- Display name of the underlying certification (e.g. ``USDA Organic``). maxLength: 255 title: Label type: string code: default: '' description: >- Stable code of the underlying certification (e.g. ``USDA_ORGANIC``). Empty for unnamed. maxLength: 50 title: Code type: string description: default: '' description: >- Free-text summary from the underlying certification record. May be empty. title: Description type: string url: default: '' description: >- Canonical reference URL from the underlying certification record. May be empty. title: Url type: string logo_url: anyOf: - type: string - type: 'null' description: >- Absolute URL of the certification's logo. ``null`` when no logo is set. title: Logo Url valid_from: anyOf: - format: date type: string - type: 'null' description: >- Start of validity for *this* certificate (ISO 8601, ``YYYY-MM-DD``). ``null`` when not recorded — treat as 'valid since unknown date'. title: Valid From expiration_date: anyOf: - format: date type: string - type: 'null' description: >- 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. title: Expiration Date is_active: description: >- 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. title: Is Active type: boolean certificate_number: default: '' description: >- Certificate identifier issued by the certification body (e.g. ``NOP-12345``). Empty when not yet recorded. maxLength: 100 title: Certificate Number type: string issuing_body: default: '' description: >- 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. maxLength: 255 title: Issuing Body type: string expiry_date: anyOf: - format: date type: string - type: 'null' description: >- 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. title: Expiry Date verification_url: default: '' description: >- 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. title: Verification Url type: string verification_status: allOf: - $ref: '#/components/schemas/VerificationStatusEnum' default: unverified description: >- 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. scope: default: '' description: >- Free-text describing what the certification covers (e.g. ``Product``, ``All organic dairy lines``). Empty when not specified. title: Scope type: string certification_value: default: '' description: >- GS1 ``certificationValue`` — the assessed level or result (e.g. ``Grade A``, ``Level 3``, ``100% Organic``). Empty when the program does not grade results. maxLength: 255 title: Certification Value type: string audit_date: anyOf: - format: date type: string - type: 'null' description: >- Date the certification audit was performed (ISO 8601). ``null`` when not recorded. title: Audit Date initial_certification_date: anyOf: - format: date type: string - type: 'null' description: >- Date the certification was originally granted (ISO 8601). ``null`` when not recorded. Use to compute years-certified. title: Initial Certification Date certificate_countries: description: >- 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'. items: type: string title: Certificate Countries type: array required: - id - label - is_active title: CertificationAssignmentOut type: object ErrorOut: description: |- RFC 9457 Problem Details response. All API errors are returned in this format with Content-Type: application/problem+json. examples: - detail: The requested resource was not found. error_code: not_found retryable: false status: 404 timestamp: '2026-03-31T12:00:00+00:00' title: Not Found type: https://closient.com/docs/errors/not_found - detail: Validation error. details: - loc: - body - name msg: Field required type: missing error_code: validation_error retryable: false status: 422 timestamp: '2026-03-31T12:00:00+00:00' title: Validation Error type: https://closient.com/docs/errors/validation_error - detail: Rate limit exceeded. Please try again later. error_code: rate_limited retry_after: 31 retryable: true status: 429 timestamp: '2026-03-31T12:00:00+00:00' title: Rate Limited type: https://closient.com/docs/errors/rate_limited properties: type: description: URI reference identifying the error type. title: Type type: string title: description: Short human-readable summary of the error. title: Title type: string status: description: HTTP status code. title: Status type: integer detail: description: Human-readable explanation of this specific occurrence. title: Detail type: string error_code: description: Machine-readable error code (e.g. not_found, unauthorized). title: Error Code type: string retryable: default: false description: Whether retrying the same request can succeed. title: Retryable type: boolean timestamp: description: ISO 8601 timestamp of when the error occurred. title: Timestamp type: string retry_after: anyOf: - type: integer - type: 'null' description: Seconds to wait before retrying (when applicable). title: Retry After owner_action_required: anyOf: - type: boolean - type: 'null' description: Whether the error requires account owner intervention. title: Owner Action Required details: description: Additional context (validation errors, etc.). title: Details required: - type - title - status - detail - error_code - timestamp title: ErrorOut type: object VerificationStatusEnum: enum: - unverified - verified - expired title: VerificationStatusEnum type: string securitySchemes: APIKeyHeaderAuth: type: apiKey in: header name: X-API-Key OAuthTokenAuth: type: http scheme: bearer SessionAuth: type: apiKey in: cookie name: sessionid ````