Order Type API Basics

You can manage order types from the Applications menu or with REST APIs. Use the /order-types endpoint from headless-admin-commerce-order to create and manage order types.

Adding an Order Type

Start a new Liferay DXP instance by running

docker run -it -m 8g -p 8080:8080 liferay/dxp:2024.q1.1

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 Type API Basics.

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

unzip liferay-t5n8.zip

Order types are scoped to an instance and require a name for creation.

Use the cURL script to add an order type. On the command line, navigate to the curl folder. Execute the OrderType_POST_ToInstance.sh script.

./OrderType_POST_ToInstance.sh

The JSON response shows the newly added order type:

{
   "actions" : {
      "permissions" : {
         "method" : "PATCH",
         "href" : "http://localhost:9090/o/headless-commerce-admin-order/v1.0/order-types/48698"
      },
      "get" : {
         "method" : "GET",
         "href" : "http://localhost:9090/o/headless-commerce-admin-order/v1.0/order-types/48698"
      },
      "update" : {
         "method" : "PATCH",
         "href" : "http://localhost:9090/o/headless-commerce-admin-order/v1.0/order-types/48698"
      },
      "delete" : {
         "method" : "DELETE",
         "href" : "http://localhost:9090/o/headless-commerce-admin-order/v1.0/order-types/48698"
      }
   },
   "active" : false,
   "customFields" : { },
   "description" : { },
   "displayDate" : "2023-03-23T16:30:00Z",
   "displayOrder" : 0,
   "externalReferenceCode" : "fd8fbd90-0f19-0d4d-46db-c7807f3660ce",
   "id" : 48698,
   "name" : {
      "en_US" : "Foo"
   },
   "workflowStatusInfo" : {
      "code" : 0,
      "label" : "approved",
      "label_i18n" : "Approved"
   }
}

Navigate to Global Menu () → Commerce → Order Types. The newly added order type 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 OrderType_POST_ToInstance class.

java -classpath .:* OrderType_POST_ToInstance

Examine the cURL Command

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

curl \
	"http://localhost:8080/o/headless-commerce-admin-order/v1.0/order-types" \
	--data-raw '
		{
			"name": {
				"en_US": "Foo"
			}
		}' \
	--header "Content-Type: application/json" \
	--request "POST" \
	--user "test@liferay.com: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/order-types"`	Specify the REST service endpoint.
`-d "{\"name\": {\"en_US\": \"Foo\"}}"`	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 OrderType_POST_ToInstance.java class adds an order type by calling the OrderTypeResource service.

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

	OrderTypeResource orderTypeResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		orderTypeResource.postOrderType(
			new OrderType() {
				{
					name = new HashMap<String, String>() {
						{
							put("en_US", "Foo");
						}
					};
				}
			}));
}

This class invokes the REST service using only three lines of code:

Line (abbreviated)	Description
`OrderTypeResource.Builder builder = ...`	Get a `Builder` for generating an `OrderTypeResource` service instance.
`OrderTypeResource orderTypeResource = builder.authentication(...).build();`	Use basic authentication and generate an `OrderTypeResource` service instance.
`orderTypeResource.postOrderType(...);`	Call the `orderTypeResource.postOrderType` method and pass the data to post.

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 remaining example Java classes call different OrderTypeResource methods.

important

See OrderTypeResource for service details.

Below are examples of calling other OrderType REST services using cURL and Java.

Get Order Types from Instance

You can list all the order types from your Liferay instance with a cURL or Java command.

OrderTypes_GET_FromInstance.sh

Command:

./OrderTypes_GET_FromInstance.sh

Code:

curl \
	"http://localhost:8080/o/headless-commerce-admin-order/v1.0/order-types" \
	--user "test@liferay.com:learn"

OrderTypes_GET_FromInstance.java

Command:

java -classpath .:* OrderTypes_GET_FromInstance

Code:

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

	OrderTypeResource orderTypeResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		orderTypeResource.getOrderTypesPage(
			null, null, Pagination.of(1, 2), null));
}

The instance’s OrderType objects appear in JSON.

Paginating, Searching, and Sorting Order Types

You can paginate, search, and sort the returned order types. See the getOrderTypesPage method for more information. Use the name field to search and sort the results:

Sort Query	Description
`name:desc`	Sort by `name` in descending order.

Read API Query Parameters for more information.

Get an Order Type

Get a specific order type with cURL and Java get commands. Replace 1234 with the ID of the order type.

tip

Use OrderTypes_GET_FromInstance.[java|sh] to get a list of all order types, and note the id of the order type you want specifically.

OrderType_GET_ById.sh

Command:

./OrderType_GET_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-commerce-admin-order/v1.0/order-types/${1}" \
	--user "test@liferay.com:learn"

OrderType_GET_ById.java

Command:

java -classpath .:* -DorderTypeId=1234 OrderType_GET_ById

Code:

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

	OrderTypeResource orderTypeResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		orderTypeResource.getOrderType(
			Long.valueOf(System.getProperty("orderTypeId"))));
}

The OrderType fields are formatted in JSON.

Patch an Order Type

Update an existing order type with cURL and Java patch commands. Replace 1234 with the ID of the order type.

OrderType_PATCH_ById.sh

Command:

./OrderType_PATCH_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-commerce-admin-order/v1.0/order-types/${1}" \
	--data-raw '
		{
			"name": {
				"en_US": "Bar"
			}
		}' \
	--header "Content-Type: application/json" \
	--request "PATCH" \
	--user "test@liferay.com:learn"

OrderType_PATCH_ById.java

Command:

java -classpath .:* -DorderTypeId=1234 OrderType_PATCH_ById

Code:

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

	OrderTypeResource orderTypeResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	orderTypeResource.patchOrderType(
		Long.valueOf(System.getProperty("orderTypeId")),
		new OrderType() {
			{
				name = new HashMap<String, String>() {
					{
						put("en_US", "Bar");
					}
				};
			}
		});
}

Delete an Order Type

Delete an existing order type with cURL and Java delete commands. Replace 1234 with the ID of the order type.

OrderType_DELETE_ById.sh

Command:

./OrderType_DELETE_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-commerce-admin-order/v1.0/order-types/${1}" \
	--request "DELETE" \
	--user "test@liferay.com:learn"

OrderType_DELETE_ById.java

Command

java -classpath .:* -DorderTypeId=1234 OrderType_DELETE_ById

Code:

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

	OrderTypeResource orderTypeResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	orderTypeResource.deleteOrderType(
		Long.valueOf(System.getProperty("orderTypeId")));
}

The API Explorer shows the OrderType services and schemas and has an interface to test each service.

Capability: