# Retrieve prices

This method allows merchants to retrieve prices in bulk based on specified filter criteria with pagination settings.


  
    Without filters, the request returns all prices in the merchant account.
    With filters, each filter field requires a value to avoid validation errors.

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

## Header parameters:

  - `merchant` (string, required)
    Unique public key provided upon registration and must be shared for identification purposes.
    Example: "api_pk_7b197...ba108f842"

  - `signature` (string, required)
    Signature of request. It allows verifying whether the request from the merchant is genuine on the payment gateway server.
    Example: "M2E3OTkyNzcz...xMmExODI4"

## 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.

  - `items.status` (string, required)
    Product price status.


  Cannot be changed if a subscription exists for the product.
    Enum: "active", "disabled"

  - `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"

  - `error.constraints` (object)
    Map of constraints.

## 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"