Configuring Fulfillment

This feature in Carts API allows you to add, update, or remove fulfillment information in the cart and associate it with individual items. The cart supports multiple fulfillment options.

Prerequisites

The following prerequisites must be completed sequentially to configure a fulfillment.

1. Create a cart.
2. Create a destination address if the fulfillment type is SHIP_TO.
3. Create an origin address if the fulfillment type is BOPIS or ROPIS.

Fulfillment Initialization

After you create a cart with Create a cart, you will see the fulfillment resource in the cart response.

The following code sample provides the structure of fulfillment object in a cart response:

Click to expand the JSON example.

{
    "id": "a7f51053-6fbd-42a6-8fbc-303bfc16c13f",
    "type": "SHIP_TO",
    "refId": "6425279f661bf878448465b4",
    "originAddress": "{{originAddressId}}",
    "destinationAddress": "{{destinationAddressId}}",
    "price": {
        "amount": 10
    },
    "fees": {
        "total": 0,
        "collection": []
    },
    "adjustments": {
        "total": 0,
        "collection": []
    },
    "tax": {
        "total": 0,
        "collection": []
    }
}

The fulfillment resource can be associated with an item using the fulfillmentId by making POST request to the {cartId}/fulfillments endpoint.

The following code sample provides how the request is structured in a request payload:

POST Response

Click to expand the curl example.

curl --location '{{cartV3_domain}}/carts/{{cartId}}/items' \
--header 'x-fabric-tenant-id: {tenantId}' \
--header 'Content-Type: application/json' \
--header 'Authorization: {authToken}' \
--data 
'{
    "sku": "5",
    "refId": "19",
    "quantity": 10,
    "price": 
    {
        "type": "UNIT",
        "amount": 100
    },
    "fulfillment": 
    {
        "id": "a7f51053-6fbd-42a6-8fbc-303bfc16c13f",  // fulfillmentId
        "inventory": 
        {
            "channels": 
                {"networkCode": "ShipToHome"},
            "type": "preOrder"
        }
    }
}'

The cart has a fulfillment object that stores all the fulfillments added to it.

You can check your fulfillment information by making a GET request to carts/{cartId}/fulfillments/{fulfillmentId} endpoint.

The following code sample provides the structure of fulfillment object in the response:

Click to expand the JSON example.

{
    "fulfillments": 
    {
        "a7f51053-6fbd-42a6-8fbc-303bfc16c13f":{
            "id": "a7f51053-6fbd-42a6-8fbc-303bfc16c13f",
            "type": "SHIP_TO",
            "refId": "6425279f661bf878448465b4",
            "attributes": {},
            "originAddress": "d48340ac-23c6-42ef-8aa3-84c43eb4e391",
            "destinationAddress": "d48340ac-23c6-42ef-8aa3-84c43eb4e391",
            "price": {
                "amount": 10
            },
            "fees": {
                "total": 0,
                "collection": []
            },
            "adjustments": {
                "total": 0,
                "collection": []
            },
            "tax": {
                "total": 0,
                "collection": []
            }
        },
        "b326819-6fbd-42a6-8fbc-303bfc16e222": {
            "id": "b326819-6fbd-42a6-8fbc-303bfc16e222",
            "type": "SHIP_TO",
            "refId": "632479f661bf87844846534",
            "attributes": {},
            "originAddress": "d48340ac-23c6-42ef-8aa3-84c43eb4e391",
            "destinationAddress": "d48340ac-23c6-42ef-8aa3-84c43eb4e391",
            "price": {
                "amount": 10
            },
            "fees": {
                "total": 0,
                "collection": []
            },
            "adjustments": {
                "total": 0,
                "collection": []
            },
            "tax": {
                "total": 0,
                "collection": []
            }
        }
    }
}

Examples

Adding a fulfillment with a single cost to multiple items

