Omnia 2.0 API (0.0.7168)

This is the API powering Omnia 2.0 and Pricemonitor, containing operations that can also be used directly by customers from their own systems.

The Omnia 2.0 API is RESTful and provides access to the backend of Omnia 2.0 and Pricemonitor. It is used to manage products, offers, contracts, and more.

This API supports both public endpoints for customer integration and internal endpoints for platform management. All endpoints are authenticated using either Basic Authentication or JWT Bearer tokens.

Download OpenAPI description
Languages
Servers
Mock server

https://api-docs.omniaretail.dev/_mock/api/omnia/

Production API

https://api.patagona.de/

Overview

Overview, explanation and pointers to the API documentation.

Products Management

Operations to manage your products.

Operations

Import products

We have two options: Either you provide the products as JSON or as CSV. The product import via JSON is recommended.

Notes:

  • When importing products, you need to provide an unique product identifier. We only allow importing products when they can be uniquely identified. In the very past we solely relied on GTIN for that, but not all customers have a GTIN. So we introduced the generic concept of the unique product identifier.
  • When importing products, you can additionally provide tags. These tags are key/value pairs (custom fields) which can be used to categorize your products: E.g. you could add the brand of the product.
    The tag names need to be unique and non-empty.
  • In some endpoints we use caching for up to 5 minutes. So your newly imported products might need up to 5 minutes to get visible.
  • Timing is important: It's recommended to import products during a period when no monitorings are scheduled. Otherwise, the monitoring does not cover the most recently added products. A subsequent monitoring run will cover the previously added products.

Recommended tags

To get the most value out of the Omnia 2.0 insights dashboards, we recommend to include the following tag-keys in your imports. These product attributes can be used to drill-down into market and pricing insights.

KeyDescription of value
brandValues should include the brand of the respective product
skuIf available, you can also include the stock keeping unit identifier
amountInStockIf available, you can also include the current stock level of each product
topCategoryYour product categories, highest level
midCategoryYour product categories, mid level
lowCategoryYour product categories, lowest level
purchasePriceThe purchase price of your product
imageUrlA url containing an image of your product
logisticalCostThe logistical cost of your product
recommendSellingPriceThe manufacturer suggested retail price or recommended retail price of your product
vatThe Value Added Tax (VAT) for your product

Notes:

  • These fields are not mandatory for a successful import. They are optional, but recommended, to get the most value out of the insights in the UI of Omnia 2.0. If you intend to use them in the recommended way
  • The keys for the tags are case sensitive, so specify exactly as above.

Import products via JSON (recommended)

The preferred way to import products via API is via JSON.

This operation adds products to our system using upsert (insert or update). It needs to be used in conjunction with a timestamp-based product deletion operation.

The delete makes sure that old products, which are not part of your assortment anymore, are dropped from the system.

Typical usage pattern:

  1. Remember the current time in UTC
  2. Add products in chunks. Recommended chunk size: 1,000 products
  3. Delete old products that are not needed in the system anymore by the timestamp from step 1 minus some extra buffer, e.g. one minute.

Import products via CSV (not recommended)

In order to provide products to our system you can send a CSV file via this operation. This endpoint deactivates all current products and activates the ones which are provided via CSV.

This creates a "task" at our side. Tasks are processed asynchronously. Typically, a big product import with 500K products takes 5-10 minutes. The mentioned endpoint returns a task id and a url where you can check the task state. Possible task states are: pending, executing, failed and succeeded. The last two states are representing a completed task. The task itself contains more details about how many products could get imported, which ones failed plus a preview failure list.

When the product import successfully completed then the previously imported products have been deleted and only the ones which you have provided via CSV file are active in our system.

Query products

Use this operation to retrieve products via a query you specify in the request. It supports returning paged results. We recommend to retrieve with a page size of up to 10,000 products.

Get all products

Use the query operation and just omit the query filter in the request. Results are paginated. A page size of at most 10,000 is recommended.

Determine internal product ids from your product ids

Our system uses internal product ids that are distinct from your products ids. These internal product ids are sometimes referred to as pricemonitor product ids.

Often API operations require internal product ids to be specified. So you may need to map your product id onto our internal product id.

There are two options:

  • Either you store the internal product ids after importing products into our system. The import operation returns the internal product ids for each imported product.
  • Or you map product ids on the fly when you need to by querying specifying your product ids in the query. It's recommended to specify 1,000 product ids at once.

