Order API

Home
Essential Knowledge
By Type
Building Blocks
APIs
Releases

Essential knowledge

Author:

Fluent Commerce

Changed on:

3 July 2024

Overview

An order is a customers request to purchase one or more items from a retailer. An order is created when a customer completes the checkout process against a Retailer Products.

Key points

Order API is used to create an order in the system.
Customer and Products information should be available.
Order details like, order items, transaction details, fulfilment choice, customer and delivery information are all required to create an order.

Deprecation Notice

This REST API has been deprecated and replaced with GraphQL APIs. Please process the entity using the appropriate GQL mutations.

Property	Value
URL	<root_url>/api/v4.1/order <root_url>/api/v4.1/order/{orderId} <root_url>/api/v4.1/order/{orderId}/attribute <root_url>/api/v4.1/order/{orderId}/cancel
Methods	GET, POST, PUT
Scheme	https
Auth	OAUTH
Permissions	ORDER_VIEW
Content-Type	application/json

Order Properties

Below are the order properties of which are available in the order object and can be updated and retrieved via the order API's.

1. createdOn

Type: String

Description:

`{ "createdOn" : "2016-10-23T23:04:39.083Z" }`

Date/time when the Order was created.

2. orderRef

Type: String

Description:

`{ "orderRef" : "23451789" }`

The unique order reference provided by the retailer.

3. orderId

Type: String

Description:

`{ "orderId" : "16425" }`

The unique order id assigned by Fluent Commerce.

4. type

Type: String

Description:

`{ "type" : "CC" }`

Type of order - click & collect (CC) or home delivery (HD) etc.

Possible values are: - **CC - **SFS - **HD - **RETURN

5. retailerId

Type: String

Description:

`{"type" : "003SurryHillsStore"}`

The unique Identification number of the retailer.

6. customer

Type: Object

1{"customerRef" : "3624"}
2{"email" : "customer@emailclient.com"}
3{"firstname" : "John"}
4{"lasname" : "Smith"}
5{"mobile" : "04xx 999 111"}

Language: plain_text

Name: Description

Description:

[Warning: empty required content area]

customerId (Integer, Optional) : Provide if existing customer. Mutually exclusive with name, email and mobile.
customerRef (String, Mandatory): Retailer reference for the customer.
firstName (String, Compulsory): Customers First Name - firstName is not required in order API, but in DB it's not null.
lastName (String, Optional): Customers Last Name - lastName is not required in order API.
email (String, Optional): Customer's email address.
mobile (String, Optional): Customer's mobile number

7. fulfilmentChoice

Type: Object

1{ "fulfilmentPrice" : "9.99" }
2{ "fulfilmentTaxPrice" : "null" }
3{ "currency" : "AUD" }
4{ "pickupLocationRef" : "1013" }
5{ "deliveryType" : "STANDARD" }
6{ "deliveryInstruction" : "Leave at front door" }
7

Language: plain_text

Name: Description

Description:

[Warning: empty required content area]

The fulfillment choice specified when booking the order

fulfilmentType (String, Optional): Indicates what fulfilment locations should be used. Allowed values are:
- CC_PFS ( Click & Collect - Pick from Store),
- CC_PFDC ( Click & Collect - Pick from DC)
- HD_PFS (Home Delivery - Pick from Store)
- HD_PFDC ( Home Delivery - Pick from DC)
fulfilmentPrice (Double, Optional): FulfilmentPrice refers to shipping fees if the order type is Home Delivery HD & C&C Fees for Click & Collect orders.
fulfilmentTaxPrice (Double, Optional): This refers to the tax cost associated with the fulfilment price.
currency (String, Optional): The type of currency, 3 letter ISO currency code.
pickupLocationRef (String, Optional): Pickup location is required for click & collect orders.
deliveryType (String, Optional): Based on retailers shipping options. Retailer fulfilment rules will determine how an order is handled. Example values are STANDARD, EXPRESS, OVERNIGHT, 3HOURS.
deliveryInstruction (String, Optional): Instruction provided by the customer ( 250 Character limit).
address (Object, Optional): Delivery address. Required if it is a home delivery.

8. items

Type: Array

1
2{ "skuRef" : "FX141123TPRT-1-2" }
3{ "requestedQty" : "1" }
4{ "skuPrice" : "59.99" }
5{ "skuTaxPrice" : "null" }
6{ "totalPrice" : "59.99" }
7{ "totalTaxPrice" : "null" }
8{ "taxType" : "null" }
9{ "currency" : "AUD" }
10{ "imageUrlRef" : "null" }

