Use cases

A list of the most common application scenarios of Commerce Layer Metrics API

The examples of the previous section aimed to help you easily understand how to use the Metrics API without claiming to be realistic or exhaustive. This section features a curated and regularly updated list of real-life use cases and common metrics and stats you may want to extract from your real organization data. Feel free to get in touch with us and ask for more in case you don't find yours in the list below or in the Postman collection.

Metrics API public Postman collection

The Metrics API Postman collection is a great way for you to explore a pretty comprehensive list of use cases as a new user and see what the requests and responses of different queries look like.

The collection is public, meaning that you can just have a look at the API calls to better understand how they work or even access with your Postman account, fork the collection, set the environment variables based on your Commerce Layer credentials, and test the Metrics API efficiently using your organization data. This way you can also watch the collection for changes and get notified when some new update is released. When you receive a notification that we have released a new version of the collection, you can pull in the changes to keep your fork up-to-date.

Forking the collection

To test the Metrics API using your organization data you need to fork the collection. To do that:

1. Log in to your Postman account, visit Commerce Layer Postman page, and select Commerce Layer Metrics API ({{latest_release_date}}) — e.g. Commerce Layer Metrics API (2022-10-17) — under the Collections tab.

2. Click on the Fork icon (or on the three dots near the collection name and select Create a fork from the dropdown menu) to fork the collection into your personal Postman account.

3. Enter a name for your fork, select a workspace to fork into (this can be your personal or team workspace), and ensure to check the Watch original collection box. This will enable you to receive notifications in Postman when there are changes to the original collection.

After clicking the Fork collection button, the fork process will begin and you can view the fork in your workspace.

Setting the environment variables

To make it easier to make requests to the Metrics API with the same setup and credentials, you can fork the Metrics API environment of the public collection as you did for the collection itself or create a new environment in your workspace to use across the forked collection. To do that:

1. Click on the Environments tab and then on Create environment at the top left corner of the page.

2. Fill out the form by adding the variables listed in the tables below.

3. Click on the Save icon to save the environment variables you have created.

4. You can also edit the name of the environment by highlighting the existing New environment name just above the form. You will see an edit icon you can click on to enter a new name.

Config and auth variables

These variables are used to properly configure the authentication flow of the collection API calls:

Variable	Description
subdomain	The unique subdomain of your Commerce Layer organization (i.e. the slugified version of your organization's name — e.g. my-store).
access_token	A valid integration access token (not required if you're using client_id and client_secret to automatically populate the Authorization header).
scope	The scope you want your call to be restricted to (e.g. market:1234).
client_id	Your integration client ID (you can copy it from the Commerce Layer Dashboard API credentials details page).
client_secret	Your integration client secret (you can copy it from the Commerce Layer Dashboard API credentials details page).

If you already don't have a valid integration token already, you can use one of the requests in the Authentication folder of the collection to get one. These are API calls to the /oauth endpoint, prefilled with your client_id and client_secret. The resulting access token will be automatically used (until its expiration) to set the Authorization header and perform all the other calls in the collection.

Filter and data variables

These are optional variables we use in the collection to populate recurring keys and that you can set based on your needs and fill with values coming from your organization (e.g. SKU codes, currencies, coupons):

Variable	Description
date_from	The lower limit of the date and time range you want to use to filter the collected results (complete date plus hours, minutes, and seconds — according to the ISO 8601 standard, e.g. 2021-01-01T00:00:00Z).
date_to	The upper limit of the date and time range you want to use to filter the collected results (complete date plus hours, minutes, and seconds — according to the ISO 8601 standard, e.g. 2021-12-31T23:59:59Z).
sku_1	The SKU code of an SKU in your organization (e.g. TSHIRT0001).
sku_2	The SKU codes of another SKU in your organization (e.g. TSHIRT0002).
item_1	The ID of an SKU or bundle in your organization (e.g. BmDzSVkXAW).
item_2	The ID of another SKU or bundle in your organization (e.g. ZrxeSRgOmB).
market_1	The name of one of the markets of your organization (e.g. North America).
currency_1	The international 3-letter code (as defined by the ISO 4217 standard) of one of the currencies you use to sell in your organization (e.g. EUR).
currency_2	The international 3-letter code (as defined by the ISO 4217 standard) of another currency you use to sell in your organization (e.g. USD).
country_1	The international 2-letter code (as defined by the ISO 3166-1 standard) of one of the countries you're selling in (e.g. US).
country_2	The international 2-letter code (as defined by the ISO 3166-1 standard) of another country you're selling in (e.g. IT).
city_1	The name of one of the cities you're shipping to (e.g. London).
city_2	The name of another city you're shipping to (e.g. New York).
coupon_1	A valid coupon code you're using for promotions in your organization (e.g. SOLDOUT0001).
promotion_1	The name of an active promotion (e.g. Percentage 50).
promotion_type_1	A valid promotion type (e.g. percentage_discount_promotions).
option_name_1	The name of an SKU option associated with an SKU in your organization (e.g. Engraving).
tag_1	The name of an existing tag (e.g. VIP).
tag_2	The name of another existing tag (e.g. pre-order).
email_domain_1	An email domain used by your customers (e.g. gmail.com).
email_domain_2	Another email domain used by your customers (e.g. hotmail.com).

If you don't set these variables in the collection environment, make sure to manually populate the related keys in the API calls that use them.

Trying out the Metrics API

If everything is set up correctly, you can head back to the forked collection, select the environment you just created, and begin making calls. Just choose a use case from the Orders, Returns, or Carts folders and hit the Send button. 🚀

Share your use cases!

A selected subset of use cases is detailed with some request/response examples on the following pages. For each of them, some similar use cases are also linked. To see the full list and make sure to be constantly up-to-date we strongly that you check the collection on Postman directly.

If you have different use cases that you're not sure how to address using the Metrics API or you think it's worth adding to the list, just reach out to us or subscribe to our public Slack channel and ask the developer community.