Overview

Overview, explanation and pointers to the API documentation.

Products Management

Operations to manage your products.

Operations

Price Recommendations

Operations to get price recommendations calculated by our system.

Operations

Offers

Operations to get and manage offers.

Operations

Provide offers for custom sources

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.

Example

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
	}]
}]

How It Works

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.

When to Send Offers

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.

Retrieve offers

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.

Continuously retrieving offers

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.

Get offers for timerange

Request

Returns the newest offers for a given time range.

Security

BasicAuth or BearerAuth

Path

contractIdstringnon-emptyrequired

Unique identifier of the contract

Example: qbcxvb

Query

startinteger(int32)

Where to start fetching the products

Default 0

limitinteger(int32)

Maximum number of results

Default 1000

Example: limit=1000

includeTagsboolean

Whether to return tags of products or not.

Default true

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/offers?start=0&limit=1000&includeTags=true&startDate=2024-01-15T00%3A00%3A00Z&endDate=2024-01-16T23%3A59%3A59Z'

Responses

A list of products with their corresponding offers.

Bodyapplication/json

dataArray of objects(com.patagona.pricemonitor.share.api.ProductAndOffers)required

data[].productobject(com.patagona.pricemonitor.share.api.ApiProduct)required

The product information.

data[].product.namestringrequired

The name of the product.

data[].product.tagsArray of objects(com.patagona.pricemonitor.share.api.Tag)required

Additional imported information as key-value pairs about this product.

data[].product.tags[].keystringrequired

data[].product.tags[].valuestringrequired

data[].product.minPriceBoundarynumber

The minimum price that Omnia 2.0 can recommend for the product. Omnia 2.0 won't recommend any price below this boundary.

data[].product.gtinnumber

GTIN / EAN of the product. This field is optional.

data[].product.customerProductIdstring

Your ID of the product. This field allows to link products in Omnia 2.0 to products in your system.

data[].product.idstringrequired

The internal product ID in Omnia 2.0.

data[].product.maxPriceBoundarynumber

The maximum price that Omnia 2.0 can recommend for the product. Omnia 2.0 won't recommend any price above this boundary.

data[].product.referencePricenumberrequired

The current selling price of the product. This price will be used as benchmark or variable for certain components in Omnia 2.0.

data[].offersArray of objects(com.patagona.pricemonitor.share.api.ApiOffer)required

The list of offers for the corresponding product.

data[].offers[].positionByTotalPriceintegerrequired

The position of the offer on the domain when sorted by total price.

data[].offers[].deliveryCostsnumberrequired

The additional charges for delivering the product to the customer's location (shipping costs).

data[].offers[].maxDeliveryTimeinteger

Optional maximum time, in hours, it takes for the product to be delivered to the customer.

data[].offers[].urlstringrequired

The direct link to the product page on the domain where this offer can be found.

data[].offers[].vendorDomainIdstring

An identifier of the vendor on the domain. Identifiers are available for certain domains only.

data[].offers[].domainstringrequired

The website from which the offer originates.

data[].offers[].pricenumberrequired

The unit price of the offer.

data[].offers[].minDeliveryTimeinteger

Optional minimum time, in hours, it takes for the product to be delivered to the customer.

data[].offers[].gtinnumber

An optional field for the GTIN / EAN of the product.

data[].offers[].positionByUnitPriceintegerrequired

The position of the offer on the domain when sorted by unit price.

data[].offers[].availabilityboolean

An optional flag indicating whether the product is currently in stock and available for purchase.

data[].offers[].attributesArray of objects(com.patagona.pricemonitor.share.api.OfferAttribute)required

A list of additional offer details.

data[].offers[].attributes[].namestringrequired

data[].offers[].attributes[].valuestringrequired

data[].offers[].vendorNamestringrequired

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

data[].offers[].retrievalDatestring(date-time)

Optional timestamp based on ISO 8601 format, indicating when this offer was fetched from the domain.

data[].offers[].creationDatestring(date-time)required

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.

data[].offers[].productNamestringrequired

The name of the product as listed on the domain.

data[].offers[].currencystringrequired

The currency in which the price and delivery costs are expressed. Provided values are ISO 4217 currency codes like "EUR".

data[].offers[].productIdstringrequired

The internal product ID in Omnia 2.0.

data[].offers[].ignoredbooleanrequired

A flag indicating whether the offer has been blacklisted or not by the Omnia 2.0 filters.

Response

application/json

{
  "data": [
    { … }
  ]
}

Query offers [vendor]

Request

Supports complex queries for offers.

Security

BasicAuth or BearerAuth

Path

contractIdstringnon-emptyrequired

Unique identifier of the contract

Example: qbcxvb

