Use cases
A list of the most common application scenarios of Commerce Layer Metrics API
Last updated
A list of the most common application scenarios of Commerce Layer Metrics API
Last updated
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.
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.
To test the Metrics API using your organization data you need to fork the collection. To do that:
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.
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.
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.
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:
Click on the Environments tab and then on Create environment at the top left corner of the page.
Fill out the form by adding the variables listed in the tables below.
Click on the Save icon to save the environment variables you have created.
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.
These variables are used to properly configure the authentication flow of the collection API calls:
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.
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):
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.
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. 🚀
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.
