# Use cases
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](#commerce-layer-metrics-api-public-postman-collection).
## Metrics API public Postman collection
The [Metrics API Postman collection](https://www.postman.com/commercelayer/workspace/commerce-layer-public-workspace/documentation/19711194-37a2d863-72f6-4b8f-8146-2f61d405fd3c) 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](#forking-the-collection), [set the environment variables](#setting-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](https://learning.postman.com/docs/collaborating-in-postman/version-control/#forking-postman-entities) 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](https://learning.postman.com/docs/collaborating-in-postman/version-control/#pulling-updates) 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](https://www.postman.com/commercelayer/), 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](https://blog.postman.com/introducing-environment-forking-and-pull-requests/) 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](/core/authentication/client-credentials.md#integration) access token (not required if you're using `client_id` and `client_secret` to automatically populate the Authorization header). |
| **`scope`** | The [scope](/core/authentication.md#authorization-scopes) 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). |
{% hint style="info" %}
If you already don't have a valid integration token already, you can use one of the requests in the [Authentication](https://www.postman.com/commercelayer/workspace/commerce-layer-public-workspace/documentation/19711194-37a2d863-72f6-4b8f-8146-2f61d405fd3c?entity=folder-19711194-e923b135-628d-4c36-9179-f9c611380) 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](/core/authentication.md#access-token-expiry)) to set the **Authorization** header and perform all the other calls in the collection.
{% endhint %}
#### 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](https://www.w3.org/TR/NOTE-datetime) 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](https://www.w3.org/TR/NOTE-datetime) 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](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/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`). |
{% hint style="info" %}
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.
{% endhint %}
### 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](https://www.postman.com/commercelayer/workspace/commerce-layer-public-workspace/documentation/19711194-37a2d863-72f6-4b8f-8146-2f61d405fd3c?entity=folder-19711194-581fbe9e-b699-445f-ad70-819dda4f6a82), [Returns](https://www.postman.com/commercelayer/workspace/commerce-layer-public-workspace/documentation/19711194-37a2d863-72f6-4b8f-8146-2f61d405fd3c?entity=folder-19711194-2f50c4c1-5e84-4670-aa84-37223cb4c069), or [Carts](https://www.postman.com/commercelayer/workspace/commerce-layer-public-workspace/documentation/19711194-37a2d863-72f6-4b8f-8146-2f61d405fd3c?entity=folder-19711194-fbf0ec93-cf7a-465d-b871-59b37379704c) folders and hit the *Send* button. :rocket:
## Share your use cases!
{% hint style="info" %}
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.
{% endhint %}
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 [join our public Discord channel](https://discord.gg/commercelayer) and ask the developer community.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.commercelayer.io/metrics/getting-started/use-cases.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.