Public API
/
Orders Management

Omnia 2.0 API (0.0.7097)

This is the API powering Omnia 2.0 and Pricemonitor, containing operations which 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.

Download OpenAPI description
omnia.json
omnia.yaml
Overview
URL https://www.omniaretail.com/
License Omnia Retail API license
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

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 our system.

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

Operations

Company Management

Company management related endpoints.

Operations

Orders Management

Manage your orders.

Operations

Add orders in bulk

Request

Path
contractIdstringrequired

ID of the contract

Example: qbcxvb
Bodyapplication/jsonrequired

Orders to be added

ordersArray of objects(com.patagona.pricemonitor.share.api.CustomerOrderV2)required

Orders in bulk

orders[].​shippingCostsnumberrequired

Shipping costs of the order

orders[].​orderIdstringrequired

Unique id of an order. It must mean unique in the shop, not in the pricemonitor.

orders[].​itemsArray of objects(com.patagona.pricemonitor.share.api.CustomerOrderItemV2)required

List of bought items

orders[].​items[].​itemIdstringrequired

ID of the item in the customer's system. It is expected to be the customerProductId. It should be guaranteed that the itemId can be always assigned to only one product or variant.

orders[].​items[].​unitPricenumberrequired

Gross unit price of a single item, including applicable taxes.

orders[].​items[].​quantityintegerrequired

How often the item was purchased.

orders[].​items[].​taxPercentagenumber

Tax percentage applied on the unit price, e.g. 20 for 20% tax. This percentage is used to determine the tax component of the unitPrice, but the unitPrice itself already includes this tax.

orders[].​totalPricenumberrequired

Total price of the order

orders[].​productMappingsArray of objects(com.patagona.pricemonitor.share.api.CustomerOrderProductMappingV2)required

A relation from the products in your system to the pricemonitor. Currently it must contain exactly one element.

orders[].​productMappings[].​sourcestringrequired

Identifier field within item. Only valid value is 'itemId'

orders[].​productMappings[].​targetstringrequired

Must be 'customerProductId' or 'productId' since plugins are still publishing both values. The semantics are actually the same. In both cases they address the customerProductId.

orders[].​originstringrequired

Origin of an order, e.g. the online shop were the order is placed

orders[].​creationDatestring(date-time)required

Date when the order is created in UTC

orders[].​currencystringrequired

Currency used in the order. ISO 4217 Currency Codes: e.g. EUR

orders[].​referrerstring

Referrer of an order. Third party (e.g. marketplace) which referred the customer to the online shop

versionstringrequired

Version of orders

curl -i -X POST \
  -u <username>:<password> \
  https://api-docs.omniaretail.dev/_mock/api/omnia/api/2/v/contracts/qbcxvb/orders \
  -H 'Content-Type: application/json' \
  -d '{
    "orders": [
      {
        "shippingCosts": 0,
        "orderId": "string",
        "items": [
          {
            "itemId": "string",
            "unitPrice": 0,
            "quantity": 0,
            "taxPercentage": 0
          }
        ],
        "totalPrice": 0,
        "productMappings": [
          {
            "source": "string",
            "target": "string"
          }
        ],
        "origin": "string",
        "creationDate": "2019-08-24T14:15:22Z",
        "currency": "string",
        "referrer": "string"
      }
    ],
    "version": "string"
  }'

Responses

Successfully added orders

Bodyapplication/json
dataArray of objects
Response
application/json
{
  "data": [
    { … }
  ]
}

Delete all orders

Request

Delete all orders for this contract.

Path
contractIdstringrequired

ID of the contract

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

Responses

Successfully deleted all orders

Bodyapplication/json
dataobject(DeletedItemsResponse)required
data.​deletedinteger

Number of deleted orders

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

PUT orders in bulk

Request

Saves orders in bulk. If an orderId was already used by this contract this order and all it's order-items will be overwritten.

  • the version of the request body must be "3"
  • requests must not contain duplicated orderId
  • the number of orders in one request must not exceed 10,000
  • each order must have at least one item
  • the orders.items.itemId fields should correspond to a customerProductId of a product definition inside the contract
Path
contractIdstringrequired

ID of the contract

Example: qbcxvb
Bodyapplication/json
ordersArray of objects(com.patagona.pricemonitor.share.api.CustomerOrderV3)required

List of orders

orders[].​shippingCostsnumberrequired

Shipping costs of the order. This amount is included in totalPrice.

orders[].​orderIdstringrequired

Unique ID of an order. This ID must be unique within the contract.

orders[].​itemsArray of objects(com.patagona.pricemonitor.share.api.CustomerOrderItemV2)required

List of purchased items.

orders[].​items[].​itemIdstringrequired

ID of the item in the customer's system. It is expected to be the customerProductId. It should be guaranteed that the itemId can be always assigned to only one product or variant.

orders[].​items[].​unitPricenumberrequired

Gross unit price of a single item, including applicable taxes.

orders[].​items[].​quantityintegerrequired

How often the item was purchased.

orders[].​items[].​taxPercentagenumber

Tax percentage applied on the unit price, e.g. 20 for 20% tax. This percentage is used to determine the tax component of the unitPrice, but the unitPrice itself already includes this tax.

orders[].​totalPricenumberrequired

Total price of the order, including all items, applicable taxes, and shipping costs.

orders[].​originstringrequired

