Upsert sales rule
Preview documentation / simulated contract (draft). Schemas and examples reflect the planned Commerce API v1 — final values will be confirmed when the production contract is frozen.
PUT /sales-rules/{externalRuleId}
Description
replacement/upsell/cross-sell/quantity/price constraint. Base URL: https://api.callbotagent.ai/api/v1/commerce.
Required scope
rules:write
Headers
| Header | Value | Required |
|---|---|---|
Content-Type |
application/json (gdy body) |
when body present |
X-CBA-Key-Id |
key identifier (in examples: cba_test_••••••••) |
yes |
X-CBA-Timestamp |
RFC 3339 UTC | yes |
X-CBA-Nonce |
unique nonce within the 300 s window | yes |
X-CBA-Content-SHA256 |
SHA-256 hex surowego body (e3b0c44… dla pustego) |
yes |
X-CBA-Signature |
hmac-sha256=<hex> |
yes |
Idempotency-Key |
idempotency key | mutations: yes |
Example request
curl -X PUT https://api.callbotagent.ai/api/v1/commerce/sales-rules/RULE-UPSELL-01 \
-H "X-CBA-Key-Id: cba_test_••••••••" \
-H "X-CBA-Timestamp: 2026-07-11T10:00:00Z" \
-H "X-CBA-Nonce: n_8f3a2c1b" \
-H "X-CBA-Content-SHA256: <sha256-body>" \
-H "X-CBA-Signature: hmac-sha256=<hex>" \
-H "Idempotency-Key: idem-sales-rules-externalRuleId-put" \
-H "Content-Type: application/json" \
-d '{"rule_type":"upsell","priority":10,"enabled":true,"applies_to":{"category":"sieci/routery"},"action":{"suggest_variant":"SKU-ROUTER-01-PRO","max_quantity":3},"source_version":"2026-07-11T09:00:00Z"}'const res = await fetch("https://api.callbotagent.ai/api/v1/commerce/sales-rules/RULE-UPSELL-01", {
method: "PUT",
headers: {
"X-CBA-Key-Id": "cba_test_••••••••",
"X-CBA-Timestamp": "2026-07-11T10:00:00Z",
"X-CBA-Nonce": "n_8f3a2c1b",
"X-CBA-Content-SHA256": "<sha256-body>",
"X-CBA-Signature": "hmac-sha256=<hex>",
"Idempotency-Key": "idem-sales-rules-externalRuleId-put",
"Content-Type": "application/json",
},
body: JSON.stringify({"rule_type":"upsell","priority":10,"enabled":true,"applies_to":{"category":"sieci/routery"},"action":{"suggest_variant":"SKU-ROUTER-01-PRO","max_quantity":3},"source_version":"2026-07-11T09:00:00Z"}),
});
const data = await res.json();Example response
{
"external_rule_id": "RULE-UPSELL-01",
"outcome": "upserted",
"enabled": true
}
Possible errors
| Status | code |
Meaning |
|---|---|---|
| 401 | invalid_signature / expired_timestamp / replay_nonce |
HMAC / replay window |
| 403 | insufficient_scope |
missing required scope |
| 404 | resource_not_found |
resource unavailable for principal |
| 409 | idempotency_key_reused / stale_source_version |
idempotency / version conflict |
| 422 | validation_failed |
body does not match schema / invariants |
| 429 | rate_limited |
limits — see Retry-After |