# Retrieve prices

This method allows merchants to <a href="https://docs.solidgate.com/billing/manage-products/#retrieve-price-details" target="_blank">retrieve prices</a> in bulk based on specified filter criteria with pagination settings.
<blockquote>
<ul>
<li>Without filters, the request returns all prices in the merchant account.</li>
<li>With filters, each filter field requires a value to avoid validation errors.</li>
</ul>
</blockquote>

Endpoint: POST /products/prices/list
Version: 1.0.0
Security: MerchantID

## Header parameters:

  - `merchant` (string, required)
    Unique <a href="https://docs.solidgate.com/payments/integrate/access-to-api/#retrieve-your-credentials" target="_blank">public key</a> provided upon registration and must be shared for identification purposes.

  - `signature` (string, required)
    <a href="https://docs.solidgate.com/payments/integrate/access-to-api/#generate-signature" target="_blank">Signature</a> of request. It allows verifying whether the request from the merchant is genuine on the payment gateway server.

## Request fields (application/json):

  - `filters` (object)
    Filter criteria for retrieving prices.

  - `filters.default` (object)
    Specify if to retrieve default prices.

  - `filters.default.operator` (string)
    Specify operator for filtering default prices.
    Enum: "eq"

  - `filters.default.value` (string)
    Set to true to retrieve default prices.
    Enum: "true", "false"

  - `filters.updated_at` (object)
    Filter by update timestamp for incremental synchronization.

  - `filters.updated_at.operator` (string)
    Comparison operator for the timestamp.
    Enum: "gte"

  - `filters.updated_at.value` (string)
    Timestamp to filter prices.
    Example: 2025-12-15 10:40:25

  - `pagination` (object)
    Pagination settings for retrieving prices.

  - `pagination.page_size` (integer)
    Page size based on the set or default value.
    Example: 100

  - `pagination.next_page_token` (string)
    Token for retrieving the next page of results. Obtained from the previous response. Omit this parameter for the first request.
    Example: eyJzdWJzY3JpcHRpb25faWQiOiI5ODlkCJkYXRlX3RvIjoiMjAyMC0wOS0xNyAxNDoxMDowMCJ9

## Response 200 fields (application/json):

  - `items` (array)
    Contains price data items, each representing a specific price configuration.

  - `items.id` (string, required)
    Unique product price identifier.
    Example: cb43b415-5522-4373-b026-a365462f9114

  - `items.default` (boolean, required)
    Indicates whether the price is the default for the product.
    Example: false

  - `items.status` (string, required)
    Product price status.
Cannot be changed if a subscription exists for the product.
    Enum: "active", "disabled", "archived"

  - `items.created_at` (string, required)
    Datetime of the product price creation.
    Example: 2025-05-31 12:53:12

  - `items.updated_at` (string, required)
    Datetime of the product price update.
    Example: 2025-05-31 12:53:13

  - `items.product_price` (integer, required)
    Product price.
    Example: 1000

  - `items.trial_price` (integer)
    Trial price.
    Example: 500

  - `items.currency` (string, required)
    Three-letter ISO-4217 currency code of the product price currency.
    Example: USD

  - `items.country` (string)
    Country code.
Not returned or expected for default prices.
    Example: USA

  - `pagination` (object)
    Contains information about the pagination of the results.

  - `pagination.page_size` (integer, required)
    Page size based on the set or default value.
    Example: 100

  - `pagination.next_page_token` (string)
    Token to retrieve the next page of results. Use this value in the next request. Empty or null if no more pages are available.
    Example: eyJzdWJzY3JpcHRpb25faWQiOiI5ODlkCJkYXRlX3RvIjoiMjAyMC0wOS0xNyAxNDoxMDowMCJ9

## Response 400 fields (application/json):

  - `error` (object, required)
    Error object.

  - `error.code` (string, required)
    Error code.
    Example: 2.01

  - `error.message` (string, required)
    Error message.
    Example: Validation error

## Response 401 fields (application/json):

  - `error` (object, required)
    Error object.

  - `error.code` (string, required)
    Error code indicating the specific authorization failure.
    Example: 1.01

  - `error.message` (string, required)
    Descriptive message providing more details about the authorization failure.
    Example: Authorization failed

## Response 403 fields (application/json):

  - `error` (object, required)
    Error object.

  - `error.code` (string, required)
    Error code indicating that access to the service is denied.
    Example: 1.02

  - `error.message` (string, required)
    Message informing that the service is not allowed for the account.
    Example: Access denied