The Order Fulfillments API allows a site visitor to retrieve and manage eCommerce order fulfillments.
An order fulfillment refers to the process of preparing and delivering orders to customers. This process usually involves receiving orders, picking the products from inventory, packing them securely, providing tracking information, and shipping them to the customer's address.
A fulfillment object contains information about an order's shipping provider, tracking details, and the line items associated with the fulfillment.
To use the Order Fulfillments API, import { orderFulfillments }
from the wix-ecom-backend
module:
import { orderFulfillments } from "wix-ecom-backend";
The following functions in the Order Fulfillments API
are restricted and only run if you elevate permissions
using the wix-auth
elevate()
function:
Warning: Elevating a function allows it to be called by any site visitor. Exercise caution to prevent security vulnerabilities.
Creates multiple fulfillments for one or more orders.
The bulkCreateFulfillments()
function returns a Promise that resolves when the fulfillments are created.
This function requires elevated permissions and runs only on the backend and on dashboard pages.
function bulkCreateFulfillments(
ordersWithFulfillments: Array<BulkCreateOrderWithFulfillments>,
): Promise<BulkCreateFulfillmentResponse>;
List of order IDs and their associated fulfillments' info.
import { orderFulfillments } from "wix-ecom-backend";
/* Sample ordersWithFulfillments value:
* {
* ordersWithFulfillments: [
* {
* orderId: 'e613320a-8e8f-4f8f-9d87-b5edc9f99788',
* fulfillments: [{
* lineItems: [{
* _id: '00000000-0000-0000-0000-000000000003',
* quantity: 1
* }],
* trackingInfo: {
* trackingNumber: '93645',
* shippingProvider: 'canadaPost'
* }
* }]
* },
* {
* orderId: 'a6c3a817-579d-4cb5-8521-2fe53b2c4bf1',
* fulfillments: [{
* lineItems: [{
* _id: '00000000-0000-0000-0000-000000000001',
* quantity: 1
* }],
* trackingInfo: {
* trackingNumber: '28674',
* shippingProvider: 'usps'
* }
* }]
* }
* ]
* };
*/
export async function myBulkCreateFulfillmentsFunction(ordersWithFulfillments) {
try {
const newBulkFulfillments = await orderFulfillments.bulkCreateFulfillments(
ordersWithFulfillments,
);
const firstNewFulfillments =
newBulkFulfillments.results[0].ordersWithFulfillments.fulfillments;
const secondNewFulfillments =
newBulkFulfillments.results[1].ordersWithFulfillments.fulfillments;
console.log(
"Success! Retrieved orders' fulfillments:",
newBulkFulfillments,
);
return newBulkFulfillments;
} catch (error) {
console.error(error);
// Handle the error
}
}
/* Promise resolves to:
*
* {
* "results": [
* {
* "itemMetadata": {
* "_id": "e613320a-8e8f-4f8f-9d87-b5edc9f99788",
* "originalIndex": 0,
* "success": true
* },
* "ordersWithFulfillments": {
* "orderId": "e613320a-8e8f-4f8f-9d87-b5edc9f99788",
* "fulfillments": [
* {
* "_id": "397788c4-1c5b-40a3-9431-d4da8662a993",
* "_createdDate": "2023-03-07T14:26:33.276Z",
* "lineItems": [
* {
* "_id": "00000000-0000-0000-0000-000000000002",
* "quantity": 1
* }
* ],
* "trackingInfo": {
* "trackingNumber": "93645",
* "shippingProvider": "canadaPost",
* "trackingLink": "https://www.canadapost.ca/cpotools/apps/track/personal/findByTrackNumber?trackingNumber=93645"
* }
* },
* {
* "_id": "a875e4b7-c25d-4228-98e2-313ea6c07f95",
* "_createdDate": "2023-03-07T14:23:59.426Z",
* "lineItems": [
* {
* "_id": "00000000-0000-0000-0000-000000000001",
* "quantity": 1
* }
* ],
* "trackingInfo": {
* "trackingNumber": "93645",
* "shippingProvider": "canadaPost",
* "trackingLink": "https://www.canadapost.ca/cpotools/apps/track/personal/findByTrackNumber?trackingNumber=93645"
* }
* },
* {
* "_id": "e75bd872-69c9-427f-983a-280412161700",
* "_createdDate": "2023-03-07T14:30:21.535Z",
* "lineItems": [
* {
* "_id": "00000000-0000-0000-0000-000000000003",
* "quantity": 1
* }
* ],
* "trackingInfo": {
* "trackingNumber": "93645",
* "shippingProvider": "canadaPost",
* "trackingLink": "https://www.canadapost.ca/cpotools/apps/track/personal/findByTrackNumber?trackingNumber=93645"
* }
* }
* ]
* }
* },
* {
* "itemMetadata": {
* "_id": "a6c3a817-579d-4cb5-8521-2fe53b2c4bf1",
* "originalIndex": 1,
* "success": true
* },
* "ordersWithFulfillments": {
* "orderId": "a6c3a817-579d-4cb5-8521-2fe53b2c4bf1",
* "fulfillments": [
* {
* "_id": "a838877d-3f13-49f3-ab29-1cde478e0949",
* "_createdDate": "2023-03-07T14:30:21.535Z",
* "lineItems": [
* {
* "_id": "00000000-0000-0000-0000-000000000001",
* "quantity": 1
* }
* ],
* "trackingInfo": {
* "trackingNumber": "28674",
* "shippingProvider": "usps",
* "trackingLink": "https://tools.usps.com/go/TrackConfirmAction.action?tLabels=28674"
* }
* }
* ]
* }
* }
* ],
* "bulkActionMetadata": {
* "totalSuccesses": 2,
* "totalFailures": 0,
* "undetailedFailures": 0
* }
* }
*
*/
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
Creates an order fulfillment.
The createFulfillment()
function returns a Promise that resolves when the fulfillment is created.
This function requires elevated permissions and runs only on the backend and on dashboard pages.
function createFulfillment(
orderId: string,
fulfillment: Fulfillment,
): Promise<CreateFulfillmentResponse>;
Order ID.
Fulfillment info.
By passing a supported shippingProvider
, the trackingLink
field is auto-populated in the response
import { orderFulfillments } from "wix-ecom-backend";
/* Sample orderId value: 'e613320a-8e8f-4f8f-9d87-b5edc9f99788';
* Sample fulfillment value:
* {
* lineItems: [{
* id: '00000000-0000-0000-0000-000000000001',
* quantity: 1
* }],
* trackingInfo: {
* trackingNumber: '12345',
* shippingProvider: 'dhl'
* }
* };
*/
export async function myCreateFulfillmentFunction(orderId, fulfillment) {
try {
const newFulfillment = await orderFulfillments.createFulfillment(
orderId,
fulfillment,
);
const fulfillmentId = newFulfillment.fulfillmentId;
const newOrderFulfillments =
newFulfillment.orderWithFulfillments.fulfillments;
const trackingLink = orderFulfillments[0].trackingInfo.trackingLink;
console.log("Success! Created new fulfillment:", newFulfillment);
return newFulfillment;
} catch (error) {
console.error(error);
// Handle the error
}
}
/* Promise resolves to:
*
* {
* "orderWithFulfillments": {
* "orderId": "e613320a-8e8f-4f8f-9d87-b5edc9f99788",
* "fulfillments": [
* {
* "_id": "91357295-a95c-4973-b210-281640f3e795",
* "_createdDate": "2023-03-06T15:23:29.967Z",
* "lineItems": [
* {
* "_id": "00000000-0000-0000-0000-000000000001",
* "quantity": 1
* }
* ],
* "trackingInfo": {
* "trackingNumber": "12345",
* "shippingProvider": "dhl",
* "trackingLink": "https://www.logistics.dhl/global-en/home/tracking.html?tracking-id=12345"
* }
* }
* ]
* },
* "fulfillmentId": "91357295-a95c-4973-b210-281640f3e795"
* }
*
*/
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
Deletes an existing order fulfillment.
The deleteFulfillment()
function returns a Promise that resolves when the fulfillment is deleted.
This function requires elevated permissions and runs only on the backend and on dashboard pages.
function deleteFulfillment(
identifiers: DeleteFulfillmentIdentifiers,
): Promise<DeleteFulfillmentResponse>;
Order and fulfillment IDs.
import { orderFulfillments } from "wix-ecom-backend";
/* Sample identifiers value:
* {
* orderId: 'e613320a-8e8f-4f8f-9d87-b5edc9f99788',
* fulfillmentId: '91357295-a95c-4973-b210-281640f3e795'
* };
*/
export async function myDeleteFulfillmentFunction(identifiers) {
try {
const { orderWithFulfillments } =
await orderFulfillments.deleteFulfillment(identifiers);
const fulfillmentsArray = orderWithFulfillments.fulfillments;
console.log("Success! Deleted fulfillment", orderWithFulfillments);
return orderWithFulfillments;
} catch (error) {
console.error(error);
// Handle the error
}
}
/* Promise resolves to:
*
* {
* "orderWithFulfillments": {
* "orderId": "e613320a-8e8f-4f8f-9d87-b5edc9f99788",
* "fulfillments": []
* }
* }
*
*/
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
Retrieves fulfillments associated with multiple specified orders.
The listFulfillmentsForMultipleOrders()
function returns a Promise that resolves when the fulfillments are retrieved.
function listFulfillmentsForMultipleOrders(
orderIds: Array<string>,
): Promise<ListFulfillmentsForMultipleOrdersResponse>;
List of order IDs for which to retrieve fulfillments.
import { orderFulfillments } from "wix-ecom-backend";
/* Sample orderIds value:
* [
* 'ed4595fc-4e3d-4ba6-8583-e9e92b97ec8a', '7001d34b-11a6-4a34-8746-dc8ababeca42'
* ];
*/
export async function myListFulfillmentsForMultipleOrdersFunction(orderIds) {
try {
const retrievedOrdersFulfillments =
await orderFulfillments.listFulfillmentsForMultipleOrders(orderIds);
const firstOrderFulfillments = retrievedOrdersFulfillments[0].fulfillments;
const secondOrderFulfillments = retrievedOrdersFulfillments[1].fulfillments;
console.log(
"Success! Retrieved orders' fulfillments:",
retrievedOrdersFulfillments,
);
return retrievedOrdersFulfillments;
} catch (error) {
console.error(error);
// Handle the error
}
}
/* Promise resolves to:
*
* {
* "ordersWithFulfillments": [
* {
* "orderId": "ed4595fc-4e3d-4ba6-8583-e9e92b97ec8a",
* "fulfillments": [
* {
* "_id": "3247615d-dbbe-4cc8-a410-6ca809f1283f",
* "_createdDate": "2023-02-27T12:02:57.364Z",
* "lineItems": [
* {
* "_id": "00000000-0000-0000-0000-000000000001",
* "quantity": 1
* }
* ],
* "trackingInfo": {
* "trackingNumber": "87236",
* "shippingProvider": "fedex",
* "trackingLink": "https://www.fedex.com/apps/fedextrack/?action=track&trackingnumber=87236"
* }
* }
* ]
* },
* {
* "orderId": "7001d34b-11a6-4a34-8746-dc8ababeca42",
* "fulfillments": [
* {
* "_id": "00a7eba6-059e-430c-9f8e-9d3d31dd5e9d",
* "_createdDate": "2023-03-07T11:51:48.233Z",
* "lineItems": [
* {
* "_id": "00000000-0000-0000-0000-000000000003",
* "quantity": 1
* }
* ],
* "trackingInfo": {
* "trackingNumber": "28674",
* "shippingProvider": "dhl",
* "trackingLink": "https://www.logistics.dhl/global-en/home/tracking.html?tracking-id=28674"
* }
* },
* {
* "_id": "47451ae1-7325-4ef6-a0d8-fb91ffa88e2e",
* "_createdDate": "2023-03-07T10:24:56.406Z",
* "lineItems": [
* {
* "_id": "00000000-0000-0000-0000-000000000001",
* "quantity": 1
* },
* {
* "_id": "00000000-0000-0000-0000-000000000002",
* "quantity": 1
* }
* ],
* "trackingInfo": {
* "trackingNumber": "43255",
* "shippingProvider": "fedex",
* "trackingLink": "https://www.fedex.com/apps/fedextrack/?action=track&trackingnumber=43255"
* }
* }
* ]
* }
* ]
* }
*
*/
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
Retrieves fulfillments associated with a specified order.
The listFulfillmentsForSingleOrder()
function returns a Promise that resolves when the fulfillments are retrieved.
function listFulfillmentsForSingleOrder(
orderId: string,
): Promise<ListFulfillmentsForSingleOrderResponse>;
Order ID for which to retrieve fulfillments.
import { orderFulfillments } from "wix-ecom-backend";
// Sample orderId value: '7001d34b-11a6-4a34-8746-dc8ababeca42';
export async function myListFulfillmentsForSingleOrderFunction(orderId) {
try {
const retrievedOrderFulfillments =
await orderFulfillments.listFulfillmentsForSingleOrder(orderId);
const fulfillmentsArray =
retrievedOrderFulfillments.orderWithFulfillments.fulfillments;
console.log(
"Success! Retrieved order fulfillments:",
retrievedOrderFulfillments,
);
return retrievedOrderFulfillments;
} catch (error) {
console.error(error);
// Handle the error
}
}
/* Promise resolves to:
*
* {
* "orderWithFulfillments": {
* "orderId": "7001d34b-11a6-4a34-8746-dc8ababeca42",
* "fulfillments": [
* {
* "_id": "00a7eba6-059e-430c-9f8e-9d3d31dd5e9d",
* "_createdDate": "2023-03-07T11:51:48.233Z",
* "lineItems": [
* {
* "_id": "00000000-0000-0000-0000-000000000003",
* "quantity": 1
* }
* ],
* "trackingInfo": {
* "trackingNumber": "28674",
* "shippingProvider": "dhl",
* "trackingLink": "https://www.logistics.dhl/global-en/home/tracking.html?tracking-id=28674"
* }
* },
* {
* "_id": "47451ae1-7325-4ef6-a0d8-fb91ffa88e2e",
* "_createdDate": "2023-03-07T10:24:56.406Z",
* "lineItems": [
* {
* "_id": "00000000-0000-0000-0000-000000000001",
* "quantity": 1
* },
* {
* "_id": "00000000-0000-0000-0000-000000000002",
* "quantity": 1
* }
* ],
* "trackingInfo": {
* "trackingNumber": "43255",
* "shippingProvider": "fedex",
* "trackingLink": "https://www.fedex.com/apps/fedextrack/?action=track&trackingnumber=43255"
* }
* }
* ]
* }
* }
*
*/
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
Updates a fulfillment's properties.
To update a field's value, include the new value in the fulfillment
field in the body params.
To remove a field's value, pass null
.
The updateFulfillment()
function returns a Promise that resolves when the fulfillment is updated.
Note: Updating line item IDs or fulfilled quantities is not allowed. To update line item IDs or quantities, delete the fulfillment and create it again.
This function requires elevated permissions and runs only on the backend and on dashboard pages.
function updateFulfillment(
identifiers: UpdateFulfillmentIdentifiers,
options: UpdateFulfillmentOptions,
): Promise<OrderWithFulfillments>;
Order and fulfillment IDs to be updated.
Available options to use when updating a fulfillment.
Updates the fulfillment's trackingNumber
import { orderFulfillments } from "wix-ecom-backend";
/* Sample identifiers value:
* {
* orderId: 'a6c3a817-579d-4cb5-8521-2fe53b2c4bf1',
* fulfillmentId: 'a838877d-3f13-49f3-ab29-1cde478e0949'
* };
*
* Sample options value:
* {
* fulfillment: {
* trackingInfo: {
* trackingNumber: '45677'
* }
* }
* };
*/
export async function myUpdateFulfillmentFunction(identifiers, options) {
try {
const updatedOrderFulfillments = await orderFulfillments.updateFulfillment(
identifiers,
options,
);
const fulfillmentsArray =
updatedOrderFulfillments.orderWithFulfillments.fulfillments;
console.log("Success! Updated fulfillment", updatedOrderFulfillments);
return updatedOrderFulfillments;
} catch (error) {
console.error(error);
// Handle the error
}
}
/* Promise resolves to:
*
* {
* "orderWithFulfillments": {
* "orderId": "a6c3a817-579d-4cb5-8521-2fe53b2c4bf1",
* "fulfillments": [
* {
* "_id": "a838877d-3f13-49f3-ab29-1cde478e0949",
* "_createdDate": "2023-03-07T14:30:21.535Z",
* "lineItems": [
* {
* "_id": "00000000-0000-0000-0000-000000000001",
* "quantity": 1
* }
* ],
* "trackingInfo": {
* "trackingNumber": "45677",
* "shippingProvider": "usps",
* "trackingLink": "https://tools.usps.com/go/TrackConfirmAction.action?tLabels=45677"
* }
* }
* ]
* }
* }
*
*/
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.