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. Never assume a simplified form. Each discount entry looks like:

When updating a rule, always use the discounts array 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.

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 array
2. Modify only the discount.percentage inside each discount 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 array from the query response and update only discount.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

Settings

All recommendation-created rules use these fixed settings:

Error Handling

References

• Discount Rules API
• Coupons API