/wix-manage

API: Shipping Delivery

Two services govern the shipping configuration of a Wix eCommerce store:

• Delivery Profiles — define geographic regions and which carriers serve each region. Each site has a default profile. Regions contain destinations (countries/subdivisions) and carriers.
• Shipping Options — define the rate entries customers see at checkout (flat, tiered, free). Each option is scoped to one or more delivery regions.

Base URL: https://www.wixapis.com/ecom

Shipping Options

Query Shipping Options

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 }
}

Create Shipping Option

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 deliveryRegionId when linking an option to one region. Passing a single region in the plural deliveryRegionIds field returns deliveryRegionId 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.

Get Shipping Option

Retrieves a single shipping option by ID.

Endpoint: GET https://www.wixapis.com/ecom/v1/shipping-options/{shippingOptionId}

Response: { "shippingOption": { ... } }

Update Shipping Option

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.

Delete Shipping Option

Permanently deletes a shipping option.

Endpoint: DELETE https://www.wixapis.com/ecom/v1/shipping-options/{shippingOptionId}

Add Delivery Region (to Shipping Option)

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"
}

Remove Delivery Region (from Shipping Option)

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 Configuration

Rate types are determined by the conditions array, not an explicit field:

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.

Delivery Profiles

Query Delivery Profiles

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": []
            }
          ]
        }
      ]
    }
  ]
}

Get Delivery Profile

Retrieves a single delivery profile by ID.

Endpoint: GET https://www.wixapis.com/ecom/v1/delivery-profiles/{deliveryProfileId}

Response: { "deliveryProfile": { ... } }

Get Delivery Profile by Region

Retrieves the profile that contains a given delivery region.

Endpoint: GET https://www.wixapis.com/ecom/v1/delivery-profiles/delivery-regions/{deliveryRegionId}

Create Delivery Profile

Creates a new delivery profile (rarely needed — most sites use the default profile).

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

Update Delivery Profile

Updates profile-level fields (name, etc.). Requires current revision.

Endpoint: PATCH https://www.wixapis.com/ecom/v1/delivery-profiles/{deliveryProfile.id}

Add Delivery Region

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.

Update Delivery Region

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}

Remove Delivery Region

Removes a delivery region from a profile.

Endpoint: DELETE https://www.wixapis.com/ecom/v1/delivery-profiles/{deliveryProfileId}/delivery-region/{deliveryRegionId}

List Installed Delivery Carriers

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
    }
  ]
}

List Delivery Carriers (in a Profile)

Lists the carriers configured within a specific delivery profile.

Endpoint: POST https://www.wixapis.com/ecom/v1/delivery-profiles/{deliveryProfileId}/delivery-carriers

Add Delivery Carrier

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:

Remove Delivery Carrier

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"
}

Update Delivery Carrier

Updates backupRate or additionalCharges for a carrier in a region.

Endpoint: PATCH https://www.wixapis.com/ecom/v1/delivery-profiles/update-delivery-carrier

Set Delivery Carrier Active Status

Activates or deactivates a carrier in a delivery region.

Endpoint: POST https://www.wixapis.com/ecom/v1/delivery-profiles/delivery-carriers/set-active-status

Known Carrier IDs