Add products in bulk (JSON)

Request

This operation is used to import products into the system from JSON formatted data:
Products that are already present will be updated and new products will be added. Identification of the products is done based on the identifying attributes, which need to be provided via the request body.

Note:
This endpoint should be used in conjunction with: DELETE /api/v3/vendor/contracts/{contractId}/products.

Procedure:
1. Add your products in bulks with multiple requests via this endpoint.
2. Send a DELETE request to /api/v3/vendor/contracts/{contractId}/products and set the parameter updatedMax to a date which is older or equal to your first request from step 1.

Security
BasicAuth or BearerAuth
Path
contractIdstringnon-emptyrequired

Unique identifier of the contract

Example: qbcxvb
Headers
content-typestringrequired
Value"application/json"
Example: application/json
patagona-tags-decimal-separatorstringrequired

The decimal separator is used for parsing numbers in tags. English and German number formats are supported: dot and comma.

Enum"."","
Example: .
Bodyapplication/jsonrequired

The body contains the products which should be added

productsArray of objects(PostProduct)required

Products which should be added to the pricemonitor

products[].​namestring[ 1 .. 999 ] charactersrequired

Product name or title as displayed to customers

Example: "Samsung Galaxy S24 Ultra 256GB"
products[].​customerProductIdstring[ 1 .. 255 ] characters

Customer-specific product identifier. This can be your internal SKU or product ID. Used for mapping products between your system and the pricemonitor.

Example: "SKU-GALAXY-S24-256"
products[].​gtininteger(int64)[ 1 .. 99999999999999 ]

Global Trade Item Number (GTIN) - typically EAN-13, UPC-A, or GTIN-14. Must be a valid positive number representing the product's global identifier.

Example: 8806094937329
products[].​referencePricenumber(double)[ 0.01 .. 9999999999999.99 ]required

Reference price for the product.

For Omnia 2.0: This represents the selling price - the actual price at which you sell the product. For Pricemonitor: One of the use cases is to treat this as MSRP (Manufacturer's Suggested Retail Price).

Used as a baseline for pricing strategies and recommendations. Will be rounded to two decimal places using half-up rounding.

Example: 1199.99
products[].​minPriceBoundarynumber(double)>= 0.01required

Minimum allowed price boundary for automated pricing. Must be less than or equal to maxPriceBoundary. Will be rounded to two decimal places using half-up rounding.

Example: 999.99
products[].​maxPriceBoundarynumber(double)[ 0.01 .. 9999999999999.99 ]required

Maximum allowed price boundary for automated pricing. Must be greater than or equal to minPriceBoundary. Will be rounded to two decimal places using half-up rounding.

Example: 1399.99
products[].​tagsArray of objects(TagInput)[ 0 .. 100 ] itemsrequired

Product tags for categorization and strategy application. Used by pricing strategies to group and target specific products.

Example: [{"key":"brand","value":"Samsung"},{"key":"category","value":"smartphones"},{"key":"storage","value":"256GB"}]
products[].​tags[].​keystring[ 1 .. 100 ] characters^[a-zA-Z0-9_-]+$required

Tag identifier/name. Must be unique within a single product. Used to categorize products for pricing strategies and reporting.

Example: "brand"
products[].​tags[].​valuestring<= 10000 charactersrequired

Tag value associated with the key. Contains the actual categorization data for the product.

Example: "Samsung"
versionstringrequired

Version of the request body. Only version 2 is supported.

Value"2"
identifyingAttributesArray of strings(PostProductsIdentifyingAttribute)required

Non-empty list of product attributes which identify your products uniquely. Please ensure that you specify only one attribute in the list. Avoid using tags as an identifier, as this feature will soon be deprecated. By doing so, may loose historical market data during product import.

Items Enum"customerProductId""gtin""name"
curl -i -X POST \
  -u <username>:<password> \
  https://api-docs.omniaretail.dev/_mock/api/omnia/api/v3/vendor/contracts/qbcxvb/products \
  -H 'content-type: application/json' \
  -H 'patagona-tags-decimal-separator: .' \
  -d '{
    "products": [
      {
        "name": "Samsung Galaxy S24 Ultra 256GB",
        "customerProductId": "SKU-GALAXY-S24-256",
        "gtin": 8806094937329,
        "referencePrice": 1199.99,
        "minPriceBoundary": 999.99,
        "maxPriceBoundary": 1399.99,
        "tags": [
          {
            "key": "brand",
            "value": "Samsung"
          },
          {
            "key": "category",
            "value": "smartphones"
          },
          {
            "key": "storage",
            "value": "256GB"
          }
        ]
      }
    ],
    "version": "2",
    "identifyingAttributes": [
      "customerProductId"
    ]
  }'

