Setting the file. One moment.
Subchapter 8.59
references/ecommerce/shipping/ecom-shipping-setup-pickup.mdMarkdown7 KBView on GitHub
Routing rule: BEFORE taking any action, call
ReadFullDocsArticleon Shipping API Reference. The endpoint shapes for List Installed Delivery Carriers, Query Delivery Profiles, Add Delivery Region, and Add Delivery Carrier all live there. Do NOT call any of these APIs without loading it first.
Call List Installed Delivery Carriers (opens in a new tab) to find the Pickup carrier’s id.
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
}
]
}Look for the carrier with "displayName": "Pickup" and save its id. This is the appId you will use in Step 4.
If no Pickup carrier appears in the list, the Pickup app is not installed on the site and must be installed before proceeding.
Call Query Delivery Profiles (opens in a new tab) to retrieve the site’s default delivery profile.
Endpoint: POST https://www.wixapis.com/ecom/v1/delivery-profiles/query
Request:
{}The response contains an array of deliveryProfiles. Find the one where "default": true. Save its id and revision. Inspect its deliveryRegions array.
Decision point:
destinations[].countryCode): save that region’s id → skip to Step 4.If no region exists for the user’s country in the default profile, call Add Delivery Region (opens in a new tab) to create one.
Endpoint: POST https://www.wixapis.com/ecom/v1/delivery-profiles/{deliveryProfileId}/delivery-region
Replace {deliveryProfileId} with the default profile’s id from Step 2.
Request:
{
"deliveryRegion": {
"name": "US Pickup",
"active": true,
"destinations": [
{
"countryCode": "US"
}
]
},
"revision": "3"
}name: descriptive, e.g. "{Country} Pickup".countryCode: ISO-3166 alpha-2 (opens in a new tab) code (e.g. "US", "IL", "DE", "GB").revision: from the profile returned in Step 2.Response:
{
"deliveryProfile": {
"id": "02625bf4-70b4-49b7-93f0-5c9d72608937",
"name": "General profile",
"default": true,
"deliveryRegions": [
{
"id": "23823d4a-0ad2-4f92-a48a-467497a9470a",
"name": "US Pickup",
"active": true,
"deliveryCarriers": [],
"destinations": [
{
"countryCode": "US",
"subdivisions": []
}
]
}
],
"revision": "4"
}
}Save the new region’s id from the response.
Call Add Delivery Carrier (opens in a new tab) to attach the Pickup carrier to the delivery region.
Endpoint: POST https://www.wixapis.com/ecom/v1/delivery-profiles/add-delivery-carrier
Request:
{
"deliveryRegionId": "<REGION_ID>",
"deliveryCarrier": {
"appId": "50d8c12f-715e-41ad-be25-d0f61375dbee",
"backupRate": {
"title": "Pickup at 123 Main St, New York",
"amount": "0",
"active": true
}
}
}deliveryRegionId: from Step 2 (existing region) or Step 3 (new region).appId: the Pickup carrier id from Step 1.backupRate.title: the pickup address customers see at checkout.backupRate.amount: "0" for free pickup, or a price string like "5.00".backupRate.active: must be true for the option to appear at checkout.Response:
{
"deliveryProfile": {
"id": "02625bf4-70b4-49b7-93f0-5c9d72608937",
"name": "General profile",
"default": true,
"deliveryRegions": [
{
"id": "23823d4a-0ad2-4f92-a48a-467497a9470a",
"name": "US Pickup",
"active": true,
"deliveryCarriers": [
{
"appId": "50d8c12f-715e-41ad-be25-d0f61375dbee",
"backupRate": {
"title": "Pickup at 123 Main St, New York",
"amount": "0",
"active": true
},
"additionalCharges": []
}
],
"destinations": [
{
"countryCode": "US",
"subdivisions": []
}
]
}
],
"revision": "5"
}
}| Error | Cause | Fix |
|---|---|---|
DESTINATIONS_COLLISION | The country is already assigned to another region in the same profile. | Skip Step 3 — use the existing region’s id and add the carrier to it in Step 4. |
CARRIER_ALREADY_EXISTS_IN_REGION | The Pickup carrier is already configured in this region. | The pickup option is already set up. No action needed. |
DELIVERY_CARRIER_MISSING_BACKUP_RATE | The backupRate or backupRate.amount field is missing. | Ensure backupRate includes title, amount, and active. |