API Reference

REST API endpoints for Sync As A Service.

Note: Most developers don't need to call these APIs directly. The SDK widget handles authentication, syncing, and data fetching automatically. Use these endpoints only for advanced backend integrations.

Base URLs:

• Production: https://sync.brandclub.com

• Sandbox: https://sync-beta.brandclub.com

Authentication: All requests (except /retailers) require an OAuth access token:

Authorization: Bearer {access_token}

The SDK handles token management automatically.

---

Retailers (Catalog)

List Available Retailers

GET /sync/retailers

Public endpoint (no auth). Returns all retailers users can connect.

Response:

[
  {
    "retailerId": 1,
    "displayName": "Amazon",
    "logo": "https://media.brandclub.com/retailer_logo/1.webp",
    "syncConfig": {
      "serverSide": true
    }
  }
]

---

Connections (User's Linked Accounts)

List Connected Retailers

GET /sync/connections

Returns user's linked retailer accounts.

Query Parameters:

• limit (integer) - Max results

• offset (integer) - Pagination offset

• status (string) - Filter by status: active, error, pending

Response:

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

Get Connection Details

GET /sync/connections/:id

Response: Same as connection object in list.

Trigger Sync for Connection

POST /sync/connections/:id/sync

Manually trigger sync for a specific retailer connection.

Response:

{
  "syncBatchId": "batch_xyz789",
  "status": "syncing",
  "startedAt": "2024-12-09T10:35:00Z"
}

Update Connection

PUT /sync/connections/:id

Update/fix an existing connection with new credentials. Use when a connection is broken (status: error) and needs re-authentication.

Request Body:

{
  "connectionInfo": "encrypted_credentials",
  "currentStamp": "totp_timestamp"
}

Response:

{
  "syncBatchId": "batch_xyz789",
  "status": "syncing",
  "retailerId": 1,
  "startedAt": "2024-12-09T10:35:00Z"
}

Sync All Connections

POST /sync/connections/sync-all

Triggers sync for all connected retailers.

---

Orders

List Orders

GET /sync/orders?retailer_id=1&limit=50&offset=0

Query Parameters:

• retailer_id - Filter by retailer

• limit - Max results (default: 50, max: 100)

• offset - Pagination

Response:

[
  {
    "orderId": "112-3456789-0123456",
    "retailerId": 1,
    "retailerName": "Amazon",
    "orderDate": "2024-12-05T14:20:00Z",
    "total": 45.99,
    "currency": "USD",
    "shipmentStatus": "delivered",
    "shipmentText": "Delivered Dec 8",
    "items": [
      {
        "retailerSku": "B0DGJ7HYG1",
        "name": "Organic Dog Food - 30lb",
        "quantity": 1,
        "price": 45.99,
        "brandName": "PetNature",
        "brandId": 12345
      }
    ]
  }
]

Get Order Details

GET /sync/orders/:id

Returns single order with full details.

---

Sync Status

Get Latest Sync

GET /sync/sessions/latest

Returns most recent sync session.

Response:

{
  "syncBatchId": "batch_xyz789",
  "status": "syncing",
  "retailerSyncSessions": [
    {
      "retailerId": 1,
      "syncStatus": "scanning"
    }
  ]
}

Get Sync By ID

GET /sync/sessions/:batchId

Returns specific sync batch status.

Sync Statuses:

• queued - Waiting

• connecting - Authenticating

• scanning - Fetching orders

• completed - Done

• error - Failed

• userintervention - MFA required

---

User Profile

Get User Info

GET /oauth2/userInfo

OIDC standard endpoint. Returns user profile.

Response:

{
  "sub": "user_abc123",
  "email": "[email protected]",
  "phone_number": "[phone]",
  "name": "Jane Smith"
}

---

OAuth Endpoints

Authorization

GET /oauth2/authorize
  ?client_id=bc_your_app
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=openid+profile
  &state=random_state
  &code_challenge=BASE64URL(SHA256(verifier))
  &code_challenge_method=S256

SDK handles this automatically. Permissions are configured per-client by Sync As A Service during onboarding.

Token Exchange

POST /oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code={code}
&redirect_uri=https://yourapp.com/callback
&client_id=bc_your_app
&code_verifier={verifier}

SDK handles this automatically.

Revoke Token

POST /oauth2/revoke
Content-Type: application/x-www-form-urlencoded

token={token}
&client_id=bc_your_app

---

Errors

All errors follow this format:

{
  "error": "unauthorized",
  "error_description": "Token expired"
}

Status Codes:

• 401 - Unauthorized (invalid token)

• 403 - Forbidden (contact Sync As A Service support)

• 404 - Not found

• 429 - Rate limit exceeded

• 502 - Upstream service error

Rate Limits

• 100 requests/minute per user

• 10 syncs/hour per retailer

Discovery

OIDC discovery document:

GET /.well-known/openid-configuration

JWKS for token validation:

GET /.well-known/jwks.json

OpenAPI Specification

Full OpenAPI 3.0 spec available at api-spec.json