1. Create a fulfillment curl.

   Click to see fulfillment curl and response examples

   curl --location '{{modular_cart_domain}}/carts/07618f2d-8559-479a-80ed-5ed7259cbd25/fulfillments' \
   --header 'Content-Type: application/json' \
   --header 'x-fabric-tenant-id:  {tenantId}' \
   --data '{
       "type": "SHIP_TO",
       "refId": "6622d50d2eee4e4e124c7467",
       "destinationAddress": "2ac62be8-2440-46e7-9a42-6b2c62fb6690",
       "price": {
           "amount": 10.0
       }
   }'
   

   Response

   {
       "id": "e4d68b36-8902-4427-a244-9eb65290855c",
       "type": "SHIP_TO",
       "refId": "6622d50d2eee4e4e124c7467",
       "destinationAddress": "2ac62be8-2440-46e7-9a42-6b2c62fb6690",
       "price": {
           "amount": 10.0
       },
       "fees": {
           "total": 0,
           "collection": []
       },
       "adjustments": {
           "total": 0,
           "collection": []
       },
       "tax": {
           "total": 0,
           "collection": []
       }
   }
   

2. Create multiple items with same fulfillment using the add items endpoint.

   Click to expand

   curl --location '{{orchestrator_domain}}/orchestrator/carts/07618f2d-8559-479a-80ed-5ed7259cbd25/items' \
   --header 'x-fabric-tenant-id:  {tenantId}' \
   --header 'x-fabric-request-id: 1' \
   --header 'x-fabric-channel-id: 12' \
   --header 'Authorization: {authToken}' \
   --header 'customer-id: 1234' \
   --header 'Content-Type: application/json' \
   --data '{
       "items": [
           {
               "quantity": 4,
               "itemId": "41",
               "sku": "SKU2",
               "priceListId": "100000",
               "price": {
                   "type": "UNIT",
                   "amount": 10
               },
               "fulfillment": {
                   "id": "e4d68b36-8902-4427-a244-9eb65290855c",
                   "inventory": {
                       "channels": {
                           "type": "WEB_PICKUP",
                           "locationNumber": "15",
                           "channelId": "12"
                       },
                       "type": "availableToPurchase"
                   }
               }
           },
           {
               "quantity": 5,
               "itemId": "44",
               "sku": "SKU3",
               "priceListId": "100000",
               "price": {
                   "type": "UNIT",
                   "amount": 100
               },
               "fulfillment": {
                   "id": "e4d68b36-8902-4427-a244-9eb65290855c",
                   "inventory": {
                       "channels": {
                           "type": "WEB_SHIP",
                           "networkCode": "ShipToHome",
                           "channelId": "12"
                       },
                       "type": "availablePreorder"
                   }
               }
           }
       ]
   }'
   

Adding a fulfillment with a custom cost to an item

1. Create a fulfillment curl.

   Click to see the curl and the JSON response

   curl --location '{{modular_cart_domain}}/carts/07618f2d-8559-479a-80ed-5ed7259cbd25/fulfillments' \
   --header 'Content-Type: application/json' \
   --header 'x-fabric-tenant-id:  {tenantId}' \
   --data '{
       "type": "SHIP_TO",
       "refId": "6622d50d2eee4e4e124c7467",
       "destinationAddress": "2ac62be8-2440-46e7-9a42-6b2c62fb6690",
       "price": {
           "amount": 10.0
       }
   }'
   

   Response:

   {
       "id": "e4d68b36-8902-4427-a244-9eb65290855c",
       "type": "SHIP_TO",
       "refId": "6622d50d2eee4e4e124c7467",
       "destinationAddress": "2ac62be8-2440-46e7-9a42-6b2c62fb6690",
       "price": {
           "amount": 10.0
       },
       "fees": {
           "total": 0,
           "collection": []
       },
       "adjustments": {
           "total": 0,
           "collection": []
       },
       "tax": {
           "total": 0,
           "collection": []
       }
   }
   

