Commerce definition

apex experiments pull <experiment> writes a top-level commerce.json when the experiment has a canonical commerce definition. plan shows both the definition change and its derived checkout carriers, warnings, and commerce launch preview. apply validates and saves the definition and sibling variation files together.

{
  "revision": 7,
  "definition": {
    "schemaVersion": 2,
    "baseCurrency": "EUR",
    "versions": { "control": "control", "order": ["control", "sale"] },
    "levers": {}
  },
  "serverOwned": { "readonly": true }
}

Edit definition.levers to change or remove a lever. Keep the positive integer revision from your pull. A stale revision returns 409 commerce_definition_revision_conflict; pull again and reconcile your edit. serverOwned is read-only, ignored on save, and recompiled by the server. Edited server output adds the warning commerce_server_owned_ignored.

apex commerce definition get <experiment> [file]
apex commerce definition put <experiment> <file>
apex commerce definition put <experiment> <file> --create

get writes the same envelope as pull, to the file or stdout. put sends only definition and expectedRevision from the file. --create sends a null revision and refuses if a row already exists. Refused writes print the 409 or 422 error code and any blocking issues.

A legacy definition pulls as { "revision": 7, "legacy": true, "carriers": {} }. It is read-only. Replace the entire envelope with { "revision": 7, "definition": { ... } } to request a validated replacement. Replacement reports legacyReplaced, carriersEqual, and changedCarriers (variation and action). Existing status and representability guards still apply. Deleting commerce.json is refused; remove a lever by omitting it from definition.levers.

For one release, experiments without a definition continue to pull step 1 files under commerce/. Unchanged files stay unchanged. Editing a supported lever file converts the set to a definition, with commerce_files_v1_converted, and creates its row only if none exists. Opaque read-only files cannot be converted. Never mix commerce.json and step 1 price, shipping, offer or post-purchase files. commerce/discount-codes.json stays separate and may coexist with either format.

A price version containing exactly one all-scope integer percent rule from -90 to -1, with no ending or overrides, remains a percent arm. Its charged and displayed price follows the baseline captured at launch. Other price rules compile into fixed prices from the resolved baseline. Unchanged levers preserve their carrier revision, checksum and server-owned launch evidence.