Setting the file. One moment.
Subchapter 8.55
references/ecommerce/shipping/ecom-shipping-api.mdMarkdown11 KBView on GitHub
Two services govern the shipping configuration of a Wix eCommerce store:
Base URL: https://www.wixapis.com/ecom
How to call these APIs: Use CallWixSiteAPI.
Retrieves all shipping options for the site. Up to 1,000 per request (cursor paging).
Endpoint: POST https://www.wixapis.com/ecom/v1/shipping-options/query
Request:
{
"query": {
"cursorPaging": { "limit": 100 }
}
}Filterable fields: id, delivery_region_id, delivery_region_ids, estimated_delivery_time, created_date, updated_date
Response:
{
"shippingOptions": [
{
"id": "abc123",
"revision": "1",
"deliveryRegionId": "region-guid",
"deliveryRegionIds": ["region-guid"],
"title": "Standard Shipping",
"category": "STANDARD",
"estimatedDeliveryTime": "3-5 business days",
"rates": [
{
"id": "rate-guid",
"title": "Standard Shipping",
"amount": "5.99",
"multiplyByQuantity": false,
"active": true,
"conditions": []
}
]
}
],
"pagingMetadata": { "count": 1, "hasNext": false }
}Creates a new shipping option and associates it with one or more delivery regions.
Endpoint: POST https://www.wixapis.com/ecom/v1/shipping-options
Required fields: shippingOption.deliveryRegionId (or deliveryRegionIds), shippingOption.title, shippingOption.rates[]
Gotcha: use the singular
deliveryRegionIdwhen linking an option to one region. Passing a single region in the pluraldeliveryRegionIdsfield returnsdeliveryRegionId is not a valid GUID.
Request:
{
"shippingOption": {
"deliveryRegionId": "region-guid",
"title": "Free Shipping Over $75",
"category": "FREE",
"estimatedDeliveryTime": "5-7 business days",
"rates": [
{
"title": "Free Shipping",
"amount": "0",
"multiplyByQuantity": false,
"active": true,
"conditions": [
{
"type": "BY_TOTAL_PRICE",
"operator": "GTE",
"value": "75"
}
]
}
]
}
}Response: { "shippingOption": { ... } } — the created option with id and revision.
Error: INVALID_QUANTITY_VALUE (400) — condition value cannot be fractional.
Retrieves a single shipping option by ID.
Endpoint: GET https://www.wixapis.com/ecom/v1/shipping-options/{shippingOptionId}
Response: { "shippingOption": { ... } }
Updates a shipping option. Requires id and the current revision. Each update increments revision.
Endpoint: PATCH https://www.wixapis.com/ecom/v1/shipping-options/{shippingOption.id}
Required fields: shippingOption.id, shippingOption.revision
Request:
{
"shippingOption": {
"id": "abc123",
"revision": "1",
"rates": [
{
"id": "rate-guid",
"title": "Free Shipping",
"amount": "0",
"multiplyByQuantity": false,
"active": true,
"conditions": [
{
"type": "BY_TOTAL_PRICE",
"operator": "GTE",
"value": "85"
}
]
}
]
}
}Response: { "shippingOption": { ... } } with updated revision.
Permanently deletes a shipping option.
Endpoint: DELETE https://www.wixapis.com/ecom/v1/shipping-options/{shippingOptionId}
Associates an additional delivery region with an existing shipping option.
Endpoint: POST https://www.wixapis.com/ecom/v1/shipping-options/{shippingOptionId}/add-delivery-region
Required fields: deliveryRegionId, revision
Request:
{
"deliveryRegionId": "region-guid",
"revision": "2"
}Removes a delivery region association from a shipping option.
Endpoint: POST https://www.wixapis.com/ecom/v1/shipping-options/{shippingOptionId}/remove-delivery-region
Required fields: deliveryRegionId, revision
Rate types are determined by the conditions array, not an explicit field:
| Rate Type | amount | conditions |
|---|---|---|
| Flat rate | any | empty [] |
| Free shipping | "0" | optional BY_TOTAL_PRICE GTE <threshold> |
| Price-based tiers | any | one or more BY_TOTAL_PRICE conditions |
| Weight-based tiers | any | BY_TOTAL_WEIGHT conditions |
| Quantity-based | any | BY_TOTAL_QUANTITY conditions |
Condition operators: EQ, GT, GTE, LT, LTE
Multiple conditions in one rate combine with AND logic.
multiplyByQuantity: true charges amount × cart quantity. Flag this configuration — it penalizes large orders and should be replaced with flat or tiered pricing.
Retrieves all delivery profiles for the site. Typically one default profile exists.
Endpoint: POST https://www.wixapis.com/ecom/v1/delivery-profiles/query
Request: {}
Response:
{
"deliveryProfiles": [
{
"id": "profile-guid",
"revision": "3",
"name": "General profile",
"default": true,
"deliveryRegions": [
{
"id": "region-guid",
"name": "United States",
"active": true,
"destinations": [
{ "countryCode": "US", "subdivisions": [] }
],
"deliveryCarriers": [
{
"appId": "45c44b27-ca7b-4891-8c0d-1747d588b835",
"backupRate": {
"title": "Standard Shipping",
"amount": "5.99",
"active": true
},
"additionalCharges": []
}
]
}
]
}
]
}Retrieves a single delivery profile by ID.
Endpoint: GET https://www.wixapis.com/ecom/v1/delivery-profiles/{deliveryProfileId}
Response: { "deliveryProfile": { ... } }
Retrieves the profile that contains a given delivery region.
Endpoint: GET https://www.wixapis.com/ecom/v1/delivery-profiles/delivery-regions/{deliveryRegionId}
Creates a new delivery profile (rarely needed — most sites use the default profile).
Endpoint: POST https://www.wixapis.com/ecom/v1/delivery-profiles
Updates profile-level fields (name, etc.). Requires current revision.
Endpoint: PATCH https://www.wixapis.com/ecom/v1/delivery-profiles/{deliveryProfile.id}
Adds a geographic region to a delivery profile. Returns the updated profile with the new region’s id.
Endpoint: POST https://www.wixapis.com/ecom/v1/delivery-profiles/{deliveryProfileId}/delivery-region
Required fields: deliveryRegion.name, deliveryRegion.destinations[], revision
Request:
{
"deliveryRegion": {
"name": "United States",
"active": true,
"destinations": [
{ "countryCode": "US" }
]
},
"revision": "3"
}Response: { "deliveryProfile": { ... } } — full updated profile with new region id.
Error: DESTINATIONS_COLLISION — country already assigned to another region in this profile. Use the existing region instead.
Updates name, active status, or destinations of an existing region.
Endpoint: PATCH https://www.wixapis.com/ecom/v1/delivery-profiles/{deliveryProfileId}/delivery-region/{deliveryRegion.id}
Removes a delivery region from a profile.
Endpoint: DELETE https://www.wixapis.com/ecom/v1/delivery-profiles/{deliveryProfileId}/delivery-region/{deliveryRegionId}
Returns all carriers installed on the site (both built-in and third-party apps). Use this to find the id of a specific carrier (e.g., Pickup, Basic Shipping) before calling Add Delivery Carrier.
Endpoint: GET https://www.wixapis.com/ecom/v1/delivery-profiles/installed-carriers
Response:
{
"installedDeliveryCarriers": [
{
"id": "50d8c12f-715e-41ad-be25-d0f61375dbee",
"displayName": "Pickup",
"fallbackDefinitionMandatory": false,
"toggleGetCarrierSettingsEnabled": true
},
{
"id": "45c44b27-ca7b-4891-8c0d-1747d588b835",
"displayName": "Basic Shipping",
"description": "Manage shipping rates and options for this region",
"fallbackDefinitionMandatory": false,
"toggleGetCarrierSettingsEnabled": true
}
]
}Lists the carriers configured within a specific delivery profile.
Endpoint: POST https://www.wixapis.com/ecom/v1/delivery-profiles/{deliveryProfileId}/delivery-carriers
Adds a carrier to a delivery region within a profile. The carrier appears as a shipping option to customers in that region.
Endpoint: POST https://www.wixapis.com/ecom/v1/delivery-profiles/add-delivery-carrier
Request:
{
"deliveryRegionId": "region-guid",
"deliveryCarrier": {
"appId": "50d8c12f-715e-41ad-be25-d0f61375dbee",
"backupRate": {
"title": "Pickup at 123 Main St",
"amount": "0",
"active": true
}
}
}Response: { "deliveryProfile": { ... } } — full updated profile.
Errors:
| Error | Cause |
|---|---|
CARRIER_ALREADY_EXISTS_IN_REGION | Carrier already in this region |
DELIVERY_CARRIER_MISSING_BACKUP_RATE | backupRate or backupRate.amount missing |
Removes a carrier from a delivery region.
Endpoint: POST https://www.wixapis.com/ecom/v1/delivery-profiles/remove-delivery-carrier
Request:
{
"deliveryRegionId": "region-guid",
"appId": "carrier-app-id"
}Updates backupRate or additionalCharges for a carrier in a region.
Endpoint: PATCH https://www.wixapis.com/ecom/v1/delivery-profiles/update-delivery-carrier
Activates or deactivates a carrier in a delivery region.
Endpoint: POST https://www.wixapis.com/ecom/v1/delivery-profiles/delivery-carriers/set-active-status
| Carrier | App ID |
|---|---|
| Basic Shipping | 45c44b27-ca7b-4891-8c0d-1747d588b835 |
| Pickup | 50d8c12f-715e-41ad-be25-d0f61375dbee |