Supplier Syndications API

Base URL

https://apis-live2.bluemeteor.com/supplierrest/api/v1/syndications/skuData

Overview

The Supplier Syndications API enables suppliers to submit SKU data for syndication and monitor processing status. The API provides clear, user-friendly responses with actionable error reporting to facilitate efficient data integration.

AI Mapping and Confidence Threshold:

The platform uses AI to map incoming attributes to the destination template schema.
A confidence threshold determines whether an AI-suggested mapping is accepted.
Default threshold: 0.80 (80%).
Distributor-specific configuration: Each distributor can define their own threshold; if none is set, the default applies.

Decision Logic (per attribute):

If confidence ≥ threshold → MAPPED (automatically accepted and visible in the UI).
If confidence < threshold or no match → UNMAPPED_HIDDEN (stored but not displayed).

Authentication

All API requests require the following headers:

Header	Required	Description
Access-Token	Yes	Bearer token for authentication
Client-Secret	Yes	Client secret issued to your application
Customer-Code	Yes	Unique customer identifier
Content-Type	Yes	Media type for request body

Status Values

Status	Description
IN_PROGRESS	Request accepted and processing is underway.
COMPLETED	All SKUs processed successfully.
COMPLETED_WITH_ERRORS	Processing finished with mixed results (some successes, some failures).
ERROR	Request failed due to authentication, validation, or system error.

Endpoints

Submit SKU Data

Use this endpoint to submit a batch of SKUs for processing. If the request is accepted, the API responds with an apiRequestKey, which can be used to track processing status and retrieve results.

Method: POST

Endpoint:

https://apis-live2.bluemeteor.com/supplierrest/api/v1/syndications/skuData

Sample Request Body

{
"customerCode": "SPCUST",
"catalogKey": "11",
"skus": [
{
"skuIndex": 1,
"templateName": "Cup template",
"skuAttributes": [
{
"attributeName": "BRAND_ID",
"attributeValue": "123"
},
{
"attributeName": "COLOR",
"attributeValue": "Red"
},
{
"attributeName": "CAPACITY_ML",
"attributeValue": 350,
"attributeValueUOM": "ml"
}
]
},

{
"skuIndex": 2,
"templateName": "Cup template",
"skuAttributes": [
{
"attributeName": "BRAND_ID",
"attributeValue": "456"
},
{
"attributeName": "COLOR",
"attributeValue": "Blue"
},

{
"attributeName": "CAPACITY_ML",
"attributeValue": 250
}
]
}
]
}

Request Parameters

Field	Data Type	Mandatory Field	Description
customerCode	string	Yes	It is the unique identifier assigned to a supplier within the system. This code ensures that SKU submissions are correctly associated with your supplier account and catalog. The value must exactly match the customer code configured by your distributor. "customerCode": "SPCUST"
catalogKey	string	Yes	It is the unique ID of the product catalog where your SKUs will be submitted. Suppliers may have access to multiple catalogs (e.g., by category, region, or business unit). Use the catalogKey provided by your distributor to ensure SKUs are sent to the correct catalog.
skus	array	Yes	Array of SKU objects to process.
skuIndex	integer	Yes	Unique identifier for the SKU within this request (must be ≥ 1, no duplicates).
templateName	string	Yes	Template name that must exactly match the syndication name displayed in the Supplier Portal (case-sensitive).
skuAttributes	array	Yes	Array of attribute objects.
attributeName	string	Yes	Attribute key as defined in the template.
attributeValue	string/ number/ boolean	Yes	Specifies the attribute value. The value’s type must match the template-defined data type.
attributeValueUOM	string	No	Specifies the unit of measure (UOM) for the attribute value. The UOM must match the one defined in the template (e.g., “ml”, “in”, “cm”).

Sample Response (Success)

HTTP 202 Accepted

{
"code": 5000,
"message": "Success",
"statusCheckTimeStampUTC": "2025-08-08T14:35:00Z",
"callBackURL": "/supplierrest/api/v1/syndications/requests/{apiRequestKey}",
"callBackInstructions": "Use the 'apiRequestKey' from this response to check status. Replace {apiRequestKey} (e.g., /supplierrest/api/v1/syndications/requests/56) and make a GET request.",
"data": {
"apiRequestKey": 56,
"status": "IN_PROGRESS",
"summary": {
"skuCounts": {
"Total SKUs received": 10,

"Total SKUs processed": 0,

"SKUs accepted": 0,

"SKUs rejected": 0,

"New SKUs created": 0,

"Existing SKUs updated": 0,
}
}
}
}

Response Parameters

Field	Description
Code	This is a numeric API response code (e.g., 5000, 4001). It is different from HTTP status codes and provides detailed SKU level processing results.
Message	Human-readable response message summarizing the result.
statusCheckTimeStampUTC	Server timestamp indicating when the response was created.
callBackURL	Endpoint URL to poll for the latest status of this request.
callBackInstructions	Instructions on how to use the callback URL, including where to insert the apiRequestKey.
apiRequestKey	Displays the unique identifier assigned to this request for tracking and status checks.
status	Current processing status (e.g., IN_PROGRESS, COMPLETED).
skuCounts	Various count metrics for SKU processing results (total received, successful, rejected, new, updated).
Total SKUs received	Total number of SKUs that were submitted in the original request.
Total SKUs processed	Number of SKUs that were processed without any errors.
Total SKUs accepted	The number of SKUs that passed all validations and were successfully added to the catalog (ready for use or syndication).
SKUs rejected	Number of SKUs that failed processing due to validation errors, permission issues, or other problems (will be 0 for successful completion).
New SKUs created	Number of completely new SKU records created in the system.
Existing SKUs updated	Number of existing SKU records that that were modified with new attribute values.

