Introduction

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:

Copy
import { orderFulfillments } from "wix-ecom-backend";

Permissions information

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.

Did this help?

bulkCreateFulfillments( )


Creates multiple fulfillments for one or more orders.

The bulkCreateFulfillments() function returns a Promise that resolves when the fulfillments are created.

Authentication

This function requires elevated permissions and runs only on the backend and on dashboard pages.

Permissions
Manage Stores - all permissions
Manage Restaurants - all permissions
Manage eCommerce - all permissions
Manage Orders
Learn more about app permissions.
Method Declaration
Copy
function bulkCreateFulfillments(
  ordersWithFulfillments: Array<BulkCreateOrderWithFulfillments>,
): Promise<BulkCreateFulfillmentResponse>;
Method Parameters
ordersWithFulfillmentsArray<BulkCreateOrderWithFulfillments>Required

List of order IDs and their associated fulfillments' info.

Returns
Return Type:Promise<BulkCreateFulfillmentResponse>
JavaScript
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 * } * } * */
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

createFulfillment( )


Creates an order fulfillment.

The createFulfillment() function returns a Promise that resolves when the fulfillment is created.

Authentication

This function requires elevated permissions and runs only on the backend and on dashboard pages.

Permissions
Manage Stores - all permissions
Manage Restaurants - all permissions
Manage eCommerce - all permissions
Manage Orders
Learn more about app permissions.
Method Declaration
Copy
function createFulfillment(
  orderId: string,
  fulfillment: Fulfillment,
): Promise<CreateFulfillmentResponse>;
Method Parameters
orderIdstringRequired

Order ID.


fulfillmentFulfillmentRequired

Fulfillment info.

Returns
Return Type:Promise<CreateFulfillmentResponse>

By passing a supported shippingProvider, the trackingLink field is auto-populated in the response

JavaScript
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" * } * */
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

deleteFulfillment( )


Deletes an existing order fulfillment.

The deleteFulfillment() function returns a Promise that resolves when the fulfillment is deleted.

Authentication

This function requires elevated permissions and runs only on the backend and on dashboard pages.

Permissions
Manage Stores - all permissions
Manage Restaurants - all permissions
Manage eCommerce - all permissions
Manage Orders
Learn more about app permissions.
Method Declaration
Copy
function deleteFulfillment(
  identifiers: DeleteFulfillmentIdentifiers,
): Promise<DeleteFulfillmentResponse>;
Method Parameters
identifiersDeleteFulfillmentIdentifiersRequired

Order and fulfillment IDs.

Returns
Return Type:Promise<DeleteFulfillmentResponse>
JavaScript
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": [] * } * } * */
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

listFulfillmentsForMultipleOrders( )


Retrieves fulfillments associated with multiple specified orders.

The listFulfillmentsForMultipleOrders() function returns a Promise that resolves when the fulfillments are retrieved.

Permissions
Manage Stores - all permissions
Read eCommerce - all read permissions
Read Orders
Read Stores - all read permissions
Manage Restaurants - all permissions
Manage eCommerce - all permissions
Manage Orders
Learn more about app permissions.
Method Declaration
Copy
function listFulfillmentsForMultipleOrders(
  orderIds: Array<string>,
): Promise<ListFulfillmentsForMultipleOrdersResponse>;
Method Parameters
orderIdsArray<string>Required

List of order IDs for which to retrieve fulfillments.

Returns
Return Type:Promise<ListFulfillmentsForMultipleOrdersResponse>
JavaScript
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" * } * } * ] * } * ] * } * */
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

listFulfillmentsForSingleOrder( )


Retrieves fulfillments associated with a specified order.

The listFulfillmentsForSingleOrder() function returns a Promise that resolves when the fulfillments are retrieved.

Permissions
Manage Stores - all permissions
Read eCommerce - all read permissions
Read Orders
Read Stores - all read permissions
Manage Restaurants - all permissions
Manage eCommerce - all permissions
Manage Orders
Learn more about app permissions.
Method Declaration
Copy
function listFulfillmentsForSingleOrder(
  orderId: string,
): Promise<ListFulfillmentsForSingleOrderResponse>;
Method Parameters
orderIdstringRequired

Order ID for which to retrieve fulfillments.

Returns
Return Type:Promise<ListFulfillmentsForSingleOrderResponse>
JavaScript
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" * } * } * ] * } * } * */
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

updateFulfillment( )


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.

Authentication

This function requires elevated permissions and runs only on the backend and on dashboard pages.

Permissions
Manage Stores - all permissions
Manage Restaurants - all permissions
Manage eCommerce - all permissions
Manage Orders
Learn more about app permissions.
Method Declaration
Copy
function updateFulfillment(
  identifiers: UpdateFulfillmentIdentifiers,
  options: UpdateFulfillmentOptions,
): Promise<OrderWithFulfillments>;
Method Parameters
identifiersUpdateFulfillmentIdentifiersRequired

Order and fulfillment IDs to be updated.


optionsUpdateFulfillmentOptions

Available options to use when updating a fulfillment.

Returns
Return Type:Promise<OrderWithFulfillments>

Updates the fulfillment's trackingNumber

JavaScript
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" * } * } * ] * } * } * */
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?