> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # BulkCreateFulfillment # Package: orders # Namespace: Fulfillments # Method link: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-fulfillments/bulk-create-fulfillments.md ## Permission Scopes: Manage Orders: SCOPE.DC-STORES.MANAGE-ORDERS ## Introduction Creates multiple fulfillments for one or more orders. --- ## REST API ### Schema ``` Method: bulkCreateFulfillment Description: Creates multiple fulfillments for one or more orders. URL: https://www.wixapis.com/ecom/v1/fulfillments/orders/bulk/create-fulfillments Method: POST # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: ordersWithFulfillments, ordersWithFulfillments.orderId, ordersWithFulfillments.fulfillments, ordersWithFulfillments.fulfillments.lineItems, ordersWithFulfillments.fulfillments.lineItems.id Method parameters: param name: ordersWithFulfillments | type: array | description: List of order GUIDs and their associated fulfillments. | required: true - name: orderId | type: string | description: Order GUID. | required: true - name: fulfillments | type: array | description: Fulfillments associated with the order. | required: true - ONE-OF: - name: trackingInfo | type: FulfillmentTrackingInfo | description: Tracking info. - name: trackingNumber | type: string | description: Shipping/delivery tracking number. - name: shippingProvider | type: string | description: Shipping provider name. Can be either a predefined provider for automatic tracking link generation, or a custom provider name for manual tracking link management. Predefined providers that support automatic tracking link generation: `"fedex"` - FedEx shipping services `"ups"` - UPS shipping services `"usps"` - United States Postal Service `"dhl"` - DHL shipping services `"canadaPost"` - Canada Post shipping services For predefined providers: - The `trackingLink` field will be automatically populated based on the `trackingNumber` - Standard tracking URL formats are used for each carrier - No additional configuration is needed For custom shipping providers: - Use any string value to identify your provider - You must manually provide the `trackingLink` - Useful for local carriers or specialized shipping services - name: trackingLink | type: string | description: URL where customers can track their shipment status. For predefined shipping providers: - Automatically generated based on the `trackingNumber` - Uses the carrier's official tracking URL format - No manual input required For custom shipping providers: - Must be provided when creating the fulfillment - Should be a valid URL to the carrier's tracking page - Can include the tracking number as a parameter if needed - name: customInfo | type: CustomFulfillmentInfo | description: Custom fulfillment info. - name: fieldsData | type: object | description: Custom fulfillment info in key:value form. - name: lineItems | type: array | description: Line items being fulfilled. - name: id | type: string | description: Line item GUID (mirrors the GUID of the order line item). - name: quantity | type: integer | description: Line item quantity. * If this property isn't passed on creation, it defaults to the number of items not already linked to a fulfillment. * If the order does not have the requested quantity of line items available to add to this fulfillment, the fulfillment will not be created and an error is returned. - name: status | type: string | description: The current status of the fulfillment process. Supported values: + `"Pending"` - Initial state when fulfillment is created but processing hasn't started. + `"Accepted"` - Order has been received and validated for fulfillment. + `"Ready"` - Items have been picked and packed, ready for shipping. + `"In_Delivery"` - Items have been handed over to the shipping carrier. + `"Fulfilled"` - Delivery has been completed successfully. The status typically progresses from Pending → Accepted → Ready → In_Delivery → Fulfilled. Status can be updated manually or automatically depending on your fulfillment workflow. - name: completed | type: boolean | description: Fulfillment handling complete. Return type: BulkCreateFulfillmentResponse - name: results | type: array | description: Items updated by bulk action. - name: itemMetadata | type: ItemMetadata | description: Item metadata. - name: id | type: string | description: Item GUID. Should always be available, unless it's impossible (for example, when failing to create an item). - name: originalIndex | type: integer | description: Index of the item within the request array. Allows for correlation between request and response items. - name: success | type: boolean | description: Whether the requested action was successful for this item. When `false`, the `error` field is populated. - name: error | type: ApplicationError | description: Details about the error in case of failure. - name: code | type: string | description: Error code. - name: description | type: string | description: Description of the error. - name: data | type: object | description: Data related to the error. - name: ordersWithFulfillments | type: OrderWithFulfillments | description: - name: orderId | type: string | description: Order GUID. - name: fulfillments | type: array | description: Fulfillments associated with the order. - ONE-OF: - name: trackingInfo | type: FulfillmentTrackingInfo | description: Tracking info. - name: trackingNumber | type: string | description: Shipping/delivery tracking number. - name: shippingProvider | type: string | description: Shipping provider name. Can be either a predefined provider for automatic tracking link generation, or a custom provider name for manual tracking link management. Predefined providers that support automatic tracking link generation: `"fedex"` - FedEx shipping services `"ups"` - UPS shipping services `"usps"` - United States Postal Service `"dhl"` - DHL shipping services `"canadaPost"` - Canada Post shipping services For predefined providers: - The `trackingLink` field will be automatically populated based on the `trackingNumber` - Standard tracking URL formats are used for each carrier - No additional configuration is needed For custom shipping providers: - Use any string value to identify your provider - You must manually provide the `trackingLink` - Useful for local carriers or specialized shipping services - name: trackingLink | type: string | description: URL where customers can track their shipment status. For predefined shipping providers: - Automatically generated based on the `trackingNumber` - Uses the carrier's official tracking URL format - No manual input required For custom shipping providers: - Must be provided when creating the fulfillment - Should be a valid URL to the carrier's tracking page - Can include the tracking number as a parameter if needed - name: customInfo | type: CustomFulfillmentInfo | description: Custom fulfillment info. - name: fieldsData | type: object | description: Custom fulfillment info in key:value form. - name: id | type: string | description: Fulfillment GUID. - name: createdDate | type: string | description: Fulfillment creation date and time in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) format. - name: lineItems | type: array | description: Line items being fulfilled. - name: id | type: string | description: Line item GUID (mirrors the GUID of the order line item). - name: quantity | type: integer | description: Line item quantity. * If this property isn't passed on creation, it defaults to the number of items not already linked to a fulfillment. * If the order does not have the requested quantity of line items available to add to this fulfillment, the fulfillment will not be created and an error is returned. - name: status | type: string | description: The current status of the fulfillment process. Supported values: + `"Pending"` - Initial state when fulfillment is created but processing hasn't started. + `"Accepted"` - Order has been received and validated for fulfillment. + `"Ready"` - Items have been picked and packed, ready for shipping. + `"In_Delivery"` - Items have been handed over to the shipping carrier. + `"Fulfilled"` - Delivery has been completed successfully. The status typically progresses from Pending → Accepted → Ready → In_Delivery → Fulfilled. Status can be updated manually or automatically depending on your fulfillment workflow. - name: completed | type: boolean | description: Fulfillment handling complete. - name: bulkActionMetadata | type: BulkActionMetadata | description: Bulk action metadata. - name: totalSuccesses | type: integer | description: Number of items that were successfully processed. - name: totalFailures | type: integer | description: Number of items that couldn't be processed. - name: undetailedFailures | type: integer | description: Number of failures without details because detailed failure threshold was exceeded. ``` ### Examples ### Bulk Create Fulfillments Creates a different fulfillment for two separate orders ```curl curl -X POST \ 'https://www.wixapis.com/ecom/v1/fulfillments/orders/bulk/create-fulfillments' \ -H 'Content-Type: application/json' \ -H 'Authorization: ' \ -d '{ "ordersWithFulfillments": [ { "orderId": "eb4b91d3-51f3-494d-94df-479ff2c6eb08", "fulfillments": [ { "lineItems": [ { "id": "00000000-0000-0000-0000-000000000001", "quantity": 1 } ], "trackingInfo": { "trackingNumber": "12345", "shippingProvider": "fedex" } } ] }, { "orderId": "719f96d3-80c7-45c2-b4c1-f15eb610f8a8", "fulfillments": [ { "lineItems": [ { "id": "00000000-0000-0000-0000-000000000001", "quantity": 1 } ], "trackingInfo": { "trackingNumber": "67890", "shippingProvider": "usps" } } ] } ] }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.orders.Fulfillments.bulkCreateFulfillment(ordersWithFulfillments) Description: Creates multiple fulfillments for one or more orders. # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: ordersWithFulfillments, ordersWithFulfillments.orderId, ordersWithFulfillments.fulfillments, ordersWithFulfillments.fulfillments.lineItems, ordersWithFulfillments.fulfillments.lineItems._id Method parameters: param name: ordersWithFulfillments | type: array | description: List of order GUIDs and their associated fulfillments. | required: true - name: orderId | type: string | description: Order GUID. | required: true - name: fulfillments | type: array | description: Fulfillments associated with the order. | required: true - ONE-OF: - name: trackingInfo | type: FulfillmentTrackingInfo | description: Tracking info. - name: trackingNumber | type: string | description: Shipping/delivery tracking number. - name: shippingProvider | type: string | description: Shipping provider name. Can be either a predefined provider for automatic tracking link generation, or a custom provider name for manual tracking link management. Predefined providers that support automatic tracking link generation: `"fedex"` - FedEx shipping services `"ups"` - UPS shipping services `"usps"` - United States Postal Service `"dhl"` - DHL shipping services `"canadaPost"` - Canada Post shipping services For predefined providers: - The `trackingLink` field will be automatically populated based on the `trackingNumber` - Standard tracking URL formats are used for each carrier - No additional configuration is needed For custom shipping providers: - Use any string value to identify your provider - You must manually provide the `trackingLink` - Useful for local carriers or specialized shipping services - name: trackingLink | type: string | description: URL where customers can track their shipment status. For predefined shipping providers: - Automatically generated based on the `trackingNumber` - Uses the carrier's official tracking URL format - No manual input required For custom shipping providers: - Must be provided when creating the fulfillment - Should be a valid URL to the carrier's tracking page - Can include the tracking number as a parameter if needed - name: customInfo | type: CustomFulfillmentInfo | description: Custom fulfillment info. - name: fieldsData | type: object | description: Custom fulfillment info in key:value form. - name: lineItems | type: array | description: Line items being fulfilled. - name: _id | type: string | description: Line item GUID (mirrors the GUID of the order line item). - name: quantity | type: integer | description: Line item quantity. * If this property isn't passed on creation, it defaults to the number of items not already linked to a fulfillment. * If the order does not have the requested quantity of line items available to add to this fulfillment, the fulfillment will not be created and an error is returned. - name: status | type: string | description: The current status of the fulfillment process. Supported values: + `"Pending"` - Initial state when fulfillment is created but processing hasn't started. + `"Accepted"` - Order has been received and validated for fulfillment. + `"Ready"` - Items have been picked and packed, ready for shipping. + `"In_Delivery"` - Items have been handed over to the shipping carrier. + `"Fulfilled"` - Delivery has been completed successfully. The status typically progresses from Pending → Accepted → Ready → In_Delivery → Fulfilled. Status can be updated manually or automatically depending on your fulfillment workflow. - name: completed | type: boolean | description: Fulfillment handling complete. Return type: PROMISE - name: results | type: array | description: Items updated by bulk action. - name: itemMetadata | type: ItemMetadata | description: Item metadata. - name: _id | type: string | description: Item GUID. Should always be available, unless it's impossible (for example, when failing to create an item). - name: originalIndex | type: integer | description: Index of the item within the request array. Allows for correlation between request and response items. - name: success | type: boolean | description: Whether the requested action was successful for this item. When `false`, the `error` field is populated. - name: error | type: ApplicationError | description: Details about the error in case of failure. - name: code | type: string | description: Error code. - name: description | type: string | description: Description of the error. - name: data | type: object | description: Data related to the error. - name: ordersWithFulfillments | type: OrderWithFulfillments | description: - name: orderId | type: string | description: Order GUID. - name: fulfillments | type: array | description: Fulfillments associated with the order. - ONE-OF: - name: trackingInfo | type: FulfillmentTrackingInfo | description: Tracking info. - name: trackingNumber | type: string | description: Shipping/delivery tracking number. - name: shippingProvider | type: string | description: Shipping provider name. Can be either a predefined provider for automatic tracking link generation, or a custom provider name for manual tracking link management. Predefined providers that support automatic tracking link generation: `"fedex"` - FedEx shipping services `"ups"` - UPS shipping services `"usps"` - United States Postal Service `"dhl"` - DHL shipping services `"canadaPost"` - Canada Post shipping services For predefined providers: - The `trackingLink` field will be automatically populated based on the `trackingNumber` - Standard tracking URL formats are used for each carrier - No additional configuration is needed For custom shipping providers: - Use any string value to identify your provider - You must manually provide the `trackingLink` - Useful for local carriers or specialized shipping services - name: trackingLink | type: string | description: URL where customers can track their shipment status. For predefined shipping providers: - Automatically generated based on the `trackingNumber` - Uses the carrier's official tracking URL format - No manual input required For custom shipping providers: - Must be provided when creating the fulfillment - Should be a valid URL to the carrier's tracking page - Can include the tracking number as a parameter if needed - name: customInfo | type: CustomFulfillmentInfo | description: Custom fulfillment info. - name: fieldsData | type: object | description: Custom fulfillment info in key:value form. - name: _id | type: string | description: Fulfillment GUID. - name: _createdDate | type: Date | description: Fulfillment creation date and time in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) format. - name: lineItems | type: array | description: Line items being fulfilled. - name: _id | type: string | description: Line item GUID (mirrors the GUID of the order line item). - name: quantity | type: integer | description: Line item quantity. * If this property isn't passed on creation, it defaults to the number of items not already linked to a fulfillment. * If the order does not have the requested quantity of line items available to add to this fulfillment, the fulfillment will not be created and an error is returned. - name: status | type: string | description: The current status of the fulfillment process. Supported values: + `"Pending"` - Initial state when fulfillment is created but processing hasn't started. + `"Accepted"` - Order has been received and validated for fulfillment. + `"Ready"` - Items have been picked and packed, ready for shipping. + `"In_Delivery"` - Items have been handed over to the shipping carrier. + `"Fulfilled"` - Delivery has been completed successfully. The status typically progresses from Pending → Accepted → Ready → In_Delivery → Fulfilled. Status can be updated manually or automatically depending on your fulfillment workflow. - name: completed | type: boolean | description: Fulfillment handling complete. - name: bulkActionMetadata | type: BulkActionMetadata | description: Bulk action metadata. - name: totalSuccesses | type: integer | description: Number of items that were successfully processed. - name: totalFailures | type: integer | description: Number of items that couldn't be processed. - name: undetailedFailures | type: integer | description: Number of failures without details because detailed failure threshold was exceeded. ``` ### Examples ### Create a fulfillment for 2 different orders (with elevated permissions) ```javascript import { orderFulfillments } from '@wix/ecom'; import { auth } from '@wix/essentials'; /* 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' * } * }] * } * ] * }; */ const elevatedBulkCreateFulfillments = auth.elevate(orderFulfillments.bulkCreateFulfillments); export async function myBulkCreateFulfillmentsFunction(ordersWithFulfillments) { try { const newBulkFulfillments = await elevatedBulkCreateFulfillments(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 * } * } * */ ``` ### Create a fulfillment for 2 different orders ```javascript import { orderFulfillments } from '@wix/ecom'; /* 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 * } * } * */ ``` ### bulkCreateFulfillments (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { orderFulfillments } from '@wix/ecom'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { orderFulfillments }, // Include the auth strategy and host as relevant }); async function bulkCreateFulfillments(ordersWithFulfillments) { const response = await myWixClient.orderFulfillments.bulkCreateFulfillments(ordersWithFulfillments); }; ``` ---