Term API Basics

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

Adding a Term

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,

  1. Download and unzip Term API Basics.

    curl https://resources.learn.liferay.com/commerce/latest/en/order-management/developer-guide/liferay-a9v8.zip -O
    
    unzip liferay-a9v8.zip
    
  2. Four parameters are required to create terms and conditions: label, name, priority, and type.

    ParameterValue TypeDescription/
    Example
    LabelTextEnter a comma-separated list of locale/value properties:
    {"en_US": "Foo", "es_ES": "Bar"}
    NameTextEnter a unique name for the terms and conditions item:
    "name": "foo"
    PriorityNumber (double)Enter a unique numeric priority:
    "priority": 1.2
    TypeTextSpecify "payment-terms" or "delivery-terms":
    "type": "payment-terms"

    Use the cURL script to add terms and conditions to your instance. On the command line, navigate to the curl folder. Execute the Term_POST_ToInstance.sh script.

    ./Term_POST_ToInstance.sh
    

    The JSON response shows the newly added terms and conditions:

    {
       "actions" : {
          "permissions" : {
             "method" : "PATCH",
             "href" : "http://localhost:8080/o/headless-commerce-admin-order/v1.0/terms/46418"
          },
          "get" : {
             "method" : "GET",
             "href" : "http://localhost:8080/o/headless-commerce-admin-order/v1.0/terms/46418"
          },
          "update" : {
             "method" : "PATCH",
             "href" : "http://localhost:8080/o/headless-commerce-admin-order/v1.0/terms/46418"
          },
          "delete" : {
             "method" : "DELETE",
             "href" : "http://localhost:8080/o/headless-commerce-admin-order/v1.0/terms/46418"
          }
       },
       "active" : false,
       "description" : {
          "en_US" : ""
       },
       "displayDate" : "2023-03-03T13:16:00Z",
       "externalReferenceCode" : "7fa19a0c-4c98-6c36-f1bc-5a2c4257220c",
       "id" : 46418,
       "label" : {
          "en_US" : "Foo"
       },
       "name" : "foo",
       "priority" : 0.0,
       "type" : "payment-terms",
       "typeLocalized" : "Payment Terms",
       "typeSettings" : "",
       "workflowStatusInfo" : {
          "code" : 0,
          "label" : "approved",
          "label_i18n" : "Approved"
       }
    }
    
  3. Navigate to Global Menu (Applications Menu icon) → CommerceTerms and Conditions. The newly added terms and conditions appear.

    Confirm the addition of terms and conditions.

  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 Term_POST_ToInstance class.

    java -classpath .:* Term_POST_ToInstance
    

Examine the cURL Command

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

curl \
	"http://localhost:8080/o/headless-commerce-admin-order/v1.0/terms" \
	--data-raw '
		{
			"label": {
				"en_US": "Foo"
			},
			"name": "foo",
			"priority": 0,
			"type": "payment-terms"
		}' \
	--header "Content-Type: application/json" \
	--request "POST" \
	--user "test@liferay.com:learn"

Here are the command’s arguments:

ArgumentsDescription
-H "Content-Type: application/json"Set the request body format to JSON.
-X POSTSet the HTTP method to invoke at the specified endpoint.
"http://localhost:8080/o/headless-commerce-admin-order/v1.0/terms"Specify the REST service endpoint.
-d "{\"label\": {\"en_US\": \"Foo\"}, \"name\": \"foo\", \"priority\": 0, \"type\": \"payment-terms\"}"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 Term_POST_ToInstance.java class adds terms and conditions by calling the TermResource service.

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

	TermResource termResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		termResource.postTerm(
			new Term() {
				{
					label = new HashMap<String, String>() {
						{
							put("en_US", "Foo");
						}
					};
					name = "foo";
					priority = 0D;
					type = "payment-terms";
				}
			}));
}

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

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

Note that 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 TermResource methods.

important

See TermResource for service details.

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

Get Terms from Instance

You can list all the terms and conditions from your Liferay instance with a cURL or Java command.

Terms_GET_FromInstance.sh

Command:

./Terms_GET_FromInstance.sh

Code:

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

Terms_GET_FromInstance.java

Command:

java -classpath .:* Terms_GET_FromInstance

Code:

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

	TermResource termResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		termResource.getTermsPage(null, null, Pagination.of(1, 2), null));
}

The instance’s Term objects are listed in JSON.

Filtering, Paginating, Searching, and Sorting Terms

You can filter, paginate, search, and sort the returned terms and conditions. See the getTermsPage method for more information. Use the priority and type fields to filter, search, and sort the results:

Filter QueryDescription
type eq 'payment-terms'The terms and conditions must be of type payment-terms
priority eq 0The terms and conditions’ priority must equal 0
Sort QueryDescription
priority:descSort by priority in descending order.
priority:desc,type:descSort by priority in descending order first, then by type in descending order.

Read API Query Parameters for more information.

Get a Term

Get specific terms and conditions with cURL and Java get commands. Replace 1234 with the ID of the terms and conditions.

tip

Use Terms_GET_FromInstance.[java|sh] to get a list of all terms and conditions, and note the id of the terms and conditions you want specifically.

Term_GET_ById.sh

Command:

./Term_GET_ById.sh 1234

Code:

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

Term_GET_ById.java

Command:

java -classpath .:* -DtermId=1234 Term_GET_ById

Code:

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

	TermResource termResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		termResource.getTerm(Long.valueOf(System.getProperty("termId"))));
}

The Term fields are formatted in JSON.

Patch a Term

Update existing terms and conditions with cURL and Java patch commands. Replace 1234 with the ID of the terms and conditions.

Term_PATCH_ById.sh

Command:

./Term_PATCH_ById.sh 1234

Code:

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

Term_PATCH_ById.java

Command:

java -classpath .:* -DtermId=1234 Term_PATCH_ById

Code:

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

	TermResource termResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	termResource.patchTerm(
		Long.valueOf(System.getProperty("termId")),
		new Term() {
			{
				label = new HashMap<String, String>() {
					{
						put("en_US", "Bar");
					}
				};
			}
		});
}

Delete a Term

Delete existing terms and conditions with cURL and Java delete commands. Replace 1234 with the ID of the terms and conditions.

Term_DELETE_ById.sh

Command:

./Term_DELETE_ById.sh 1234

Code:

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

Term_DELETE_ById.java

Command

java -classpath .:* -DtermId=1234 Term_DELETE_ById

Code:

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

	TermResource termResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	termResource.deleteTerm(Long.valueOf(System.getProperty("termId")));
}

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

Capabilities

Product

Contact Us

Connect

Powered by Liferay
© 2024 Liferay Inc. All Rights Reserved • Privacy Policy