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: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 Price List API Basics.
curl https://resources.learn.liferay.com/commerce/latest/en/pricing/developer-guide/liferay-c2v4.zip -O
unzip liferay-c2v4.zip
-
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.
-
Use the cURL script to add a new price list to the catalog. On the command line, navigate to the
curl
folder. Execute thePriceList_POST_ToCatalog.sh
script with the appropriate catalog ID value as a parameter../PriceList_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" } }
-
To verify the price list addition, open the Global Menu () and navigate to Commerce → Price Lists. The new price list 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
PriceList_POST_ToCatalog
class, replacing thecatalogId
with the appropriate value.java -classpath .:* -DcatalogId=1234 PriceList_POST_ToCatalog
Examine the cURL Command
The PriceList_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 "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-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 "test@liferay.com: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 PriceList_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(
"test@liferay.com", "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).
The main
method’s comment demonstrates running the class.
The remaining example Java classes call different PriceListResource
methods.
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 "test@liferay.com: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(
"test@liferay.com", "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.
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.
PriceList_GET_ById.sh
Command:
./PriceList_GET_ById.sh 1234
Code:
curl \
"http://localhost:8080/o/headless-commerce-admin-pricing/v2.0/price-lists/${1}" \
--user "test@liferay.com:learn"
PriceList_GET_ById.java
Command:
java -classpath .:* -DpriceListId=1234 PriceList_GET_ById
Code:
public static void main(String[] args) throws Exception {
PriceListResource.Builder builder = PriceListResource.builder();
PriceListResource priceListResource = builder.authentication(
"test@liferay.com", "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.
PriceList_PATCH_ById.sh
Command:
./PriceList_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 "test@liferay.com:learn"
PriceList_PATCH_ById.java
Command:
java -classpath .:* -DpriceListId=1234 PriceList_PATCH_ById
Code:
public static void main(String[] args) throws Exception {
PriceListResource.Builder builder = PriceListResource.builder();
PriceListResource priceListResource = builder.authentication(
"test@liferay.com", "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.
PriceList_DELETE_ById.sh
Command:
./PriceList_DELETE_ById.sh 1234
Code:
curl \
"http://localhost:8080/o/headless-commerce-admin-pricing/v2.0/price-lists/${1}" \
--request "DELETE" \
--user "test@liferay.com:learn"
PriceList_DELETE_ById.java
Command
java -classpath .:* -DpriceListId=1234 PriceList_DELETE_ById
Code:
public static void main(String[] args) throws Exception {
PriceListResource.Builder builder = PriceListResource.builder();
PriceListResource priceListResource = builder.authentication(
"test@liferay.com", "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.