2. Add a custom cost to the item using the add item endpoint.

   Click to see the curl and the JSON response

   The example shows adding an additional $5.00 as the fulfillment cost for the item.

   curl --location 'https:{{modular_cart_domain}}/carts/7d403833-8e0c-43f5-aded-72d6a2eaf062/items' \
   --header 'x-fabric-tenant-id:  {tenantId}' \
   --header 'Content-Type: application/json' \
   --data '{
       "sku": "5",
       "refId": "1",
       "quantity": 1,
       "priceListId": "100000",
       "price": {
           "type": "UNIT",
           "amount": 100
       },
       "fulfillment": {
           "id": "e4d68b36-8902-4427-a244-9eb65290855c",
           "inventory": {
               "channels": {
                   "networkCode": "ShipToHome"
               },
               "type": "backOrder"
           },
           "price": {
               "amount": 5
           }
       }
   }'
   

   price.fulfillments accepts both the fulfillment cost and any additional fulfillment amount added to the item.

   Response:

   {
       "lineItems": {
           "total": 100,
           "collection": [
               {
                   "id": "806d6671-801d-4554-976d-0d38e525a852",
                   "sku": "5",
                   "refId": "1",
                   "quantity": 1,
                   "priceListId": "100000",
                   "position": 1,
                   "price": {
                       "unit": 100,
                       "amount": 100
                   },
                   "fees": {
                       "total": 0,
                       "collection": []
                   },
                   "promotions": {
                       "total": 0,
                       "collection": []
                   },
                   "adjustments": {
                       "total": 0,
                       "collection": []
                   },
                   "fulfillment": {
                       "id": "cda19e15-ab04-419e-8fc1-61fa7874beb0",
                       "price": {
                           "amount": 5
                       },
                       "inventory": {
                           "type": "backOrder",
                           "channels": {
                               "networkCode": "ShipToHome"
                           }
                       },
                       "tax": {
                           "total": 0,
                           "collection": []
                       }
                   },
                   "attributes": {},
                   "tax": {
                       "total": 0,
                       "collection": []
                   },
                   "updatedAt": "2024-08-31T15:17:20.584Z",
                   "createdAt": "2024-08-31T15:17:20.584Z"
               }
           ]
       },
       "id": "7d403833-8e0c-43f5-aded-72d6a2eaf062",
       "attributes": {
           "key": "value"
       },
       "configuration": {
           "order": {
               "validate": {
                   "paymentsRemaining": "BLOCK",
                   "taxRemaining": "BLOCK",
                   "invalidItem": "BLOCK",
                   "itemOutOfStock": "BLOCK"
               }
           },
           "product": {
               "cacheExpiry": 1,
               "behaviors": {
                   "add": "NONE",
                   "update": "NONE",
                   "get": "NONE",
                   "cacheExpiry": "NONE"
               },
               "maxQuantity": {
                   "behaviors": {
                       "add": "NONE",
                       "update": "NONE",
                       "get": "NONE"
                   }
               }
           },
           "inventory": {
               "cacheExpiry": 1,
               "behaviors": {
                   "add": "NONE",
                   "update": "NONE",
                   "get": "NONE",
                   "cacheExpiry": "NONE"
               },
               "check": "SKU"
           },
           "tax": {
               "cacheExpiry": 5,
               "behaviors": {
                   "cacheExpiry": "NONE"
               }
           },
           "promotions": {
               "cacheExpiry": 5,
               "behaviors": {
                   "cacheExpiry": "WARN"
               }
           },
           "maxQuantity": {
               "limit": 10,
               "behaviors": {
                   "add": "NONE",
                   "update": "NONE",
                   "get": "NONE"
               }
           }
       },
       "customerContext": {},
       "status": "ACTIVE",
       "state": [
           {
               "resource": "CART",
               "resourceId": "",
               "key": "MISSING_PAYMENT_DETAILS",
               "description": "No payment details have been added to this Cart"
           },
           {
               "resource": "CART",
               "resourceId": "",
               "key": "MISSING_TAX",
               "description": "No tax has been added to this Cart"
           }
       ],
       "price": {
           "total": 115,
           "subtotal": 100,
           "tax": 0,
           "fulfillments": 15,
           "discounts": 0,
           "fees": 0,
           "adjustments": 0
       },
       "promotions": {
           "total": 0,
           "collection": null
       },
       "fees": {
           "total": 0,
           "collection": []
       },
       "adjustments": {
           "total": 0,
           "collection": []
       },
       "addresses": {
           "702009a6-fc56-4df7-a1b4-c73cf916d9fc": {
               "id": "702009a6-fc56-4df7-a1b4-c73cf916d9fc",
               "name": {
                   "first": "Pat",
                   "last": "E"
               },
               "email": "[e-mail]",
               "phone": {
                   "number": "9050123102",
                   "type": "MOBILE"
               },
               "addressLine1": "Princeton",
               "addressLine2": "Street 2",
               "addressLine3": "Stars Hollow",
               "city": "Phillidelphia",
               "region": "Pennsylvania",
               "country": "US",
               "postalCode": "1-21-12",
               "updatedAt": "2024-08-31T15:17:17.312Z",
               "createdAt": "2024-08-31T15:17:17.312Z"
           }
       },
       "summary": {
           "totalItems": 1,
           "totalUniqueItems": 1
       },
       "fulfillments": {
           "cda19e15-ab04-419e-8fc1-61fa7874beb0": {
               "id": "cda19e15-ab04-419e-8fc1-61fa7874beb0",
               "type": "SHIP_TO",
               "refId": "1",
               "attributes": {
                   "test1": {},
                   "channelId": [
                       "12"
                   ]
               },
               "originAddress": "",
               "destinationAddress": "702009a6-fc56-4df7-a1b4-c73cf916d9fc",
               "price": {
                   "amount": 10
               },
               "fees": {
                   "total": 0,
                   "collection": []
               },
               "adjustments": {
                   "total": 0,
                   "collection": []
               },
               "tax": {
                   "total": 0,
                   "collection": []
               }
           }
       },
       "coupons": [],
       "appliedCoupons": [],
       "notAppliedCoupons": [],
       "validations": {
           "promotions": null,
           "lineItems": [],
           "product": null,
           "tax": null
       },
       "payments": {
           "authorized": 0,
           "collection": []
       },
       "channelId": "13",
       "currency": "USD",
       "updatedAt": "2024-08-31T15:17:18.982Z",
       "createdAt": "2024-08-31T15:17:07.865Z"
   }
   

