Setup Discount Rules

Prerequisites

• Wix Stores (or another eCommerce business solution) installed on the site
• At least one product in the catalog

Required APIs

• Create Discount Rule
• Get Discount Rule
• Query Discount Rules
• Update Discount Rule
• Delete Discount Rule

Critical: discounts structure

The API always returns the full normalized structure, values wrapper included. Never assume a simplified form. Each entry of discounts.values looks like:

When updating a rule, always reuse the discounts.values entries as returned from the query/get, modifying only the specific fields you need. Do not reconstruct from scratch unless creating a new rule.

Step 1: Query existing discount rules

Endpoint: POST https://www.wixapis.com/ecom/v1/discount-rules/query

Request — list all rules:

Request — find by name (exact match):

Filterable fields: id, name, active, revision, created_date, updated_date, active_time_info.start, active_time_info.end

Response:

Note existing rules and their scopes to avoid stacking conflicts.

Guardrails — run before creating or updating any discount

These checks guard every discount creation (rule or coupon). Run them before the create/update calls below. User input overrides all caps — if the merchant explicitly asks for a value beyond a threshold, honor it and document the override in your reasoning.

Conflict / stacking (uses the Step 1 query of active rules; for coupons, also query active coupons):

• Same-scope overlap — a new rule conflicts with an existing active rule when scopes overlap (both CATALOG; CATALOG vs COLLECTION; same COLLECTION/SPECIFIC_PRODUCTS id). Wix stacks automatic rules → warn and offer to deactivate the existing one.
• Time overlap — overlapping activeTimeInfo on the same scope (existingStart < newEnd AND existingEnd > newStart) → warn about the overlap window.
• Cross-mechanism (automatic + coupon) — automatic discounts and coupons both apply at checkout. If creating a rule, query active coupons on overlapping scope (and vice-versa); warn with the combined effective discount. (Only one coupon per checkout, but automatic rules are unlimited.)

Margin / sanity:

• Global cap — default max discount 25%; flag anything higher (proceed only on explicit request).
• Minimum margin — default floor 15%; if cost data is available, effective_margin = (price − cost − discount_amount) / price × 100 must stay ≥ 15% (block + explain otherwise).
• % sanity — > 50% warn (show a $100 → $(100−pct) example); = 100% block unless confirmed ("makes the product free"); > 100% always block.
• Stacking margin — when a new discount overlaps existing active ones, evaluate the combined discount against the cap and margin floor, not just the new one in isolation.

When a discount isn't applying as expected, see Troubleshoot: Discount Not Applying.

Step 2: Create a percentage discount rule

Endpoint: POST https://www.wixapis.com/ecom/v1/discount-rules

Request — 20% off all products:

Request — 15% off a specific collection:

Step 3: Create a fixed-amount discount rule

Request — $5 off specific products:

Step 4: Update a discount rule

Always fetch the rule first (via Get or Query), then modify only the fields you need. The mask field tells the API which fields to update — omit it to replace all writable fields.

Endpoint: PATCH https://www.wixapis.com/ecom/v1/discount-rules/{discountRule.id}

Required: discountRule.id, discountRule.revision (must match current revision)

Request — change percentage on an existing rule (full discounts replacement):

Request — change only active status (field mask for partial update):

Step 5: Find by name and update (complete pattern)

The safe pattern for "find a rule by name and update its percentage":

1. Query with name filter → get the rule's id, revision, and discounts.values entries
2. Modify only percentage on each entry, keeping all other fields intact
3. PATCH with the modified discounts and mask: { paths: ["discounts"] }

Step 5a — Query by name:

Extract from response: discountRules[0].id, discountRules[0].revision, discountRules[0].discounts

Step 5b — Update percentage (modify the returned discounts in-place):

Take the discounts.values entries from the query response and update only percentage on each entry:

Step 6: Deactivate or delete a discount rule

To deactivate without deleting:

To delete permanently:

Endpoint: DELETE https://www.wixapis.com/ecom/v1/discount-rules/{discountRuleId}

Key field rules

Scope types

Store catalog app ID (required in all scopes): 215238eb-22a5-4c36-9e7b-e7c08025e04e

Recommendation → API Mapping

When creating a discount rule from a recommendation output, use this mapping to convert the recommendation's simplified JSON into the actual Discount Rules API payload.

Constants

• Store catalog app ID: 215238eb-22a5-4c36-9e7b-e7c08025e04e — used in all scope constructions below.
• Initial state: Recommendations create rules as active: false with status: "PENDING". The merchant must approve before the rule goes live.

Scope mapping

The recommendation's scope field maps to the API's internal scope structure. The scope ID uses a prefix convention:

Example — SITE scope:

Example — ITEMS scope (with product IDs):

Example — CATEGORY scope (with collection IDs):

Discount type mapping

All discount entries use targetType: "SPECIFIC_ITEMS" with the scope wrapped in specificItemsInfo.scopes[].

Trigger mapping (conditions)

Triggers determine WHEN the discount activates. They are built from the recommendation's conditions fields. If no conditions exist (both minSubTotal and minItemQuantity are 0), do NOT set a trigger — the discount applies unconditionally.

Example — minSubTotal trigger (upsell boost: spend $200+):

Example — minItemQuantity trigger (bundle: buy 3+):

Example — AND trigger (both conditions):

Date handling

Error Handling

References

• Discount Rules API
• Coupons API