Language: json

Name: Description

Description:

[Warning: empty required content area]

An array of order line item objects in order.

skuId (String, Optional): The unique identifier that is generated when an SKU is created.
skuRef (String, Compulsory): The unique reference or code provided externally.
requestedQty (Integer, Optional): The total quantity being requested for fulfilment.
skuPrice (Double, Optional): The amount paid for the unit item excluding tax.
skuTaxPrice (Double, Optional): The amount of tax paid for the unit item.
totalPrice (Double, Compulsory): The total amount paid for the line item excluding tax.
totalTaxPrice (Double, Optional): The total amount of tax paid for the line item.
taxType (String, Optional): Identified what type of tax is associated with the Order Item.
Allowed values are:
- GST,
- VAT,
- EXCL
- TAX
currency (String, Optional): The type of currency used to pay for the unit, this should be provided if the amount is received, 3 letter ISO currency code.
imageUrlRef (String, Optional): Can be used to provide the Image URL so that order items have an image displayed.
comments (Array[CommentRequest], optional) : Array of comments.

9. Location

Type: Object

1
2
3{ "companyName" : "null" }
4{ "street" : "25, James drive" }
5{ "city" : "Sydney" }
6{ "postcode" : "2000" }
7{ "state" : "NSW" }
8{ "country" : "AU" }

Language: plain_text

Name: Description

Description:

[Warning: empty required content area]

Fulfillment choice address

locationRef(String, Optional): Reference provided by the retailer.
companyName(String, Optional): Name of the company if delivering to a business location.
street(String, Optional): customer street address.
city(String, Optional): Customers city.
postcode(String, Optional): Customers postcode details.
state(String, Optional): Customers state.
country(String, Optional): Customers country

10. Attributes

Type: Array

Description:

1"attributes": [
2{
3"name" : "Supplier Address",
4"type" : "address",
5"value" : {
6    "value" : "46, Kippax Street",
7    "Suburb" : "Surry Hills",
8    "Post Code" : "2010",
9    "State" : "NSW,
10    "State" : "AU"
11    }
12},
13
14{
15"name" : "ECP",
16"type" : "string",
17"value" : "XSD987"
18}
19
20]

Language: json

Name: Order Attributes

Description:

Order Attributes and its value like,
ShipFrom address
ShipTo address
Price
Items
Packing instructions

An array of attributes. Attributes are used to provide additional information about the order. Standard attribute types like string, and integer and complex types like address which has more than one value are supported as well.

name (String, Optional): Name of attributes.
type (String, Optional): Type of value provided (String, Integer, Address etc).
value (String, Optional): attribute value

11. CommentRequest

Type: Array

1{ "entityId" : "124232" }
2{ "entityType" : "ORDER" }
3{ "retailerId" : "Order item comment" }

Language: plain_text

Name: Description

Description:

[Warning: empty required content area]

An array of commentRequest objects. One or more comments per order item.

body (String, Optional): Comment text. Max length 200 characters per comment.
entityId (String, Optional): ID of the entity.
entityType (String, Optional): = Entity type. Allowed values are:
- ORDER'
- FULFILMENT
- CONSIGNMENT
retailerId (String, Optional): Retailer ID

What you can do with Order API

Create a new order

This API is used to create an order in the system. Information such as order details, order items, transaction details, fulfilment choice, and customer and delivery information are all required to create an order.

POST:

`/api/v4.1/order`

Request and response

Request parameters and sample

Order Request

