Sync API

Exhaustive reference for the Sync APIs — every endpoint, field, and example. Retail media partners use them to synchronize a marketplace's catalog for advertising services, including Sponsored Products, Sponsored Brand, Sponsored Display, and Display Ads. They cover four core entities — Seller, Product, Product Variant, and Category — plus a general catch-all.

For why the catalog matters and how the entities fit together, see Catalog API.

General Notes:

• Each endpoint is a POST to the production environment (https://api.binoban.io); on-prem and air-gapped deployments use their own apiPath instead.
• The {sourceIdentifier} in endpoint URLs is a unique identifier provided by Binoban.
• A Bearer token is required for authentication and will be provided by Binoban.
• All APIs expect JSON payloads and return JSON responses.
• Ingestion is asynchronous — a successful call returns {"status":"QUEUED"}.

Sync Seller API

Synchronizes seller information for a marketplace. This API is a POST request to the production environment (https://api.binoban.io) and requires Bearer token authentication.

Endpoint: POST /api/tracker/catalog/{sourceIdentifier}/seller

Authorization: Bearer Token (provided by Binoban)

Headers:

• accept: */*
• Content-Type: application/json

Request Body:

Field	Description	Type	Constraints	Mandatory
sellerId	Unique identifier for the seller	String	maxLength: 255	Yes
firstName	Seller's first name	String	maxLength: 255	No
lastName	Seller's last name	String	maxLength: 255	No
email	Seller's registered email, pattern: ^(?=.{1,64}@)[\p{L}0-9_-]+(\.[\p{L}0-9_-]+)*@[^-][\p{L}0-9-]+(\.[\p{L}0-9-]+)*(\.[\p{L}]{2,})$example: test@example.org	String	maxLength: 255	Yes
nationalId	Seller's national ID	String	minLength: 10,maxLength: 10	No
address	Seller's address	String	maxLength: 512	No
phoneNumber	Seller's mobile number	String	maxLength: 20	No
isActive	Indicates if the seller is active	Boolean	-	Yes
isBrand	Indicates if the seller is a brand	Boolean	-	Yes
isMarketPlaceOwner	Indicates if the seller owns the marketplace	Boolean	-	Yes
createdAt	Seller creation timestamp	String	ISO 8601 format	No
attributes	Additional seller attributes	Object	-	No

Example Request:

{
  "sellerId": "seller789",
  "firstName": "James",
  "lastName": "Wilson",
  "email": "james.wilson@example.com",
  "nationalId": "123456789",
  "address": "456 Maple Avenue, Springfield, USA",
  "phoneNumber": "+12025550123",
  "isActive": true,
  "isBrand": true,
  "isMarketPlaceOwner": false,
  "createdAt": "2025-04-16T08:50:09.453Z",
  "attributes": {
    "sellerCode": "SL789",
    "rating": 4.8,
    "returnPolicy": "30-day return"
  }
}

Response (200 OK):

{
  "status": "QUEUED"
}

Notes:

• The {sourceIdentifier} is a unique identifier provided by Binoban.
• Mandatory fields: sellerId, email, isActive, isBrand, isMarketPlaceOwner.
• The attributes field is optional for flexible metadata (e.g., seller rating, return policy).

Sync Product API

Synchronizes product information for a marketplace. This API is a POST request to the production environment (https://api.binoban.io) and requires Bearer token authentication.

Endpoint: POST /api/tracker/catalog/{sourceIdentifier}/product

Authorization: Bearer Token (provided by Binoban)

Headers:

• accept: */*
• Content-Type: application/json

Request Body:

Field	Description	Type	Constraints	Mandatory
productId	Unique identifier for the product	String	maxLength: 255	Yes
name	Product name	String	maxLength: 255	Yes
nameEn	Product name in English	String	maxLength: 255	No
createdAt	Product creation timestamp	String	$date-time (ISO 8601 format)	No
brand	Product brand	String	maxLength: 255	No
categoryId	Leaf category ID linked to the product	String	maxLength: 255	Yes
mainImage	URL of the main product image	String	maxLength: 512	Yes
additionalMedia	URLs of additional images or videos	Array[String]	-	No
description	Product description	String	-	No
totalStock	Total stock quantity	Integer	$int32	Yes
isAvailable	Indicates if the product is available	Boolean	-	Yes
url	Product URL on the website	String	maxLength: 512	Yes
attributes	Additional product attributes	Object	-	No

Example Request:

{
  "productId": "shoe123",
  "name": "UltraBoost Sneakers",
  "nameEn": "UltraBoost Sneakers",
  "createdAt": "2025-04-16T10:54:51.959Z",
  "brand": "Nike",
  "categoryId": "cat456",
  "mainImage": "https://cdn.example.com/images/shoe123-main.jpg",
  "additionalMedia": [
    "https://cdn.example.com/images/shoe123-side.jpg",
    "https://cdn.example.com/images/shoe123-video.mp4"
  ],
  "description": "Lightweight sneakers with responsive cushioning, ideal for both casual wear and intense workouts.",
  "totalStock": 100,
  "isAvailable": true,
  "url": "https://www.example.com/products/ultraboost-sneakers",
  "attributes": {
    "weight": "250g",
    "material": "knit fabric"
  }
}

Response (200 OK):

{
  "status": "QUEUED"
}

Notes:

• The {sourceIdentifier} is a unique identifier provided by Binoban.
• Mandatory fields: productId, name, categoryId, mainImage, totalStock, isAvailable, url.
• The attributes field is optional for flexible metadata (e.g., product weight, material).

Sync Product Variant API

Synchronizes product variant information for a marketplace. A product variant is a unique version of a product offered by a specific seller or with distinct specifications (e.g., size, color, price). For example, the same sneaker may have variants with different prices or sizes based on the seller. The Buy Box is the prominent section on the product page where the "winning" variant (Buy Box winner) is shown to buyers, selected based on factors like price, seller rating, or stock. Other variants appear in a secondary section. This API is a POST request to the production environment (https://api.binoban.io) and requires Bearer token authentication.

Endpoint: POST /api/tracker/catalog/{sourceIdentifier}/productVariant

Authorization: Bearer Token (provided by Binoban)

Headers:

• accept: */*
• Content-Type: application/json

Request Body:

Field	Description	Type	Constraints	Mandatory
variantId	Unique identifier for the product variant	String	maxLength: 255	Yes
productId	ID of the product this variant belongs to	String	maxLength: 255	Yes
sellerId	ID of the seller offering this variant	String	maxLength: 255	Yes
price	Price of the variant	Number	-	Yes
discountedPrice	Discounted price of the variant, if applicable	Number	-	No
stock	Stock quantity for the variant	Number	-	Yes
isAvailable	Indicates if the variant is available	Boolean	-	Yes
isBuyBoxWinner	Indicates if this variant is the Buy Box winner	Boolean	-	Yes
image	URL of the variant-specific image	String	maxLength: 512	No
attributes	Additional variant attributes	Object	-	No
url	Product URL on the website	String	maxLength: 512	No

Example Request:

{
  "variantId": "var123",
  "productId": "shoe123",
  "sellerId": "seller789",
  "price": 150.0,
  "discountedPrice": 120.0,
  "stock": 15,
  "isAvailable": true,
  "isBuyBoxWinner": true,
  "url":"https://www.example.com/products/ultraboost-sneakers",
  "image": "https://cdn.example.com/images/variant123.jpg",
  "attributes": {
    "color": "white",
    "size": "41"
  }
}

Response (200 OK):

{
  "status": "QUEUED"
}

Notes:

• The {sourceIdentifier} is a unique identifier provided by Binoban.
• Mandatory fields: variantId, productId, sellerId, price, stock, isAvailable, isBuyBoxWinner.
• The attributes field is optional for flexible metadata (e.g., size, color).

Sync Category API

Synchronizes category information for a marketplace. This API is a POST request to the production environment (https://api.binoban.io) and requires Bearer token authentication.

Endpoint: POST /api/tracker/catalog/{sourceIdentifier}/category

Authorization: Bearer Token (provided by Binoban)

Headers:

• accept: */*
• Content-Type: application/json

Request Body:

Field	Description	Type	Constraints	Mandatory
categoryId	Unique identifier for the category	String	maxLength: 255	Yes
name	Category name	String	maxLength: 255	Yes
parentCategoryId	ID of the parent category in the category tree	String	maxLength: 255	No
level	Level of the category in the category tree	Integer	$int32	Yes
isLeaf	Indicates if the category is a leaf (end) category	Boolean	-	Yes
url	Category URL on the website	String	maxLength: 512	Yes

Example Request:

{
  "categoryId": "cat456",
  "name": "Sneakers",
  "parentCategoryId": "cat123",
  "level": 2,
  "isLeaf": true,
  "url": "https://www.example.com/categories/sneakers"
}

Response (200 OK):

{
  "status": "QUEUED"
}

Notes:

• The {sourceIdentifier} is a unique identifier provided by Binoban.
• Mandatory fields: categoryId, name, level, isLeaf, url.

Sync General Catalog API

Synchronizes general catalog data for integration with the Binoban platform. This API allows sending flexible, arbitrary data structures for various use cases. It is a POST request to the production environment (https://api.binoban.io) and requires Bearer token authentication.

Endpoint: POST /api/tracker/catalog/{sourceIdentifier}/general

Authorization: Bearer Token (provided by Binoban)

Headers:

• accept: */*
• Content-Type: application/json

Request Body:

Field	Description	Type	Constraints	Mandatory
id	Unique identifier for the catalog entity	String	maxLength: 255	Yes
type	Type or category of the catalog entity	String	maxLength: 255	No
data	Flexible object containing entity-specific data	Object	Arbitrary key-value pairs	No

Example Request:

{
  "id": "entity789",
  "type": "generic",
  "data": {
    "name": "Sample Item",
    "value": 42,
    "description": "A generic catalog item"
  }
}

Response (200 OK):

{
  "status": "QUEUED"
}

Notes:

• The {sourceIdentifier} is a unique identifier provided by Binoban.
• Mandatory field: id.
• The type field is optional and can be used to categorize the entity (e.g., generic, item, record).
• The data field is a flexible object that can contain any key-value pairs, with no predefined structure.
• String fields have maximum length constraints: id, type (255 characters).