Create or replace an automatic promotion rule

UPSERTS one automatic promotion rule by id: there is no separate create and update, and no PATCH. Posting an existing id REPLACES that rule wholesale — every field not in your body is destroyed, including the reward mechanics. DANGER: the API exposes NO read-modify-write path for a rule. The only reads (GET /v1/promotions, GET /v1/promotions/{id}) return a six-field directory projection with no mechanics in it, so you CANNOT fetch a live rule, edit one field and post it back. Call this only when you already hold the rule’s complete definition — because you are creating it now, or because the caller supplied every field. If you were asked to tweak an existing promotion (extend a window, change a percentage) and you do not have its full mechanics, STOP and ask; do not reconstruct plausible values to satisfy the schema, as that silently overwrites a live pricing rule. Pick the type by the mechanic you want: bogo (buy buyQuantity of buySkuId, get getQuantity of getSkuId at getDiscountBps off — 10000 bps makes it free), threshold (once skuId reaches minQuantity units, a percent or flat reward comes off that SKU’s subtotal) or bundle (buy the components together and pay bundlePriceCents). Money is integer CENTS and percentages are BASIS POINTS (1000 = 10%). validFrom/validUntil are inclusive ISO-8601 instants (Z or a UTC offset) and validUntil must not precede validFrom. Use this for an always-on offer any matching basket earns; use POST /v1/coupons instead when the reduction must be unlocked by a code the customer presents.