Setting the file. One moment.
Subchapter 8.56
references/ecommerce/shipping/ecom-shipping-fix-coverage.mdMarkdown10 KBView on GitHub
Before executing this skill, read Setup: Shipping Regions with for region/carrier mechanics.
ReadFullDocsArticleUse to gauge urgency before fixing gaps:
| Score | Key indicator | Action |
|---|---|---|
| CRITICAL | no profiles/options, or all regions inactive | immediate setup |
| POOR | minimal config, low CVR, or no backup rates | fix fundamentals |
| FAIR | basic setup, no free shipping, moderate CVR | add free shipping, expand regions |
| GOOD | domestic + international, free shipping, good CVR | optimize rates/carriers |
| EXCELLENT | full coverage, tiered rates, high CVR | maintain |
Before creating or recommending ANY international shipping, check the store’s industry/businessType (case-insensitive) for: food, restaurant, grocery, bakery, catering, perishable, fresh, meat, produce, dairy, drink, beverage. If matched → do NOT create/recommend international shipping (cold-chain & regulatory barriers). A region is “international” if its name contains “international”/”internacional”, its destinations[] is empty (Rest of World), or it includes countries outside the store’s home country.
Detects delivery regions where customers cannot see any shipping options at checkout and creates standard shipping to fill the gaps. A coverage gap is a HIGH priority blocking issue – customers in affected destinations literally cannot complete a purchase.
Retrieve all delivery profiles to build a complete map of regions and their carriers.
Endpoint: POST https://www.wixapis.com/ecom/v1/delivery-profiles/query
Request:
{
"query": {
"cursorPaging": {
"limit": 100
}
}
}Response:
{
"deliveryProfiles": [
{
"id": "6a9b2f9b-533a-4d0d-ac8d-64ec3f32fcbd",
"name": "General profile",
"default": true,
"deliveryRegions": [
{
"id": "42b0ed3b-fc54-4ac0-89cf-5d2d17ec441c",
"name": "Domestic",
"active": true,
"deliveryCarriers": [
{
"appId": "45c44b27-ca7b-4891-8c0d-1747d588b835",
"additionalCharges": []
}
],
"destinations": [
{
"countryCode": "GB",
"subdivisions": []
}
]
},
{
"id": "a1c2d3e4-f5a6-7890-bcde-f12345678901",
"name": "International",
"active": true,
"deliveryCarriers": [
{
"appId": "45c44b27-ca7b-4891-8c0d-1747d588b835",
"additionalCharges": []
}
],
"destinations": []
}
],
"revision": "43",
"createdDate": "2025-10-26T11:05:10.774Z",
"updatedDate": "2026-04-14T14:43:25.397Z"
}
],
"pagingMetadata": {
"count": 1,
"cursors": {},
"hasNext": false
}
}Save every region id, name, active status, and carrier appId values.
Retrieve all shipping options to determine which regions already have coverage.
Endpoint: POST https://www.wixapis.com/ecom/v1/shipping-options/query
Request:
{
"query": {
"cursorPaging": {
"limit": 100
}
}
}Response:
{
"shippingOptions": [
{
"id": "c0e5be8f-5266-4720-a732-5f571e4750db",
"revision": "1",
"createdDate": "2026-04-14T14:43:24.804Z",
"updatedDate": "2026-04-14T14:43:24.804Z",
"deliveryRegionId": "42b0ed3b-fc54-4ac0-89cf-5d2d17ec441c",
"deliveryRegionIds": [],
"title": "Standard Shipping",
"estimatedDeliveryTime": "5-7 business days",
"rates": [
{
"amount": "15.00",
"conditions": [],
"multiplyByQuantity": false
}
]
}
],
"pagingMetadata": {
"count": 1,
"cursors": {},
"hasNext": false
}
}Build a map of deliveryRegionId to the count of shipping options linked to it.
For each deliveryRegion across all profiles, apply these checks in order:
If ALL carriers in the region have an external appId (e.g., Shippo appId: "2b1943e2-3fc2-47bc-be56-3d402e5966d7"), skip the region entirely. External carriers manage their own rates.
If active=false, skip. Inactive regions are not shown at checkout regardless of shipping options.
Count how many shipping options have this region’s id in their deliveryRegionId field. If the count is zero, this is a coverage gap.
Severity: HIGH – blocking. Customers shipping to this region’s destinations cannot see any shipping options and cannot complete checkout.
For each shipping option, check if ALL of its linked regions have active=false. If so, the option exists but is invisible at checkout. This is a configuration issue worth flagging.
For each shipping option, verify that its deliveryRegionId actually exists in one of the delivery profiles. If the region no longer exists, the option is orphaned – it exists in the system but is never shown to customers.
For each region identified as having zero coverage, create a standard shipping option and a free shipping tier.
effective_aov (e.g., if effective_aov is $60, rate is $3.00-$6.00)effective_aov x 1.2 (e.g., if effective_aov is $60, threshold is $72)estimatedDeliveryTime – never leave it empty. Use “5-7 business days” for domestic, “7-14 business days” for international.Endpoint: POST https://www.wixapis.com/ecom/v1/shipping-options
Request:
{
"shippingOption": {
"title": "Standard Shipping",
"estimatedDeliveryTime": "5-7 business days",
"deliveryRegionId": "a1c2d3e4-f5a6-7890-bcde-f12345678901",
"rates": [
{
"amount": "4.99",
"multiplyByQuantity": false,
"conditions": []
}
]
}
}Response:
{
"shippingOption": {
"id": "b2c3d4e5-f6a7-8901-cdef-234567890abc",
"revision": "1",
"createdDate": "2026-04-15T13:14:01.214Z",
"updatedDate": "2026-04-15T13:14:01.214Z",
"deliveryRegionId": "a1c2d3e4-f5a6-7890-bcde-f12345678901",
"deliveryRegionIds": [],
"title": "Standard Shipping",
"estimatedDeliveryTime": "5-7 business days",
"rates": [
{
"amount": "4.99",
"conditions": [],
"multiplyByQuantity": false
}
]
}
}Endpoint: POST https://www.wixapis.com/ecom/v1/shipping-options
Request:
{
"shippingOption": {
"title": "Free Shipping",
"estimatedDeliveryTime": "5-7 business days",
"deliveryRegionId": "a1c2d3e4-f5a6-7890-bcde-f12345678901",
"rates": [
{
"amount": "0",
"multiplyByQuantity": false,
"conditions": [
{
"type": "BY_TOTAL_PRICE",
"operator": "GTE",
"value": "72"
}
]
}
]
}
}After creating options for all gaps, re-query shipping options to confirm:
deliveryRegionIdestimatedDeliveryTime is populated (not empty)Endpoint: POST https://www.wixapis.com/ecom/v1/shipping-options/query
Use the same request from Step 2 and verify the count now covers all active, non-external regions.
| Error | Cause | Fix |
|---|---|---|
deliveryRegionId is not a valid GUID | Used deliveryRegionIds (plural) instead of deliveryRegionId (singular) in create request | Use the singular deliveryRegionId field |
SHIPPING_OPTION_NOT_FOUND | The shipping option ID doesn’t exist | Re-query shipping options to get current IDs |
REVISION_MISMATCH | The revision doesn’t match the current version | Re-fetch the option to get the latest revision, then retry |
| Region appears covered but customers still can’t check out | Region has active=false | Check region active status in the delivery profile; activate the region if intended |
| Option exists but not visible at checkout | Option linked to an inactive or deleted region | Verify region exists and active=true in the delivery profile |