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:2025.q1.6-lts

Sign in to Liferay at http://localhost:8080 using the email address [e-mail] and the password test. When prompted, change the password to learn.

Once Liferay is running,

1. Download and unzip Order API Basics.

   curl https://resources.learn.liferay.com/commerce/latest/en/order-management/developer-guide/liferay-w6c8.zip -O
   

   unzip liferay-w6c8.zip
   

2. 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.

   

3. Use the cURL script to add a new order to the channel. On the command line, navigate to the curl folder. Execute the Orders_POST_ToChannel.sh script with the appropriate values for account ID, channel ID, and currency code.

   ./Orders_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"
      }
   }
   

4. Navigate to Global Menu () → Commerce → Orders. The new order appears.

   

5. Alternatively, call the REST service using the Java client. Navigate into the java folder and compile the source files:

   javac -classpath .:* *.java
   

6. Run the Orders_POST_ToChannel class, replacing accountId, channelId, and currenyCode with the appropriate values.

   java -classpath .:* -DaccountId=1234 -DchannelId=5678 -DcurrencyCode=Foo Orders_POST_ToChannel
   

Examine the cURL Command

The Orders_POST_ToChannel.sh script calls the REST service with a cURL command.

curl \
	"http://localhost:8080/o/headless-commerce-admin-order/v1.0/orders" \
	--data-raw '
		{
			"accountId": "'"${1}"'",
			"channelId": "'"${2}"'",
			"currencyCode": "'"${3}"'"
		}' \
	--header "Content-Type: application/json" \
	--request "POST" \
	--user "[e-mail]:learn"

Here are the command’s arguments:

Arguments	Description
-H "Content-Type: application/json"	Set the request body format to JSON.
-X POST	Set the HTTP method to invoke at the specified endpoint.
"http://localhost:8080/o/headless-commerce-admin-order/v1.0/orders"	Specify the REST service endpoint.
-d "{\"accountId\": ${1}, \"channelId\": ${2}, \"currencyCode\": \"${3}\"}"	Enter the data to post.
-u "[e-mail]:learn"	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 Orders_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(
		"[e-mail]", "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
OrderResource.Builder builder = ...	Get a Builder for generating an OrderResource service instance.
OrderResource orderResource = builder.authentication(...).build();	Use basic authentication and generate an OrderResource service instance.
orderResource.postOrder(...);	Call the orderResource.postOrder method and pass the data to post.

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" \
	--user "[e-mail]: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(
		"[e-mail]", "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
orderId eq 45958	The order ID must equal 45958.
createDate gt 2022-12-31T12:00:00Z	The order create date must be greater than 31st December 2022 12:00:00.
orderStatus/any(x:(x eq 10) or (x eq 1))	The order status must be either processing (10) or pending (1). The term any specifies that at least one of the subsequent expressions must return true.
accountId/any(x:(x eq 44170) or (x eq 44178))	The account ID must equal 44170 or 44178. The term any specifies that at least one of the subsequent expressions must return true.

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
Canceled	8
Partially Shipped	14
On Hold	20

Sort Query	Description
createDate:desc	Sort by createDate in descending order.
createDate:desc,modifiedDate:desc	Sort by createDate in descending order first, then by modifiedDate in descending order.

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.

Orders_GET_ById.sh

Command:

./Orders_GET_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-commerce-admin-order/v1.0/orders/${1}" \
	--user "[e-mail]:learn"

Orders_GET_ById.java

Command:

java -classpath .:* -DorderId=1234 Orders_GET_ById

Code:

public static void main(String[] args) throws Exception {
	OrderResource.Builder builder = OrderResource.builder();

	OrderResource orderResource = builder.authentication(
		"[e-mail]", "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.

Orders_PATCH_ById.sh

Command:

./Orders_PATCH_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-commerce-admin-order/v1.0/orders/${1}" \
	--data-raw '
		{
			"externalReferenceCode": "Able"
		}' \
	--header "Content-Type: application/json" \
	--request "PATCH" \
	--user "[e-mail]:learn"

Orders_PATCH_ById.java

Command:

java -classpath .:* -DorderId=1234 Orders_PATCH_ById

Code:

public static void main(String[] args) throws Exception {
	OrderResource.Builder builder = OrderResource.builder();

	OrderResource orderResource = builder.authentication(
		"[e-mail]", "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.

Orders_DELETE_ById.sh

Command:

./Orders_DELETE_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-commerce-admin-order/v1.0/orders/${1}" \
	--request "DELETE" \
	--user "[e-mail]:learn"

Orders_DELETE_ById.java

Command

java -classpath .:* -DorderId=1234 Orders_DELETE_ById

Code:

public static void main(String[] args) throws Exception {
	OrderResource.Builder builder = OrderResource.builder();

	OrderResource orderResource = builder.authentication(
		"[e-mail]", "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.

Note

On Liferay DXP 2024.Q4+/Portal GA129+, you can use external reference codes to GET/PUT/PATCH/DELETE orders.

Related Topics

• Order Type API Basics
• Term API Basics