Bodyapplication/jsonrequired

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 a StringValueProvider with the attributeName value "productId"
the right side being a StringConstantValueProvider with the value being the actual pricemonitor product ID to filter offers for
the comparison being a StringEquality

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 a NumberValueProvider with the attributeName value "ignoredBy"
- the right side being a NumberConstantValueProvider with the value being the numeric contract id to filter offers for
- the comparison being a NumberEquality

Filtering for offers of a certain vendor
This can be done by a ComparisonFilter with

the left side being a StringValueProvider with the attributeName value "reseller_name"
the right side being a StringConstantValueProvider with the value being the actual vendor name to filter offers for
the comparison being a StringEquality

Note: This endpoint will only return the newest offers for each product for a given time range.

filterobject(GenericFilter)

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.

paginationobject(Pagination)required

pagination.limitinteger

Default 100

pagination.startintegerrequired

rangeobject(TimeRange)required

range.endstring(date-time)required

Timestamp of end of time range, formatted as ISO Date in UTC

Example: "2018-04-06T13:46:13Z"

range.startstring(date-time)required

Timestamp of start of time range, formatted as ISO Date in UTC

Example: "2018-04-04T13:46:13Z"

sortobject(OffersQuerySortOrderV30)

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"
    }
  }'

Responses

Returns either an Error or a list of ApiOffers matching the given filter.

Bodyapplication/json

dataArray of objects(com.patagona.pricemonitor.share.api.ApiOffer)required

data[].positionByTotalPriceintegerrequired

The position of the offer on the domain when sorted by total price.

data[].deliveryCostsnumberrequired

The additional charges for delivering the product to the customer's location (shipping costs).

data[].maxDeliveryTimeinteger

Optional maximum time, in hours, it takes for the product to be delivered to the customer.

data[].urlstringrequired

The direct link to the product page on the domain where this offer can be found.

data[].vendorDomainIdstring

An identifier of the vendor on the domain. Identifiers are available for certain domains only.

data[].domainstringrequired

The website from which the offer originates.

data[].pricenumberrequired

The unit price of the offer.

data[].minDeliveryTimeinteger

Optional minimum time, in hours, it takes for the product to be delivered to the customer.

data[].gtinnumber

An optional field for the GTIN / EAN of the product.

data[].positionByUnitPriceintegerrequired

The position of the offer on the domain when sorted by unit price.

data[].availabilityboolean

An optional flag indicating whether the product is currently in stock and available for purchase.

data[].attributesArray of objects(com.patagona.pricemonitor.share.api.OfferAttribute)required

A list of additional offer details.

data[].attributes[].namestringrequired

data[].attributes[].valuestringrequired

data[].vendorNamestringrequired

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

data[].retrievalDatestring(date-time)

Optional timestamp based on ISO 8601 format, indicating when this offer was fetched from the domain.

data[].creationDatestring(date-time)required

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.

data[].productNamestringrequired

The name of the product as listed on the domain.

data[].currencystringrequired

The currency in which the price and delivery costs are expressed. Provided values are ISO 4217 currency codes like "EUR".

data[].productIdstringrequired

The internal product ID in Omnia 2.0.

data[].ignoredbooleanrequired

A flag indicating whether the offer has been blacklisted or not by the Omnia 2.0 filters.

Response

application/json

{
  "data": [
    { … }
  ]
}

Query offer statistics per product

Request

This endpoint can be used to query offer statistics (e.g. offer count, average price) grouped by product. Only the most recent market data is considered per product and domain.

Security

BasicAuth or BearerAuth

Path

contractIdstringnon-emptyrequired

Unique identifier of the contract

Example: qbcxvb

