Fulfillment Options API
Author:
Fluent Commerce
Changed on:
3 July 2024
Overview
The Fulfillment Options API retrieves the proposed Fulfillment Options for the customer order.
Key points
- Fulfillment Options Properties
- What you can do with Fulfillment Options
- FulfilmentOptions.FulfilmentOptionsAddress
- InventoryPosition.ProposedFulfilment.Item
- Attribute
- FulfilmentOptions.UnfulfilledItem
- FulfilmemntPlan
- FulfilmentPlan.Fulfilment
- FulfilmentPlan.Fulfilment.FulfilmentItem
- Exception
- Response on Failures
Fulfillment Options Properties
Below are the properties available in the Fulfillment options object which can be updated and retrieved through the APIs in this document.
1. id
Type: String
1{ "id" : "442755c4-28ee-4404-9e21-abe29bb3a1e5" }Language: java
Name: Description
Description:
[Warning: empty required content area]Unique ID of the Fulfillment Option.
2. status
Type: String
1{ "status" : "OPTIONS_PROVIDED" }Language: java
Name: Description
Description:
[Warning: empty required content area]Status of the Fulfillment Option.
3. limit
Type: Integer
1{ "limit" : 10 }Language: java
Name: Description
Description:
[Warning: empty required content area]Limit the number of Fulfillment Plans to be returned.
4. count
Type: Integer
1{ "count" : 1 }Language: json
Name: Description
Description:
[Warning: empty required content area]The number of Fulfillment Plans returned in this response.
5. total
Type: String
1{ "total" : 1 }Language: java
Name: Description
Description:
[Warning: empty required content area]The total number Fulfillment Plans generated.
6. orderType
Type: String
1{ "orderType" : "HD" }Language: java
Name: Description
Description:
[Warning: empty required content area]Type of order - eg. click & collect (CC) or home delivery (HD).
7. locationRef
Type: String
1{ "locationRef" : "LO1013" }Language: json
Name: Description
Description:
[Warning: empty required content area]The unique reference of the location.
8. trackingId
Type: Integer
1{ "trackingId" : "41123TP" }Language: java
Name: Description
Description:
[Warning: empty required content area]A unique identifier for the end user to link related Fulfillment Options.
9. retailerId
Type: Long
1{ "retailerID" : 1 }Language: json
Name: Description
Description:
[Warning: empty required content area]Unique ID of the retailer
10. address
Type: FulfilmentOptions.FulfilmentOptionsAddress
Description: For orderType=HD. The delivery address of the order.
11. items
Type: List
Description: List of InventoryPosition.ProposedFulfilment.Item to be fulfillled.
12. attributes
Type: List
Description:
- List of Attribute
- Attributes are used to provide additional information about the fulfillment options.
- Standard attribute types like string, integer and complex types like address are supported as well.
13. unfulfilledItems
Type: List
Description: List of FulfilmentOptions.UnfulfilledItem that were unavailable to be filled by any FulfilmentPlans.
14. plans
Type: List
Description: List of FulfilmentPlan.
15. flexType
Type: String
1{ "flexType" : "FULFILMENT_OPTIONS::DEFAULT" }Language: java
Name: Description
Description:
[Warning: empty required content area]Type of workflow.
16. flexVersion
Type: Integer
1{ "flexVersion" : 1 }Language: java
Name: Description
Description:
[Warning: empty required content area]Version of the flexType workflow
FulfilmentOptions.FulfilmentOptionsAddress
1. address1
Type: String
1{ "address1" : "46 Kippax Street" }Language: java
Name: Description
Description:
[Warning: empty required content area]2. address2
Type: String
1{ "address2" : "ABC Pvt Ltd" }Language: java
Name: Description
Description:
[Warning: empty required content area]3. city
Type: String
1{ "city" : "Surry Hills" }Language: java
Name: Description
Description:
[Warning: empty required content area]4. country
Type: String
1{ "country" : "AU" }Language: json
Name: Description
Description:
[Warning: empty required content area]5. postcode
Type: String
1{ "postcode" : "2000" }Language: java
Name: Description
Description:
[Warning: empty required content area]6. state
Type: String
1{ "state" : "NSW" }Language: java
Name: Description
Description:
[Warning: empty required content area]7. latitude
Type: Double
1{ "latitude" : "-27.469712" }Language: json
Name: Description
Description:
[Warning: empty required content area]8. longitude
Type: Double
1{ "longitude" : "153.02568" }Language: java
Name: Description
Description:
[Warning: empty required content area]InventoryPosition.ProposedFulfilment.Item
1. skuRef
Type: String
1{ "skuRef" : "FX141123TPRT-1-2" }Language: java
Name: Description
Description:
[Warning: empty required content area]SKU Reference of the requested item
2. requestedQuantity
Type: Integer
1{ "requestedQuantity" : 1 }Language: java
Name: Description
Description:
[Warning: empty required content area]Requested Quantity of the item
3. availableQuantity
Type: Integer
1{ "availableQuantity" : 1 }Language: java
Name: Description
Description:
[Warning: empty required content area]Available Quantity of the item
Attribute
1. name
Type: String
1{ "name" : "Supplier Address" }Language: java
Name: Description
Description:
[Warning: empty required content area]Name of the attribute.
2. type
Type: String
1{ "type" : "ADDRESS" }Language: java
Name: Description
Description:
[Warning: empty required content area]Type of the value provided. Possible Values are:
- 'STRING',
- 'TEXT',
- 'INTEGER',
- 'BOOLEAN',
- 'ADDRESS',
- 'OBJECT',
- 'CUSTOM'
3. value
Type: Object
1{
2
3"value" : {
4
5"address1" : "46 Kippax Street",
6"address2" : "Surry Hills",
7"postcode" : "2010",
8"state" : "NSW,
9"country" : "AU"
10
11}
12
13
14
15}Language: java
Name: Description
Description:
[Warning: empty required content area]Value of the attribute.
FulfilmentOptions.UnfulfilledItem
1. skuRef
Type: String
1{ "skuRef" : "DMI111" }Language: java
Name: Description
Description:
[Warning: empty required content area]The SKU that was unfulfilled.
2. unavailableQty
Type: Integer
1{ "unavailableQty" : 1 }Language: java
Name: Description
Description:
[Warning: empty required content area]Quantity of this SKU that was unfulfilled.
3. reasonCode
Type: String
1{ "reasonCode" : "123C" }Language: java
Name: Description
Description:
[Warning: empty required content area]Reason Code for the item being unfulfilled.
4. reason
Type: String
1{ "reason" : "Too Heavy" }Language: java
Name: Description
Description:
[Warning: empty required content area]Reason Code for the item being unfulfilled.
FulfilmentPlan
1. id
Type: String
1{ "id" : "d8d46b57-a2d8-472d-a632-c47916a6a0da" }Language: java
Name: Description
Description:
[Warning: empty required content area]Unique ID of the Fulfillment Plan.
2. retailerId
Type: String
1{ "retailerID" : 1 }Language: java
Name: Description
Description:
[Warning: empty required content area]Unique ID of the retailer.
3. planId
Type: String
1{ "planId" : "d8d46b57-a2d8-472d-a632-c47916a6a0da" }Language: java
Name: Description
Description:
[Warning: empty required content area]Unique ID of the Fulfillment Plan (same as id).
4. planType
Type: String
1{ "planType" : "HD" }Language: json
Name: Description
Description:
[Warning: empty required content area]Type of the Fulfillment Plan.
5. eta
Type: String
1{ "eta" : "20H" }Language: java
Name: Description
Description:
[Warning: empty required content area]ETA of the FulfillmentPlan as configured in the workflows.
Accepted formats are either a numeric string, a numeric string suffixed with either an hour "H" or day "D" character, or null.
1{ "eta" : "8H" } # 8 hours
2
3{ "eta" : "8" } # Converts to "8H" (8 hours)
4
5{ "eta" : "1D" } # 1 day
6
7{ "eta" : "24" } # Converts to "1D" (1 day)
8
9{ "eta" : "48" } # Converts to "2D" (2 days)
10
11{ "eta" : "25" } # Also converts to "2D" (2 days) because it's greater than 1 day/24 hoursLanguage: java
Name: Example values
Description:
[Warning: empty required content area]A null value for eta converts to "1D" (1 day).
6. splits
Type: Integer
1{ "splits" : 0 }Language: java
Name: Description
Description:
[Warning: empty required content area]The number of times this order was split.
7. fulfilments
Type: List
Description: List of FulfilmentPlan.Fulfilment.
8. exceptions
Type: List
Description: List of Exception.
9. fulfilmentOptionsId
Type: String
1{ "fulfilmentOptionsId" : "442755c4-28ee-4404-9e21-abe29bb3a1e5" }Language: json
Name: Description
Description:
[Warning: empty required content area]ID of the Fulfillment Option that created this plan.
10. attributes
Type: List
Description: List of Attributes.
11. status
Type: String
1{ "status" : "COMPLETE" }Language: java
Name: Description
Description:
[Warning: empty required content area]Status of the Fulfillment Plan.
12. flexType
Type: String
1{ "flexType" : "FULFILMENT_PLAN::DEFAULT" }Language: json
Name: Description
Description:
[Warning: empty required content area]Unique ID of the retailer
13. flexVersion
Type: Integer
1{ "flexVersion" : 1 }Language: json
Name: Description
Description:
[Warning: empty required content area]Unique ID of the retailer
FulfilmentPlan.Fulfilment
1. fulfilmentType
Type: String
1{ "fulfilmentType" : "HD" }Language: java
Name: Description
Description:
[Warning: empty required content area]Type of the Fulfillment.
2. locationRef
Type: String
1{ "locationRef" : "LOC123" }Language: java
Name: Description
Description:
[Warning: empty required content area]Location of the Fulfillment.
3. ETA
Type: String
1{ "eta" : "20H" }Language: java
Name: Description
Description:
[Warning: empty required content area]ETA of the Fulfillment Plan as configured in the workflow.
4. items
Type: String
Description: List of FulfilmentPlan.Fulfilment.FulfilmentItem.
FulfilmentPlan.Fulfilment.FulfilmentItem
1. skuRef
Type: String
1{ "skuRef" : "DM12345" }Language: java
Name: Description
Description:
[Warning: empty required content area]SKU Reference of the Fulfillment Item.
2. availableQty
Type: Integer
1{ "availableQty" : 1 }Language: java
Name: Description
Description:
[Warning: empty required content area]Available Quantity of the Fulfillment Item.
Exception
1. code
Type: String
1{ "code" : "1" }Language: java
Name: Description
Description:
[Warning: empty required content area]Error Code.
2. message
Type: String
1{ "message" : "WARNING" }Language: java
Name: Description
Description:
[Warning: empty required content area]Error Message.
3. attributes
Type: List
Description: List of Attributes
What you can do with Fulfillment Options
Create a Fulfillment Option
With this endpoint you can create a fulfillment options entity.
POST:
`/api/v4.1/fulfilmentOptions`Request and response
Request parameters and sample
Fulfillment Option request
1FulfilmentOptions Request {
2
3limit (integer)
4orderType (string)
5locationRef (string)
6trackingId (string)
7retailerId (long)
8status (string)
9address (FulfilmentOptions.FulfilmentOptionsAddress)
10items (list of Item)
11attributes (list of Attribute)
12}
13
14
15FulfilmentOptionsAddress {
16 address1 (string)
17 address2 (string)
18 city (string)
19 postcode (string)
20 state (string)
21 country (string)
22 latitude (double)
23 longitude (double)
24}
25
26Item {
27skuRef (string)
28requestedQuantity (integer)
29availableQuantity (integer)
30},
31
32Attribute {
33 name (string),
34 type (string) = ['STRING', 'TEXT', 'INTEGER', 'BOOLEAN', 'ADDRESS', 'OBJECT', 'CUSTOM'],
35 value (object)
36}Language: java
Name: Fulfillment Option request Example
Description:
[Warning: empty required content area]1{
2 "limit": 10,
3 "orderType": "HD",
4 "locationRef": "DR001",
5 "trackingId": "track",
6 "address": {
7 "address1": "46 Kippax Street",
8 "city": "Surry Hills",
9 "postcode": "2010",
10 "state": "NSW",
11 "country": "Australia"
12 },
13 "items": [
14 {
15 "skuRef": "DM12345",
16 "requestedQuantity": 1
17 }
18 ],
19 "attributes": [
20 {
21 "name": "type",
22 "value": "special",
23 "type": "STRING"
24 }
25 ],
26 "retailerId": 1
27}Language: json
Name: Example request
Description:
[Warning: empty required content area]Response Parameters and sample
1entityType (string)
2type (string)
3id (string)
4count (integer)
5total (integer)
6limit (integer)
7orderType (string)
8locationRef (string)
9trackingId (string)
10retailerId (long)
11status (string)
12createdOn (string)
13ref (string)
14address (FulfilmentOptions.FulfilmentOptionsAddress)
15items (list of Item)
16attributes (list of Attribute)
17plans (list of FulfilmentPlan)
18unfulfilledItems (list of UnfulfilledItem)
19}
20
21FulfilmentOptionsAddress {
22 address1 (string)
23 address2 (string)
24 city (string)
25 postcode (string)
26 state (string)
27 country (string)
28 latitude (double)
29 longitude (double)
30 }
31
32Item {
33 skuRef (string)
34 requestedQuantity (integer)
35 availableQuantity (integer)
36 }
37
38Attribute {
39 name (string),
40 type (string) = ['STRING', 'TEXT', 'INTEGER', 'BOOLEAN', 'ADDRESS', 'OBJECT', 'CUSTOM'],
41 value (object)
42 }
43
44UnfulfilledItem {
45 skuRef (string)
46 unavailableQty (integer)
47 reasonCode (string)
48 reason (string)
49 }
50
51FufilmentPlan {
52 id (string)
53 retailerId (string)
54 planId (string)
55 planType (string)
56 eta (string)
57 splits (integer)
58 fulfilments (list of FulfilmentPlan.Fulfilment)
59 exceptions (list of Exception)
60 fulfilmentOptionsId (string)
61 attributes (list of Attribute)
62 status (string)
63 entityType (string)
64 flexType (string)
65 flexVersion (integer)
66 createdOn (string)
67 type (string)
68 ref (string)
69 }
70
71 Exception {
72 code (string)
73 message (integer)
74 attributes (list of Attribute)
75 }
76
77 FufilmentPlan.Fulfilment {
78 fulfilmentType (string)
79 locationRef (string)
80 eta (string)
81 items (list of FulfilmentPlan.Fulfilment.FulfilmentItem)
82 }
83
84FufilmentPlan.Fulfilment.FulfilmentItem {
85 skuRef (string)
86 availableQty (integer)Language: java
Name: Fulfillment Response Example
Description:
[Warning: empty required content area]1{
2 "id": "442755c4-28ee-4404-9e21-abe29bb3a1e5",
3 "limit": 10,
4 "count": 1,
5 "orderType": "HD",
6 "locationRef": "DR001",
7 "trackingId": "track",
8 "address": {
9 "address1": "46 Kippax Street",
10 "city": "Surry Hills",
11 "postcode": "2010",
12 "state": "NSW",
13 "country": "Australia"
14 },
15 "items": [
16 {
17 "skuRef": "DM12345",
18 "requestedQuantity": 1,
19 "availableQuantity": null
20 }
21 ],
22 "attributes": [
23 {
24 "name": "type",
25 "value": "special",
26 "type": "STRING"
27 }
28 ],
29 "status": "OPTIONS_PROVIDED",
30 "plans": [
31 {
32 "id": "d8d46b57-a2d8-472d-a632-c47916a6a0da",
33 "planId": "d8d46b57-a2d8-472d-a632-c47916a6a0da",
34 "eta": "20H",
35 "planType": "HD",
36 "splits": 0,
37 "flexType" : "FULFILMENT_PLAN::DEFAULT",
38 "flexVersion": 1,
39 "fulfilmentOptionsId": "442755c4-28ee-4404-9e21-abe29bb3a1e5",
40 "fulfilments": [
41 {
42 "fulfilmentType": "HD",
43 "locationRef": "123",
44 "eta": "20H",
45 "items": [
46 {
47 "skuRef": "DM12345",
48 "availableQty": 1
49 }
50 ]
51 }
52 ],
53 "attributes": [
54 {
55 "name": "type",
56 "value": "special",
57 "type": "STRING"
58 }
59 ],
60 "status": "COMPLETE",
61 "exceptions": [
62 {
63 "code": "1",
64 "message": "warning",
65 "attributes": [
66 {
67 "name": "type",
68 "value": "special",
69 "type": "STRING"
70 }
71 ]
72 }
73 ],
74 "retailerId": 1
75 }
76 ],
77 "unfulfilledItems": [
78 {
79 "skuRef": "DMI111",
80 "unavailableQty": 1,
81 "reasonCode": "123",
82 "reason": "Too Heavy"
83 }
84 ],
85 "retailerId": 1,
86 "flexType" : "FULFILMENT_OPTIONS::DEFAULT",
87 "flexVersion": 1
88}Language: java
Name: Example response
Description:
[Warning: empty required content area]View a Fulfillment Option
With this endpoint you can get details about a single Fulfillment Option.
GET:
`/api/v4.1/fulfilmentOptions/{id}`Request and response
Request parameters and sample
Fulfillment Option Request
`/api/v4.1/fulfilmentOptions/{id}`** Example request**
`/api/v4.1/fulfilmentOptions/{id}`Response Parameters and sample
Fulfillment Options Response
1{
2 entityType (string)
3 type (string)
4 id (string)
5 count (integer)
6 total (integer)
7 limit (integer)
8 orderType (string)
9 locationRef (string)
10 trackingId (string)
11 retailerId (long)
12 status (string)
13 createdOn (string)
14 ref (string)
15 address (FulfilmentOptions.FulfilmentOptionsAddress)
16 items (list of Item)
17 attributes (list of Attribute)
18 plans (list of FulfilmentPlan)
19 unfulfilledItems (list of UnfulfilledItem)
20
21
22 FulfilmentOptionsAddress {
23 address1 (string)
24 address2 (string)
25 city (string)
26 postcode (string)
27 state (string)
28 country (string)
29 latitude (double)
30 longitude (double)
31 }
32
33
34 Item {
35 skuRef (string)
36 requestedQuantity (integer)
37 availableQuantity (integer)
38 }
39
40 Attribute {
41 name (string),
42 type (string) = ['STRING', 'TEXT', 'INTEGER', 'BOOLEAN', 'ADDRESS', 'OBJECT', 'CUSTOM'],
43 value (object)
44 }
45
46 UnfulfilledItem {
47 skuRef (string)
48 unavailableQty (integer)
49 reasonCode (string)
50 reason (string)
51 }
52
53 FufilmentPlan {
54 id (string)
55 retailerId (string)
56 planId (string)
57 planType (string)
58 eta (string)
59 splits (integer)
60 fulfilments (list of FulfilmentPlan.Fulfilment)
61 exceptions (list of Exception)
62 fulfilmentOptionsId (string)
63 attributes (list of Attribute)
64 status (string)
65 entityType (string)
66 flexType (string)
67 flexVersion (integer)
68 createdOn (string)
69 type (string)
70 ref (string)
71 }
72
73 Exception {
74 code (string)
75 message (integer)
76 attributes (list of Attribute)
77 }
78
79 FufilmentPlan.Fulfilment {
80 fulfilmentType (string)
81 locationRef (string)
82 eta (string)
83 items (list of FulfilmentPlan.Fulfilment.FulfilmentItem)
84 }
85} Language: java
Name: Fulfillment Options Response Example
Description:
[Warning: empty required content area]Example response
1{
2 "id": "442755c4-28ee-4404-9e21-abe29bb3a1e5",
3 "limit": 10,
4 "count": 1,
5 "orderType": "HD",
6 "locationRef": "DR001",
7 "trackingId": "track",
8 "address": {
9 "address1": "46 Kippax Street",
10 "city": "Surry Hills",
11 "postcode": "2010",
12 "state": "NSW",
13 "country": "Australia"
14 },
15 "items": [
16 {
17 "skuRef": "DM12345",
18 "requestedQuantity": 1,
19 "availableQuantity": null
20 }
21 ],
22 "attributes": [
23 {
24 "name": "type",
25 "value": "special",
26 "type": "STRING"
27 }
28 ],
29 "status": "OPTIONS_PROVIDED",
30 "plans": [
31 {
32 "id": "d8d46b57-a2d8-472d-a632-c47916a6a0da",
33 "planId": "d8d46b57-a2d8-472d-a632-c47916a6a0da",
34 "eta": "20H",
35 "planType": "HD",
36 "splits": 0,
37 "flexType" : "FULFILMENT_PLAN::DEFAULT",
38 "flexVersion": 1,
39 "fulfilmentOptionsId": "442755c4-28ee-4404-9e21-abe29bb3a1e5",
40 "fulfilments": [
41 {
42 "fulfilmentType": "HD",
43 "locationRef": "123",
44 "eta": "20H",
45 "items": [
46 {
47 "skuRef": "DM12345",
48 "availableQty": 1
49 }
50 ]
51 }
52 ],
53 "attributes": [
54 {
55 "name": "type",
56 "value": "special",
57 "type": "STRING"
58 }
59 ],
60 "status": "COMPLETE",
61 "exceptions": [
62 {
63 "code": "1",
64 "message": "warning",
65 "attributes": [
66 {
67 "name": "type",
68 "value": "special",
69 "type": "STRING"
70 }
71 ]
72 }
73 ],
74 "retailerId": 1
75 }
76 ],
77 "unfulfilledItems": [
78 {
79 "skuRef": "DMI111",
80 "unavailableQty": 1,
81 "reasonCode": "123",
82 "reason": "Too Heavy"
83 }
84 ],
85 "retailerId": 1,
86 "flexType" : "FULFILMENT_OPTIONS::DEFAULT",
87 "flexVersion": 1
88}Language: json
Name: Example response
Description:
[Warning: empty required content area]Update Fulfillment Option Status
This endpoint changes the state of the Fulfillment Option entity.
PUT:
`/api/v4.1/fulfilmentOptions/state/{stateName}`1{
2"id": "442755c4-28ee-4404-9e21-abe29bb3a1e5"
3}Language: json
Name: Example response
Description:
[Warning: empty required content area]Response on Failures
NAME | TYPE | DESCRIPTION |
error | Array | Array of errors |
message | String | Additional information on the code Unauthorized | Bad Request | Forbidden | Not Found | Status 500 Error |
code | String | Status Code for the above messages 401 | 400 | 403 | 404 | 500 |