Responses

The response provides sorted import results in respective to the order of the provided products.

Bodyapplication/json
dataArray of objects(PostProductsApiResponse)
Response
application/json
{ "data": [ {} ] }

Add products in bulk (CSV)

Request

This operation is used to import products into the system from CSV formatted data. This process is represented by a task, which is processed asynchronously. In the response you will receive a url which is used to check the status of the import process.

When the process is done all products in csv file from the request body will be in the pricemonitor. Products that were already present before have been updated and new products have been added.

Warning: All products that were in the pricemonitor before but are not present in the new import will be deleted.

Identification of the products is done based on the identifying attributes (see parameter: patagona-product-identifying-attributes)

Note: It is recommended to use the JSON variant to add products as it works synchronously and more efficient.

Security
BasicAuth or BearerAuth
Path
contractIdstringnon-emptyrequired

Unique identifier of the contract

Example: qbcxvb
Headers
content-typestringrequired
Enum"text/csv""text/comma-separated-values""text/csv; charset=UTF-8""text/comma-separated-values; charset=UTF-8"
Example: text/csv
patagona-product-identifying-attributesstringrequired

A single CSV column that identify a product uniquely. Avoid using tags as an identifier, as this feature will soon be deprecated By doing so, you may loose historical market data during product import.

Example: id-column
patagona-product-namestringrequired

Csv column that contains the product name

Example: name-column
patagona-product-reference-pricestringrequired

Csv column that contains the reference price

Example: reference-price-column
patagona-product-min-pricestringrequired

Csv column that contains the min price

Example: min-price-column
patagona-product-max-pricestringrequired

Csv column that contains the max price

Example: max-price-column
patagona-product-gtinstring

Csv column that contains the gtin

Example: max-price-column
patagona-product-customer-idstring

Csv column that contains an id (There is no requirement for this field to be unique)

Example: id-column
patagona-decimal-separatorstringrequired

Decimal separator used for parsing numbers
The values for patagona-decimal-separator, patagona-csv-column-separator and patagona-csv-quotation-character must be different from one another.
Available values: ",", "."

Example: .
patagona-csv-column-separatorstringrequired

The csv column separator
It can be provided either as text or as Base64 encoded string (e.g. needed for tab as separator).
The values for patagona-decimal-separator, patagona-csv-column-separator and patagona-csv-quotation-character must be different from one another.

Example: ,
patagona-csv-quotation-characterstringrequired

The csv quotation character
The values for patagona-decimal-separator, patagona-csv-column-separator and patagona-csv-quotation-character must be different from one another.

Example: "
Bodytext/csvrequired

CSV file containing the products. Note: The CSV file should be encoded in UTF-8.

string
curl -i -X PUT \
  -u <username>:<password> \
  https://api-docs.omniaretail.dev/_mock/api/omnia/api/v3/vendor/contracts/qbcxvb/products \
  -H 'content-type: text/csv' \
  -H 'patagona-csv-column-separator: ,' \
  -H 'patagona-csv-quotation-character: "' \
  -H 'patagona-decimal-separator: .' \
  -H 'patagona-product-customer-id: id-column' \
  -H 'patagona-product-gtin: max-price-column' \
  -H 'patagona-product-identifying-attributes: id-column' \
  -H 'patagona-product-max-price: max-price-column' \
  -H 'patagona-product-min-price: min-price-column' \
  -H 'patagona-product-name: name-column' \
  -H 'patagona-product-reference-price: reference-price-column' \
  -d string

Responses

The field data.url in the returned object allows to check the status of the import process. It will point to the endpoint GET /api/2/v/contracts/{contractId}/tasks/{taskId}.
The field data.id is the task id corresponding to the product import.

Bodyapplication/json
dataobject(Task)required
data.​idstring
data.​urlstring
Response
application/json
{ "data": { "id": "string", "url": "string" } }

Delete products

Request

Delete all products or delete products by a last updated timestamp and/or a tag.

Note: Avoid any product import requests concurrently with DELETE requests to prevent potential issues.

