Removed value: -"UAH"

Previous value: -"ISO 4217 currency code for the order (uppercase, e.g. UAH). Default UAH."New value: +"Required ISO 4217 currency code from the source facts or selected CRM product prices. Never guess or convert between currencies."

Removed value: -{
-  "description": "Money taken off by the promo code, in the order currency. A sum, not a percent: a percent at order level is ambiguous (before or after line discounts, with shipping or without). Does NOT change total — send the total the buyer actually paid.",
-  "minimum": 0,
-  "type": "number"
-}

Removed value: -{
-  "description": "The promo code the storefront applied to this order, recorded as-is. The CRM never validates or computes it — the cart owns that — but storing it is what makes 'did that campaign pay for itself?' answerable later.",
-  "maxLength": 64,
-  "type": "string"
-}

Added value: +{
+  "additionalProperties": false,
+  "description": "Ask the CRM to validate and calculate this promo code. Do not supply promoCode, discountAmount or shippingThresholdAmount alongside it. An optional expectedTotal refuses a changed quote; the server always owns the actual discount.",
+  "properties": {
+    "code": {
+      "description": "CRM-managed promo code, 3–64 letters, digits, hyphens or underscores; case-insensitive. Must be enabled for this connection's source; a personal or capture code also needs the buyer email it was issued to.",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{2,63}$",
+      "type": "string"
+    },
+    "expectedTotal": {
+      "description": "Net merchandise total the buyer was shown, as a decimal string with up to two decimals (for example \"199.90\"), in the order currency. If the CRM now calculates a different amount the request is refused with price_changed.",
+      "pattern": "^\\d{1,10}(?:\\.\\d{1,2})?$",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code"
+  ],
+  "type": "object"
+}

Previous value: -[
-  "externalId",
-  "items"
-]New value: +[
+  "currency",
+  "externalId",
+  "items"
+]

Added value: +{
+  "description": "The carrier's own identifier for the branch or parcel locker, as returned by GET /api/v1/carriers/{carrier}/warehouses. The same value the shipment-label endpoint calls warehouseRef. Sent, this removes all guessing; omitted, the CRM falls back to matching `branch` as text.",
+  "maxLength": 64,
+  "type": "string"
+}

Added value: +{
+  "description": "House number for courier delivery, structured rather than inside the address line because carriers validate it on its own (Nova Poshta accepts up to 11 characters matching digits plus an optional Cyrillic letter or block, e.g. \"12Б\" or \"12/4\").",
+  "maxLength": 35,
+  "type": "string"
+}

Added value: +{
+  "description": "The carrier's own identifier for the destination city, as returned by GET /api/v1/carriers/{carrier}/cities. Required alongside branchRef or streetRef for a waybill to be created from the order alone.",
+  "maxLength": 64,
+  "type": "string"
+}

Added value: +{
+  "description": "Apartment or office number for courier delivery.",
+  "maxLength": 35,
+  "type": "string"
+}

Added value: +{
+  "description": "The carrier's own identifier for the street, as returned by GET /api/v1/carriers/{carrier}/streets. Courier delivery only; pair it with `building`.",
+  "maxLength": 64,
+  "type": "string"
+}

Added value: +{
+  "description": "Money taken off by the promo code, in the order currency. A sum, not a percent: a percent at order level is ambiguous (before or after line discounts, with shipping or without). Does NOT change total — send the total the buyer actually paid.",
+  "minimum": 0,
+  "type": "number"
+}

Added value: +{
+  "description": "The promo code the storefront applied to this order, recorded as-is. The CRM never validates or computes it — the cart owns that — but storing it is what makes 'did that campaign pay for itself?' answerable later.",
+  "maxLength": 64,
+  "type": "string"
+}

Previous value: -"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"New value: +"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"

Added value: +{
+  "additionalProperties": false,
+  "description": "How the buyer asked to receive the order: carrier, branch/courier/pickup, branch text, recipient, cash-on-delivery and a delivery note. This is the buyer's choice at checkout — it does not dispatch anything. Record what actually ships with POST /orders/{externalId}/shipments.",
+  "properties": {
+    "branch": {
+      "description": "Branch or parcel locker as the buyer named it, e.g. \"відділення №5\" or \"поштомат 12345\". Free text: the CRM resolves it against the live branch list of the carrier when creating a waybill.",
+      "maxLength": 200,
+      "type": "string"
+    },
+    "carrier": {
+      "description": "Carrier slug the buyer chose, from GET /capabilities (e.g. \"nova_poshta\", \"ukrposhta\", \"pickup\"). This is a preference, not a dispatch — the shipment endpoint still records what actually ships.",
+      "maxLength": 120,
+      "type": "string"
+    },
+    "cod": {
+      "description": "True when the buyer pays on delivery (cash on delivery).",
+      "type": "boolean"
+    },
+    "comment": {
+      "description": "Delivery note from the buyer, e.g. \"дзвонити після 18:00\". Not the order notes.",
+      "maxLength": 1000,
+      "type": "string"
+    },
+    "method": {
+      "description": "How the parcel reaches the buyer: \"branch\" (carrier office/locker), \"courier\" (to the address) or \"pickup\" (buyer collects from you).",
+      "enum": [
+        "branch",
+        "courier",
+        "pickup"
+      ],
+      "type": "string"
+    },
+    "phone": {
+      "description": "Recipient phone, when it differs from the buyer's own contact phone.",
+      "maxLength": 50,
+      "type": "string"
+    },
+    "recipientName": {
+      "description": "Who receives the parcel, when that is not the buyer (a gift, an office).",
+      "maxLength": 200,
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

Added value: +{
+  "description": "Internal note stored on the order. For a delivery instruction from the buyer use delivery.comment instead.",
+  "maxLength": 5000,
+  "type": "string"
+}

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +"ISO 4217 currency code for the order (uppercase, e.g. UAH). Default UAH."

Added value: +"Optional buyer snapshot (name/email/phone, or a storefront customer externalId). Omit for an anonymous order."

Added value: +"A stable unique id for this order in your system — the idempotency key. Re-sending the same externalId returns the existing order instead of creating a duplicate (e.g. 'mcp-<uuid>')."

Added value: +"Order line items (1-100). Each snapshots productName/sku/unitPrice."

Added value: +"Percentage discount on this line (0-100). Default 0."

Added value: +"Line item name, snapshotted onto the order. Use search_products to quote a real catalog product's name. Required."

Added value: +"Quantity ordered (integer, at least 1)."

Added value: +"Product SKU snapshot (from search_products). Optional."

Added value: +"Price per unit in the order currency, as a decimal (e.g. 199.99). Snapshotted onto the line."