Currency API Basics

Liferay DXP 2024.Q1+/Portal 7.4 GA112+

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

Important

The currency APIs were released behind a release feature flag in Liferay DXP 2024.Q1/Portal 7.4 GA112. It was made Generally Available (GA) in 2024.Q2/GA120.

Adding a Currency

Start a new Liferay instance by running

docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.120-ga120

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

Once Liferay is running,

1. Download and unzip Currency API Basics.

   curl https://resources.learn.liferay.com/commerce/latest/en/product-management/developer-guide/liferay-e6w7.zip -O
   

   unzip liferay-e6w7.zip
   

Currencies are scoped to an instance, and each currency must specify a unique code. You must also provide a name and rate to create a currency.

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

./Currency_POST_ToInstance.sh

The JSON response shows a new currency was added:

{
  "active" : false,
  "code" : "AED",
  "formatPattern" : {
     "en_US" : "###,##0.00"
  },
  "id" : 35562,
  "maxFractionDigits" : 2,
  "minFractionDigits" : 2,
  "name" : {
     "en_US" : "UAE Dirham"
  },
  "primary" : false,
  "priority" : 0.0,
  "rate" : 3.67,
     "roundingMode" : "HALF_EVEN",
     "symbol" : ""
  }

The rate field specifies the conversion rate relative to the primary currency. For instance, if your primary currency is United States Dollar (USD) and you’re creating UAE Dirham (AED), the rate determines how many dirhams make up a dollar. If you’re setting a currency as primary, the rate must be 1.00.

The values for maxFractionDigits and minFractionDigits default to 2. This specifies the decimal precision for the currency.

The value for roundingMode defaults to HALF_EVEN. This uses the java.math.RoundingMode enum to provide rounding strategies for currencies. You can use the following values for the rounding mode: UP, DOWN, CEILING, FLOOR, HALF_UP, HALF_DOWN, HALF_EVEN, and UNNECESSARY.

Rounding Mode	Positive Value	Rounded Value	Negative Value	Rounded Value	Description
UP	3.14	4	-3.14	-4	Rounds towards positive infinity for positive numbers. For negative numbers, UP rounds away from 0.
DOWN	3.14	3	-3.14	-3	Rounds towards zero for positive and negative numbers.
CEILING	3.14	4	-3.14	-3	Rounds towards positive infinity for positive numbers. For negative numbers, CEILING rounds towards from 0.
FLOOR	3.14	3	-3.14	-4	Rounds towards zero for positive numbers. For negative numbers, FLOOR rounds towards from 0.
HALF_UP	3.5	4	-3.5	-3	Rounds towards the nearest neighbor. If the number is exactly halfway between two neighbors, it rounds up.
HALF_DOWN	3.5	3	-3.5	-4	Rounds towards the nearest neighbor. If the number is exactly halfway between two neighbors, it rounds down.
HALF_EVEN	2.5	2	-2.5	-2	Rounds towards the nearest neighbor. If the number is exactly halfway between two neighbors, it rounds to the nearest even neighbor.
UNNECESSARY	3.14	NA	-3.14	NA	Throws an ArithmeticException to ensure no rounding occurs.

To verify the currency addition, open the Global Menu () and navigate to Commerce → Currencies. The new currency appears.

Alternatively, call the REST service using the Java client:

1. Navigate into the java folder and compile the source files:

   javac -classpath .:* *.java
   

2. Run the Currency_POST_ToInstance class.

   java -classpath .:* Currency_POST_ToInstance
   

Examine the cURL Command

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

curl \
	"http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/currencies" \
	--data-raw '
		{
			"code": "AED",
			"name": {
				"en_US": "UAE Dirham"
			},
		   "rate": 3.67
		}' \
	--header "Content-Type: application/json" \
	--request "POST" \
	--user "[e-mail]:learn"

Here are the command’s arguments:

Arguments	Description
"http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/currencies"	Specify the REST service endpoint.
--data-raw "{ "code": "AED", "name": { "en_US": "UAE Dirham" }, "rate": 3.67 }"	Enter the data to post.
--header "Content-Type: application/json"	Set the request body format to JSON.
--request POST	Set the HTTP method to invoke at the specified endpoint.
--user "[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 Currency_POST_ToInstance.java class adds a currency by calling the CurrencyResource service.

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

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

	System.out.println(
		currencyResource.postCurrency(
			new Currency() {
				{
					code = "AED";
					name = new HashMap<String, String>() {
						{
							put("en_US", "UAE Dirham");
						}
					};
					rate = new BigDecimal(3.67);
				}
			}));
}

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

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

Note

The main method’s comment demonstrates running the class.

The remaining example Java classes call different CurrencyResource methods.

Important

See CurrencyResource for service details.

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

Get Currencies from Instance

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

Currencies_GET_FromInstance.sh

Command:

./Currencies_GET_FromInstance.sh

Code:

curl \
	"http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/currencies" \
	--user "[e-mail]:learn"

Currencies_GET_FromInstance.java

Command:

java -classpath .:* Currencies_GET_FromInstance

Code:

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

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

	System.out.println(
		currencyResource.getCurrenciesPage(
			null, null, Pagination.of(1, 2), null));
}

The instance’s Currency objects are formatted in JSON.

Filtering, Paginating, Searching, and Sorting Currencies

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

• active
• primary
• code
• name

Filter Query	Description
name eq 'UAE Dirham'	The currency name must equal UAE Dirham.
code eq 'AED'	The currency code must be AED.
active eq false	The currency is not active

You can use the name field in your queries to sort the results:

Sort Query	Description
name:desc	Sort by currency name in descending order.

Read API Query Parameters for more information.

Get a Currency

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

tip

Use Currency_GET_ById.[java|sh] to get a list of all currencies, and note the id of the currency you want specifically.

Currency_GET_ById.sh

Command:

./Currency_GET_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/currencies/${1}" \
	--user "[e-mail]:learn"

Currency_GET_ById.java

Command:

java -classpath .:* -DcurrencyId=1234 Currency_GET_ById

Code:

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

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

	System.out.println(
		currencyResource.getCurrency(
			Long.valueOf(System.getProperty("currencyId"))));
}

The Currency fields are listed in JSON.

Patch a Currency

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

Currency_PATCH_ById.sh

Command:

./Currency_PATCH_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/currencies/${1}" \
	--data-raw '
		{
			"name": {
				"en_US": "United Arab Emirates Dirham"
			}
		}' \
	--header "Content-Type: application/json" \
	--request "PATCH" \
	--user "[e-mail]:learn"

Currency_PATCH_ById.java

Command:

java -classpath .:* -DcurrencyId=1234 Currency_PATCH_ById

Code:

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

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

	currencyResource.patchCurrency(
		Long.valueOf(System.getProperty("currencyId")),
		new Currency() {
			{
				name = new HashMap<String, String>() {
					{
						put("en_US", "United Arab Emirates Dirham");
					}
				};
			}
		});
}

Delete a Currency

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

Currency_DELETE_ById.sh

Command:

./Currency_DELETE_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/currencies/${1}" \
	--request "DELETE" \
	--user "[e-mail]:learn"

Currency_DELETE_ById.java

Command

java -classpath .:* -DcurrencyId=1234 Currency_DELETE_ById

Code:

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

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

	currencyResource.deleteCurrency(
		Long.valueOf(System.getProperty("currencyId")));
}

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

Related Topics

• Currencies
• Consuming REST Services