Security
BasicAuth or BearerAuth
Path
contractIdstringnon-emptyrequired

Unique identifier of the contract

Example: qbcxvb
Query
updatedMaxstring(date-time)

Last updated timestamp of products, formatted as ISO Date (i.e. 2019-11-20T13:46:13Z) in UTC.
Products can be deleted which haven't been updated since the specified timestamp.
If the query parameter is missing all products are deleted.

tagKeystring

Tag key to consider for deleting products. This parameter works in combination with tagValue.

tagValuestring

Tag value to consider for deleting products. This parameter works in combination with tagKey.

curl -i -X DELETE \
  -u <username>:<password> \
  'https://api-docs.omniaretail.dev/_mock/api/omnia/api/v3/vendor/contracts/qbcxvb/products?tagKey=string&tagValue=string&updatedMax=2019-08-24T14%3A15%3A22Z'

Responses

Returns the number of deleted products.

Bodyapplication/json
dataobject
Response
application/json
{ "data": { "deleted": 0 } }

Return the extended tags for the given product

Request

Security
BasicAuth or BearerAuth
Path
contractIdstringnon-emptyrequired

Unique identifier of the contract

Example: qbcxvb
productIdstringrequired

ID of the product

Example: 1
curl -i -X GET \
  -u <username>:<password> \
  https://api-docs.omniaretail.dev/_mock/api/omnia/api/v3/vendor/contracts/qbcxvb/products/1/extendedtags

Responses

Returns a list of ExtendedTags for the given product.

Bodyapplication/json
dataArray of objects(ExtendedTag)required
data[].​booleanValueboolean
data[].​doubleValuenumber(double)
data[].​integerValueinteger(int32)
data[].​labelstringrequired
data[].​stringValuestringrequired
Response
application/json
{ "data": [ {} ] }

Get monitoring status of queried products

Request

Security
BasicAuth or BearerAuth
Path
contractIdstringnon-emptyrequired

Unique identifier of the contract

Example: qbcxvb
Query
productIdsArray of integers[ 1 .. 1000 ] itemsuniquerequired

The product ids for which the monitoring state should be returned

curl -i -X GET \
  -u <username>:<password> \
  'https://api-docs.omniaretail.dev/_mock/api/omnia/api/v3/vendor/contracts/qbcxvb/products/monitoringstatus?productIds=0'

Responses

Monitoring status of the queried products

Bodyapplication/json
dataArray of objects(com.patagona.pricemonitor.share.api.ProductMonitoringStatus)required
data[].​productIdnumberrequired

The product that gets monitored

data[].​statusOnDomainArray of objects(com.patagona.pricemonitor.share.api.ProductMonitoringStatusOnDomain)required

The monitoring status on each domain. It will contain an entry for each domain which is active for that contract.

data[].​statusOnDomain[].​domainstringrequired

The domain which gets monitored.

data[].​statusOnDomain[].​startedAtstring(date-time)

The last time pricemonitor tried to monitor the product on the given domain. If this doesn't exist it mean's that pricemonitor haven't tried to monitor this product on the domain yet. One reason could be that the product is very new or the domain has just recently been added to the contract.

data[].​statusOnDomain[].​completedAtstring(date-time)

The last time pricemonitor completed monitoring the product on the given domain.

data[].​statusOnDomain[].​outcomeobject(com.patagona.pricemonitor.share.api.ProductMonitoringStatusOnDomainOutcome)

Describes the result of a monitoring attempt.

Response
application/json
{ "data": [ {} ] }

Get price recommendations for one product

Request

This endpoint returns all price recommendations for one product within a given time range.

Security
BasicAuth or BearerAuth
Path
contractIdstringnon-emptyrequired

Unique identifier of the contract

Example: qbcxvb
productIdstringnon-emptyrequired

Internal product identifier in the pricemonitor system

Example: 862342
Query
startDatestring(date-time)

Start of time range for data retrieval.

Format: ISO 8601 date-time in UTC (e.g., 2024-01-15T10:30:00Z)

Default behavior:

  • If omitted and endDate is provided: startDate = endDate - 48 hours
  • If both omitted: range is NOW - 48 hours to NOW
Example: startDate=2024-01-15T00:00:00Z
endDatestring(date-time)

End of time range for data retrieval.

Format: ISO 8601 date-time in UTC (e.g., 2024-01-16T10:30:00Z)

