promotion.create
Create a promotion (born a draft unless status=active). The class is DERIVED from the benefit — never sent. store_id confines it to ONE store; absent = the whole tenant.
- Scope:
promotion.write - System: no
- Reachable from:
POST /v1/commands/promotion.create(tenant credential) · MCP toolpromotion.create· SDKclient.call('promotion.create', …) - Events:
promotion.created
Input (JSON Schema)
Section titled “Input (JSON Schema)”{ "properties": { "benefit": { "oneOf": [ { "properties": { "kind": { "const": "percentage", "type": "string" }, "max_discount_amount": { "anyOf": [ { "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, { "type": "null" } ] }, "percent_bp": { "maximum": 10000, "minimum": 1, "type": "integer" }, "scope": { "default": "each_item", "enum": [ "each_item", "whole_line" ], "type": "string" } }, "required": [ "kind", "percent_bp" ], "type": "object" }, { "properties": { "amount": { "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, "kind": { "const": "fixed_amount", "type": "string" } }, "required": [ "kind", "amount" ], "type": "object" }, { "properties": { "kind": { "const": "free_shipping", "type": "string" }, "max_covered_amount": { "anyOf": [ { "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, { "type": "null" } ] }, "shipping_method_ids": { "default": [], "items": { "minLength": 1, "type": "string" }, "type": "array" } }, "required": [ "kind" ], "type": "object" }, { "properties": { "buy_qty": { "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, "discount_bp": { "default": 10000, "maximum": 10000, "minimum": 1, "type": "integer" }, "get_qty": { "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, "kind": { "const": "bxgy", "type": "string" }, "max_repeats": { "anyOf": [ { "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, { "type": "null" } ] } }, "required": [ "kind", "buy_qty", "get_qty" ], "type": "object" }, { "properties": { "items": { "items": { "properties": { "qty": { "default": 1, "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, "sku_id": { "minLength": 1, "type": "string" } }, "required": [ "sku_id" ], "type": "object" }, "minItems": 1, "type": "array" }, "kind": { "const": "gift", "type": "string" }, "mode": { "default": "automatic", "enum": [ "automatic", "offered" ], "type": "string" }, "out_of_stock_policy": { "default": "skip", "enum": [ "skip", "apply_anyway" ], "type": "string" } }, "required": [ "kind", "items" ], "type": "object" } ] }, "conditions": { "default": [], "items": { "oneOf": [ { "properties": { "amount": { "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, "base": { "default": "after", "enum": [ "before", "after" ], "type": "string" }, "kind": { "const": "min_subtotal", "type": "string" } }, "required": [ "kind", "amount" ], "type": "object" }, { "properties": { "kind": { "const": "min_quantity", "type": "string" }, "qty": { "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" } }, "required": [ "kind", "qty" ], "type": "object" }, { "properties": { "kind": { "const": "payment_method", "type": "string" }, "methods": { "items": { "enum": [ "pix", "card", "promissory", "zero" ], "type": "string" }, "minItems": 1, "type": "array" } }, "required": [ "kind", "methods" ], "type": "object" }, { "properties": { "kind": { "const": "first_purchase", "type": "string" } }, "required": [ "kind" ], "type": "object" }, { "properties": { "kind": { "const": "cart_contains", "type": "string" }, "product_ids": { "items": { "minLength": 1, "type": "string" }, "minItems": 1, "type": "array" } }, "required": [ "kind", "product_ids" ], "type": "object" }, { "properties": { "field": { "enum": [ "name", "email", "created_at" ], "type": "string" }, "kind": { "const": "customer_attribute", "type": "string" }, "operator": { "enum": [ "eq", "before", "after" ], "type": "string" }, "value": { "minLength": 1, "type": "string" } }, "required": [ "kind", "field", "operator", "value" ], "type": "object" }, { "properties": { "field": { "minLength": 1, "type": "string" }, "kind": { "const": "customer_field", "type": "string" }, "operator": { "enum": [ "eq", "neq", "in" ], "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "items": { "type": "string" }, "type": "array" } ] } }, "required": [ "kind", "field", "operator", "value" ], "type": "object" }, { "properties": { "cluster_id": { "minLength": 1, "type": "string" }, "kind": { "const": "customer_in_cluster", "type": "string" } }, "required": [ "kind", "cluster_id" ], "type": "object" } ] }, "type": "array" }, "ends_at": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "label": { "maxLength": 200, "minLength": 1, "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "type": "string" }, "per_customer_limit": { "anyOf": [ { "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, { "type": "null" } ] }, "show_progress": { "default": false, "type": "boolean" }, "stackable": { "default": false, "type": "boolean" }, "starts_at": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "type": "string" }, { "type": "null" } ] }, "status": { "default": "draft", "enum": [ "draft", "active" ], "type": "string" }, "store_id": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ] }, "target": { "default": { "kind": "all" }, "oneOf": [ { "properties": { "kind": { "const": "all", "type": "string" } }, "required": [ "kind" ], "type": "object" }, { "properties": { "kind": { "const": "products", "type": "string" }, "product_ids": { "items": { "minLength": 1, "type": "string" }, "minItems": 1, "type": "array" } }, "required": [ "kind", "product_ids" ], "type": "object" }, { "properties": { "kind": { "const": "skus", "type": "string" }, "sku_ids": { "items": { "minLength": 1, "type": "string" }, "minItems": 1, "type": "array" } }, "required": [ "kind", "sku_ids" ], "type": "object" }, { "properties": { "category_ids": { "items": { "minLength": 1, "type": "string" }, "minItems": 1, "type": "array" }, "kind": { "const": "categories", "type": "string" } }, "required": [ "kind", "category_ids" ], "type": "object" }, { "properties": { "brand_ids": { "items": { "minLength": 1, "type": "string" }, "minItems": 1, "type": "array" }, "kind": { "const": "brands", "type": "string" } }, "required": [ "kind", "brand_ids" ], "type": "object" }, { "properties": { "collection_ids": { "items": { "minLength": 1, "type": "string" }, "minItems": 1, "type": "array" }, "kind": { "const": "collections", "type": "string" } }, "required": [ "kind", "collection_ids" ], "type": "object" } ] }, "trigger": { "default": "automatic", "enum": [ "automatic", "coupon" ], "type": "string" }, "usage_limit": { "anyOf": [ { "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, { "type": "null" } ] } }, "required": [ "name", "label", "benefit" ], "type": "object"}Result (200)
Section titled “Result (200)”{ "additionalProperties": false, "properties": { "promotion_id": { "type": "string" } }, "required": [ "promotion_id" ], "type": "object"}Errors
Section titled “Errors”validation_failed (400) · unauthorized (401) · forbidden (403) · conflict (409) · internal (500)