Bodyapplication/json

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}]
    }
  }
} ```

paginationobject(com.patagona.pricemonitor.share.api.Pagination)required

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.

pagination.startintegerrequired

pagination.limitintegerrequired

rangeobject(com.patagona.pricemonitor.share.api.ZonedTimeRange)required

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.

range.startstring(date-time)required

The starting point of the time range, represented as a timestamp in ISO 8601 format (e.g., "2023-10-19T13:45:30Z") in UTC.

range.endstring(date-time)required

The ending point of the time range, represented as a timestamp in ISO 8601 format (e.g., "2023-10-19T14:45:30Z") in UTC.

filterobject(com.patagona.pricemonitor.share.api.OneOfProductsQuery)

An optional parameter to further filter the data based on product criteria.

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"
        ]
      }
    }
  }'

Responses

Returns a list of offer statistics per product. When a product has no market data then no offer statistics are returned for that product.

Bodyapplication/json

dataArray of objects(com.patagona.pricemonitor.share.api.PostOfferStatisticsResponseV31)required

data[].productIdstringrequired

Pricemonitor's internal unique product identifier.

data[].offerCountintegerrequired

The number of offers found on all domains for the product.

data[].statsobject(com.patagona.pricemonitor.share.api.ProductOfferStatisticsV31)required

The aggregated offer price statistics for the product.

data[].stats.unitPriceStatsobject(com.patagona.pricemonitor.share.api.PriceStatisticsV31)required

Offer statistics considering the unit price.

data[].stats.unitPriceStats.minnumberrequired

The minimum offer price.

data[].stats.unitPriceStats.avgnumberrequired

The average offer price.

data[].stats.unitPriceStats.maxnumberrequired

The maximum offer price.

data[].stats.unitPriceStats.cheapestShopsArray of stringsrequired

The shop names that offer for minimum price.

data[].stats.totalPriceStatsobject(com.patagona.pricemonitor.share.api.PriceStatisticsV31)required

Offer statistics considering the unit price plus delivery costs.

data[].stats.totalPriceStats.minnumberrequired

The minimum offer price.

data[].stats.totalPriceStats.avgnumberrequired

The average offer price.

data[].stats.totalPriceStats.maxnumberrequired

The maximum offer price.

data[].stats.totalPriceStats.cheapestShopsArray of stringsrequired

The shop names that offer for minimum price.

data[].stats.domainStatsArray of objects(com.patagona.pricemonitor.share.api.DomainOfferStatisticsV31)required

A list of offer statistics per domain. Domains without competitor offers are not included in the list.

data[].stats.domainStats[].domainstringrequired

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[].stats.domainStats[].competitorOfferCountintegerrequired

The number of competitor offers available in the specified domain.

Response

application/json

{
  "data": [
    { … }
  ]
}

Add offers in bulk

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.

Security

BasicAuth or BearerAuth

Path

contractIdstringnon-emptyrequired

Unique identifier of the contract

Example: qbcxvb

Bodyapplication/jsonrequired

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.

Array [

productIdstringrequired

Omnia's internal product id.

creationDatestring(date-time)required

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.

domainstringrequired

Domain from which the offers originate (e.g., "example.com").

offersArray of objects(com.patagona.pricemonitor.share.api.ApiOfferV2)required

Non-empty list of offers.

offers[].deliveryCostsnumberrequired

The additional charges for delivering the product to the customer's location.

offers[].urlstringrequired

The direct link to the product page on the domain where this offer can be found.

offers[].vendorDomainIdstring

Optional identifier representing the vendor on a certain domain.

offers[].pricenumberrequired

The current listed unit price of the product.

offers[].availabilityboolean

An optional flag indicating whether the product is currently in stock and available for purchase.

offers[].attributesArray of objects(com.patagona.pricemonitor.share.api.ApiOfferAttributeV2)required

A list of additional offer details.

offers[].attributes[].keystringrequired

The attribute name. It's not allowed to be empty.

offers[].attributes[].valuestringrequired

The corresponding attribute value.

offers[].vendorNamestringrequired

The display name of the shop which sells the product.

offers[].retrievalDatestring(date-time)

Optional timestamp based on ISO 8601 when this offer information was last fetched from the domain.

offers[].idstringrequired

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.

offers[].productNamestringrequired

The name of the product as listed on the domain.

offers[].currencystringrequired

The currency in which the price and delivery costs are expressed. Allowed values are ISO 4217 currency codes like "EUR".

offers[].minDeliveryHoursinteger

Optional minimum time, in hours, it takes for the product to be delivered to the customer.

offers[].maxDeliveryHoursinteger

Optional maximum time, in hours, it takes for the product to be delivered to the customer.

]

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
        }
      ]
    }
  ]'

Responses

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.

Bodyapplication/json

dataArray of objects

Example: [{"data":true},{"errors":[{"code":"string","message":"string"}]}]

Response

application/json

{
  "data": [
    { … },
    { … }
  ]
}

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

Omnia 2.0 API (0.0.7187)

Overview

Products Management

Price Recommendations

Offers

Provide offers for custom sources

Example

How It Works

When to Send Offers

Retrieve offers

Continuously retrieving offers

Get offers for timerange

Request

Responses

Was this helpful?

Query offers [vendor]

Request

Responses

Was this helpful?

Query offer statistics per product

Request

Responses

Was this helpful?

Add offers in bulk

Request

Responses

Was this helpful?

Feeds Management

Logs Management

Company Management

Orders Management

Settings Management

Tasks Management

Strategies Management

Domains

Plugin Registration

Omnia 2.0 API (0.0.7187)

Overview

Products Management

Price Recommendations

Offers

Provide offers for custom sources

Example

How It Works

When to Send Offers

Retrieve offers

Continuously retrieving offers

Get offers for timerange

Request

Responses

Was this helpful?

Query offers [vendor]

RequestExpand all

Responses

Was this helpful?

Query offer statistics per product

RequestExpand all

Responses

Was this helpful?

Add offers in bulk

Request

Responses

Was this helpful?

Feeds Management

Logs Management

Company Management

Orders Management

Settings Management

Tasks Management

Strategies Management

Domains

Plugin Registration

Request

Request