Documentation

Documentation Menu
Go Back

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,

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

  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 (Applications Menu icon) and go to Control Panel → Accounts. Find the account and copy its ID. Alternatively, select the account and copy the Account ID.

    Copy the account ID.

    To get the channel ID, open the Global Menu (Applications Menu icon) and go to Commerce → Channels. Select the channel where you’ll add orders and copy its ID.

    Copy the channel 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 Order_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"
   }
}

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

    Confirm that a new order was added.

  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 Order_POST_ToChannel class, replacing accountId, channelId, and currenyCode 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

-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 "test@liferay.com: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 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

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" \
	 -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

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

Cancelled

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.

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.

Not finding what you're looking for?

Pardon our dust as we revamp and transition our product documentation to this site. If something seems missing, please check Liferay Help Center documentation for Liferay DXP 7.2 and previous versions.

Try Liferay's Help Center