1OrderRequest {
2    attributes (Array[Attribute], optional),
3    
4    Attribute {
5        name (string, optional),
6        type (string, optional) = ['STRING', 'INTEGER'],
7        value (string, optional)
8        },
9    customer (Customer, optional),
10    
11    Customer {
12
13        customerId (integer, optional),
14        customerRef (string, optional),
15        email (string, optional),
16        firstName (string, optional),
17        lastName (string, optional),
18        mobile (string, optional)
19        },
20    fulfilmentChoice (FulfilmentChoice,optional),
21    
22    FulfilmentChoice {
23        address (Location, optional),
24    
25    Location {
26
27        city (string, optional),
28        companyName (string, optional),
29        country (string, optional),
30        locationRef (string, optional),
31        name (string, optional),
32        postcode (string, optional),
33        state (string, optional),
34        street (string, optional)
35    },
36    currency (string, optional),
37
38    fulfilmentPrice (number, optional), fulfilmentTaxPrice (number, optional), 
39    fulfilmentType (string, optional) = ['CFS', 'STC', 'SFDC', 'CC_PFS', 'CC_PFDC', 'HD_PFS', 'HD_PFDC', 'R_RTDC', 'R_RTS'], 
40    preferredLocationRef (string, optional) },
41    
42    fulfilments (Array[Fulfilment], optional),
43    
44    Fulfilment {
45
46        fulfilmentId (string, optional),
47        fulfilmentRef (string, optional),
48        fulfilmentType (string, optional) = ['CFS', 'STC', 'SFDC', 'CC_PFS', 'CC_PFDC', 'HD_PFS', 'HD_PFDC', 'R_RTDC', 'R_RTS'],
49        orderId (string, optional),
50        status (string, optional)
51        },
52    items (Array[OrderItem], optional),
53    
54    OrderItem {
55        comments (Array[CommentRequest],optional),
56
57"""- note "FulfilmentChoice"""     
58            CommentRequest {
59                body (string, optional),
60                entityId (string, optional),
61                entityType (string, optional) = ['ORDER', 'FULFILMENT', 'CONSIGNMENT'],
62                retailerId (string, optional)
63                },
64
65        currency (string, optional),
66
67        imageUrlRef (string, optional),
68        productId (string, optional),
69        requestedQty (integer, optional),
70        skuId (string, optional),
71        skuPrice (number, optional),
72        skuRef (string, optional),
73        skuTaxPrice (number, optional),
74        taxType (string, optional) = ['GST', 'VAT', 'EXCLTAX'],
75        totalPrice (number, optional),
76        totalTaxPrice (number, optional)
77    },
78
79    orderRef (string, optional),
80    retailerId (string, optional),
81    totalPrice (number, optional),
82    totalTaxPrice (number, optional),
83    type (string, optional) = ['CC', 'SFS', 'HD', 'RETURN']
84
85}

Language: json

Name: Order Request

Description:

Order info like,
CustomerId, CustomerRef, Firstname, Lastname, Address
FulfillmentChoice
Location
Fulfillment plan
OrderItem

1{
2 "customer":{
3 "firstName":"nick",
4 "lastName":"yaw",
5 "customerRef":"00006T5B",
6 "mobile":"0410496842",
7 "email":"nick@parcelpoint.com.au"
8 },
9 "items":[
10 {
11 "skuRef":"117161458",
12 "skuPrice":19.99,
13 "totalPrice":59.99,
14 "requestedQty":1
15 }
16 ],
17 "orderRef":"1171615111",
18 "retailerId":"433",
19 "fulfilmentChoice":{
20 "fulfilmentPrice":0,
21 "fulfilmentTaxPrice":0,
22 "fulfilmentType":"HD_PFS",
23 "deliveryType":"STANDARD",
24 "deliveryInstruction":"home delivery",
25 "address":{
26 "name":"nrjxp",
27 "street":"24 pacific higway",
28 "city":"Wahroonga",
29 "postcode":"2076",
30 "state":"NSW",
31 "country":"Australia"
32 }
33 },
34 "type":"HD"
35}

Language: json

Name: Order Example

Description:

Order sample with values - OrderApi field values

Response Parameters and sample

Order response

1SuccessMessageResponse {
2    id (object, optional),
3    message (string, optional),
4    status (string, optional)
5    }

Language: json

Name: Order Response

Description:

Order Response msg. with status

1{
2 "id": 427323
3}

Language: json

Name: Example Response

Description:

Sample Response Id

Get the details of an order

This API is used to retrieve the information about an order

GET:

`/api/v4.1/order/{orderId}`

Request and response

Request parameters and sample

Parameters in URL

Name

Type

Required

Description

orderId

`String`

Yes

The Order Id

Example request /api/v4.1/order/41241412412

Response Parameters and Sample

Order response

