Location API
Author:
Fluent Commerce
Changed on:
3 July 2024
Overview
A Location is any place where an order can be fulfilled and/or collected by the customer. Locations can include a store, warehouse, drop-ship vendor, lockers, or a third-party logistics or collection point.
Key points
- Overview
- Operations
- Models
Location API
Overview
Property | Value |
URL | |
Methods | |
Scheme | |
Auth | |
Permissions | |
Content-Type | |
Operations
[GET] /location Finds all Locations for the given criteria
Returns a page of Locations filtered by the given combination of parameters. If no parameters are provided, the default page size and sort order will be applied, and the Locations for which your authenticated user is authorized will be returned.
Authentication
Required
Permissions
LOCATION_VIEW permission required.
Parameters
Name | Default Value | Multiple? | Description |
retailerId | ❌ | The | |
agentNetwork | ✅ | The | |
agentNetworkTypes | ✅ | The | |
agentStatuses | ✅ | The | |
northEastLat | ❌ | Used to signify the most north east latitude (top right) corner of a map area to include in the location search | |
northEastLon | ❌ | Used to signify the most north east longitude (top right) corner of a map area to include in the location search | |
southWestLat | ❌ | Used to signify the most south west latitude (bottom left) corner of a map area to include in the location search | |
southWestLon | ❌ | Used to signify the most south west longitude (bottom left) corner of a map area to include in the location search | |
query | ❌ | A free text query search parameter | |
start | 0 | ❌ | The index of the first record of a page to be returned. |
count | 100 | ❌ | The number of results to be returned per page. Max 10000. |
Responses
Response Content-Type:
`application/json`Code | Description |
200 | Successful Operation |
400 | Client Error - Invalid Request |
401 | Authorization Error - Invalid Bearer Token / No permission |
403 | Authorization Error - Forbidden |
404 | Client Error - Not Found |
500 | Server Error |
Example
1 {
2 "start": 1,
3 "count": 100,
4 "hasMore": false,
5 "results": [
6 {
7 "locationId": "71",
8 "locationRef": "F_GFD",
9 "alternateId": null,
10 "name": "FC Fashion Imperial Centre Gosford",
11 "city": "Gosford",
12 "state": "NSW",
13 "country": "Australia",
14 "street": "171 Mann St",
15 "postcode": "2250",
16 "status": "ACTIVE",
17 "type": "STORE",
18 "createdOn": "2021-04-09",
19 "latitude": -33.41933105522871,
20 "longitude": 151.34394556084268,
21 "homeDeliverySafetyStock": null,
22 "clickAndCollectSafetyStock": null,
23 "distance": null,
24 "phoneNumber": null,
25 "openingHours": {
26 "mon": {
27 "start": 0,
28 "end": 0
29 },
30 "tue": {
31 "start": 0,
32 "end": 0
33 },
34 "wed": {
35 "start": 0,
36 "end": 0
37 },
38 "thu": {
39 "start": 0,
40 "end": 0
41 },
42 "fri": {
43 "start": 0,
44 "end": 0
45 },
46 "sat": {
47 "start": 0,
48 "end": 0
49 },
50 "sun": {
51 "start": 0,
52 "end": 0
53 }
54 },
55 "networkName": [
56 "F_CC"
57 ],
58 "directions": null
59 },
60 {
61 "locationId": "5",
62 "locationRef": "F_MEL",
63 "alternateId": null,
64 "name": "FC Fashion Melbourne",
65 "city": "Clayton",
66 "state": "VIC",
67 "country": "Australia",
68 "street": "Clayton Street",
69 "postcode": "3168",
70 "status": "ACTIVE",
71 "type": "STORE",
72 "createdOn": "2021-02-02",
73 "latitude": -37.8136,
74 "longitude": 144.9631,
75 "homeDeliverySafetyStock": null,
76 "clickAndCollectSafetyStock": null,
77 "distance": null,
78 "phoneNumber": null,
79 "openingHours": {
80 "mon": {
81 "start": 0,
82 "end": 0
83 },
84 "tue": {
85 "start": 0,
86 "end": 0
87 },
88 "wed": {
89 "start": 0,
90 "end": 0
91 },
92 "thu": {
93 "start": 0,
94 "end": 0
95 },
96 "fri": {
97 "start": 0,
98 "end": 0
99 },
100 "sat": {
101 "start": 0,
102 "end": 0
103 },
104 "sun": {
105 "start": 0,
106 "end": 0
107 }
108 },
109 "networkName": [
110 "FC_Group",
111 "F_VIC",
112 "F_CC"
113 ],
114 "directions": null
115 }
116 ]
117 }Language: json
Name: Response
Description:
[Warning: empty required content area]1 {
2 "errors": [
3 {
4 "code": "401",
5 "message": "Invalid user, Authorization header value does not belong to a valid user"
6 }
7 ]
8 } Language: json
Name: Example Error Response:
Description:
[Warning: empty required content area][GET] /location/{locationId} Finds a location by location ID
Returns the details of the Location filtered by the given location ID provided on the API.
Authentication
Required
Permissions
LOCATION_VIEW permission required.
Parameters
Name | Default Value | Multiple? | Description |
locationId | ❌ | The unique location identifier assigned by Fluent Commerce |
Responses
Response Content Type:
`application/json`Code | Description |
200 | Successful Operation |
400 | Client Error - Invalid Request |
401 | Authorization Error - Invalid Bearer Token / No permission |
403 | Authorization Error - Forbidden |
404 | Client Error - Not Found |
500 | Server Error |
Example
1 {
2 "locationRef": "SHA108",
3 "status": "ACTIVE",
4 "name": "Seed Heritage Wintergarden",
5 "email": "customercare@seedheritage.com",
6 "supportPhone": "07 3012 7749",
7 "type": "STORE",
8 "timeZone": "Australia/Queensland",
9 "pickAndPackTimeLimit": 15,
10 "homeDeliverySafetyStock": 2,
11 "clickAndCollectSafetyStock": 0,
12 "clickAndCollectNetworks": [],
13 "useInventoryForHomeDelivery": [
14 "433"
15 ],
16 "useInventoryForClickAndCollect": [
17 "437"
18 ],
19 "address": {
20 "city": "Brisbane",
21 "country": "Australia",
22 "postcode": "4000",
23 "state": "QLD",
24 "street": "TENANCY QSM 101A QUEENS ST MALL",
25 "latitude": "-27.469712",
26 "longitude": "153.02568"
27 },
28 "openingHours": {
29 "monStartMin": "900",
30 "monEndMin": "1000",
31 "tueStartMin": "900",
32 "tueEndMin": "1000",
33 "wedStartMin": "900",
34 "wedEndMin": "1000",
35 "thuStartMin": "900",
36 "thuEndMin": "1000",
37 "friStartMin": "900",
38 "friEndMin": "1000",
39 "satStartMin": "900",
40 "satEndMin": "1000",
41 "sunStartMin": "900",
42 "sunEndMin": "1000"
43 },
44 "storageAreas": []
45 }Language: json
Name: Response
Description:
[Warning: empty required content area]1 {
2 "errors": [
3 {
4 "code": "401",
5 "message": "Invalid user, Authorization header value does not belong to a valid user"
6 }
7 ]
8 } Language: json
Name: Example Error Response:
Description:
[Warning: empty required content area][GET] /location/{locationId}/attribute Retrieves Location Attributes
Returns all the attributes of a Location filtered by the Location Id provided on the API.
Authentication
Required
Permissions
LOCATION_VIEW permission required.
Parameters
Name | Default Value | Multiple? | Description |
locationId | ❌ | The unique location identifier assigned by Fluent Commerce |
Responses
Response Content-Type:
`application/json`Code | Description |
200 | Successful Operation |
400 | Client Error - Invalid Request |
401 | Authorization Error - Invalid Bearer Token / No permission |
403 | Authorization Error - Forbidden |
404 | Client Error - Not Found |
500 | Server Error |
Example
1 {
2 "locationId": "16567",
3 "attributes": [
4 {
5 "name": "Safety instructions",
6 "type" : "string",
7 "value": "Wear safety grear"
8 },
9 {
10 "name": "Order code 2",
11 "type" : "string",
12 "value": "124"
13 },
14 {
15 "name": "Address",
16 "type" : "address",
17 "value" : {
18 "Address 1" : "46, Kipax Street",
19 "Suburb" : "Surry Hills",
20 "Post code" : "2010",
21 "State" : "NSW"
22 }
23 }
24 ]
25 }Language: json
Name: Response
Description:
[Warning: empty required content area]1 {
2 "errors": [
3 {
4 "code": "401",
5 "message": "Invalid user, Authorization header value does not belong to a valid user"
6 }
7 ]
8 } Language: json
Name: Example Error Response:
Description:
[Warning: empty required content area][GET] /location/{locationId}/storageArea/{storageAreaRef} Retrieves details of a Location's Storage Area
Returns the details of the Location's Storage Area filtered by the Location Id and the associated
`storageAreaRef`Authentication
Required
Permissions
LOCATION_VIEW permission required.
Parameters
Name | Default Value | Multiple? | Description |
locationId | ❌ | The unique location identifier assigned by Fluent Commerce | |
storageAreaRef | ❌ | The |
Responses
Response Content-Type:
`application/json`Code | Description |
200 | Successful Operation |
400 | Client Error - Invalid Request |
401 | Authorization Error - Invalid Bearer Token / No permission |
403 | Authorization Error - Forbidden |
404 | Client Error - Not Found |
500 | Server Error |
Example
1 {
2 "externalId": "12345",
3 "status": "ENABLED",
4 "type": "SERVICE_COUNTER",
5 "attributes": [{"name": "toTime", "type": null, "value": "2016-11-28 16:30:22"}]
6 }Language: json
Name: Response
Description:
[Warning: empty required content area]1 {
2 "errors": [
3 {
4 "code": "401",
5 "message": "Invalid user, Authorization header value does not belong to a valid user"
6 }
7 ]
8 } Language: json
Name: Example Error Response:
Description:
[Warning: empty required content area][POST] /location Creates a new Location in the Fluent Platform
Create a new Location within the Fluent Platform.
Authentication
Required
Permissions
LOCATION_VIEW, LOCATION_CREATE and LOCATION_EDIT permissions are required.
Parameters
Name | Description |
body *required | The Location object that needs to be created |
Responses
Response Content-Type:
`application/json`Code | Description |
200 | Successful Operation |
400 | Client Error - Invalid Request |
401 | Authorization Error - Invalid Bearer Token / No permission |
403 | Authorization Error - Forbidden |
404 | Client Error - Not Found |
500 | Server Error |
Example:
1 {
2 "locationRef": "Tes92909",
3 "status": "ACTIVE",
4 "name": "Test User",
5 "email": "test@parcelpoint.com.au",
6 "supportPhone": "123-567",
7 "type": "STORE",
8 "timeZone": "Australia/Sydney",
9 "homeDeliverySafetyStock": null,
10 "clickAndCollectSafetyStock": null,
11 "directions": "directions to a location",
12 "address" : {
13 "city": "Sydney",
14 "country": "Australia",
15 "postcode": "2000",
16 "state": "NSW",
17 "street": "46 kippax street"
18 },
19 "openingHours" : {
20 "monStartMin": "0900",
21 "monEndMin": "1800",
22 "tueStartMin": "0900",
23 "tueEndMin": "1800",
24 "wedStartMin": "0900",
25 "wedEndMin": "1800",
26 "thuStartMin": "0900",
27 "thuEndMin": "1800",
28 "friStartMin": "0900",
29 "friEndMin": "1800",
30 "satStartMin": "0900",
31 "satEndMin": "1800",
32 "sunStartMin": "0900",
33 "sunEndMin": "1800"
34 },
35 "storageAreas": [
36 "AAA" ,
37 "BBB"
38 ],
39 "agentNetworks": [
40 "1221",
41 "4234"
42 ]
43 }Language: json
Name: Request body
Description:
[Warning: empty required content area]1 {
2 "id": "65789"
3 }Language: json
Name: Example Success Response:
Description:
[Warning: empty required content area]1 {
2 "errors": [
3 {
4 "code": "401",
5 "message": "Invalid user, Authorization header value does not belong to a valid user"
6 }
7 ]
8 }Language: json
Name: Example Error Response:
Description:
[Warning: empty required content area][PUT] /location/{locationId} Update an existing Location in the Fluent Platform
Update an existing Location within the Fluent Platform.
Authentication
Required
Permissions
LOCATION_VIEW and LOCATION_EDIT permissions are required.
Parameters
Name | Default Value | Multiple? | Description |
locationId | ❌ | The unique location identifier assigned by Fluent Commerce | |
body *required | ❌ | The Updated Location object |
Responses
Response Content-Type:
`application/json`Code | Description |
200 | Successful Operation |
400 | Client Error - Invalid Request |
401 | Authorization Error - Invalid Bearer Token / No permission |
403 | Authorization Error - Forbidden |
404 | Client Error - Not Found |
500 | Server Error |
Example
1 {
2 "locationRef": "Tes92909",
3 "status": "ACTIVE",
4 "name": "Test User",
5 "email": "test@parcelpoint.com.au",
6 "supportPhone": "123-567",
7 "type": "STORE",
8 "timeZone": "Australia/Sydney",
9 "address" : {
10 "city": "Sydney",
11 "country": "Australia",
12 "postcode": "2000",
13 "state": "NSW",
14 "street": "46 kippax street"
15 },
16 "openingHours" : {
17 "monStartMin": "0900",
18 "monEndMin": "1800",
19 "tueStartMin": "0900",
20 "tueEndMin": "1800",
21 "wedStartMin": "0900",
22 "wedEndMin": "1800",
23 "thuStartMin": "0900",
24 "thuEndMin": "1800",
25 "friStartMin": "0900",
26 "friEndMin": "1800",
27 "satStartMin": "0900",
28 "satEndMin": "1800",
29 "sunStartMin": "0900",
30 "sunEndMin": "1800"
31 },
32 "storageAreas": [
33 "G1",
34 "G2"
35 ],
36 "attributes": [
37 {
38 "name": "Location code 1",
39 "type" : "string",
40 "value": "G334"
41 }
42 ]
43 }Language: json
Name: Request body
Description:
[Warning: empty required content area]1 {
2 "id": "65789"
3 }Language: json
Name: Example Success Response:
Description:
[Warning: empty required content area]1 {
2 "errors": [
3 {
4 "code": "401",
5 "message": "Invalid user, Authorization header value does not belong to a valid user"
6 }
7 ]
8 }Language: json
Name: Example Error Response:
Description:
[Warning: empty required content area][PUT] /location/eta Update Location ETA
Update transit time between from location and to location based on distance and regular transport mechanisms.
Authentication
Required
Permissions
LOCATION_VIEW and LOCATION_EDIT permissions are required.
Parameters
Name | Default Value | Multiple? | Description |
etas array *required | ❌ | An array of etas with from location, to location and the eta value |
Responses
Response Content Type:
`application/json`Code | Description |
200 | Successful Operation |
400 | Client Error - Invalid Request |
401 | Authorization Error - Invalid Bearer Token / No permission |
403 | Authorization Error - Forbidden |
404 | Client Error - Not Found |
500 | Server Error |
Example:
1 {
2 "etas": [
3 {
4 "fromLocation": 538045,
5 "toLocation": 538044,
6 "eta": 45
7 },
8 {
9 "fromLocation": 538046,
10 "toLocation": 538045,
11 "eta": 57
12 },
13 {
14 "fromLocation": 8977,
15 "toLocation": 538044,
16 "eta": 10
17 }
18 ]
19 }Language: json
Name: Request body
Description:
[Warning: empty required content area]1 {
2 "updatedEtas": [
3 {
4 "fromLocation": 538045,
5 "toLocation": 538044,
6 "eta": 45
7 },
8 {
9 "fromLocation": 538046,
10 "toLocation": 538045,
11 "eta": 57
12 }
13 ]
14 }Language: json
Name: Example Success Response:
Description:
[Warning: empty required content area]1 {
2 "failedEtas": [
3 {
4 "fromLocation": 8977,
5 "toLocation": 538044,
6 "error": "Object of type [Agent] was not found using id : [8977]"
7 }
8 ]
9 }Language: json
Name: Example Error Response:
Description:
[Warning: empty required content area]Models
Location Model
Key | Type | Mandatory? | Possible Values | Constraints | Description |
locationRef | String | ✅ | Max length: 8 Characters | The location number provided by the retailer | |
locationId | String | ❌ | The unique location identifier assigned by Fluent Commerce | ||
alternateId | String | ❌ | Max length: 8 Characters | External reference 2 | |
status | String | ✅ | ACTIVE, INACTIVE | The location status | |
name | String | ✅ | The name of the location | ||
String | ✅ | The location email | |||
supportPhone | String | ✅ | Max length: 20 Characters | The location contact number | |
type | String | ✅ | STORE, WAREHOUSE | Type of the location | |
timeZone | String | ✅ | Time Zone associated with the location | ||
pickAndPackTimeLimit | Integer | ✅ | 1. Excludes non-trading hours 2. Does not apply to warehouse fulfilment or Click & Collect orders | The Pick & Pack Time Limit defines the time permitted to complete a fulfilment in store. If a fulfilment reaches this expiry time, it will be reassigned or cancelled as per the reassignment rules. The Pick & Pack time limit is shown in hours. The default is 3 hours. | |
clickAndCollectNetworks | Array | ❌ | |||
useInventoryForHomeDelivery | Array | ❌ | | The Location acts as a fulfillment center for the Home Delivery networks listed | |
useInventoryForClickAndCollect | Array | ❌ | | The Location acts as a fulfillment center for the Click & Collect networks listed | |
storageAreas | Array | ❌ | List of all storage areas at the location | ||
address | Address | ✅ | The address of the location including retailer's business name, name of the location, | ||
openingHours | Object [dayStartMin(double), dayEndMin(double), allHours(Boolean)] | ✅ | | ||
agentNetworks | Array | ❌ | | List of networks this location is assigned to | |
homeDeliverySafetyStock | String | ❌ | Only applies for clients with inventory integrations. Use 'NULL' when Safety Stock Levels do not apply | The Home Delivery safety stock level configured for this location. This figure is used to calculate the Available to Sell (ATS) inventory. | |
clickAndCollectSafetyStock | String | ❌ | Only applies for clients with inventory integrations. Use 'NULL' when Safety Stock Levels do not apply. | The Click & Collect safety stock level configured for this location. This figure is used to calculate the Available to Sell (ATS) inventory. | |
agentNetworkTypes | Array | ❌ | CP, CC, HD | Search parameter used to retrieve Locations within a specific agent network type. CP - Collection Point network, CC - Click & Collect network, HD - Home Delivery network | |
etas | Array [fromLocation(Long), toLocation(Long), eta(Long)] | ❌ | Estimated transit time between two locations. This is used to calculate time of availability when goods have to be shipped form one location to other for Click'n Collect orders. Array includes fromLocation, toLocation and eta | ||
externalId | String | ❌ | Location External reference (Retailers reference to identify location). | ||
retailerId | String | ❌ | The retailer identifier assigned by Fluent Commerce | ||
sort | String | ❌ | By default, the search results are sorted by name in ascending order. Currently only default sorting is supported | ||
query | String | ❌ | Location reference or location name to search for | ||
distance | Integer | ❌ | Distance from centre of map to location | ||
directions | String | ❌ | Instructions to get to location | ||
createdOn | DateTime | ❌ | Date/time when the Location was created | ||
attributes | Array [name(String), type(String), value(String)] | ❌ | Array of attributes. Attributes are used to provide additional information about the order. Standard attribute types like string, integer and complex types like address which has more than one value are supported as well. Array includes |
Error Model
Key | Type | Possible Values | Description |
errors | Array | List of errors | |
code | String | 400, 401, 403, 404, 500 | error code |
message | String | description of the error |