Default behavior:

  • If omitted and startDate is provided: endDate = startDate + 48 hours
  • If both omitted: range is NOW - 48 hours to NOW
Example: endDate=2024-01-16T23:59:59Z
curl -i -X GET \
  -u <username>:<password> \
  'https://api-docs.omniaretail.dev/_mock/api/omnia/api/v3/vendor/contracts/qbcxvb/products/862342/pricerecommendationhistory?endDate=2024-01-16T23%3A59%3A59Z&startDate=2024-01-15T00%3A00%3A00Z'

Responses

A list of price recommendations

Bodyapplication/json
dataArray of objects(com.patagona.pricemonitor.share.api.ApiPriceRecommendation)required
data[].​oldPricenumber

The price of the cheapest offer of the own shop(s) on the relevant domain

data[].​deliveryCostsnumber

The delivery costs which were considered for the recommended price

data[].​timestampstring(date-time)required

The timestamp when the price recommendation has been calculated

data[].​oldDeliveryCostsnumber

The delivery costs corresponding to oldPrice

data[].​tagsArray of objects(com.patagona.pricemonitor.share.api.ExtendedTag)required

Additional information on this product

data[].​tags[].​doubleValuenumber

The double value depends on the decimal separator which has been provided during product import.

data[].​tags[].​integerValueinteger

The integer value of the tag. It's only defined when the stringValue consists solely of digits.

data[].​tags[].​labelstringrequired

The name of the tag. It can't be empty.

data[].​tags[].​stringValuestringrequired

The text value of the tag.

data[].​tags[].​booleanValueboolean

The boolean value of the tag. It's only set to true when the stringValue is "1" or "true".

data[].​pricenumberrequired

The recommended price of the relevant domain

data[].​oldPositioninteger

The old position on the relevant domain

data[].​gtinnumber

GTIN of the product

data[].​relativePriceChangePercentagenumber

Absolute percentage how the recommended price changed compared to the oldPrice e.g. 200 stands for 200% which means the recommended price has doubled

data[].​newPositioninteger

The new position on the relevant domain

data[].​decisiveStrategyBranchNamestring

The strategy branch name that calculated the price. This is only filled if the Strategy branch that calculated the price was given a name in the strategy tree. It will have the name that was active at the time the price was calculated (see timestamp)

data[].​customerProductIdstring

The customer's id of the product

data[].​originalMaxPriceBoundarynumberrequired

Max price boundary during the time when the price was calculated

data[].​relevantDomainstring

The decisive domain of the price recommendation. It's been determined by the cheapest price recommendation.

data[].​originalMinPriceBoundarynumberrequired

Min price boundary during the time when the price was calculated

data[].​currencystringrequired

The currency of the price recommendation.

data[].​productIdstringrequired

The internal product id of the pricemonitor

data[].​originalTagsArray of objects(com.patagona.pricemonitor.share.api.ExtendedTag)required

List of tags which were set during the time when the price has been calculated. ATTENTION: These are historic tags which are maybe outdated or incomplete.

data[].​originalTags[].​doubleValuenumber

The double value depends on the decimal separator which has been provided during product import.

data[].​originalTags[].​integerValueinteger

The integer value of the tag. It's only defined when the stringValue consists solely of digits.

data[].​originalTags[].​labelstringrequired

The name of the tag. It can't be empty.

data[].​originalTags[].​stringValuestringrequired

The text value of the tag.

data[].​originalTags[].​booleanValueboolean

The boolean value of the tag. It's only set to true when the stringValue is "1" or "true".

data[].​decisiveStrategyTreeLeafNodeIdintegerrequired

The leaf node of the strategy branch that calculated the price. This id references the node in the strategy branch that was active at the time the price was calculated (see timestamp)

Response
application/json
{ "data": [ {} ] }

Query products of a contract

Request

This endpoint can be used for querying either all products or certain products by the 'customerProductId' or 'productId'.

Security
BasicAuth or BearerAuth
Path
contractIdstringnon-emptyrequired

Unique identifier of the contract

Example: qbcxvb
Bodyapplication/json

