Specification API Basics

Specification API Basics

You can manage product specifications from the Applications menu or with REST APIs. Call the headless-commerce-admin-catalog services to create and manage specifications.

Adding a Specification

Start a new Liferay DXP instance by running

docker run -it -m 8g -p 8080:8080 liferay/dxp:7.4.13-u75

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

Once Liferay is running,

  1. Download and unzip Specification API Basics.

    curl https://resources.learn.liferay.com/commmerce/latest/en/product-management/developer-guide/liferay-u9x9.zip -O
    unzip liferay-u9x9.zip
  2. Specifications are scoped to an instance, and each specification must specify a unique key and a title.

    Use the cURL script to add a new specification. On the command line, navigate to the curl folder. Execute the Specification_POST_ToInstance.sh script.


    The JSON response shows a new specification was added:

       "description" : { },
       "facetable" : false,
       "id" : 45936,
       "key" : "foo",
       "title" : {
          "en_US" : "Foo"
  3. To verify the specification addition, open the Global Menu (Applications Menu icon) and navigate to CommerceSpecifications. The new specification appears under the Specification Labels tab.

    Confirm that a new specification was added.


    Currently, the API cannot add a specification label to a specification group or create a specification group. You must instead use the Specifications UI. Open the Global Menu (Applications Menu icon) and navigate to CommerceSpecifications. See Specification Groups for more information.

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

    javac -classpath .:* *.java
  5. Run the Specification_POST_ToInstance class.

    java -classpath .:* Specification_POST_ToInstance

Examine the cURL Command

The Specification_POST_ToInstance.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-catalog/v1.0/specifications" \
	 -d "{\"key\": \"foo\", \"title\": {\"en_US\": \"Foo\"}}" \
	 -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-catalog/v1.0/specifications" Specify the REST service endpoint.
-d "{\"key\": \"foo\", \"title\": {\"en_US\": \"Foo\"}}" Enter the data to post.
-u "[email protected]:learn" Enter basic authentication credentials.

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 Specification_POST_ToInstance.java class adds a specification by calling the SpecificationResource service.

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

Line (abbreviated) Description
SpecificationResource.Builder builder = ... Get a Builder for generating a SpecificationResource service instance.
SpecificationResource specificationResource = builder.authentication(...).build(); Use basic authentication and generate a SpecificationResource service instance.
specificationResource.postSpecification(...); Call the specificationResource.postSpecification method and pass the data to post.

The project includes the com.liferay.headless.commerce.admin.catalog.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).


The main method’s comment demonstrates running the class.

The remaining example Java classes call different SpecificationResource methods.


See SpecificationResource for service details.

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

Get Specifications from Instance

List all the specifications in your Liferay instance with a cURL or Java command.







java -classpath .:* Specifications_GET_FromInstance


The instance’s Specification objects are formatted in JSON.

Filtering, Paginating, Searching, and Sorting Specifications

This API also accepts parameters to filter, paginate, search, and sort the specifications. See the getSpecificationsPage method for more information. You can use the following Specification fields in your queries to filter, search, and sort the results:

  • key
  • title
Filter Query Description
key eq 'foo' The specification key must equal foo.
title eq 'Bar' The specification title must be Bar.
Sort Query Description
key:desc Sort by key in descending order.
title:asc Sort by title in ascending order.

Read API Query Parameters for more information.

Get a Specification

Get a specific specification with cURL or Java get commands. Replace 1234 with the specification’s ID.


Use Specifications_GET_FromInstance.[java|sh] to get a list of all specifications, and note the id of the specification you want specifically.



./Specification_GET_ById.sh 1234




java -classpath .:* -DspecificationId=1234 Specification_GET_ById


The Specification fields are listed in JSON.

Patch a Specification

Update an existing specification with cURL and Java patch commands. Replace 1234 with your specification’s ID.



./Specification_PATCH_ById.sh 1234




java -classpath .:* -DspecificationId=1234 Specification_PATCH_ById


Delete a Specification

Delete an existing specification with cURL and Java delete commands. Replace 1234 with your specification’s ID.



./Specification_DELETE_ById.sh 1234




java -classpath .:* -DspecificationId=1234 Specification_DELETE_ById


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