Quickstart

This guide walks you through integrating your WMS with an existing Data Border deployment. If you need to deploy Data Border first, see the Deployment Guide.

Prerequisites

A Data Border instance deployed and accessible (e.g., https://adb.yourdomain.com)
A JWT for tenant creation (provided by your Data Border administrator)
An Amazon SP-API application configured in Seller Central

Step 1: Create Your Tenant

Your WMS is represented as a "tenant" in Data Border. Create one using the admin JWT:

curl -X POST https://adb.yourdomain.com/api/create-tenant \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ADMIN_JWT" \
  -d '{
    "name": "My WMS System",
    "redirectOrigin": "https://your-wms.com"
  }'

Response:

{
  "success": true,
  "data": {
    "tenant_id": "clx1y2z3a4b5c6d7e8f9g0h1",
    "refresh_token": "rt_abc123..."
  }
}

Store the refresh_token securely. You'll need it to obtain access tokens.

Step 2: 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" \
  -H "Authorization: Bearer YOUR_ADMIN_JWT" \
  -d '{
    "tenant_id": "clx1y2z3a4b5c6d7e8f9g0h1",
    "refresh_token": "rt_abc123..."
  }'

Response:

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

Step 3: Connect an Amazon Seller

Redirect your user to initiate the OAuth flow:

https://adb.yourdomain.com/auth/initialize
  ?state=your-custom-state-data
  &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 after OAuth (e.g., internal user ID)
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
  &seller_id=seller_abc123
  &code=temp_claim_code_xyz789

Step 4: 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 5: 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 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.