Adding a fulfillment with the type BOPIS or ROPIS requires a locationId

Use the add fulfillment endpoint to add a location when creating a fulfillment as in the following example:

Click to see curl example.

curl --location '{{modular_cart_domain}}/carts/7d403833-8e0c-43f5-aded-72d6a2eaf062/fulfillments' \
    --header 'Content-Type: application/json' \
    --header 'x-fabric-tenant-id:  {tenantId}' \
    --data '{
        "type": "BOPIS",
        "refId": "1",
        "originAddress": "702009a6-fc56-4df7-a1b4-c73cf916d9fc",
        "locationId": "1",
        "attributes": {
            "channelId": [
                "12"
            ],
            "test1": 123
        },
        "price": {
            "amount": 10
        },
        "pickupPerson": {
            "primary": {
                "name": {
                    "firstName": "BOB"
                },
                "email": "123",
                "phone": {
                    "type": "MOBILE",
                    "number": "1231231234"
                },
                "addressId": "702009a6-fc56-4df7-a1b4-c73cf916d9fc"
            }
        }
    }'

Adding the same destination address to different fulfillments for multiple items

Use the add fulfillment endpoint to create multiple fulfillment with the same addresses as in the following example:

Click to see curl example.

curl --location '{{modular_cart_domain}}/carts/7d403833-8e0c-43f5-aded-72d6a2eaf062/fulfillments' \
--header 'Content-Type: application/json' \
--header 'x-fabric-tenant-id:  {tenantId}' \
--data '{
    "type": "BOPIS",
    "refId": "1",
    "originAddress": "702009a6-fc56-4df7-a1b4-c73cf916d9fc",
    "destinationAddress": "702009a6-fc56-4df7-a1b4-c73cf916d9fc",
    "locationId": "1",
    "attributes": {
        "channelId": [
            "12"
        ],
        "test1": 123
    },
    "price": {
        "amount": 10
    },
    "pickupPerson": {
        "primary": {
            "name": {
                "firstName": "BOB"
            },
            "email": "123",
            "phone": {
                "type": "MOBILE",
                "number": "1231231234"
            },
            "addressId": "702009a6-fc56-4df7-a1b4-c73cf916d9fc"
        }
    }
}'