1OrderResponse {
2createdOn (string, optional),
3customer (Customer, optional),
4
5Customer {
6    customerId (integer, optional),
7    customerRef (string, optional),
8    email (string, optional),
9    firstName (string, optional),
10    lastName (string, optional),
11    mobile (string, optional)
12   },
13   fulfilmentChoice (FulfilmentChoice,optional),
14   
15   FulfilmentChoice {
16    address (Location, optional),
17    
18    currency (string, optional),
19    fulfilmentPrice (number, optional),
20    fulfilmentTaxPrice (number, optional),
21    fulfilmentType (string, optional) = ['CFS', 'STC', 'SFDC', 'CC_PFS', 'CC_PFDC', 'HD_PFS', 'HD_PFDC', 'R_RTDC', 'R_RTS'],
22    preferredLocationRef (string, optional)
23   },
24   fulfilments (Array[Fulfilment], optional),
25   
26   Fulfilment {
27    fulfilmentId (string, optional),
28    fulfilmentRef (string, optional),
29    fulfilmentType (string, optional) = ['CFS', 'STC', 'SFDC', 'CC_PFS', 'CC_PFDC', 'HD_PFS', 'HD_PFDC', 'R_RTDC', 'R_RTS'],
30    orderId (string, optional),
31    status (string, optional)
32   },
33   items (Array[OrderItem], optional),
34   
35   OrderItem {
36    comments (Array[CommentRequest],optional),
37    
38    CommentRequest {
39        body (string, optional),
40        entityId (string, optional),
41        entityType (string, optional) = ['ORDER', 'FULFILMENT', 'CONSIGNMENT'],
42        retailerId (string, optional)
43       },
44       
45    currency (string, optional),
46
47    imageUrlRef (string, optional),
48    productId (string, optional),
49    requestedQty (integer, optional),
50    skuId (string, optional),
51    skuPrice (number, optional),
52    skuRef (string, optional),
53    skuTaxPrice (number, optional),
54    taxType (string, optional) = ['GST', 'VAT', 'EXCLTAX'],
55    totalPrice (number, optional),
56    totalTaxPrice (number, optional)
57   },
58   orderId (string, optional), orderRef (string, optional), retailer (Retailer, optional),
59   
60   {
61    retailerId (string, optional)
62   },
63   status (string, optional),
64    type (string, optional) = ['CC', 'SFS', 'HD', 'RETURN'] 
65    stringEnum:"CC", "SFS", "HD", "RETURN" 
66}
67    
68

Language: json

Name: Order Response

Description:

Order Response
CustomerId, CustomerRef, Firstname, Lastname, Address
FulfillmentChoice
Location
Fulfillment plan
OrderItem

1{
2"orderId": "16567",
3"orderRef": "1442900789",
4"status": "BOOKED",
5"type": "HD",
6"customer": {
7"customerId": 310728,
8"customerRef": "08141413",
9"firstName": "Rick",
10"lastName": "Leathers",
11"email": "nick@parcelpoint.com.au",
12"mobile": "0424188192"
13},
14"retailer": {
15"retailerId": "211"
16},
17"fulfilments": [
18{
19"orderId": "16567",
20"fulfilmentId": "4160",
21"fulfilmentRef": null,
22"status": "CREATED",
23"fulfilmentType": "HD_PFDC"
24}
25],
26"items": [
27{
28"imageUrlRef": "",
29"requestedQty": 1,
30"skuId": "198005",
31"skuRef": "FX141123TPRT-1-2",
32"skuPrice": 59.99,
33"skuTaxPrice": null,
34"totalPrice": 59.99,
35"totalTaxPrice": null,
36"taxType": null,
37"currency": null
38}
39],
40"fulfilmentChoice": {
41"fulfilmentType": "HD_PFDC",
42"fulfilmentPrice": null,
43"fulfilmentTaxPrice": null,
44"currency": null,
45"pickupLocationRef": null,
46"deliveryType": "STANDARD",
47"deliveryInstruction": "home delivery",
48"address": {
49"locationRef": "1013",
50"companyName": null,
51"name": "TestUser",
52"street": "24 pacific higway",
53"city": "wahroonga",
54"postcode": "123456",
55"state": "SFO",
56"country": "USA"
57}
58}
59}
60

Language: json

Name: Example Response

Description:

Sample Order Response with attribute values,

OrderId, Orderref,
CustomerId, Firstname, Lastname, email, phone#
RetailerId, FulfillmentChoice, FulfillmentId,
SkuId, price, units, currency
Shipfrom Address, Shipto address,
etc .....

Search for orders

This API returns a list of orders against a given set of search criteria

GET:

`/api/v4.1/order`

Example:

`/api/v4.1/order?customerRef=1234`

Cancel an order

This API is used to cancel an existing order. Orders can be cancelled only if the fulfilment has been created but not yet actioned or if the order is in a cancelled or rejected state.

