# Price Groups

## Prerequisites

* An `access_token` from [headless-api-authentication](https://dev.ucommerce.net/readme/headless/headless-api-authentication "mention")
* A `cultureCode`, e.g., `en-US` (string)

## Get Price Groups

### Optional Parameters

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

### 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](https://dev.ucommerce.net/readme/extensions/custom-price-group-criteria) 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="../error-handling" %}
[error-handling](https://dev.ucommerce.net/readme/headless/error-handling)
{% endcontent-ref %}