Skip to content

Designed
Create or replace custom chapter

Request

Writes the custom chapter's content, which is custom fields only (CustomFields rules: an entry replaces its component's values; a component the payload does not carry keeps what it holds). Custom chapters belong to this specification only (never library chapters). Either party may write them.

Security
oauth2(Required scopes: t1_api)
Path
specificationIdstring, (uuid)required

The unique identifier of the specification

chapterTypestringrequired

Retailer-defined custom chapter type code (communicated with the template at onboarding). Standard chapters have their own routes; library chapter types are rejected (they cannot be customized).

Headers
If-Matchstring

Optional optimistic concurrency: the ETag returned by the chapter GET. When provided, the write is rejected with 412 if the specification changed since the chapter was read (anything on it: another chapter, a contact, a share), or, for a library chapter, if the chapter changed. Guards against concurrent writers within the same owner company (cross-company overwrite is already impossible — the chapter is the ownership boundary).

Bodyapplication/jsonrequired
customFieldsArray of objects or null(CustomFields)required

Custom field VALUES, one entry per custom component of the chapter. The template places retailer-defined custom components in the chapter; each component is a group of fields with its own published JSON Schema, listed by GET /v2/public/templates/{templateId}/chapters/ {chapterType}/custom-fields-schema. A published component never changes, and the same componentId is valid in every template that uses it.

WRITE RULES

  • An entry replaces the values of its component: a field the values object does not carry is cleared. A component the array does not carry keeps what it holds. null or absent = not supplied.
  • An entry is addressed by componentId. sectionCode is needed only when the component appears in more than one section of the chapter; without it, that is a 422 naming the missing field, customFields[i].sectionCode.
  • A componentId (or componentId + sectionCode) that is not in the chapter, or the same one twice: 422 naming the entry.
  • To change one field, read the entry, change it and send the whole values object back, with If-Match: the ETag of the chapter read. Without it, an edit made in between by the counterpart company is overwritten.
  • values is validated against the component's JSON Schema (types, formats, bounds, reference-list items, files owned by your company). A refusal is a 422 naming the field, customFields[i].values.<field>.
  • Mandatory fields (CustomFieldsSchema mandatoryFields) are not checked on write; they are checked when the section is validated.
  • Who may write follows the section that holds the component: in a custom section either party may write; in a standard section the section's own rule applies (e.g. retailer or supplier sections of the general chapter: owner company only). A read returns one entry per custom component of the chapter, with sectionCode always set.
curl -i -X PUT \
  'https://apis.traceone.com/spec/v2/food/specifications/{specificationId}/custom-chapters/{chapterType}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'If-Match: string' \
  -d '{
    "customFields": [
      {
        "componentId": "616ccd92-d666-4180-8349-8d125b269fac",
        "sectionCode": "string",
        "values": {}
      }
    ]
  }'

Responses

The chapter was replaced. Read it back, with its new ETag, from the chapter GET.

Response
No content