> 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

# CreateFulfillment

# Package: orders

# Namespace: Fulfillments

# Method link: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-fulfillments/create-fulfillment.md

## Permission Scopes:
Manage Orders: SCOPE.DC-STORES.MANAGE-ORDERS

## Introduction

Creates an order fulfillment.

---

## REST API

### Schema

```
 Method: createFulfillment
 Description: Creates an order fulfillment.
 URL: https://www.wixapis.com/ecom/v1/fulfillments/orders/{orderId}/create-fulfillment
 Method: POST
 # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present.
 Required parameters:  fulfillment, fulfillment.lineItems, fulfillment.lineItems.id
 Method parameters: 
   param name: fulfillment | type: Fulfillment | description: for now, this is a sub-object of Orders, so can refer to order line items by id. | required: true
    - ONE-OF: - required: true
     - 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<FulfillmentLineItem> | description: Line items being fulfilled. | required: true
           - 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: CreateFulfillmentResponse
  - name: orderWithFulfillments | type: OrderWithFulfillments | description: Order GUID and the orders' fulfillments. 
     - name: orderId | type: string | description: Order GUID. 
     - name: fulfillments | type: array<Fulfillment> | 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<FulfillmentLineItem> | 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: fulfillmentId | type: string | description: GUID of created fulfillment. 

 Possible Errors:
   HTTP Code: 409 | Status Code: ALREADY_EXISTS | Application Code: TRACKING_NUMBER_ALREADY_EXISTS | Description: fulfillment with tracking number already exist


```

### Examples

### Create Fulfillment
Passing a shipping provider that supports auto-filling the `trackingLink` in the response.

```curl
curl -X POST \
  'https://www.wixapis.com/ecom/v1/fulfillments/orders/58c9a790-27b7-463f-a865-c7cb494f7c29/create-fulfillment' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: <AUTH>' \
  -d '{
    "fulfillment": {
      "lineItems": [
        {
          "id": "00000000-0000-0000-0000-000000000001",
          "quantity": 1
        }
      ],
      "trackingInfo": {
        "trackingNumber": "12345",
        "shippingProvider": "fedex"
      }
    }
  }'
```

---

## JavaScript SDK

### Schema

```
 Method: wixClientAdmin.orders.Fulfillments.createFulfillment(orderId, fulfillment)
 Description: Creates an order fulfillment.
 # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present.
 Required parameters:  orderId, fulfillment, fulfillment.lineItems, fulfillment.lineItems._id
 Method parameters: 
   param name: fulfillment | type: Fulfillment | description: for now, this is a sub-object of Orders, so can refer to order line items by id. | required: true
    - ONE-OF: - required: true
     - 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<FulfillmentLineItem> | description: Line items being fulfilled. | required: true
           - 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. 
   param name: orderId | type: string | description: Order GUID. | required: true
 Return type: PROMISE<CreateFulfillmentResponse>
  - name: orderWithFulfillments | type: OrderWithFulfillments | description: Order GUID and the orders' fulfillments. 
     - name: orderId | type: string | description: Order GUID. 
     - name: fulfillments | type: array<Fulfillment> | 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<FulfillmentLineItem> | 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: fulfillmentId | type: string | description: GUID of created fulfillment. 

 Possible Errors:
   HTTP Code: 409 | Status Code: ALREADY_EXISTS | Application Code: TRACKING_NUMBER_ALREADY_EXISTS | Description: fulfillment with tracking number already exist


```

### Examples

### Create a fulfillment (with elevated permissions)
By passing a supported `shippingProvider`, the `trackingLink` field is auto-populated in the response

```javascript
import { orderFulfillments } from '@wix/ecom';
import { auth } from '@wix/essentials';

/* 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'
*   }
* };
*/

const elevatedCreateFulfillment = auth.elevate(orderFulfillments.createFulfillment);

export async function myCreateFulfillmentFunction(orderId, fulfillment) {
  try {
    const newFulfillment = await elevatedCreateFulfillment(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"
 * }
 *
 */
```

### Create a fulfillment
By passing a supported `shippingProvider`, the `trackingLink` field is auto-populated in the response

```javascript
import { orderFulfillments } from '@wix/ecom';

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

### createFulfillment (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 createFulfillment(orderId,fulfillment) {
  const response = await myWixClient.orderFulfillments.createFulfillment(orderId,fulfillment);
};
```

---