Submit Feedback

Discount API Basics

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

Adding a Discount

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

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

unzip liferay-r6f7.zip

Discounts are scoped to an instance. Use the cURL script to add a new discount. On the command line, navigate to the curl folder. Execute the Discount_POST_ToInstance.sh script.

./Discount_POST_ToInstance.sh

The JSON response shows a new discount was added:

{
   "actions" : {
      "permissions" : {
         "method" : "PATCH",
         "href" : "http://localhost:8080/o/headless-commerce-admin-pricing/v2.0/discounts/46111"
      },
      "get" : {
         "method" : "GET",
         "href" : "http://localhost:8080/o/headless-commerce-admin-pricing/v2.0/discounts/46111"
      },
      "update" : {
         "method" : "PATCH",
         "href" : "http://localhost:8080/o/headless-commerce-admin-pricing/v2.0/discounts/46111"
      },
      "delete" : {
         "method" : "DELETE",
         "href" : "http://localhost:8080/o/headless-commerce-admin-pricing/v2.0/discounts/46111"
      }
   },
   "active" : false,
   "amountFormatted" : "0.00%",
   "couponCode" : "",
   "customFields" : { },
   "displayDate" : "2023-02-27T12:31:00Z",
   "externalReferenceCode" : "9df9ffc2-be00-680b-2a2c-69f572bbe65c",
   "id" : 46111,
   "level" : "L1",
   "limitationTimes" : 0,
   "limitationTimesPerAccount" : 0,
   "limitationType" : "unlimited",
   "numberOfUse" : 0,
   "rulesConjunction" : false,
   "target" : "Products",
   "title" : "Foo",
   "useCouponCode" : false,
   "usePercentage" : true
}

To verify the discount addition, open the Global Menu () and navigate to Commerce → Discounts. The new discount 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 Discount_POST_ToInstance class.

java -classpath .:* Discount_POST_ToInstance

Adding a Coupon Code

To add a coupon code to the discount, set useCouponCode to true and set a value in the couponCode field. To restrict the coupon code’s usage, use the settings described in the table below.

Restriction Type	Settings	Description
Number of uses	`"limitationType" : "limited for total"` `"limitationTimes" : 5` (any integer)	The coupon code can be used a total of 5 times.
Number of uses per account	`"limitationType": "limited for account"` `"limitationTimesPerAccount" : 5` (any integer)	Each account can use the coupon code up to 5 times.
Number of uses and by account	`"limitationType" : "limited for account and total"` `"limitationTimesPerAccount": 2` (any integer) `"limitationTimes" : 5` (any integer)	Each account can use the coupon code up to 2 times, with total usage capped at 5.

Examine the cURL Command

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

curl \
	"http://localhost:8080/o/headless-commerce-admin-pricing/v2.0/discounts" \
	--data-raw '
		{
			"level": "L1",
			"limitationType": "unlimited",
			"target": "products",
			"title": "Foo",
			"usePercentage": true
		}' \
	--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/discounts"`	Specify the REST service endpoint.
`-d "{\"level\": \"L1\", \"limitationType\": \"unlimited\", \"target\": \"products\", \"title\": \"Foo\", \"usePercentage\": true}"`	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 Discount_POST_ToInstance.java class adds a discount by calling the DiscountResource service.

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

	DiscountResource discountResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		discountResource.postDiscount(
			new Discount() {
				{
					level = "L1";
					limitationType = "unlimited";
					target = "products";
					title = "Foo";
					usePercentage = true;
				}
			}));
}

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

Line (abbreviated)	Description
`DiscountResource.Builder builder = ...`	Get a `Builder` for generating a `DiscountResource` service instance.
`DiscountResource discountResource = builder.authentication(...).build();`	Use basic authentication and generate a `DiscountResource` service instance.
`discountResource.postDiscount(...);`	Call the `discountResource.postDiscount` 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 DiscountResource methods.

important

See DiscountResource for service details.

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

Get Discounts from Instance

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

Discounts_GET_FromInstance.sh

Command:

./Discounts_GET_FromInstance.sh

Code:

curl \
	"http://localhost:8080/o/headless-commerce-admin-pricing/v2.0/discounts" \
	--user "test@liferay.com:learn"

Discounts_GET_FromInstance.java

Command:

java -classpath .:* Discounts_GET_FromInstance

Code:

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

	DiscountResource discountResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	Page<Discount> page = discountResource.getDiscountsPage(
		null, null, Pagination.of(1, 2), null);

	System.out.println(page);
}

The instance’s Discount objects are formatted in JSON.

Get a Discount

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

tip

Use Discounts_GET_FromInstance.[java|sh] to get a list of all discounts, and note the id of the discount you want specifically.

Discount_GET_ById.sh

Command:

./Discount_GET_ById.sh 1234

Code:

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

Discount_GET_ById.java

Command:

java -classpath .:* -DdiscountId=1234 Discount_GET_ById

Code:

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

	DiscountResource discountResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		discountResource.getDiscount(
			Long.valueOf(System.getProperty("discountId"))));
}

The Discount fields are listed in JSON.

Patch a Discount

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

Discount_PATCH_ById.sh

Command:

./Discount_PATCH_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-commerce-admin-pricing/v2.0/discounts/${1}" \
	--data-raw '
		{
		"limitationType": "unlimited",
		"target": "subtotal",
		"title": "Bar"
		}' \
	--header "Content-Type: application/json" \
	--request "PATCH" \
	--user "test@liferay.com:learn"

Discount_PATCH_ById.java

Command:

java -classpath .:* -DdiscountId=1234 Discount_PATCH_ById

Code:

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

	DiscountResource discountResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	discountResource.patchDiscount(
		Long.valueOf(System.getProperty("discountId")),
		new Discount() {
			{
				limitationType = "unlimited";
				target = "subtotal";
				title = "Bar";
			}
		});
}

Delete a Discount

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

Discount_DELETE_ById.sh

Command:

./Discount_DELETE_ById.sh 1234

Code:

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

Discount_DELETE_ById.java

Command

java -classpath .:* -DdiscountId=1234 Discount_DELETE_ById

Code:

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

	DiscountResource discountResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	discountResource.deleteDiscount(
		Long.valueOf(System.getProperty("discountId")));
}

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

Capability: