Skip to main content

Syncing Product Data

Cova curates a comprehensive set of the data commonly used to build ecommerce sites, menu boards, and other product-driven offerings: product names and attributes, images, pricing, applicable taxes, and real-time stock levels.

When a partner is connected to a Cova retailer, the first step is to synchronize all product data and store it in your system. After that, you need to stay informed of changes to product properties, pricing, and available inventory. If a change is missed or fails to process, individual products can be synchronized separately. These three scenarios are described below.

All three use a DetailedProductData endpoint and the same Include* options. See Endpoints for the full request and response reference, and the overview for paging and empty arrays.

Initial Sync​

Use Detailed Product Data (POST /dataplatform/v1/companies/{companyId}/DetailedProductData) to gather all aggregated data, based on the options set in the request body. It is intended for first-time synchronization or occasional, on-demand updates.

warning

Continuous use of this endpoint is strongly discouraged. If you use it as a complete system refresh, don't expose it to end users. Make it an internal tool that runs on demand, only when absolutely necessary.

  • LocationId can be null. The results then include data for all locations where applicable (for example, with IncludeAvailability or IncludePricing). Because product records are shared among a retailer's locations, null is usually the most efficient choice for an initial company-wide synchronization.
  • Use Skip and Top to balance call volume against response size. See Paging.

Incremental Sync​

Recommended for continuous use

Incremental Sync is the recommended API for keeping your data up to date on an ongoing basis. After your Initial Sync, poll this endpoint rather than repeating the initial call.

Use Detailed Product Data - Updated As Of (POST /dataplatform/v1/companies/{companyId}/DetailedProductData/UpdatedAsOf/{updatedAsOfUTC}) to retrieve products that have changed since a point in time. This covers changes to product properties, prices, stock levels, and more.

Poll this endpoint about once per minute, setting the "as of" date to roughly two to three minutes in the past. The overlap reduces the risk of missing changes because of date calculations, latency, or race conditions. You may receive data from previous calls until the change date falls outside the requested range.

Once per minute is the maximum recommended frequency for a near real-time experience. Consider whether a more relaxed cadence suits your system and reduces processing and network traffic.

  • The "as of" date is UTC.
  • LocationId can be null to return data for all locations.
  • Set InStockOnly to false so availability data is still returned when a product reaches zero quantity.
  • When anything related to a product changes, all current data for that product is returned, whether or not it specifically changed, for the data your request body asks for.
  • The product UpdatedDateUtc doesn't reflect changes to pricing, inventory levels, packages, and so on.

Targeted Sync​

Use Detailed Product Data - By Product Id List (POST /dataplatform/v1/companies/{companyId}/DetailedProductData/ByProductIdList) to retrieve between one and 500 products by ProductId. This is useful when a product or products are reported to be out of sync.