Sales File API

With this API you can submit your sales data to Shoptimiza. This might be interesting in the following scenarios:

  • To speed up recommendation building
  • If a merchant has an offline shop and an online shop and the latter does not yet produce enough data we can use the data produced by the former POS

Our first step is to build our "sales file". The sales file is just a listing with the last 6 months/1 year sales.

This is just a plain text file. Each line of the file is a JSON object with two fields:

  • key is the order ID. Should be a String
  • items order's product IDs as String

Sample file:


On the previous sample file we have defined 4 orders: 122, 139, 144 and 155. Order 122 has 4 items: 508, 563, 572 and 807.
Important We are only interested in the different products, not their quantities. For instance, if order 888 had 1000 units of product 123 our line will look like:


What should I do with this file?

We can upload that file to Shoptimiza or we can just upload it to our own web server.

Upload to Shoptimiza

You can upload the file with our Nodejs client. If you want to create a custom solution based on C# please checkout this class

You can POST your file to$API_KEY/sales-file replacing $API_KEY with your API Key. The body of your request should be the file contents. You should also include our header X-Shoptimiza-Auth. You can learn more about our authentication mechanism here.

You should upload the file every 7 days so we can update your recommendations.

If you choose this strategy you should configure your account to not pull your data from your website. You can do this by login into your Shoptimiza account, click on "configuration" then "deactivate pull data".

Publishing your file in web server

We can fetch your file from any url. We will fetch every 7 days. Once you have published your sales file you need to login into your account, click on "configuration" and on "data source" set "pull data URL" to the new URL. Bear in mind that anyone that knows this url can download the file

Securing the file

We will send the X-Shoptimiza-Auth header on each request we make to your web server. You can protect your file by checking the header. You have more information about our header here. We also have a PHP library. Wanna see it action? Checkout our PrestaShop extension