Order API Basics¶
You can manage orders from the Applications menu or with REST APIs. Call the headless-admin-commerce-order services to create and manage orders.
Adding an Order¶
Start a new Liferay DXP instance by running
docker run -it -m 8g -p 8080:8080 liferay/dxp:7.4.13-u55
Sign in to Liferay at http://localhost:8080 using the email address test@liferay.com and the password test. When prompted, change the password to learn.
Once Liferay is running,
Download and unzip Order API Basics.
curl https://learn.liferay.com/commmerce/latest/en/order-management/developer-guide/liferay-w6c8.zip -O
unzip liferay-w6c8.zip
Three parameters are required to create an order: an account ID, a channel ID, and the ISO 4217 currency code (e.g., USD) of the currency used.
To get the account ID, open the Global Menu (
) and go to Control Panel → Accounts. Find the account and copy its ID. Alternatively, select the account and copy the Account ID.
To get the channel ID, open the Global Menu (
) and go to Commerce → Channels. Select the channel where you’ll add orders and copy its ID.
Use the cURL script to add a new order to the channel. On the command line, navigate to the
curl
folder. Execute theOrder_POST_ToChannel.sh
script with the appropriate values for account ID, channel ID, and currency code../Order_POST_ToChannel.sh 1234 5678 USD
The JSON response shows a new order has been added for that account and channel:
{ "accountExternalReferenceCode" : "cc-west", "accountId" : 1234, "actions" : { "get" : { "method" : "GET", "href" : "http://localhost:8080/o/headless-commerce-admin-order/v1.0/orders/{id}" }, "update" : { "method" : "PATCH", "href" : "http://localhost:8080/o/headless-commerce-admin-order/v1.0/orders/{id}" }, "delete" : { "method" : "DELETE", "href" : "http://localhost:8080/o/headless-commerce-admin-order/v1.0/orders/{id}" } }, "advanceStatus" : "", "billingAddressId" : 0, "channelExternalReferenceCode" : "c8957c2f-4eb1-ce8f-4a38-5251bf740198", "channelId" : 5678, "couponCode" : "", "createDate" : "2023-01-03T12:25:15Z", "currencyCode" : "USD", "customFields" : { }, "deliveryTermDescription" : "", "deliveryTermId" : 0, "deliveryTermName" : "", "externalReferenceCode" : "3ebcbc91-7240-2763-c2ce-f2a592851053", "id" : 45955, "modifiedDate" : "2023-01-03T12:25:15Z", "orderDate" : "2023-01-03T12:25:15Z", "orderStatus" : 1, "orderStatusInfo" : { "code" : 1, "label" : "pending", "label_i18n" : "Pending" }, "orderTypeId" : 0, "paymentMethod" : "", "paymentStatus" : 1, "paymentStatusInfo" : { "code" : 1, "label" : "pending", "label_i18n" : "Pending" }, "paymentTermDescription" : "", "paymentTermId" : 0, "paymentTermName" : "", "printedNote" : "", "purchaseOrderNumber" : "", "shippingAddressId" : 0, "shippingAmountFormatted" : "$ 0.00", "shippingAmountValue" : 0.0, "shippingDiscountAmount" : 0, "shippingDiscountAmountFormatted" : "$ 0.00", "shippingDiscountPercentageLevel1" : 0, "shippingDiscountPercentageLevel1WithTaxAmount" : 0, "shippingDiscountPercentageLevel2" : 0, "shippingDiscountPercentageLevel2WithTaxAmount" : 0, "shippingDiscountPercentageLevel3" : 0, "shippingDiscountPercentageLevel3WithTaxAmount" : 0, "shippingDiscountPercentageLevel4" : 0, "shippingDiscountPercentageLevel4WithTaxAmount" : 0, "shippingDiscountWithTaxAmount" : 0, "shippingDiscountWithTaxAmountFormatted" : "$ 0.00", "shippingOption" : "", "shippingWithTaxAmountFormatted" : "$ 0.00", "shippingWithTaxAmountValue" : 0.0, "subtotalAmount" : 0.0, "subtotalDiscountAmount" : 0, "subtotalDiscountAmountFormatted" : "$ 0.00", "subtotalDiscountPercentageLevel1" : 0, "subtotalDiscountPercentageLevel1WithTaxAmount" : 0, "subtotalDiscountPercentageLevel2" : 0, "subtotalDiscountPercentageLevel2WithTaxAmount" : 0, "subtotalDiscountPercentageLevel3" : 0, "subtotalDiscountPercentageLevel3WithTaxAmount" : 0, "subtotalDiscountPercentageLevel4" : 0, "subtotalDiscountPercentageLevel4WithTaxAmount" : 0, "subtotalDiscountWithTaxAmount" : 0, "subtotalDiscountWithTaxAmountFormatted" : "$ 0.00", "subtotalFormatted" : "$ 0.00", "subtotalWithTaxAmountFormatted" : "$ 0.00", "subtotalWithTaxAmountValue" : 0.0, "taxAmount" : 0, "taxAmountFormatted" : "$ 0.00", "taxAmountValue" : 0.0, "totalAmount" : 0.0, "totalDiscountAmount" : 0, "totalDiscountAmountFormatted" : "$ 0.00", "totalDiscountPercentageLevel1" : 0, "totalDiscountPercentageLevel2" : 0, "totalDiscountPercentageLevel3" : 0, "totalDiscountPercentageLevel4" : 0, "totalDiscountWithTaxAmount" : 0, "totalDiscountWithTaxAmountFormatted" : "$ 0.00", "totalFormatted" : "$ 0.00", "totalWithTaxAmountFormatted" : "$ 0.00", "totalWithTaxAmountValue" : 0.0, "transactionId" : "", "workflowStatusInfo" : { "code" : 0, "label" : "approved", "label_i18n" : "Approved" } }
Navigate to Global Menu (
) → Commerce → Orders. The new order appears.
Alternatively, call the REST service using the Java client. Navigate into the
java
folder and compile the source files:javac -classpath .:* *.java
Run the
Order_POST_ToChannel
class, replacingaccountId
,channelId
, andcurrenyCode
with the appropriate values.java -classpath .:* -DaccountId=1234 -DchannelId=5678 -DcurrencyCode=Foo Order_POST_ToChannel
Examine the cURL Command¶
The Order_POST_ToChannel.sh
script calls the REST service with a cURL command.
curl \
-H "Content-Type: application/json" \
-X POST \
"http://localhost:8080/o/headless-commerce-admin-order/v1.0/orders" \
-d "{\"accountId\": ${1}, \"channelId\": ${2}, \"currencyCode\": \"${3}\"}" \
-u "[email protected]:learn"
Here are the command’s arguments:
Arguments |
Description |
---|---|
|
Set the request body format to JSON. |
|
Set the HTTP method to invoke at the specified endpoint. |
|
Specify the REST service endpoint. |
|
Enter the data to post. |
|
Enter basic authentication credentials. |
Note
Basic authentication is used here for demonstration purposes. For production, you should authorize users via OAuth2. See Using OAuth2 to Authorize Users for a sample React application using OAuth2.
The other cURL commands use similar JSON arguments.
Examine the Java Class¶
The Order_POST_ToChannel.java
class adds an order by calling the order related services.
public static void main(String[] args) throws Exception {
OrderResource.Builder builder = OrderResource.builder();
OrderResource orderResource = builder.authentication(
"[email protected]", "learn"
).build();
System.out.println(
orderResource.postOrder(
new Order() {
{
accountId = Long.valueOf(
System.getProperty("accountId"));
channelId = Long.valueOf(
System.getProperty("channelId"));
currencyCode = String.valueOf(
System.getProperty("currencyCode"));
}
}));
}
This class invokes the REST service using only three lines of code:
Line (abbreviated) |
Description |
---|---|
|
Get a |
|
Use basic authentication and generate an |
|
Call the |
Note that the project includes the com.liferay.headless.commerce.admin.order.client.jar
file as a dependency. You can find client JAR dependency information for all REST applications in the API explorer in your installation at /o/api
(e.g., http://localhost:8080/o/api).
Note
The main
method’s comment demonstrates running the class.
The other example Java classes call different OrderResource
methods.
Important
See OrderResource for service details.
Below are examples of calling other Order
REST services using cURL and Java.
Get Orders from Instance¶
You can list all orders from your Liferay instance with a cURL or Java command.
Orders_GET_FromInstance.sh¶
Command:
./Orders_GET_FromInstance.sh
Code:
curl \
"http://localhost:8080/o/headless-commerce-admin-order/v1.0/orders" \
-u "[email protected]:learn"
Orders_GET_FromInstance.java¶
Command:
java -classpath .:* Orders_GET_FromInstance
Code:
public static void main(String[] args) throws Exception {
OrderResource.Builder builder = OrderResource.builder();
OrderResource orderResource = builder.authentication(
"[email protected]", "learn"
).build();
System.out.println(
orderResource.getOrdersPage(null, null, Pagination.of(1, 2), null));
}
The instance’s Order
objects are listed in JSON.
Filtering, Paginating, Searching, and Sorting Orders¶
Orders returned by this API can be filtered, paginated, searched, and sorted. See the getOrdersPage
method for more information. Use the following Order
fields to filter, search, and sort the results:
accountId
channelId
orderStatus
orderId
createDate
modifiedDate
orderDate
Filter Query |
Description |
---|---|
|
The order ID must equal 45958. |
|
The order create date must be greater than 31st December 2022 12:00:00. |
|
The order status must be either processing (10) or pending (1). The term |
|
The account ID must equal |
To filter by orderStatus
, you must use its associated integer value. The table below maps each the order status to its integer value.
Order Status |
Integer Value |
---|---|
Open |
2 |
In Progress |
6 |
Pending |
1 |
Processing |
10 |
Shipped |
15 |
Completed |
0 |
Cancelled |
8 |
Partially Shipped |
14 |
On Hold |
20 |
Sort Query |
Description |
---|---|
|
Sort by |
|
Sort by |
Read API Query Parameters for more information.
Get an Order¶
Get a specific order with cURL and Java get
commands. Replace 1234
with the order’s ID.
Tip
Use Orders_GET_FromInstance.[java|sh]
to get a list of all orders, and note the id
of the order you want specifically.
Order_GET_ById.sh¶
Command:
./Order_GET_ById.sh 1234
Code:
curl \
"http://localhost:8080/o/headless-commerce-admin-order/v1.0/orders/${1}" \
-u "[email protected]:learn"
Order_GET_ById.java¶
Command:
java -classpath .:* -DorderId=1234 Order_GET_ById
Code:
public static void main(String[] args) throws Exception {
OrderResource.Builder builder = OrderResource.builder();
OrderResource orderResource = builder.authentication(
"[email protected]", "learn"
).build();
System.out.println(
orderResource.getOrder(
Long.valueOf(System.getProperty("orderId"))));
}
The Order
fields are formatted in JSON.
Patch an Order¶
Update an existing order with cURL and Java patch
commands. Replace 1234
with your order’s ID.
Order_PATCH_ById.sh¶
Command:
./Order_PATCH_ById.sh 1234
Code:
curl \
-H "Content-Type: application/json" \
-X PATCH \
"http://localhost:8080/o/headless-commerce-admin-order/v1.0/orders/${1}" \
-d "{\"externalReferenceCode\": \"Able\"}" \
-u "[email protected]:learn"
Order_PATCH_ById.java¶
Command:
java -classpath .:* -DorderId=1234 Order_PATCH_ById
Code:
OrderResource orderResource = builder.authentication(
"[email protected]", "learn"
).build();
orderResource.patchOrder(
Long.valueOf(System.getProperty("orderId")),
new Order() {
{
externalReferenceCode = "Able";
}
});
}
Delete an Order¶
Delete an existing order with cURL and Java delete
commands. Replace 1234
with your order’s ID.
Order_DELETE_ById.sh¶
Command:
./Order_DELETE_ById.sh 1234
Code:
curl \
-X DELETE \
"http://localhost:8080/o/headless-commerce-admin-order/v1.0/orders/${1}" \
-u "[email protected]:learn"
Order_DELETE_ById.java¶
Command
java -classpath .:* -DorderId=1234 Order_DELETE_ById
Code:
public static void main(String[] args) throws Exception {
OrderResource.Builder builder = OrderResource.builder();
OrderResource orderResource = builder.authentication(
"[email protected]", "learn"
).build();
orderResource.deleteOrder(Long.valueOf(System.getProperty("orderId")));
}
The API Explorer shows the Order
services and schemas and has an interface to test each service.