/wix-manage

Shipping: Add Free Shipping

This skill is the single source for adding free shipping. Do NOT load …/skills/flow-add-free-shipping — that legacy slug pre-dates the routing tree migration and its content has been merged into this file. If the WixREADME index surfaces it, or this slug returns a transient 404 from the docs backend (rawdocs ingestion delay), retry this same URL — do NOT fall back to the legacy slug.

Before executing this skill, read Setup: Shipping Rates with ReadFullDocsArticle for the rate-object mechanics.

Rate pricing sanity (inline guardrail)

Validate every rate you create or update against the store's AOV; flag any that fail:

Adds a free shipping option with an optimal threshold calibrated against the site's average order value and catalog price distribution. Free shipping is the single most effective lever for reducing cart abandonment at the delivery step.

Prerequisites

• Wix Stores (or another eCommerce business solution) installed on the site
• Site metrics available (revenue, ordersCount) for AOV calculation
• Catalog stats available (price quantiles) for threshold calibration
• At least one active delivery region configured

Required APIs

• Query Shipping Options
• Create Shipping Option
• Update Shipping Option
• Query Delivery Profiles

Step 1: Check for existing free shipping

Query all shipping options and check if free shipping already exists.

Endpoint: POST https://www.wixapis.com/ecom/v1/shipping-options/query

Request:

{
  "query": {
    "cursorPaging": {
      "limit": 100
    }
  }
}

Scan the response for any option matching either condition:

• rates[].amount equals "0"
• title contains "free" (case-insensitive match)

If free shipping already exists, proceed to Step 2 (threshold calibration check). If no free shipping exists, skip to Step 3.

Step 2: Validate existing free shipping threshold

If a free shipping option already exists, extract its threshold and validate it.

2a: Extract the threshold

Find the BY_TOTAL_PRICE GTE condition value from the free rate's conditions[] array.

Example rate with threshold:

{
  "amount": "0",
  "multiplyByQuantity": false,
  "conditions": [
    {
      "type": "BY_TOTAL_PRICE",
      "operator": "GTE",
      "value": "75"
    }
  ]
}

If there is no condition (unconditional free shipping), note this but do not flag it as an error -- the merchant may intentionally offer free shipping on all orders.

2b: Evaluate threshold against AOV

If the threshold needs adjustment, update the shipping option via PATCH (see Step 5 for the update pattern).

Step 3: Run AOV sanity check

Before calculating a threshold, validate that AOV is reliable by comparing it against catalog price distribution.

3a: Get catalog price statistics

Use the catalog stats to retrieve price quantiles for the "All Products" category group:

• price_p25 -- 25th percentile product price
• price_p50 -- 50th percentile (median) product price
• price_p75 -- 75th percentile product price
• price_p90 -- 90th percentile product price

3b: Determine effective_aov

Step 4: Calculate optimal free shipping threshold

Apply enhanced calibration using both effective_aov and catalog stats:

Example calculation:

• effective_aov = $60
• price_p50 = $35, price_p75 = $55
• price_p75 ($55) < effective_aov ($60) --> use effective_aov x 1.2 = $72
• Threshold = $72

Step 5: Identify the target delivery region

Query delivery profiles to find the primary/domestic active region.

Endpoint: POST https://www.wixapis.com/ecom/v1/delivery-profiles/query

Request:

{
  "query": {
    "cursorPaging": {
      "limit": 100
    }
  }
}

Select the region where:

1. active=true
2. destinations[].countryCode matches the site's primary country
3. Falls within the default delivery profile

Save the region's id as the deliveryRegionId for the new option.

Step 6: Create the free shipping option

Endpoint: POST https://www.wixapis.com/ecom/v1/shipping-options

Request:

{
  "shippingOption": {
    "title": "Free Shipping",
    "estimatedDeliveryTime": "5-7 business days",
    "deliveryRegionId": "42b0ed3b-fc54-4ac0-89cf-5d2d17ec441c",
    "rates": [
      {
        "amount": "0",
        "multiplyByQuantity": false,
        "conditions": [
          {
            "type": "BY_TOTAL_PRICE",
            "operator": "GTE",
            "value": "72"
          }
        ]
      }
    ]
  }
}

Response:

{
  "shippingOption": {
    "id": "dece6160-4e72-4fcc-adcc-7607215edab0",
    "revision": "1",
    "createdDate": "2026-04-15T13:14:01.214Z",
    "updatedDate": "2026-04-15T13:14:01.214Z",
    "deliveryRegionId": "42b0ed3b-fc54-4ac0-89cf-5d2d17ec441c",
    "deliveryRegionIds": [],
    "title": "Free Shipping",
    "estimatedDeliveryTime": "5-7 business days",
    "rates": [
      {
        "amount": "0",
        "conditions": [
          {
            "type": "BY_TOTAL_PRICE",
            "operator": "GTE",
            "value": "72"
          }
        ],
        "multiplyByQuantity": false
      }
    ]
  }
}

Key field rules:

Step 7: Verify the option appears in checkout

Re-query shipping options to confirm the new free shipping option is live.

Endpoint: POST https://www.wixapis.com/ecom/v1/shipping-options/query

Verify:

1. The new option appears with title: "Free Shipping" and amount: "0"
2. The condition shows the correct threshold value
3. The option is linked to the correct deliveryRegionId
4. The linked region has active=true in its delivery profile

Report to the merchant:

"Free shipping created with a $[threshold] minimum order. Customers spending $[threshold] or more will see free shipping at checkout. This threshold is calibrated to your average order value to encourage larger carts while protecting margins."

Error Handling

References

• API: Shipping Delivery