This document provides detailed information about the next-external-pricen-data-api, which allows users to upload various types of data in jsonl format. The API is secured using an API key passed in the Authorization header.

The base URL for all API endpoints is:

Copy

https://next-api.pricen.io/v2/pricen/

The API uses an API key for authentication. The key must be included in the Authorization header of every request.

Security Scheme:

Example:

Copy

Authorization: <API_KEY>

Pricen enables users to perform bulk uploads directly to their bulk uploads S3 bucket, provided the user has an account with an API key set up properly. With the API key, the user can request a signed URL to S3, which they can use to upload a gzipped json or jsonl file. Pricen will then process the file further. Using bulk upload is much more cost and time-efficient compared to pushing the same payloads in smaller batches through the REST API.

Here’s an example of how to perform a bulk transfer using Node.js:

typescript

Copy

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://next-api.pricen.io/v2/pricen/bulk-uploads/orders-upload-link'; // Step 1: Request pre-signed URL axios.get(endpoint, { headers: { Authorization: token, }, }) .then((response) => { const { uploadUrl, uploadFields } = response.data.data; // Step 2: Prepare payload const payload = JSON.stringify([ { soldFrom: 'www.acme-inc.com', orderNumber: 'ORD9876-11', orderLineNumber: 'ORD9876-11-1', createdAt: '2021-03-20T09:12:28Z', price: 99.95, currency: 'EUR', quantity: 1, sku: 'SKU-123456-Y4', }, ]); // Step 3: Compress payload const gzipBuffer = zlib.gzipSync(payload); // Step 4: Upload file return axios.put(uploadUrl, gzipBuffer, { headers: { 'Content-Encoding': 'gzip', 'Content-Type': 'application/json', ...uploadFields, }, }); }) .then(() => { console.log('Bulk upload completed successfully!'); }) .catch((error) => { console.error('Error during bulk upload:', error.response?.data || error.message); });

The bulk transfer architecture involves the following steps:

Open image-20250227-151922.png

Retrieve a pre-signed URL to upload OrderLine objects in jsonl format.

Example Response:

json

Copy

{ "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": "ASIAXXX/20250117/some-aws-region-1/s3/aws4_request", "X-Amz-Date": "20250117T092725Z", "X-Amz-Security-Token": "ssijdhfksdjhfkljlsh", "key": "youraccountid/bulk-uploads/supplemental-data/products/COGS-2025-01-17T09:27:25.044Z.jsonl.gz", "Policy": "sfndklaskjldhf", "X-Amz-Signature": "3d93c156f943a2685faf5d87dca11b128f8217173a2826affa0905ccfacb887d" } } }

Retrieve a pre-signed URL to upload CompetitorProductVariant objects in jsonl format.

Retrieve a pre-signed URL to upload StoreProduct objects in jsonl format.

Retrieve a pre-signed URL to upload Store objects in jsonl format.

Retrieve a pre-signed URL to upload ProductVariant objects in jsonl format.

Retrieve a pre-signed URL to upload SupplementalData objects in jsonl format.

Represents an order line item.

Required Fields:

Properties:

Description:
The OrderLineItem represents historical sales and transactional data. It captures detailed information about each line item in an order, such as the product sold, the price paid, the quantity, and the currency. This data is critical for training and using AI models to analyze sales trends, predict demand, and optimize pricing strategies. By providing a comprehensive view of past transactions, the OrderLineItem enables the platform to generate actionable insights and improve decision-making.

Key Use Cases:

Description:
The ProductVariant represents product information data, forming the core of the product catalog. It includes all basic attributes of a product variant, such as SKU, price, categories, and stock count. This data is essential for managing the product catalog, enabling dynamic pricing, and ensuring accurate inventory management. The ProductVariant serves as the foundation for all product-related operations within the platform.

Key Use Cases:

Required Fields:

Properties:

Description:
The CompetitorProductVariant represents competitor pricing data, which is crucial for implementing competitive match rules in dynamic pricing. By capturing competitor prices, the platform can adjust pricing strategies to remain competitive in the market. This data is used to analyze competitor behavior, identify pricing trends, and optimize pricing decisions to maximize revenue and market share.

Key Use Cases:

Example:

j

Copy

{ "gid": "BLUE-SHIRT-1-M", "competitorName": "Acme Inc.", "price": 99.95, "currency": "EUR", "sku": "SKU-123456-Y4", "dateForPrice": "2025-01-17" }

Required Fields:

Properties:

Represents a competitor's product variant.

Required fields:

Optional fields:

Description:
The StoreProduct represents the mapping between products and stores. It is required for store-level and sales channel management, allowing businesses to manage product availability, pricing, and promotions at the store level. This data ensures that products are correctly associated with the appropriate stores and sales channels, enabling localized pricing and inventory management.

Key Use Cases:

Example:

json

Copy

{ "storeId": "store-123", "gid": "BLUE-SHIRT-1-M", "price": 99.95, "currency": "EUR", "sku": "SKU-123456-Y4"

Required Fields:

Properties:

Description:
The Store represents store information, including details such as store name, region, and pricing status. This data is essential for managing store operations, enabling businesses to track and manage stores effectively. The Store object supports store-level analytics, pricing strategies, and inventory management.

Key Use Cases:

Example:

json

Copy

{ "storeName": "Acme Store #1", "pricingEnabled": true, "region": "North America", "zone": "West Coast" }

Required Fields:

Properties:

Description:
The SupplementalData represents any additional product attributes that need to be loaded through the API. This data is used to enrich the product catalog with custom or extended attributes that are not part of the standard product schema. It allows businesses to include additional information, such as product specifications, custom tags, or metadata, to support advanced analytics and decision-making.

Key Use Cases:

Example:

json

Copy

{ "gid": "BLUE-SHIRT-1-M", "additionalProperties": { "color": "blue", "size": "M", "restockDate": "2025-02-01", "material": "cotton", "weight": "200g" } }

Required Fields:

Properties:

Represents supplemental data for products.

Represents the response for bulk upload requests.

Properties:

All errors are returned in the following format:

json

Copy

{ "error": { "code": "ERROR_CODE", "message": "Description of the error." } }

This concludes the API documentation for the next-external-pricen-data-api. For further assistance, please contact support.

The mapping is done based on the gid field, which can be any identifier you choose. It should be the same for both ProductVariant and CompetitorProductVariant. While EAN codes can be used, they are not mandatory. Our algorithms also rely on other parameters, and we have internal mappings even when products don’t have EAN codes.

For price history, we usually deduce the price from historical sales data. There is no need to provide explicit price history for products. For order history, we recommend providing 18 months of data to cover seasonality effectively.

Yes, you can filter by all attributes, including EAN codes. You can place the EAN code in the gid field or provide it as a separate field (ean). Even the additionalProperties can be used for filtering if configured.

No, promotional prices should not be included in the otherPrices field. Instead, place the normal price in the compareAtPrice field and the discounted price (what the customer pays) in the price field.

Yes, you can upload test data to the buckets returned by the API signed URL as many times as needed. We can clear out the data and repeat the process until everything is correct.

Product availability is different from the variantStatus field. Availability can be provided in the additionalProperties field (e.g., availableForSale). The variantStatus field indicates whether the product is included in the product catalog and analytics. A disabled status means the product is effectively "deleted" from the system.

For our analytics, the most important data is order history (sales data). We recommend providing 12-18 months of order history to cover seasonality. While we can accept historical price and availability changes, they are less critical without corresponding sales data.