# Price Groups

## Prerequisites

* An `access_token` from [Headless API Authentication](/readme/headless/headless-api-authentication.md)
* A `cultureCode`, e.g., `en-US` (string)

## Get Price Groups

### Optional Parameters

* `maxItems`, limits the number of results returned. in [Pagination](/readme/headless/pagination.md)
* `nextPagingToken`, required to fetch the next page. Read more in [Pagination](/readme/headless/pagination.md)
* `filters-*,` used for [filtering](#filtering-valid-price-groups) for valid price groups based on [price group criteria](/readme/miscellaneous/price-group-criteria.md).

### Request

```bash
curl -D- -X GET <base_url>/api/v1/price-groups?cultureCode=<cultureCode>&maxItems=<maxItems>&nextPagingToken=<nextPagingToken> \
    -H 'Authorization: Bearer <ACCESS_TOKEN>'
    -H 'Content-Type: application/json'
```

### Response

```json
{
    "nextPagingToken": null,
    "priceGroups": [
        {  
            id: "{id}",
            name: "{priceGroupsName}"
        }
    ]
}
```

## Error Handling

| Error              | Description                                      |
| ------------------ | ------------------------------------------------ |
| BadRequest (400)   | Invalid access token; Invalid culture code etc.  |
| Unauthorized (401) | The token is expired.                            |
| Forbidden (403)    | The token does not have access to this endpoint. |

Error Response Example

```json
{
"errors":
    [
        {
            "error-description": "Invalid cultureCode.",
            "error": "BadRequest"
        }
    ]
}
```

## Filtering Valid Price Groups

To get the valid price groups for a context, this endpoint supports giving it a set of properties prefixed with `filters-`. Setting any filter property will make the API only return price groups that are valid according to the criteria set up for them.\
The API will map any parameters prefixed  `filters-` to a dictionary of properties, sent to the `GetPriceGroups` pipeline, in the following way:\
The parameter name will be mapped to the key in the dictionary, with the `filters-` part of the name stripped off. The parameter value will be mapped to the value in the dictionary.

```sh
curl -D- -X GET <base_url>/api/v1/price-groups?filters-customer=29ae4d70-f0dd-4eca-83bf-7125920f3279&cultureCode=<cultureCode>&maxItems=<maxItems>&nextPagingToken=<nextPagingToken> \
    -H 'Authorization: Bearer <ACCESS_TOKEN>'
    -H 'Content-Type: application/json'
```

In the above example, we're calling the API with a `filters-customer` query parameter.\
The key will be `customer` and the value will be `29ae4d70-f0dd-4eca-83bf-7125920f3279` - the GUID of the current customer.

This can be used to send filtering properties used by either the built-in criteria, or your custom criteria. The built-in criteria uses the following keys:

* Key `customer` - Validates the customer against all customer group or organization criteria.
  * Value: `Guid` of the customer
* Key `customerGroup` - Validates the customer group against all customer group criteria.
  * Value: `Guid` of the customer group
* Key `organization` - Validates the organization against all organization criteria.
  * Value: `Guid` of the organization

The time-based criterion doesn't use any properties as it is validated via server time. This means, that, if no other filter properties are needed, you will need to add an unused filter property, e.g. `filters-time=` to trigger the filtering.

See the [guide on extending price group criteria](/readme/extensions/custom-price-group-criteria.md) for more details on how to use the properties in a pipeline task.

{% hint style="info" %}
If any filtering properties are given, all criteria will be checked. This means that even if the only filtering property sent is a customer guid, all time-based criteria will also influence the filtering.
{% endhint %}

## Related Articles

{% content-ref url="/pages/OKRcu1Dp3gn5Y38w55HD" %}
[Error Handling](/readme/headless/error-handling.md)
{% endcontent-ref %}


---

# 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://dev.ucommerce.net/readme/headless/reference/price-groups.md?ask=<question>
```

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.