List prices

3 minute(s) read

Get

/api/data/v1/prices

Retrieves published price records for a specific pricing element in a framework.

Because pricing data can be large, the endpoint accepts query parameters so you can:

Pin the request to the right pricing context: which framework/version and which pricing element to query
Narrow the result set to just the products and scope combinations you need
Ask for prices as of a specific date, so you get the records that were effective at that point in time
Page through results safely when there are many records

What you get back
A list of published price records. Each record includes the price value and supporting fields that explain where it applies, such as product, element scope, scenario, and effective date range.

Security

HTTP

Type bearer

Enter an access token to authenticate your requests. For details, read Get an access token.

Query parameters

elementId

string (uuid) Required

Identifier of a framework's pricing element whose prices you want to get.

frameworkVersionId

string (uuid)

Framework version identifier. Together with elementId, this defines the published pricing dataset to query.

Provide either frameworkVersionId or frameworkId. They are mutually exclusive, but one of them is required.

frameworkId

string (uuid)

Framework identifier. Together with elementId, this defines the published pricing dataset to query.

Provide either frameworkVersionId or frameworkId. They are mutually exclusive, but one of them is required.

productId

array of string

Identifiers of products whose prices you want to get.

ExampleSKU-001

scope.

string

Scope filters that allow you to request prices only for certain scopes supported by the element. Use the following format for this query parameter: scope.<key>=<value>, where <key> must match a scope attribute defined on the element’s scopes.

Note: The Try it & see response feature on this page can’t execute requests that use dynamic query parameter names, such as scope.ProductId=SKU-1. To use this query parameter, run the request from your preferred tool and manually add it to the request URL.

Examplescope.ProductId=SKU-1

effectiveAt

string (date-time)

Date in the YYYY-MM-DD format. The API returns the records that are effective at that time. If you don’t specify a date, the API uses today’s date.

The date must be within the retention window, otherwise the API returns the 400 validation error.

Example2026-01-01T00:00:00Z

cursor

string

Cursor for pagination.

limit

integer

Сontrols how many records to return per page.

Minimum1.0

Maximum1000.0

Default200

Example300

Responses

200

Price records response

example

{
  "data": {
    "records": [
      {
        "PriceRecordId": "125492",
        "PriceValue": 100,
        "Currency": "USD",
        "ScenarioId": "1254891-54593",
        "ElementScopeId": "00257",
        "ProductId": "SKU-001",
        "EffectiveFrom": "2025-01-01",
        "EffectiveTo": "9999-12-31"
      }
    ]
  },
  "pagination": {
    "cursor": "200",
    "hasMore": true
  },
  "meta": {
    "requestId": "req-123",
    "effectiveAt": "2025-01-01",
    "frameworkVersionId": "0325620-84236",
    "pricingView": "published_flattened",
    "scenarioId": "1254891-54593"
  }
}

Expand All

object

data

object

records

Array of object (PriceRecord)

A list of price records.

object

A published price and its key details like a unique ID, value, currency, effective date, and product it applies to.

pagination

object (Pagination)

Results pagination details.

cursor

string | null

Cursor for pagination.

hasMore

boolean

True if more records are available.

meta

object (EnvelopeMeta)

requestId

string

Request identifier for tracing.

effectiveAt

string (date-time)

frameworkVersionId

string (uuid)

Framework version identifier.

pricingView

string

scenarioId

string (uuid)

Related scenario identifier.

400

Validation error

validationError

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request",
    "requestId": "req-123",
    "details": {}
  }
}

Expand All

object

error

object (Error)

code

string

message

string

requestId

string

details

401

Unauthorized

unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Unauthorized",
    "requestId": "req-123"
  }
}

Expand All

object

error

object (Error)

code

string

message

string

requestId

string

details

403

Forbidden

forbidden

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Forbidden",
    "requestId": "req-123"
  }
}

Expand All

object

error

object (Error)

code

string

message

string

requestId

string

details

404

Queried element not found

notFound

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Not found",
    "requestId": "req-123"
  }
}

Expand All

object

error

object (Error)

code

string

message

string

requestId

string

details

500

Internal error

internalError

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal error",
    "requestId": "req-123"
  }
}

Expand All

object

error

object (Error)

code

string

message

string

requestId

string

details

502

Upstream error

upstreamError

{
  "error": {
    "code": "UPSTREAM_ERROR",
    "message": "Upstream dependency failed",
    "requestId": "req-123"
  }
}

Expand All

object

error

object (Error)

code

string

message

string

requestId

string

details

Was this topic helpful?