POST:

`/api/v4.1/order/{orderId}/cancel`

Request and response

Request parameters and sample

Order request

`/api/v4.1/order/{orderId}/cancel`

Example request

`/api/v4.1/order/427323/cancel`

Response Parameters and sample

Order response

1SuccessMessageResponse {
2    id (object, optional),
3    message (string, optional),
4    status (string, optional)
5}

Language: json

Name: Order Response

Description:

Order msg.Id, msg desc. and status

1{
2 "id":"427323"
3}

Language: json

Name: Example Response

Description:

Sample Response with Id

Update order attributes

This API is used to update additional information (attributes) and store it against the order.

PUT:

`/api/v4.1/order/{orderId}/attribute`

Request and response

Request parameters and sample

Order request

1OrderRequest {
2   attributes (Array[Attribute], optional),
3   
4   Attribute {
5    name (string, optional),
6    type (string, optional) = ['STRING', 'INTEGER'],
7    value (string, optional)
8   }
9}
10

Language: json

Name: Order Request

Description:

Order Request with parameter Attributes

1{
2"attributes": [
3{
4"name": "Order code 1",
5"type" : "string"
6"value": "123"
7},
8{
9"name": "Order code 2",
10"type" : "string"
11"value": "124"
12},
13{
14"name": "Address",
15"type" : "address",
16"value" : {
17"Address 1" : "46, Kipax Street",
18"Suburb" : "Surry Hills"
19"Post code" : "2010",
20"State" : "NSW"
21}
22}
23]
24}

Language: json

Name: Example Request

Description:

Sample Request with Attribute values.

This API is used to update additional information (attributes) and store it against the order.
Order info., Address

Response parameters and sample

Order response

1attributeResponse{
2   updatedAttributes (Array[attributeRecord], optional), [
3   Attribute {
4    name (string, optional),
5    value (string, optional)
6   }
7  ],
8  
9  failedAttributes (Array[attributeFailureRecord], optional), [
10      Attribute {
11        name (string, optional),
12        value (string, optional),
13        error (string, optional),
14      }
15    ]
16    
17}

Language: json

Name: Order Response

Description:

Order Response in,
UpdateAttributes name and values
Failed Attributes name and values

1{
2"updatedattributes": [ {
3"name": "ordercode_1",
4"value": "123"
5},
6{
7"name": "ordercode_2",
8"value": "124"
9}],
10"failedattributes": [
11{
12"name": "address",
13"value" : {
14"Address 1" : "46, Kipax Street",
15"Suburb" : "Surry Hills"
16"Post code" : "2010",
17"State" : "NSW"
18},
19"error": "attributes not allowed for the user ID : [8977]"
20}
21]
22}

Language: json

Name: Example Response

Description:

Sample Response on,
UpdateAttributes name and values,
FailureAttributes name and values

and error msg.

Read order attributes

This API is used to retrieve existing attributes of an order.

GET:

`/api/v4.1/order/{orderId}/attribute`

Request and response

Request parameters and sample

Order request

`/api/v4.1/order/{orderId}/attribute`

Example request

`/api/v4.1/order/16567/attribute`

Response Parameters and sample

1orderResponse {
2orderId (string),
3attributes (array), [
4    attributes {
5    name (string),
6    type (string),
7    value (string)
8   }
9  ]
10
11}

Language: json

Name: Order Response

Description:

Order Response with Attributes,
OrderId and its values

1{
2"orderId": "16567",
3"attributes": [
4{
5"name": "Order code 1",
6"type" : "string",
7"value": "123"
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: Example Response

Description:

Sample Response with attribute values,
OrderId
Name and address with values

Response on Failures

NAME	TYPE	DESCRIPTION
error	`Array`	Array of errors
message	`String`	Additional information on the code Unauthorised \| Bad Request \| Forbidden \| Not Found \| Status 500 Error
code	`String`	Status Code for the above messages 401 \| 400 \| 403 \| 404 \| 500

Order API

Overview

Key points

Order Properties

1. createdOn

2. orderRef

3. orderId

4. type

5. retailerId

6. customer

7. fulfilmentChoice

8. items

9. Location

10. Attributes

11. CommentRequest

What you can do with Order API

Create a new order

Get the details of an order

Search for orders

Cancel an order

Update order attributes

Read order attributes

Response on Failures

Fluent Commerce

Building Blocks

By Type

Helpful Resources

Quick Links