Update Custom Field

Sparse-update a custom field by name. Only the keys you send are changed. Sending name returns 422 — identity is immutable. To rename, delete then create; historical buyer answers stored under the old name are orphaned.

validation is replace-all of the nested object; null clears it. Extra validation.precision is refused. Sending order moves the field to that position and renumbers the rest of the collection, so the response may show a different order on fields you did not send. See Order.

Live writes return 409 when the product has has_draft: true. Draft writes require draft_version.

Request

Live:

• PATCH /products/{productId}/custom-fields/{name}
• PATCH /products/{productId}/waitlist-custom-fields/{name}
• PATCH /product-variants/{id}/custom-fields/{name}

Draft:

• PATCH /products/{productId}/draft/custom-fields/{name}
• PATCH /products/{productId}/draft/waitlist-custom-fields/{name}
• PATCH /products/{productId}/draft/variants/{id}/custom-fields/{name}

Path Parameters

Parameter	Type	Required	Description
productId	string	Yes	Product UUID (product-nested paths).
id	string	Yes	Variant UUID (variant-nested paths).
name	string	Yes	Field identity slug.

Request Body

All fields optional. Draft writes also require draft_version.

Parameter	Type	Required	Description
type	string	No	See Types.
label	string	No	Buyer-facing copy, max 255.
placeholder	string	No	Form-hint copy. null clears it.
enabled	boolean	No	false hides without deleting.
required	boolean	No	Inert when enabled is false.
order	integer	No	Moves the field to this 0-based position. See Order.
validation	object	No	Replace-all, or null to clear.
options	array	No	Replace-all of select choices.
sync_easymail	boolean	No	Marks the definition for Easymail sync when also enabled.
draft_version	integer	Draft only	Current overlay version. Minimum 1.

Example Request

curl -X PATCH "https://cart.easy.tools/api/v1/products/0632bef5-c308-42cd-9cba-89a7a4f722bb/custom-fields/size" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

Response

Success Response (200)

Returns the updated Custom Field Object. Draft updates also include draft_version and preview_url.

{
  "name": "size",
  "type": "select",
  "label": "Size",
  "placeholder": null,
  "enabled": false,
  "required": true,
  "order": 0,
  "validation": null,
  "options": [
    { "value": "s", "label": "S" },
    { "value": "m", "label": "M" }
  ],
  "sync_easymail": false
}

Error Responses

Bad Request (400)

{
  "message": "Invalid product ID"
}

Not Found Error (404)

{
  "message": "Custom field with name size not found"
}

Conflict Error (409 — Unpublished Draft)

Live write while has_draft is true:

{
  "message": "This product has an unpublished draft. Publish, unpublish, or delete the draft before making live changes."
}

Conflict Error (409 — Stale Draft Version)

Draft write when draft_version does not match:

{
  "message": "The draft was edited elsewhere. GET the draft and retry with the current draft_version."
}

Validation Error (422 Unprocessable Entity)

{
  "message": "The given data was invalid.",
  "errors": {
    "name": ["The name field is prohibited."]
  }
}

Unauthorized Error (401)

{
  "message": "Unauthenticated."
}

Forbidden Error (403)

{
  "message": "This action is unauthorized."
}