Pricen Bulk Data API – Step‑by‑Step Guide

Important to note: you are not sending the data directly to Pricen’s API. Instead, you use the API for two things:

Validation: check that a single item is in the right format.
Upload links: request a temporary link and fields for file upload. The actual data file is then sent to cloud storage (not directly into the API).

1) Main points to get started

We use bulk file uploads. Instead of sending one product or order at a time, you send a file that contains many items.
Always send all the products. We create the pricing history based on this data.
Always send all the orders for one day:
- First upload: please send 1–2 years of order history.
- After that: only send the last 14 days. This helps catch late orders, returns, or edits without needing to resend your full history.
Before sending a file, you can test a single item with our validation endpoints.
API key: You will receive your personal API key from Pricen Customer Support.

2) Where do I get the upload link?

All requests go to:

Production (live): https://api.pricen.ai/v2/data/

Every request must include your API key:

Authorization: <YOUR_API_KEY>

3) What files should I send, and how often?

Type of data	What’s inside	How often	Required?
Products	All current product variants	Once per day (maximum). Even if products change more often, only send one full file per day.	Yes
Orders	First transfer: 1–2 years. After that: last 14 days	Once per day (maximum).	Yes
Stores	List of your stores/channels	New file when stores change, but no more than once per day.	Only when you are using multiple stores.
Store Products	Full details of how products belong to stores/channels (not just mappings)	New file whenever changes happen, but no more than once per day.	Only when you are using multiple stores.
Competitor Products	Prices from your competitors	Once per day (maximum), or weekly if that fits your setup.	No
Supplemental Data	Extra data sets (e.g., costs)	New file whenever updated.	No

4) Understanding the data schemas

Each dataset (Products, Orders, Stores, etc.) has a defined schema in the API documentation: Pricen Bulk Transfer API Docs.

At the bottom of that documentation page, you will find all the schemas. When you click open an entity there, you will see:

Required fields marked with a red star. These are the fields you must always provide.
Descriptions next to each field. These explain what the field means and give guidance on how to fill it in.
Optional fields without a star. You can include these if you have the data, but they are not mandatory.

A good way to proceed is:

Open the entity schema (for example, Product or Order).
Identify all the required fields (red stars).
Map those fields to the information you already have in your system (e.g., your product code = sku).
Use the descriptions as plain‑English explanations if you are unsure.
Add optional fields later when you are comfortable.

This way you ensure you always meet the minimum requirements while being able to expand with more details when available.

5) File format

Files must be JSON Lines (JSONL) format → one JSON object per line.
Compress the file into gzip format (.jsonl.gz) before upload.

Example to create and compress:

gzip -c products.jsonl > products.jsonl.gz

Simple examples (one line each):

Product:

{"gid":"BLUE-SHIRT-1-M","groupId":"BLUE-SHIRT-1","groupName":"The Blue Shirt","variantName":"The Blue Shirt #1, size M","price":99.95,"categories":["Apparel","Shirts"],"currency":"EUR","cogs":22.57,"sku":"SKU-123456-Y4","stockCount":90}

Order:

{"soldFrom":"Acme Store #1","orderNumber":"ORD9876-11","orderLineNumber":"ORD9876-11-1","createdAt":"2025-01-17T09:12:28Z","price":99.95,"currency":"EUR","quantity":1,"productId":"product-123","sku":"SKU-123456-Y4"}

Competitor product:

{"gid":"COMP-1","price":89.00,"competitorName":"RivalShop","currency":"EUR","sku":"SKU-123456-Y4","dateForPrice":"2025-01-17"}

6) How to test a single item (validation)

Validation endpoints are provided to help you while you are building your integration and creating your schemas. They are not meant to be used for every item, every time. Use them only during development to check that your data structure matches what the API expects.

Send one item to the relevant validation endpoint (e.g., /validate/product, /validate/order).
The API will respond with either “valid” or an error message telling you what is wrong.

7) How to upload a file

When you ask the API for an upload link, the response will always look similar to this:

{
    "requestId": "EhpTQixbAi0EMvg=",
    "data": {
        "uploadUrl": "https://name-of-bucket.s3.eu-north-1.amazonaws.com/",
        "uploadFields": {
            "Content-Type": "application/json",
            "Content-Encoding": "gzip",
            "bucket": "name-of-bucket",
            "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
            "X-Amz-Credential": "...",
            "X-Amz-Date": "20250117T092725Z",
            "X-Amz-Security-Token": "...",
            "key": "youraccountid/bulk-uploads/.../file.jsonl.gz",
            "Policy": "...",
            "X-Amz-Signature": "..."
        }
    }
}

This means:

You must send the file to the uploadUrl.
You must include all the fields under uploadFields.

There are two common ways to do this:

Option 1: cURL (POST with form fields)

curl -X POST \
  -F "Content-Type=application/json" \
  -F "Content-Encoding=gzip" \
  -F "bucket=name-of-bucket" \
  -F "X-Amz-Algorithm=AWS4-HMAC-SHA256" \
  -F "X-Amz-Credential=..." \
  -F "X-Amz-Date=20250117T092725Z" \
  -F "X-Amz-Security-Token=..." \
  -F "key=youraccountid/bulk-uploads/.../file.jsonl.gz" \
  -F "Policy=..." \
  -F "X-Amz-Signature=..." \
  -F "[email protected]" \
  "https://name-of-bucket.s3.eu-north-1.amazonaws.com/"

Option 2: Programmatic upload (using PUT with headers)

Some HTTP libraries (like axios) let you send the upload as a PUT request with headers, passing the uploadFields values as headers. For example:

import axios from 'axios';
import fs from 'fs';
import zlib from 'zlib';

// Replace with your API key
const token = 'YOUR_API_KEY';

// Replace with the appropriate endpoint
const endpoint = 'https://api.pricen.ai/v2/data/bulk-uploads/orders-upload-link';

axios
  .get(endpoint, {
    headers: { Authorization: token },
  })
  .then((response) => {
    const { uploadUrl, uploadFields } = response.data.data;

    // Prepare payload
    const payload = JSON.stringify([
      { orderNumber: 'ORD9876-11', ... }
    ]);
    const gzipBuffer = zlib.gzipSync(payload);

    // Upload
    return axios.put(uploadUrl, gzipBuffer, {
      headers: {
        'Content-Encoding': 'gzip',
        'Content-Type': 'application/json',
        ...uploadFields,
      },
    });
  })
  .then(() => console.log('Upload successful!'))
  .catch((err) => console.error('Upload failed:', err.message));

Both styles do the same thing — the key is that you must always include all the fields returned by the API, whether as form fields (POST) or as headers (PUT).

8) End‑to‑end example

# 1) Get an upload link for products
curl -H "Authorization: $PRICEN_API_KEY" \
  https://api.pricen.ai/v2/data/bulk-uploads/products-upload-link

# 2) Compress your file
gzip -c products.jsonl > products.jsonl.gz

# 3) Upload

# With curl (POST):
curl -X POST \
  -F "...fields from response..." \
  -F "[email protected]" \
  "<UPLOAD_URL>"

# With axios (PUT):
# Handled in the JavaScript code example above

9) Common mistakes to avoid

Sending single items instead of files → always send .jsonl.gz files.
Forgetting to include all orders for a product on a given day.
Uploading without including the required fields.
Formatting the authorization header incorrectly.
Incorrect JSONL formatting (extra commas, not one object per line).

10) Getting help

For API keys or upload issues, contact Pricen Customer Support.
Full API documentation (including all schemas) is available here: Pricen Bulk Transfer API Docs.