This is the API powering Omnia 2.0 and Pricemonitor, containing operations that can also be used directly by customers from their own systems.
Omnia 2.0 API (0.0.7187)
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.
https://api-docs.omniaretail.dev/_mock/api/omnia/
https://api.patagona.de/
Use this operation to provide external offers for your products to our system. It serves as an alternative to our automatic domain-wise market data monitoring.
To use this operation, you need Omnia's internal product IDs. See how to determine internal product IDs.
Here is an example of a JSON body to provide one offer for one product via API.
Click to expand
[{
"productId": "67784570",
"creationDate": "2024-06-11T00:15:07.099Z",
"domain": "google.de",
"offers": [{
"vendorName": "amazon.de",
"vendorDomainId": 1,
"url": "https://www.amazon.de/-/en/dp/013142467X/",
"price": 58.84,
"deliveryCosts": 9.95,
"currency": "EUR",
"id": "636354d0-c865-4c56-84b3-bd9172e826aa",
"productName": "Test item",
"attributes": [{
"key": "size",
"value": "L"
}],
"maxDeliveryHours": 48,
"minDeliveryHours": 12,
"retrievalDate": "2024-06-11T10:50:45.659Z",
"availability": true
}]
}]
This endpoint allows you to submit market data ("offers") for your products in bulk. Offers are submitted as snapshots.
A snapshot is defined as:
- a product
- a domain (where the offers come from)
- a timestamp
- and a complete list of corresponding offers at that moment
Snapshots form a linear history per product and domain. That means:
- You can only submit newer snapshots than the ones already stored.
- Each snapshot must contain all relevant offers for that product + domain at that timestamp.
- This endpoint is append-only - no edits or deletions of past offers are allowed.
Internally, only the most recent snapshot is considered per product + domain, e.g., for price calculation or analytics.
Snapshots are processed immediately after being accepted.
- A regular daily import is a solid default.
- Ideally submit offers before a price calculation tasks runs to ensure that recommended prices are based on up-to-date data.
- Real-time ingestion is supported.
Use this operation to get all offers for a contract. It's a paginated endpoint, so you have to scroll through all offers.
It's important that you define a timerange (by providing startDate
and endDate
parameters) in order to guarantee a stable pagination.
This endpoint returns the most recent offers per product and domain: This means that offers from older monitoring runs within the provided timerange are ignored.
For continuously getting market data we recommend the following usage pattern:
Get the offers for the last 15 minutes with a time offset of 15 minutes.
Runtime Timestamp | startDate | endDate |
---|---|---|
12:00 | 11:30 | 11:45 |
12:15 | 11:45 | 12:00 |
12:30 | 12:00 | 12:15 |
… |
Note: The time offset is important since offers are not immediately visible via the API. Sometimes there is a slight delay in offer storing.
- Mock server
https://api-docs.omniaretail.dev/_mock/api/omnia/api/v3/vendor/contracts/{contractId}/offers
- Production API
https://api.patagona.de/api/v3/vendor/contracts/{contractId}/offers
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
-u <username>:<password> \
'https://api-docs.omniaretail.dev/_mock/api/omnia/api/v3/vendor/contracts/qbcxvb/offers?start=0&limit=1000&includeTags=true&startDate=2024-01-15T00%3A00%3A00Z&endDate=2024-01-16T23%3A59%3A59Z'
A list of products with their corresponding offers.
The product information.
Additional imported information as key-value pairs about this product.
The minimum price that Omnia 2.0 can recommend for the product. Omnia 2.0 won't recommend any price below this boundary.
Your ID of the product. This field allows to link products in Omnia 2.0 to products in your system.
The maximum price that Omnia 2.0 can recommend for the product. Omnia 2.0 won't recommend any price above this boundary.
The list of offers for the corresponding product.
The position of the offer on the domain when sorted by total price.
The additional charges for delivering the product to the customer's location (shipping costs).
Optional maximum time, in hours, it takes for the product to be delivered to the customer.
The direct link to the product page on the domain where this offer can be found.
An identifier of the vendor on the domain. Identifiers are available for certain domains only.
Optional minimum time, in hours, it takes for the product to be delivered to the customer.
The position of the offer on the domain when sorted by unit price.
An optional flag indicating whether the product is currently in stock and available for purchase.
A list of additional offer details.
The display name of the shop which sells the product. In some cases (e.g. marketplaces) with some additional information about the seller: e.g. Amazon NL - Sold By Amazon NL
Optional timestamp based on ISO 8601 format, indicating when this offer was fetched from the domain.
An optional timestamp in ISO 8601 format indicating when this offer was stored in Omnia 2.0. This is not the timestamp when the offer was fetched from the domain; for that, use retrievalDate.
The currency in which the price and delivery costs are expressed. Provided values are ISO 4217 currency codes like "EUR".
{ "data": [ { … } ] }
The request body specifies which offers will be searched for.
Warning: It's highly recommended to not use this endpoint since it is error-prone due to complex query structure! Supported are queries with three different types of filters:
- Filtering for offers of a certain product
This can be done by a ComparisonFilter with
- the
left
side being aStringValueProvider
with theattributeName
value "productId" - the
right
side being aStringConstantValueProvider
with thevalue
being the actual pricemonitor product ID to filter offers for - the
comparison
being aStringEquality
- Filtering for valid offers of a certain product
This can be done by an AndFilter with
- a) A product filter (see first supported filter)
- b) A NotFilter which contains a ComparisonFilter
- the
left
side being aNumberValueProvider
with theattributeName
value "ignoredBy" - the
right
side being aNumberConstantValueProvider
with thevalue
being the numeric contract id to filter offers for - the
comparison
being aNumberEquality
- the
- Filtering for offers of a certain vendor
This can be done by a ComparisonFilter with
- the
left
side being aStringValueProvider
with theattributeName
value "reseller_name" - the
right
side being aStringConstantValueProvider
with thevalue
being the actual vendor name to filter offers for - the
comparison
being aStringEquality
Note: This endpoint will only return the newest offers for each product for a given time range.
This is a placeholder for filter expressions. They are using advanced features and are not covered by openapi. If you need to use filter expressions please contract us.
- Mock server
https://api-docs.omniaretail.dev/_mock/api/omnia/api/v3/vendor/contracts/{contractId}/offers/query
- Production API
https://api.patagona.de/api/v3/vendor/contracts/{contractId}/offers/query
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
-u <username>:<password> \
https://api-docs.omniaretail.dev/_mock/api/omnia/api/v3/vendor/contracts/qbcxvb/offers/query \
-H 'Content-Type: application/json' \
-d '{
"filter": {},
"pagination": {
"limit": 100,
"start": 0
},
"range": {
"end": "2018-04-06T13:46:13Z",
"start": "2018-04-04T13:46:13Z"
},
"sort": {
"metric": "TotalPrice",
"order": "asc"
}
}'
Returns either an Error or a list of ApiOffers matching the given filter.
The position of the offer on the domain when sorted by total price.
The additional charges for delivering the product to the customer's location (shipping costs).
Optional maximum time, in hours, it takes for the product to be delivered to the customer.
The direct link to the product page on the domain where this offer can be found.
An identifier of the vendor on the domain. Identifiers are available for certain domains only.
Optional minimum time, in hours, it takes for the product to be delivered to the customer.
The position of the offer on the domain when sorted by unit price.
An optional flag indicating whether the product is currently in stock and available for purchase.
A list of additional offer details.
The display name of the shop which sells the product. In some cases (e.g. marketplaces) with some additional information about the seller: e.g. Amazon NL - Sold By Amazon NL
Optional timestamp based on ISO 8601 format, indicating when this offer was fetched from the domain.
An optional timestamp in ISO 8601 format indicating when this offer was stored in Omnia 2.0. This is not the timestamp when the offer was fetched from the domain; for that, use retrievalDate.
The currency in which the price and delivery costs are expressed. Provided values are ISO 4217 currency codes like "EUR".
{ "data": [ { … } ] }
The request body may include an optional products query. If omitted, all products are queried. Currently, product queries can be performed on two attributes:
- "customerProductId"
- "productId" (Patagona's internal product id; must be a numerical integer)
Pagination is supported with a maximum limit of 10,000. For optimized performance:
- Use a limit of 10,000 products per page when querying all products of a contract.
- Prefer using "productId" for queries when a product query is utilized.
Pagination operates based on the provided products query. This is particularly useful when querying a set of customerProductId's. For chunked requests over a set of ids, it's straightforward to specify up to 10,000 customerProductId's in the query with pagination set at start: 0, limit: 10,000. The allowed query pattern is structured as follows:
"pagination": {
"start": ${start},
"limit": ${limit}
},
"range": {
"start": ${start},
"end": ${end}
},
"filter": {
"oneOf": {
"field": "customerProductId",
"values": [${customerProductIds as a list of strings}]
}
}
} ```
Specifies the pagination details such as the start index and the number of records to fetch (limit). At maximum it's allowed to query 10,000 records.
Defines the time range for which offer statistics are queried. Note: The maximum time span between the start and end should not exceed 48 hours.
The starting point of the time range, represented as a timestamp in ISO 8601 format (e.g., "2023-10-19T13:45:30Z") in UTC.
- Mock server
https://api-docs.omniaretail.dev/_mock/api/omnia/api/v3.1/vendor/contracts/{contractId}/offers/stats/query
- Production API
https://api.patagona.de/api/v3.1/vendor/contracts/{contractId}/offers/stats/query
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
-u <username>:<password> \
https://api-docs.omniaretail.dev/_mock/api/omnia/api/v3.1/vendor/contracts/qbcxvb/offers/stats/query \
-H 'Content-Type: application/json' \
-d '{
"pagination": {
"start": 0,
"limit": 10
},
"range": {
"start": "2023-10-17T08:00:00Z",
"end": "2023-10-19T08:00:00Z"
},
"filter": {
"oneOf": {
"field": "customerProductId",
"values": [
"1",
"2",
"3",
"4",
"5",
"6",
"7",
"8",
"9",
"10"
]
}
}
}'
Returns a list of offer statistics per product. When a product has no market data then no offer statistics are returned for that product.
The aggregated offer price statistics for the product.
Offer statistics considering the unit price.
Offer statistics considering the unit price plus delivery costs.
A list of offer statistics per domain. Domains without competitor offers are not included in the list.
This field specifies the domain where the competitor offers are sourced from. It's a string representing the domain name, such as "google.de".
{ "data": [ { … } ] }
Request
This endpoint can be used to provide external offers to Omnia 2.0. It's a bulk endpoint which accepts an array of individual POST offers requests each based on a "snapshot" - a unique combination of product, domain, and timestamp for a list of offers.
Validation rules before storage:
- The product must exist in the contract.
- Only snapshots newer than those already stored will be accepted.
- Each domain must use a consistent currency.
- Duplicate snapshots in the same request are stored once.
- Conflicting snapshots for the same product + domain + timestamp are all rejected.
- Offer IDs must be unique across all offers.
- The domain field must not be empty.
- Offer prices must be ≥ 0.01, delivery costs must be ≥ 0.
A list of individual POST offers requests (snapshots) to be stored.
Submit up to 1,000 snapshots per request for optimal performance. Snapshots are validated and processed in the order provided. The response follows the same order.
ISO 8601 timestamp when the offers have been gathered. Must be more recent than existing snapshots for the same product and domain, otherwise the request will be rejected.
Non-empty list of offers.
The additional charges for delivering the product to the customer's location.
The direct link to the product page on the domain where this offer can be found.
An optional flag indicating whether the product is currently in stock and available for purchase.
A list of additional offer details.
Optional timestamp based on ISO 8601 when this offer information was last fetched from the domain.
A unique identifier for the offer. It's crucial that it's unique across all offers independent of the timestamp. If you don't have a unique identifier then please use a UUID.
The currency in which the price and delivery costs are expressed. Allowed values are ISO 4217 currency codes like "EUR".
Optional minimum time, in hours, it takes for the product to be delivered to the customer.
- Mock server
https://api-docs.omniaretail.dev/_mock/api/omnia/api/2/v/contracts/{contractId}/offers
- Production API
https://api.patagona.de/api/2/v/contracts/{contractId}/offers
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
-u <username>:<password> \
https://api-docs.omniaretail.dev/_mock/api/omnia/api/2/v/contracts/qbcxvb/offers \
-H 'Content-Type: application/json' \
-d '[
{
"productId": "string",
"creationDate": "2019-08-24T14:15:22Z",
"domain": "string",
"offers": [
{
"deliveryCosts": 0,
"url": "string",
"vendorDomainId": "string",
"price": 0,
"availability": true,
"attributes": [
{
"key": "string",
"value": "string"
}
],
"vendorName": "string",
"retrievalDate": "2019-08-24T14:15:22Z",
"id": "string",
"productName": "string",
"currency": "string",
"minDeliveryHours": 0,
"maxDeliveryHours": 0
}
]
}
]'
The request was successfully processed. Each individual POST offers request was validated and handled separately. The 'data' field in the response contains one entry per request item, in the same order as submitted.
Each entry is either:
true
: The offer snapshot was accepted and stored.ApiErrorResponse
: The snapshot was rejected, including details about the reason.
{ "data": [ { … }, { … } ] }