Check SKU Data Status

This endpoint is used to poll the processing status and retrieve results for a previously submitted SKU data request. Provide the apiRequestKey (returned from the initial POST request) to check progress and access the final results.

Method: GET

Endpoint: https://apis-live2.bluemeteor.com/supplierrest/api/v1/syndications/requests/{apiRequestKey}

Path Parameters

Parameter	Type	Required	Description
apiRequestKey	integer	Yes	The key returned from the POST request

Sample Response

HTTP 200 OK- When the processing is completed successfully

{
"code": 5000,
"message": "All SKUs processed successfully.",
"statusCheckTimeStampUTC": “2025-08-21T10:11:33.241068+00:00”,
"data": {
"apiRequestKey": 128,
"status": "COMPLETED",
"summary": {
"skuCounts": {
"Total SKUs received": 10,
"Total SKUs processed": 10,

"SKUs accepted": 10,
"SKUs rejected": 0,
"New SKUs created": 5,
"Existing SKUs updated": 5
}
},
"results": {
"successfulSkuIndexes": [26, 27, 28, 29, 30, 21, 22, 23, 24, 25],
"failedSkus": []
}
}
}

Response Parameters

Field	Description
Code	Response code indicator
Message	Human-readable response message summarizing the result.
statusCheckTimeStampUTC	Server timestamp indicating when this status was generated, used for freshness comparison.
apiRequestKey	The unique identifier for this processing request, matching the key from the original POST response
status	Current processing status - "COMPLETED" indicates all SKUs were processed successfully
Total SKUs received	Total number of SKUs that were submitted in the original request
Total SKUs processed	Number of SKUs that were processed without any errors
Total SKUs accepted	The number of SKUs that passed all validations and were successfully added to the catalog (ready for use or syndication)
SKUs rejected	Number of SKUs that failed processing (will be 0 for successful completion)
New SKUs created	Number of completely new SKU records created in the system
Existing SKUs updated	Number of existing SKU records that were updated with new data
successfulSkuIndexes	List of skuIndex values from the original request that were processed successfully
failedSkus	List of failed SKU objects (will be empty array [] for successful completion)

HTTP Status Code Summary

Status Code	Status Text	When it Occurs	Description
200	OK	GET requests	Request processed successfully. Status can be IN_PROGRESS, COMPLETED, or COMPLETED_WITH_ERRORS
202	Accepted	POST requests	SKU data submission accepted and is being processed.
400	Bad Request	POST requests	Invalid request data (validation errors, invalid customer code, invalid catalog key, malformed JSON)
401	Unauthorized	POST/GET requests	Authentication failed (invalid/expired token, invalid client secret)
404	Not Found	GET requests	The specified apiRequestKey does not exist or is invalid

Error Code Reference

The following error codes that may appear:

Template-Related Errors

Code	Description
TEMPLATE_NOT_FOUND	The specified template name was not found.
TEMPLATE_NAME_DUPLICATE	Multiple templates exist with the same name (distributor issue).
TEMPLATE_INVALID	The template exists but is currently in UNPUBLISHED or SCHEDULED FOR PUBLISHING state.

SKU-Level Errors

Code	Description
DUPLICATE_SKU_INDEX	Duplicate skuIndex found within the request (see conflictsWith field).
DUPLICATE_PRIMARY_KEY	The SKU data conflicts with existing primary key constraints.
MISSING_PRIMARY_IDENTIFIER	If a SKU is missing its primary key.
SKU_PROCESSING_FAILED	If a SKU has failed processing because of an unexpected error.

Request Validation Errors

Code	Description
MISSING_FIELD	A required field is missing from the request.
INVALID_TYPE	A field has an incorrect data type.
PAYLOAD_VALIDATION_FAILED	The request payload failed validation against the expected schema, contains invalid data, or exceeds the 16 MB size limit.

Authentication & Authorization Errors

Code	Description
AUTHENTICATION_FAILED	Invalid or expired authentication credentials.
INVALID_CUSTOMER_CODE	The provided customer code is not recognized.
INVALID_CATALOG_KEY	The catalog key is not valid for the specified customer.

Operational Errors

Code	Description
API_REQUEST_KEY_NOT_FOUND	The specified apiRequestKey does not exist.

Best Practices

Request Guidelines

Ensure skuIndex values are unique, positive integers within each request.
Use exact template names as they appear in the supplier portal (case-sensitive).
Include appropriate attributeValueUOM for numeric measurements.
Ensure attribute values are provided in the correct data type (string, number, boolean, or date) as required by your template configuration.
Ensure the payload is in the exact format as shown in the sample above and should not exceed 16 MB in size.

Error Handling

Check both request level and SKU level errors.
Use error codes for programmatic handling rather than parsing messages.
For TEMPLATE_NAME_DUPLICATE errors, contact your distributor to resolve naming conflicts.
For SKU_UPDATE_NOT_ALLOWED errors, submit a take-back request for the specific SKU in the portal before retrying the update.