The body contains the products query.
Currently, it supports only product queries for two attributes:

  • by "customerProductId"
  • by "productId" (Patagona's internal product id). Allowed values for 'productId' are numerical integer values
The maximum allowed limit in the pagination is 10000.
For better performance, when paginating over all products of a contract, we recommend to use a limit of 10000 products per page. Pagination works with respective to the given products query.
This is most relevant when querying for a set of customerProductId's.
When the requests are chunked over a set of ids, it is easiest to provide up to 10000 customerProductId's in the query and keep the pagination at start: 0, limit: 10000.
It also contains a boolean optional parameter 'includeTags' which is used to include the tags of the products in the response.
The only allowed pattern is currently:
{
"pagination": {
"start": ${start},
"limit": ${limit}
},
"filter": {
"oneOf": {
"field": "customerProductId",
"values": [${customerProductIds as a list of strings}]
}
},
"includeTags": ${includeTags}
}

example:
{
"pagination": {
"start": 0,
"limit": 10
},
"filter": {
"oneOf": {
"field": "customerProductId",
"values": ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10"]
}
},
"includeTags": true
}
paginationobject(com.patagona.pricemonitor.share.api.Pagination)required

This model describes a step in a paginated endpoint. It consists of the start index, set to 0 for the first page. The next page starts at (previous start) + limit. Reasonable values for the limit parameter depend on the specific endpoint.

pagination.​startintegerrequired
pagination.​limitintegerrequired
filterobject(com.patagona.pricemonitor.share.api.Query)

This class specifies a general query language, even though all fields are marked as optional, exactly one has to be specified. Please note that depending on the endpoint only a subset of the query language might be supported. Refer to the endpoint specific documentation to view the restrictions.

includeTagsboolean

Whether to include tags in the response or not

curl -i -X POST \
  -u <username>:<password> \
  https://api-docs.omniaretail.dev/_mock/api/omnia/api/v3.1/vendor/contracts/qbcxvb/products/query \
  -H 'Content-Type: application/json' \
  -d '{
    "pagination": {
      "start": 0,
      "limit": 0
    },
    "filter": {
      "regex": {
        "field": "string",
        "pattern": "string"
      },
      "in": {
        "field": "string",
        "query": {}
      },
      "or": [
        {}
      ],
      "const": true,
      "not": {},
      "oneOf": {
        "field": "string",
        "values": [
          "string"
        ]
      },
      "lt": {
        "field": "string",
        "value": "string"
      },
      "gt": {
        "field": "string",
        "value": "string"
      },
      "eq": {
        "field": "string",
        "value": "string"
      },
      "and": [
        {}
      ]
    },
    "includeTags": true
  }'

Responses

Returns a list of found products.

Bodyapplication/json
dataArray of objects(com.patagona.pricemonitor.share.api.ApiProductV3)required
data[].​namestringrequired

Name of the product.

data[].​tagsArray of objects(com.patagona.pricemonitor.share.api.ExtendedTag)required

Additional information on this product.

data[].​tags[].​doubleValuenumber

The double value depends on the decimal separator which has been provided during product import.

data[].​tags[].​integerValueinteger

The integer value of the tag. It's only defined when the stringValue consists solely of digits.

data[].​tags[].​labelstringrequired

The name of the tag. It can't be empty.

data[].​tags[].​stringValuestringrequired

The text value of the tag.

data[].​tags[].​booleanValueboolean

The boolean value of the tag. It's only set to true when the stringValue is "1" or "true".

data[].​minPriceBoundarynumber

Maximum price which pricemonitor can recommend for the product. It won't recommend any price above this boundary.

data[].​gtinnumber

GTIN of the product. Can be optionally.

data[].​customerProductIdstring

The customer's id of the product. This field allows to link products in pricemonitor to products in the customer's system.

data[].​idstringrequired

Id of the product in the pricemonitor.

data[].​maxPriceBoundarynumber

Minimum price which pricemonitor can recommend for the product. It won't recommend any price below this boundary.

data[].​referencePricenumberrequired

Some price that will be used as benchmark for certain components in pricemonitor.

Response
application/json
{ "data": [ {} ] }

Get Amazon Buy Box statistics for time range

Request

Provides latest Amazon Buy Box statistics, i.e., whether a

  • product is in Amazon Buy Box for Prime users
  • product is in Amazon Buy Box for Non-Prime users per product per Amazon domain for a given time range.
Security
BasicAuth or BearerAuth
Path
contractIdstringnon-emptyrequired

Unique identifier of the contract

Example: qbcxvb
Query
startDatestring(date-time)

Start of time range for data retrieval.

