Price List API Basics

You can manage price lists from the Applications menu or with REST APIs. Call the headless-admin-commerce-pricing services to create and manage price lists.

Adding a Price List

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 Price List API Basics.

   curl https://resources.learn.liferay.com/commerce/latest/en/pricing/developer-guide/liferay-c2v4.zip -O
   

   unzip liferay-c2v4.zip
   

2. Price lists are scoped to catalogs, so you need the catalog ID to create one.

   To get a catalog’s ID, open the Global Menu (), and go to Commerce → Catalogs. Select a catalog and copy its ID.

   

3. Use the cURL script to add a new price list to the catalog. On the command line, navigate to the curl folder. Execute the PriceLists_POST_ToCatalog.sh script with the appropriate catalog ID value as a parameter.

   ./PriceLists_POST_ToCatalog.sh 1234
   

   The JSON response shows a new price list was added:

   {
      "actions" : {
         "permissions" : {
         "method" : "PATCH",
         "href" : "http://localhost:8080/o/headless-commerce-admin-pricing/v2.0/price-lists/46002"
         },
         "get" : {
         "method" : "GET",
         "href" : "http://localhost:8080/o/headless-commerce-admin-pricing/v2.0/price-lists/46002"
         },
         "update" : {
         "method" : "PATCH",
         "href" : "http://localhost:8080/o/headless-commerce-admin-pricing/v2.0/price-lists/46002"
         },
         "delete" : {
         "method" : "DELETE",
         "href" : "http://localhost:8080/o/headless-commerce-admin-pricing/v2.0/price-lists/46002"
         }
      },
      "active" : true,
      "author" : "Test Test",
      "catalogBasePriceList" : false,
      "catalogId" : 1234,
      "catalogName" : "Master",
      "createDate" : "2023-01-04T12:41:03Z",
      "currencyCode" : "USD",
      "customFields" : { },
      "displayDate" : "2023-01-04T12:41:00Z",
      "externalReferenceCode" : "b314f22b-72ff-c47c-4fb6-c34539257821",
      "id" : 46002,
      "name" : "Able",
      "netPrice" : true,
      "parentPriceListId" : 0,
      "priority" : 0.0,
      "type" : "price-list",
      "workflowStatusInfo" : {
         "code" : 0,
         "label" : "approved",
         "label_i18n" : "Approved"
      }
   }
   

4. To verify the price list addition, open the Global Menu () and navigate to Commerce → Price Lists. The new price list 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 PriceLists_POST_ToCatalog class, replacing the catalogId with the appropriate value.

   java -classpath .:* -DcatalogId=1234 PriceLists_POST_ToCatalog
   

Examine the cURL Command

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

curl \
	"http://localhost:8080/o/headless-commerce-admin-pricing/v2.0/price-lists" \
	--data-raw '
		{
			"catalogId": "'"${1}"'",
			"currencyCode": "USD",
			"name": "Able",
			"type": "price-list"
		}' \
	--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-pricing/v2.0/price-lists"	Specify the REST service endpoint.
-d "{\"catalogId\": ${1}, \"currencyCode\": \"USD\", \"name\": \"Able\", \"type\": \"price-list\"}"	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 PriceLists_POST_ToCatalog.java class adds a price list by calling the PriceListResource service.

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

	PriceListResource priceListResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	System.out.println(
		priceListResource.postPriceList(
			new PriceList() {
				{
					catalogId = Long.valueOf(
						System.getProperty("catalogId"));
					currencyCode = "USD";
					name = "Able";
					type = PriceList.Type.PRICE_LIST;
				}
			}));
}

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

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

Note that the project includes the com.liferay.headless.commerce.admin.pricing.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 PriceListResource methods.

Important

See PriceListResource for service details.

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

Get Price Lists from Instance

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

PriceLists_GET_FromInstance.sh

Command:

./PriceLists_GET_FromInstance.sh

Code:

curl \
	"http://localhost:8080/o/headless-commerce-admin-pricing/v2.0/price-lists" \
	--user "[e-mail]:learn"

PriceLists_GET_FromInstance.java

Command:

java -classpath .:* PriceLists_GET_FromInstance

Code:

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

	PriceListResource priceListResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	Page<PriceList> page = priceListResource.getPriceListsPage(
		null, null, Pagination.of(1, 2), null);

	System.out.println(page);
}

The instance’s PriceList objects are formatted in JSON.

Filtering, Paginating, Searching, and Sorting Price Lists

This API also accepts parameters to filter, paginate, search, and sort the price lists. See the getPriceListsPage method for more information. Use the following PriceList fields to filter, search, and sort the results.

• accountId
• accountGroupId
• catalogId
• channelId
• orderTypeId
• name
• catalogBasePriceList
• type
• createDate

Filter Query	Description
name eq 'Able'	The price list name must equal Able.
createDate gt 2022-12-31T12:00:00Z	The price list create date must be greater than 31st December 2022 12:00:00.
catalogId/any(x:(x eq 43956) and (x eq 43199))	Match price lists associated to catalogs 43956 and 43199. The term any means that at least one of the subsequent expressions must return true.

The accountId, accountGroupId, catalogId, channelId, and orderTypeId filter fields are collection fields. Filtering by a collection field must be done as shown in the third row of the table above.

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

Read API Query Parameters for more information.

Get a Price List

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

Tip

Use PriceLists_GET_FromInstance.[java|sh] to get a list of all price lists, and note the id of the price list you want specifically.

PriceLists_GET_ById.sh

Command:

./PriceLists_GET_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-commerce-admin-pricing/v2.0/price-lists/${1}" \
	--user "[e-mail]:learn"

PriceLists_GET_ById.java

Command:

java -classpath .:* -DpriceListId=1234 PriceLists_GET_ById

Code:

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

	PriceListResource priceListResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	System.out.println(
		priceListResource.getPriceList(
			Long.valueOf(System.getProperty("priceListId"))));
}

The PriceList fields are listed in JSON.

Patch a Price List

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

PriceLists_PATCH_ById.sh

Command:

./PriceLists_PATCH_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-commerce-admin-pricing/v2.0/price-lists/${1}" \
	--data-raw '
		{
			"name": "Baker"
		}' \
	--header "Content-Type: application/json" \
	--request "PATCH" \
	--user "[e-mail]:learn"

PriceLists_PATCH_ById.java

Command:

java -classpath .:* -DpriceListId=1234 PriceLists_PATCH_ById

Code:

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

	PriceListResource priceListResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	priceListResource.patchPriceList(
		Long.valueOf(System.getProperty("priceListId")),
		new PriceList() {
			{
				name = "Baker";
			}
		});
}

Delete a Price List

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

PriceLists_DELETE_ById.sh

Command:

./PriceLists_DELETE_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-commerce-admin-pricing/v2.0/price-lists/${1}" \
	--request "DELETE" \
	--user "[e-mail]:learn"

PriceLists_DELETE_ById.java

Command

java -classpath .:* -DpriceListId=1234 PriceLists_DELETE_ById

Code:

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

	PriceListResource priceListResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	priceListResource.deletePriceList(
		Long.valueOf(System.getProperty("priceListId")));
}

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

Related Topics

• Discount API Basics