Plan a customer customization schema change

Declarative schema workflow, shared by channels, blogs, product and customer customizations and checkout profiles:

GET .../schema exports the current schema (target attributes plus ordinary fields).
POST .../plan diffs a desired document against the target and returns the ops, drift, warnings and a fingerprint. Nothing is written.
POST .../apply with the same document plus that fingerprint writes the change. It fails with 409 when the target changed since the plan (a fresh plan is returned), with 422 when the plan has blocked ops or warnings, and with 422 when it has destructive ops and confirm_destructive is not true.

Fields absent from the document are kept and reported as drift unless prune: true removes them (destructive). Planning or applying a channel, blog or checkout profile slug that does not exist yet creates it on apply.

See the channel endpoints for full request and response examples.

Authorization

AuthorizationBearer <token>

Personal access token tied to a user account. Requires the X-Nimbu-Site header to scope requests.

In: header

X-Nimbu-Site<token>

Identifier of the site context when authenticating with a personal access token.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

fields*array<>

Desired fields in order. Existing fields absent from the list are reported as drift, or removed when prune is true.

prune?boolean

Remove fields and options that exist on the target but are absent from the document (destructive).

fingerprint?string

Apply only: the fingerprint returned by the plan. A mismatch returns 409 with a fresh plan.

confirm_destructive?boolean

Apply only: must be true when the plan contains destructive ops.

Response Body

`application/json`

curl -X POST "https://example.com/customers/customizations/plan" \  -H "Content-Type: application/json" \  -d '{    "fields": [      {        "name": "string"      }    ]  }'

{
  "target": "string",
  "fingerprint": "string",
  "exists": true,
  "ops": [
    {
      "kind": "create_target",
      "risk": "safe",
      "field": "string",
      "attr": "string",
      "option": "string",
      "type": "string",
      "from": null,
      "to": null,
      "entries": 0,
      "entries_with_value": 0,
      "reason": "string"
    }
  ],
  "drift": [
    {
      "field": "string",
      "type": "string",
      "option": "string",
      "note": "string"
    }
  ],
  "warnings": [
    "string"
  ],
  "info": [
    "string"
  ]
}

{
  "message": "string",
  "plan": {
    "target": "string",
    "fingerprint": "string",
    "exists": true,
    "ops": [
      {
        "kind": "create_target",
        "risk": "safe",
        "field": "string",
        "attr": "string",
        "option": "string",
        "type": "string",
        "from": null,
        "to": null,
        "entries": 0,
        "entries_with_value": 0,
        "reason": "string"
      }
    ],
    "drift": [
      {
        "field": "string",
        "type": "string",
        "option": "string",
        "note": "string"
      }
    ],
    "warnings": [
      "string"
    ],
    "info": [
      "string"
    ]
  }
}

Plan a customer customization schema change

Authorization

Request Body

Response Body

200application/json

422application/json

`application/json`

`application/json`