In This Article

Apply Shipping Recommendations

Download skillThe skill is a reference md and part of wix-manage skill. You can use the following command to add the full wix-manage skill to your project:

Copy

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

Step 1: Query the current shipping configuration

Call Query Delivery Profiles 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:

Copy

Response:

Copy

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:

Copy

Response:

Copy

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:

Copy

Response:

Copy

Request — free shipping with price threshold:

Copy

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:

Copy

Response:

Copy

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

Did this help?