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, retailer connection, syncing, and MFA automatically. Use these endpoints for advanced backend integrations or custom UIs.

Base URLs:

Production: https://sync-api.stackline.com
Sandbox: https://sync-api-beta.stackline.com

Authentication: All requests (except GET /sync/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 required). Returns all retailers users can connect.

Response:

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

Field

Type

Description

displayName

string

Retailer display name

logo

string

Logo URL

syncConfig.serverSide

boolean

Whether sync is enabled

Connections (User's Linked Accounts)

List Connected Retailers

GET /sync/connections

Returns user's linked retailer accounts.

Query Parameters:

Parameter

Type

Description

limit

integer

Max results

offset

integer

Pagination offset

status

string

Filter: valid, invalid, pending

Response:

[
  {
    "displayName": "Amazon",
    "logo": "https://media.brandclub.com/retailer_logo/1.webp",
    "status": "valid",
    "lastSyncAt": "2024-12-09T10:30:00Z"
  }
]

Connection Statuses:

Status

Meaning

valid

Connected and working

invalid

Needs reconnection

pending

Currently being validated

Get Connection Details

GET /sync/connections/:id

Returns a single connection. Same shape as an item in the list response.

Connect a Retailer

POST /sync/connections/connect

Connect a new retailer account. Credentials must be encrypted using the TOTP from GET /sync/auth/totp.

Note: The SDK widget handles this entire flow automatically, including credential encryption and MFA. Use this endpoint only if building a custom connection UI.

Request Body:

{
  "retailerId": 1,
  "connectionInfo": "encrypted_credentials",
  "currentStamp": "totp_timestamp",
  "mode": "CONNECT"
}

Field

Type

Required

Description

retailerId

integer

Yes

Retailer to connect (from catalog)

connectionInfo

string

Yes

Encrypted credentials (see TOTP section)

currentStamp

string

Yes

TOTP timestamp from GET /sync/auth/totp

mode

string

Yes

CONNECT (new) or FIX (repair broken)

Response:

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

After connecting, poll GET /sync/sessions/:batchId to track sync progress.

Update Connection (Fix)

PUT /sync/connections/:id

Re-authenticate a broken connection (status: invalid). Same encryption requirements as connect.

Request Body:

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

Response:

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

Trigger Sync for Connection

POST /sync/connections/:id/sync

Manually trigger sync for a specific connected retailer.

Response:

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

Sync All Connections

POST /sync/connections/sync-all

Triggers sync for all connected retailers at once.

Response:

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

Returns { "status": "no_retailers" } if no valid connections exist.

Orders

List Orders

GET /sync/orders

Returns purchase history as line-item level data.

Query Parameters:

Parameter

Type

Default

Description

retailer_id

integer

Filter by retailer

limit

integer

Max results (max: 1000)

offset

integer

Pagination offset

start_date

string

Filter orders after this date (ISO 8601)

end_date

string

Filter orders before this date (ISO 8601)

format

string

json

Response format: json or csv

JSON Response:

[
  {
    "retailerOrderId": "112-3456789-0123456",
    "retailerName": "Amazon",
    "orderDate": "2024-12-05T14:20:00Z",
    "total": 45.99,
    "currency": "USD",
    "shipmentStatus": "delivered",
    "shipmentText": "Delivered Dec 8",
    "items": [
      {
        "name": "Organic Dog Food - 30lb",
        "quantity": 1,
        "price": 45.99,
        "sku": "B0DGJ7HYG1",
        "brandName": "PetNature",
        "department": "Pet Supplies",
        "category": "Dog Food",
        "subCategory": "Dry Food"
      }
    ]
  }
]

CSV Response (format=csv):

Returns a downloadable CSV file with columns: Retailer, Retailer Order ID, Order Date, Item Name, Brand, Dept, Category, SubCategory, SKU, Quantity, Price, Currency, Shipment Status, Order Total. See Data Reference for details.

Get Order Details

GET /sync/orders/:id

Returns a single order. Same shape as an item in the list response.

Trigger Order Sync

POST /sync/orders/trigger

Trigger a sync to fetch latest orders.

Query Parameters:

Parameter

Type

Description

retailer

integer

Optional — sync a specific retailer only

Response:

{
  "triggered": true,
  "syncBatchId": "batch_xyz789"
}

Sync Sessions

Get Latest Sync

GET /sync/sessions/latest

Returns the most recent sync session.

Response:

{
  "syncBatchId": "batch_xyz789",
  "status": "syncing",
  "createdAt": "2024-12-09T10:30:00Z",
  "retailerSyncSessions": [
    {
      "displayName": "Amazon",
      "logo": "https://media.brandclub.com/retailer_logo/1.webp",
      "syncStatus": "scanning"
    }
  ]
}

Global Status:

Status

Meaning

syncing

At least one retailer is still syncing

normal

All retailers finished (or no active sync)

Get Sync By ID

GET /sync/sessions/:batchId

Returns a specific sync batch. Same response shape as latest.

Per-Retailer Sync Statuses (in retailerSyncSessions[].syncStatus):

Status

Description

queued

Waiting to start

connecting

Authenticating with retailer

scanning

Fetching orders

processing

Analyzing data

completed

Done

error

Failed

timed_out

Connection timed out

userintervention

MFA required

Submit MFA

POST /sync/sessions/:syncId/mfa

Submit an MFA response during sync. Required when a retailer's syncStatus is userintervention.

Note: The SDK widget handles MFA automatically. Use this endpoint only if building a custom sync UI.

Request Body (choose method):

{
  "eventType": "choose",
  "reqId": "mfa_request_id",
  "selectedOption": "sms"
}

Request Body (enter code):

{
  "eventType": "enter",
  "reqId": "mfa_request_id",
  "otpValue": "123456"
}

Field

Type

Required

Description

eventType

string

Yes

choose (select method) or enter (code)

reqId

string

Yes

MFA request ID from sync session events

selectedOption

string

choose

MFA method to use (e.g., sms, email)

otpValue

string

enter

Verification code entered by user

Response:

{
  "success": true
}

Credential Encryption

Get TOTP

GET /sync/auth/totp

Returns a time-based token for encrypting retailer credentials before calling POST /sync/connections/connect.

Note: The SDK widget handles credential encryption automatically. Use this endpoint only if building a custom connection UI.

Response:

{
  "token": "encryption_token",
  "currentStamp": "1702123456"
}

Use token to encrypt credentials client-side. Pass currentStamp back when connecting.

User Profile

Get Profile

GET /sync/profile

Returns the authenticated user's profile.

Response:

{
  "name": "Jane Smith",
  "email": "[email protected]",
  "phoneNumber": "***0100",
  "createdAt": "2024-01-15T08:00:00Z"
}

Phone number is masked for privacy (last 4 digits only).

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 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

User Info (OIDC)

GET /oauth2/userInfo

Standard OIDC endpoint. Returns user claims.

Response:

{
  "sub": "user_abc123",
  "email": "[email protected]",
  "phone_number": "+1-555-0100",
  "name": "Jane Smith"
}

Errors

All errors follow this format:

{
  "error": "error_type",
  "details": "Human-readable description"
}

Status Codes:

Code

Meaning

400

Bad request (missing or invalid parameters)

401

Unauthorized (missing or invalid token)

403

Forbidden (insufficient permissions)

404

Not found

429

Rate limit exceeded

502

Upstream service error (retry with backoff)

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

PreviousWidget Reference NextData Reference

Last updated 6 hours ago

Was this helpful?

hashtagRetailers (Catalog)

hashtagList Available Retailers

hashtagConnections (User's Linked Accounts)

hashtagList Connected Retailers

hashtagGet Connection Details

hashtagConnect a Retailer

hashtagUpdate Connection (Fix)

hashtagTrigger Sync for Connection

hashtagSync All Connections

hashtagOrders

hashtagList Orders

hashtagGet Order Details

hashtagTrigger Order Sync

hashtagSync Sessions

hashtagGet Latest Sync

hashtagGet Sync By ID

hashtagSubmit MFA

hashtagCredential Encryption

hashtagGet TOTP

hashtagUser Profile

hashtagGet Profile

hashtagOAuth Endpoints

hashtagAuthorization

hashtagToken Exchange

hashtagRevoke Token

hashtagUser Info (OIDC)

hashtagErrors

hashtagRate Limits

hashtagDiscovery

Retailers (Catalog)

List Available Retailers

Connections (User's Linked Accounts)

List Connected Retailers

Get Connection Details

Connect a Retailer

Update Connection (Fix)

Trigger Sync for Connection

Sync All Connections

Orders

List Orders

Get Order Details

Trigger Order Sync

Sync Sessions

Get Latest Sync

Get Sync By ID

Submit MFA

Credential Encryption

Get TOTP

User Profile

Get Profile

OAuth Endpoints

Authorization

Token Exchange

Revoke Token

User Info (OIDC)

Errors

Rate Limits

Discovery