Data Reference

What data you receive from Brandclub Sync.

Data Model: Line-item level data (denormalized). Each item/SKU includes its own shipment and order metadata.

Data Structure

We provide flattened, line-item level data—each SKU is a separate record with denormalized order and shipment information.

[
  {
    "orderId": "112-3456789-0123456",
    "retailerId": 1,
    "retailerName": "Amazon",
    "orderDate": "2024-12-05T14:20:00Z",
    "retailerSku": "B0DGJ7HYG1",
    "itemName": "Organic Dog Food - Chicken & Rice 30lb",
    "quantity": 1,
    "price": 45.99,
    "shipmentStatus": "delivered",
    "shipmentText": "Delivered Dec 8",
    "brandName": "PetNature",
    "brandId": 12345
  },
  {
    "orderId": "112-3456789-0123456",
    "retailerId": 1,
    "retailerName": "Amazon",
    "orderDate": "2024-12-05T14:20:00Z",
    "retailerSku": "B09Y987654",
    "itemName": "Stainless Steel Dog Bowl",
    "quantity": 1,
    "price": 12.99,
    "shipmentStatus": "delivered",
    "shipmentText": "Delivered Dec 8",
    "brandName": "PawPerfect",
    "brandId": 67890
  }
]

Note: Items from the same order share the same orderId but each item is a separate record.

Sample CSV Export

order_id,retailer_id,retailer_name,order_date,retailer_sku,item_name,quantity,price,shipment_status,shipment_text,brand_name,brand_id
112-3456789-0123456,1,Amazon,2024-12-05T14:20:00Z,B0DGJ7HYG1,"Organic Dog Food - Chicken & Rice 30lb",1,45.99,delivered,"Delivered Dec 8",PetNature,12345
112-3456789-0123456,1,Amazon,2024-12-05T14:20:00Z,B09Y987654,Stainless Steel Dog Bowl,1,12.99,delivered,"Delivered Dec 8",PawPerfect,67890
113-9876543-7654321,1,Amazon,2024-12-03T09:15:00Z,B08Z789012,"Premium Cat Litter 40lb",1,23.47,in_transit,"Arriving Dec 11",CleanPaws,54321
456-1234567-8901234,2,Walmart,2024-12-01T16:30:00Z,001234567890,Stainless Steel Water Bottle,2,7.99,delivered,"Delivered Dec 3",HydroMax,98765

Each row = one item/SKU. Multi-item orders appear as multiple rows with the same order_id.

Data Fields

Field	Type	Description	Example
orderId	string	Retailer's order number	112-3456789-0123456
retailerId	integer	Retailer ID (1=Amazon, 2=Walmart, etc.)	1
retailerName	string	Retailer name	Amazon
orderDate	datetime	Purchase date (ISO 8601)	2024-12-05T14:20:00Z
retailerSku	string	Retailer's product identifier	B0DGJ7HYG1 (Amazon ASIN)
itemName	string	Product name/title	Organic Dog Food - 30lb
quantity	integer	Units purchased	1
price	number	Unit price	45.99
shipmentStatus	string	Delivery status	delivered, in_transit, pending
shipmentText	string	Human-readable status	Delivered Dec 8
brandName	string	Product brand	PetNature
brandId	integer	Brand identifier	12345

Key Point: Each item has its own shipmentStatus and shipmentText—items in the same order can have different shipment statuses if shipped separately.

Retailer Data

Connected retailers:

{
  "retailerId": 1,
  "displayName": "Amazon",
  "status": "active",
  "lastSyncAt": "2024-12-09T10:30:00Z"
}

Retailer IDs:

• Amazon = 1

• Walmart = 2

• Target = 3

• Kroger = 4

• CVS = 6

• (See full list in Supported Retailers)

Personally Identifiable Information (PII)

What's Included

Minimal PII:

• User's name (if available)

• Phone number (for authentication only)

• Email (if available)

Not Included:

• Credit card numbers

• Billing addresses

• Shipping addresses

• Payment methods

• Social security numbers

PII in Order Data

Addresses are NOT included.

Order data contains:

• ✅ Product names and SKUs

• ✅ Prices and quantities

• ✅ Order dates and shipment status

• ❌ Personal addresses

• ❌ Payment details

• ❌ Recipient information

Field Availability

Not all fields are guaranteed:

Field	Availability
Order date	Always
Retailer name	Always
Item names	Usually (~95%)
Item prices	Usually (~90%)
Brand names	Often (~70%)
SKUs	Often (~70%)
Brand IDs	Sometimes (~50%)
Shipment status	Often (~60%)

Supported Retailers

Currently supported:

• Amazon

• Walmart

• Target

• Kroger (and family: Ralphs, Fred Meyer, etc.)

• CVS

• Walgreens

• Costco

• Best Buy

• Home Depot

• Chewy

• Petco

• PetSmart

• Sephora

• Ulta

• More being added

Total: 15+ retailers

Example Use Cases

Loyalty Programs:

// Award points based on brand purchases
items.forEach((item) => {
  if (item.brandName === "PetNature") {
    awardPoints(user, item.price * item.quantity * 10);
  }
});

Promotions:

// Validate purchase for rebate
const qualifying = items.some(
  (item) =>
    item.retailerSku === "B0DGJ7HYG1" && item.orderDate >= promoStartDate
);

Analytics:

// Track popular brands
const brandCounts = items.reduce((acc, item) => {
  acc[item.brandName] = (acc[item.brandName] || 0) + item.quantity;
  return acc;
}, {});

Data Freshness

• Initial sync: Within minutes of connection

• Recurring sync: Every 24 hours

• Manual sync: On-demand via API

• Historical data: Up to 12 months (retailer-dependent)

Aggregating to Order Level

If you need order-level totals, aggregate the line items:

// Group items by orderId
const orderGroups = items.reduce((acc, item) => {
  if (!acc[item.orderId]) {
    acc[item.orderId] = {
      orderId: item.orderId,
      retailerId: item.retailerId,
      retailerName: item.retailerName,
      orderDate: item.orderDate,
      items: [],
      total: 0,
    };
  }
  acc[item.orderId].items.push(item);
  acc[item.orderId].total += item.price * item.quantity;
  return acc;
}, {});