Origin of an order, e.g., the online shop where the order is placed.

orders[].​creationDatestring(date-time)required

Timestamp in ISO 8601 format indicating when the order is placed.

orders[].​currencystringrequired

Currency used in the order, represented by ISO 4217 Currency Codes (e.g., EUR).

orders[].​referrerstring

Optional referrer of an order. Third party (e.g. marketplace) which referred the customer to the online shop.

versionstringrequired

Version of orders. Currently only "3" is allowed

curl -i -X PUT \
  -u <username>:<password> \
  https://api-docs.omniaretail.dev/_mock/api/omnia/api/v3/vendor/contracts/qbcxvb/orders \
  -H 'Content-Type: application/json' \
  -d '{
    "orders": [
      {
        "shippingCosts": 5.9,
        "orderId": "2023-11_customer-a_001",
        "items": [
          {
            "unitPrice": 6.02,
            "itemId": "itemId",
            "quantity": 1,
            "taxPercentage": 19
          }
        ],
        "totalPrice": 11.92,
        "origin": "Amazon.de",
        "creationDate": "2023-11-23T11:20:21.034+01:00",
        "currency": "EUR"
      }
    ],
    "version": "3"
  }'

Responses

The response provides the ids of the successfully imported orders

Bodyapplication/json
dataobject(com.patagona.pricemonitor.share.api.PutItemsResponseV3)required

Represents list of unique identifiers

data.​idsArray of stringsrequired

list of ids of the items that have been saved or updated

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

Get all orders

Request

Returns all orders for a given contract.

Path
contractIdstringrequired

ID of the contract

Example: qbcxvb
Query
startinteger(int32)required
limitinteger(int32)required
startDatestring(date-time)

Timestamp of start of time range for fetching orders. Formatted as ISO 8601 format with timezone with reference to UTC (e.g. for [Europe/Berlin] in winter time: 2023-11-01T14:50:45.495+01:00. In summer time: 2023-11-01T14:50:45.495+02:00). If this value is omitted then no lower time limit is considered.

endDatestring(date-time)

Timestamp of end of time range for fetching orders. Formatted as ISO 8601 format with timezone with reference to UTC (e.g. for [Europe/Berlin] in winter time: 2023-11-01T14:50:45.495+01:00. In summer time: 2023-11-01T14:50:45.495+02:00). If this value is omitted then no upper time limit is considered.

curl -i -X GET \
  -u <username>:<password> \
  'https://api-docs.omniaretail.dev/_mock/api/omnia/api/v3/vendor/contracts/qbcxvb/orders?endDate=2019-08-24T14%3A15%3A22Z&limit=0&start=0&startDate=2019-08-24T14%3A15%3A22Z'

Responses

This is a generated entry and needs to be described.

Bodyapplication/json
object
Response
application/json
{}

Query order statistics per product

Request

This endpoint can be used to query order statistics grouped by product.

Path
contractIdstringrequired

ID of the contract

Example: qbcxvb
Bodyapplication/jsonrequired

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 "customerProductId" for queries when a product query is utilized.

Pagination operates based on the provided products query. 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 order statistics are queried. Note: The maximum time span between the start and end should not exceed 30 days.

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/vendor/contracts/qbcxvb/orders/stats/query \
  -H 'Content-Type: application/json' \
  -d '{
    "pagination": {
      "start": 0,
      "limit": 10
    },
    "range": {
      "start": "2023-11-01T08:00:00Z",
      "end": "2023-11-15T08:00:00Z"
    },
    "filter": {
      "oneOf": {
        "field": "customerProductId",
        "values": [
          "1",
          "2",
          "3",
          "4",
          "5",
          "6",
          "7",
          "8",
          "9",
          "10"
        ]
      }
    }
  }'

Responses

Returns a list of order statistics per product. When a product has no sold items then no order statistics are returned for that product.

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

Pricemonitor's internal unique product identifier.

data[].​itemIdstringrequired

The unique identifier of the sold item, expected to align with the customerProductId.

data[].​numberOfSoldItemsintegerrequired

The total count of how often the product has been sold.

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

Delete orders by query

Request

This endpoint can be used to delete customer orders by an order query

Path
contractIdstringrequired

ID of the contract

Example: qbcxvb
Bodyapplication/jsonrequired

The request body should contain a list of order queries. Each query should contain an order id and creation date.

The allowed query pattern is structured as follows:

{
  "orders": [
   {
    "orderId": ${orderId},
    "creationDate": ${creationDate}
  }
   ]
}

ordersArray of objectsrequired

List of order queries, each query should include an order id and its corresponding creation date

orders[].​orderIdstringrequired

Unique identifier of the order

orders[].​creationDatestring(date-time)required

Creation date of the corresponding order. It is a Timestamp in UTC time zone

curl -i -X POST \
  -u <username>:<password> \
  https://api-docs.omniaretail.dev/_mock/api/omnia/api/v3/vendor/contracts/qbcxvb/orders/delete/query \
  -H 'Content-Type: application/json' \
  -d '{
    "orders": [
      {
        "orderId": "123",
        "creationDate": "2023-11-01T08:00:00Z"
      }
    ]
  }'

Responses

Returns the number of orders that have been deleted successfully

Bodyapplication/json
dataobject(DeletedItemsResponse)required
data.​deletedinteger

Number of deleted orders

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

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 the 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 registered plugins.

Operations