Quickstart

This guide walks you through integrating your WMS with an existing Data Border deployment.

Prerequisites

A Data Border instance deployed and accessible (e.g., https://adb.yourdomain.com)
A Data Border tenant created through the Data Border portal
An Amazon SP-API application configured in Seller Central

Step 1: Get a Data Border Access Token

Exchange your refresh token for an access token (valid for 30 days):

curl -X POST https://adb.yourdomain.com/api/get-adb-access-token \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "clx1y2z3a4b5c6d7e8f9g0h1",
    "refresh_token": "rt_abc123..."
  }'

Response:

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs..."
  }
}

Step 2: Connect an Amazon Seller

Redirect your user to initiate the OAuth flow:

https://adb.yourdomain.com/auth/initialize
  ?state=your-custom-state-data
  &tenantId=clx1y2z3a4b5c6d7e8f9g0h1
  &marketplace_region=us-east-1
  &amazonTokenSecret=YOUR_32_CHAR_RANDOM_SECRET
  &sellerRedirectUrl=https://your-wms.com/oauth/callback

Parameters:

state - Any data you want returned unchanged after OAuth (e.g., internal user ID)
tenantId - Your Data Border tenant ID (from the portal)
marketplace_region - us-east-1 (North America), eu-west-1 (Europe), or us-west-2 (Far East)
amazonTokenSecret - A 32-64 character random secret for encrypting Amazon tokens
sellerRedirectUrl - Where to redirect after successful authentication

The sellerRedirectUrl must start with your tenant's redirectOrigin for security.

After the seller authorizes your application on Amazon, they'll be redirected to your callback URL with:

https://your-wms.com/oauth/callback
  ?state=your-custom-state-data
  &tenant_id=clx1y2z3a4b5c6d7e8f9g0h1
  &seller_id=seller_abc123
  &code=temp_claim_code_xyz789

Step 3: Claim the Seller

Exchange the temporary code for a permanent seller refresh token:

curl -X POST https://adb.yourdomain.com/api/claim-code \
  -H "Content-Type: application/json" \
  -H "x-adb-access-token: YOUR_ADB_ACCESS_TOKEN" \
  -d '{
    "seller_id": "seller_abc123",
    "name": "ACME Corp Amazon Store",
    "callback_url": "https://your-wms.com/callbacks/seller_abc123",
    "code": "temp_claim_code_xyz789"
  }'

Response:

{
  "success": true,
  "data": {
    "refresh_token": "sr_def456..."
  }
}

Step 4: Get a Seller Access Token

Now you can get seller-level access tokens (valid for 24 hours):

curl -X POST https://adb.yourdomain.com/api/get-seller-access-token \
  -H "Content-Type: application/json" \
  -H "x-adb-access-token: YOUR_ADB_ACCESS_TOKEN" \
  -d '{
    "seller_id": "seller_abc123",
    "refresh_token": "sr_def456..."
  }'

Response:

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs..."
  }
}

Step 5: Verify the Connection

Before using the APIs, verify that the seller's Amazon token is working:

curl -X GET https://adb.yourdomain.com/api/pii/probe \
  -H "x-seller-access-token: YOUR_SELLER_ACCESS_TOKEN" \
  -H "x-amazon-token-secret: YOUR_32_CHAR_RANDOM_SECRET"

Response (success):

{
  "success": true,
  "data": {
    "message": "Amazon access token is valid"
  }
}

This is a lightweight check that makes no changes and returns no PII. If it passes, all seller-scoped API calls are expected to work.

Step 6: Start Using the APIs

With your seller access token, you can now:

Fetch Orders (with PII scrubbed)

curl "https://adb.yourdomain.com/passthrough-api/orders/v0/orders?MarketplaceIds=ATVPDKIKX0DER" \
  -H "x-seller-access-token: YOUR_SELLER_ACCESS_TOKEN" \
  -H "x-amazon-token-secret: YOUR_32_CHAR_RANDOM_SECRET"

Generate a Shipping Label

curl -X POST https://adb.yourdomain.com/api/label-proxy/forward \
  -H "Content-Type: application/json" \
  -H "x-seller-access-token: YOUR_SELLER_ACCESS_TOKEN" \
  -H "x-amazon-token-secret: YOUR_32_CHAR_RANDOM_SECRET" \
  -H "x-original-url: https://api.easypost.com/v2/shipments" \
  -H "x-amazon-order-id: 123-4567890-1234567" \
  -H "x-unique-shipment-id: WMS-SHIP-001" \
  -H "Authorization: Bearer EASYPOST_API_KEY" \
  -d '{
    "shipment": {
      "to_address": {
        "name": "{{ship_to_name}}",
        "street1": "{{ship_to_address1}}",
        "city": "{{ship_to_city}}",
        "state": "{{ship_to_state}}",
        "zip": "{{ship_to_zip}}",
        "country": "{{ship_to_country}}"
      }
    }
  }'

Notice you're using placeholders like {{ship_to_name}}. Data Border replaces these with real customer data, sends the request to EasyPost, and returns a scrubbed response.

Print a Label

curl -X POST https://adb.yourdomain.com/api/print/send \
  -H "Content-Type: application/json" \
  -H "x-seller-access-token: YOUR_SELLER_ACCESS_TOKEN" \
  -H "x-amazon-token-secret: YOUR_32_CHAR_RANDOM_SECRET" \
  -d '{
    "shipment_id": "ship_abc123def456",
    "printer_type": "label",
    "printer_id": "warehouse-zebra-1",
    "label_uuids": ["550e8400-e29b-41d4-a716-446655440000"]
  }'

Next Steps

Label Proxy

Learn how placeholder-based label generation works.

Secure Printing

Set up Device Hub for direct label printing.

API Reference

Complete API documentation.