Format: ISO 8601 date-time in UTC (e.g., 2024-01-15T10:30:00Z)

Default behavior:

  • If omitted and endDate is provided: startDate = endDate - 48 hours
  • If both omitted: range is NOW - 48 hours to NOW
Example: startDate=2024-01-15T00:00:00Z
endDatestring(date-time)

End of time range for data retrieval.

Format: ISO 8601 date-time in UTC (e.g., 2024-01-16T10:30:00Z)

Default behavior:

  • If omitted and startDate is provided: endDate = startDate + 48 hours
  • If both omitted: range is NOW - 48 hours to NOW
Example: endDate=2024-01-16T23:59:59Z
startinteger(int32)

Where to start fetching the Amazon Buy Box statistics. Must be positive. Default value is 0.

limitinteger(int32)

Maximum number of results. Must be positive and not bigger than 50,000. Default value is 50,000.

Example: limit=50000
curl -i -X GET \
  -u <username>:<password> \
  'https://api-docs.omniaretail.dev/_mock/api/omnia/api/v3/vendor/contracts/qbcxvb/products/amazon/buybox/stats?endDate=2024-01-16T23%3A59%3A59Z&limit=50000&start=0&startDate=2024-01-15T00%3A00%3A00Z'

Responses

List of Amazon Buybox statistics per product

Bodyapplication/json
dataArray of objects(com.patagona.pricemonitor.share.api.AmazonBuyboxProductStatsV3)required
data[].​productIdnumberrequired

Internal product identifier

data[].​isInPrimeBuyboxbooleanrequired

Indicates if product is Amazon Prime product and is in Amazon Buybox

data[].​isInNonPrimeBuyboxbooleanrequired

Indicates if product is in Amazon Buybox

Response
application/json
{ "data": [ {} ] }

Get all products for a contractDeprecated

Request

⚠️ DEPRECATED: This endpoint is deprecated and should no longer be used.

Retrieves all products for a contract without pagination support. This endpoint has performance limitations and lacks proper pagination. Use the newer product query endpoints instead.

Note: The attributes parameter is required but poorly documented in this legacy version.

Security
BasicAuth or BearerAuth
Path
contractIdstringnon-emptyrequired

Unique identifier of the contract

Example: qbcxvb
Query
attributesstringrequired

REQUIRED: Comma-separated list of product attributes to include in the response.

Available attributes: gtin, identifier, name, referencePrice, minPriceBoundary, maxPriceBoundary, tags, strategy

Enum"gtin""identifier""name""referencePrice""minPriceBoundary""maxPriceBoundary""tags""strategy"
Example: attributes=gtin,name,referencePrice,tags
curl -i -X GET \
  -u <username>:<password> \
  'https://api-docs.omniaretail.dev/_mock/api/omnia/api/2/v/contracts/qbcxvb/products?attributes=gtin%2Cname%2CreferencePrice%2Ctags'

Responses

No response was specified

Bodyapplication/jsonArray [
tagsArray of objects(Tag)
gtininteger(int64)
maxPriceBoundarynumber(double)
minPriceBoundarynumber(double)
namestring
productIdstring
referencePricenumber(double)
]
Response
application/json
[ { "tags": [], "gtin": 0, "maxPriceBoundary": 0.1, "minPriceBoundary": 0.1, "name": "string", "productId": "string", "referencePrice": 0.1 } ]

Price Recommendations

Operations to get price recommendations calculated by our system.

Operations

Offers

Operations to get and manage offers.

Operations

Feeds Management

Manage your data-feeds.

Operations

Logs Management

Operations to store log messages in the system.

You can integrate this API into your own system and publish integration logs to the system so that Omnia Retail can analyze them.

Operations

Company Management

Operations for managing company entities, including creation, retrieval, and contract management.

Operations

Orders Management

Operations for managing orders, including bulk order imports and order tracking.

Operations

Settings Management

Operations to manage the settings of contracts. Only a limited number of these operations are available to customers directly.

Operations

Tasks Management

Operations to view and manage the tasks running in the platform. Customers can only view tasks.

Operations

Strategies Management

Operations to view and manage pricing strategies.

Operations

Domains

Operations to view all supported domains.

A domain is an external datasource or website that contains information about offers for products for sale. Information like product characteristics and sales characterics like price, stock level and delivery times and costs.

Operations

Plugin Registration

Operations to view and manage registered plugins for system integration.

Operations