/wix-manage

Pricing: Create Coupon

This skill is the single source for coupon creation. Do NOT load …/skills/setup-coupons — that legacy slug pre-dates the routing tree migration and its content has been merged into this file. If the WixREADME index surfaces it, ignore it.

Prerequisites

• Wix Stores (or another eCommerce business solution) installed on the site

Required APIs

• Create Coupon — POST /v2/coupons
• Update Coupon — PATCH /v2/coupons/{id}
• Query Coupons — POST /v2/coupons/query
• Delete Coupon — DELETE /v2/coupons/{id}

Step 1: Query existing coupons

Before creating a coupon, check for code conflicts and existing promotions on the same scope.

Endpoint: POST https://www.wixapis.com/stores/v2/coupons/query

Request:

{
  "query": {
    "paging": {
      "limit": 100
    }
  }
}

Response:

{
  "coupons": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "specification": {
        "name": "Summer Sale",
        "code": "SUMMER20",
        "percentOffRate": 20,
        "scope": {
          "namespace": "stores"
        },
        "startTime": 1717200000000,
        "expirationTime": 1719792000000,
        "usageLimit": 100,
        "limitPerCustomer": 1,
        "active": true
      },
      "numberOfUsages": 12,
      "expired": false
    }
  ]
}

Check for: duplicate codes, overlapping scopes with active coupons, and cross-mechanism stacking with active automatic discount rules.

Guardrails — run before creating the coupon

• Duplicate / conflicting code — reject a code already in use.
• Cross-mechanism stacking — coupons stack with automatic discount rules at checkout. Query active discount rules on overlapping scope; if found, warn with the combined effective discount ("a 20% coupon during a 20% automatic sale = ~36% off"). Only one coupon applies per checkout, but automatic rules are unlimited.
• % sanity — > 50% warn (show a $100 → $(100−pct) example); = 100% block unless confirmed; > 100% always block.
• Margin — if cost data is available, ensure the discount doesn't push price below cost; otherwise warn for > 40%.
• User override — explicit merchant values override these caps; document the override in your reasoning.

(The automatic-rule side of these checks lives in Create Discount Rule → "Guardrails".)

Step 2: Create a percentage-off coupon

Endpoint: POST https://www.wixapis.com/stores/v2/coupons

Request — 15% off all store products:

{
  "specification": {
    "name": "Spring Sale 15%",
    "code": "SPRING15",
    "percentOffRate": 15,
    "scope": {
      "namespace": "stores"
    },
    "startTime": 1714521600000,
    "usageLimit": 200,
    "limitPerCustomer": 1,
    "active": true
  }
}

Response:

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}

Request — 20% off a specific collection:

{
  "specification": {
    "name": "Electronics Deal",
    "code": "ELEC20",
    "percentOffRate": 20,
    "scope": {
      "namespace": "stores",
      "group": {
        "name": "collection",
        "entityId": "collection-uuid-here"
      }
    },
    "startTime": 1714521600000,
    "expirationTime": 1717200000000,
    "usageLimit": 50,
    "limitPerCustomer": 1,
    "active": true
  }
}

Request — 10% off a specific product:

{
  "specification": {
    "name": "VIP Product Discount",
    "code": "VIP10",
    "percentOffRate": 10,
    "scope": {
      "namespace": "stores",
      "group": {
        "name": "product",
        "entityId": "product-uuid-here"
      }
    },
    "startTime": 1714521600000,
    "limitPerCustomer": 1,
    "active": true
  }
}

Step 3: Create a fixed-amount coupon

Request — $10 off all products:

{
  "specification": {
    "name": "Save $10",
    "code": "SAVE10",
    "moneyOffAmount": 10,
    "scope": {
      "namespace": "stores"
    },
    "startTime": 1714521600000,
    "active": true
  }
}

Step 4: Create a minimum subtotal coupon

Instead of targeting a scope, you can require a minimum cart subtotal. This is a oneOf with scope — you set EITHER scope OR minimumSubtotal, not both.

Request — 15% off orders over $100:

{
  "specification": {
    "name": "Spend $100, Save 15%",
    "code": "SPEND100",
    "percentOffRate": 15,
    "minimumSubtotal": 100,
    "startTime": 1714521600000,
    "usageLimit": 500,
    "limitPerCustomer": 1,
    "active": true
  }
}

Key field rules

Coupon types (oneOf — set exactly one)

Note: Free shipping as an automatic discount rule is NOT supported — use the freeShipping coupon type here, or configure a free-shipping rate via the Shipping Options API.

Scope values for Wix Stores

Recommendation → Coupon API Mapping

When the recommendation output has mechanism: "COUPON", use this mapping to convert it into a Coupons API payload.

Scope mapping

Important limitation: The Coupons API scope supports only one entityId (one product or one collection). If the recommendation targets multiple products or categories:

• For CATEGORY with multiple categoryIds: Create one coupon per collection, or pick the primary collection.
• For ITEMS with multiple productIds: Create one coupon per product, or use minimumSubtotal instead of scope if the intent is cart-level.

Discount type mapping

Condition mapping

Code generation

Full mapping example

Recommendation output:

{
  "mechanism": "COUPON",
  "scope": "CATEGORY",
  "categoryIds": ["electronics-collection-uuid"],
  "name": "Tech Insider Deal",
  "discountType": "PERCENTAGE",
  "discount": 20,
  "code": "TECH20",
  "usageLimit": 100,
  "limitPerCustomer": 1,
  "conditions": {
    "startDate": "2026-06-01",
    "endDate": "2026-06-30"
  }
}

Coupon API request:

{
  "specification": {
    "name": "Tech Insider Deal",
    "code": "TECH20",
    "percentOffRate": 20,
    "scope": {
      "namespace": "stores",
      "group": {
        "name": "collection",
        "entityId": "electronics-collection-uuid"
      }
    },
    "startTime": 1748736000000,
    "expirationTime": 1751328000000,
    "usageLimit": 100,
    "limitPerCustomer": 1,
    "active": true
  }
}

Key differences from Automatic Discounts

Error Handling

References

• Coupons API
• Valid Scope Values