> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt ## Resource: Recipe: Apply Shipping Recommendations ## Article: Recipe: Apply Shipping Recommendations ## Article Link: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/recipe-apply-shipping-recommendations.md ## Article Content: # Apply Shipping Recommendations ## Prerequisites - Wix Stores (or another eCommerce business solution) installed on the site - Shipping recommendations data available (from the AI recommendation system or provided directly) ## Required APIs - [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/query-delivery-profiles.md) - [Get Delivery Profile](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/get-delivery-profile.md) --- ## Step 1: Query the current shipping configuration Call [Query Delivery Profiles](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/query-delivery-profiles.md) to understand the site's delivery setup — profiles, regions, carriers, and backup rates. **Endpoint**: `POST https://www.wixapis.com/ecom/v1/delivery-profiles/query` **Request**: ```json { "query": { "cursorPaging": { "limit": 100 } } } ``` **Response**: ```json { "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": [] } ] } ], "revision": "43", "createdDate": "2025-10-26T11:05:10.774Z", "updatedDate": "2026-04-14T14:43:25.397Z" } ], "pagingMetadata": { "count": 1, "cursors": {}, "hasNext": false } } ``` Save the profile `id`, `revision`, and each region's `id` and `active` status. Identify which regions have carriers with missing backup rates (`backupRate` absent or `backupRate.active: false`). --- ## Step 2: Query existing shipping options **Endpoint**: `POST https://www.wixapis.com/ecom/v1/shipping-options/query` **Request**: ```json { "query": { "cursorPaging": { "limit": 100 } } } ``` **Response**: ```json { "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 } } ``` Note: The response uses `deliveryRegionId` (singular) as the primary field linking an option to a region. --- ## Step 3: Apply recommendation — Create a new shipping option When the recommendation action is `create_shipping_option`, create a new option linked to a specific delivery region. **Endpoint**: `POST https://www.wixapis.com/ecom/v1/shipping-options` **Request** — flat rate example: ```json { "shippingOption": { "title": "Express Shipping", "estimatedDeliveryTime": "1-2 business days", "deliveryRegionId": "42b0ed3b-fc54-4ac0-89cf-5d2d17ec441c", "rates": [ { "amount": "12.99", "multiplyByQuantity": false, "conditions": [] } ] } } ``` **Response**: ```json { "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": "Express Shipping", "estimatedDeliveryTime": "1-2 business days", "rates": [ { "amount": "12.99", "conditions": [], "multiplyByQuantity": false } ] } } ``` **Request** — free shipping with price threshold: ```json { "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": "75" } ] } ] } } ``` **Key field rules:** | Field | Required | Notes | |---|---|---| | `title` | Yes | Display name at checkout | | `estimatedDeliveryTime` | Yes | Free text shown to customers | | `deliveryRegionId` | Yes | Region UUID from Step 1. Must use **singular** field, not `deliveryRegionIds` | | `rates` | Yes | Array of rate objects | | `rates[].amount` | Yes | Decimal string (`"5.99"`, `"0"` for free) | | `rates[].multiplyByQuantity` | Yes | Almost always `false` | | `rates[].conditions` | Yes | Empty array for flat rate; see condition types below | **Condition types** (for tiered/conditional rates): | Type | Description | Example | |---|---|---| | `BY_TOTAL_PRICE` | Cart total threshold | `"operator": "GTE", "value": "75"` | | `BY_TOTAL_WEIGHT` | Weight threshold | `"operator": "LTE", "value": "10"` | | `BY_TOTAL_QUANTITY` | Item count threshold | `"operator": "GTE", "value": "3"` | Operators: `EQ`, `GT`, `GTE`, `LT`, `LTE` --- ## Step 4: Apply recommendation — Update an existing shipping option When the recommendation action is `update_shipping_option`, update an existing option's title, delivery time, or rates. **Endpoint**: `PATCH https://www.wixapis.com/ecom/v1/shipping-options/{shippingOptionId}` Replace `{shippingOptionId}` with the option's `id` from Step 2. **Request**: ```json { "shippingOption": { "id": "c0e5be8f-5266-4720-a732-5f571e4750db", "revision": "1", "title": "Updated Standard Shipping", "estimatedDeliveryTime": "3-5 business days", "rates": [ { "amount": "9.99", "multiplyByQuantity": false, "conditions": [] } ] } } ``` **Response**: ```json { "shippingOption": { "id": "c0e5be8f-5266-4720-a732-5f571e4750db", "revision": "2", "createdDate": "2026-04-14T14:43:24.804Z", "updatedDate": "2026-04-15T13:14:13.716Z", "deliveryRegionId": "42b0ed3b-fc54-4ac0-89cf-5d2d17ec441c", "deliveryRegionIds": [], "title": "Updated Standard Shipping", "estimatedDeliveryTime": "3-5 business days", "rates": [ { "amount": "9.99", "conditions": [], "multiplyByQuantity": false } ] } } ``` The `revision` field is required and must match the current revision. The response returns the incremented revision. --- ## Step 5: Verify the changes After applying recommendations, query shipping options again (Step 2) to confirm the changes took effect. Verify: - New options appear in the list with the correct title, rates, and region link - Updated options reflect the new values and incremented revision - The option is linked to the correct `deliveryRegionId` --- ## Error Handling | 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 | ## References - [Delivery Profiles API](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/delivery-profiles/introduction.md) - [Shipping Options API](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery/shipping-options/introduction.md)