If you are not using an external platform such as one of the external platforms we are already integrated with and do not want to use our provided API to push data you will need to provide a custom API for us to injest data for your business.

Authorization

We recommend setting up API authorization using an API key which we will provide in the headers for all requests made to your API. The recommended setup is to provide an API key in the headers in all requests, such as:

headers: {
  Authorization: `Bearer <api-key>`,
},

However, you can use the approach which best fits your needs.

Data Ingestion API Reference

To ingest data we need to pull in data matching all the tables defined in the data tables section. We recommend the following design for this API, but you can design it according to your own needs and preferences as long as the request and response data adhere to the requirements outlined below.

We recommend hosting separate API endpoints for each table:

  • POST https://<your-company-api>.com/luca/v1/data/products
  • POST https://<your-company-api>.com/luca/v1/data/orders
  • POST https://<your-company-api>.com/luca/v1/data/order-line-items
    Note that the order line items can be provided with the orders data or as a separate dataset (see details here).
  • POST https://<your-company-api>.com/luca/v1/data/inventory
  • POST https://<your-company-api>.com/luca/v1/data/competitor-data

It is important that the data returned exactly matches the defined table schemas. Optional fields can be omitted, but all required fields must be present and match the expected type, and any fields marked as unique must be universally unique for that table.

For the tables which include historical data (i.e. orders, order-line-items, inventory and competitor-data) the API should include a data range filter:

NameRequired?TypeField DescriptionExample
start_daterequireddateThe starting date to fetch records from, format MM-DD-YYYY."11-02-2023"
end_daterequireddateThe ending date to fetch records to, format MM-DD-YYYY."11-05-2023"
store_idoptionalstringThis is the store identifier to push the price to, which should match the store identifier for the product. This is required if you have multiple stores which price products differently.

For the products table we will store all the records, updating any existing records using the unique identifier for the table. For this table, you can include pagination in the API if you need to.

Data Backfill

Once your API is ready we will run a data ingestion pipeline to ingest your historical data (will we probably injest data in requests of 1 day at a time).

Once the data has been backfilled we will continue to run data ingestion on a regular cadence (e.g. daily) to pull in your ongoing product and sales data.