API Reference
This section provides complete documentation for all ShipStream Data Border API endpoints.
Base URL
All API endpoints are relative to your Data Border instance:
https://your-data-border-instance.example.com
Authentication
Data Border uses multiple authentication methods depending on the endpoint:
| Method | Header | Used For |
|---|---|---|
| Tenant Refresh Token | (in request body) | Exchanging for a Data Border access token |
| Data Border Access Token | x-adb-access-token: <token> | Seller management |
| Seller Access Token | x-seller-access-token: <token> | All seller operations |
| Amazon Token Secret | x-amazon-token-secret: <secret> | Decrypting Amazon tokens |
API Groups
Tenant Management
Manage Data Border access tokens.
| Endpoint | Method | Description |
|---|---|---|
/api/get-adb-access-token | POST | Exchange refresh token for access token |
Seller Management
Connect Amazon sellers and manage their access.
| Endpoint | Method | Description |
|---|---|---|
/api/claim-code | POST | Claim OAuth authorization code |
/api/get-seller-access-token | POST | Get seller access token |
/api/create-sandbox-seller-with-tokens | POST | Create sandbox seller (testing only) |
OAuth
Amazon OAuth integration for seller authorization.
| Endpoint | Method | Description |
|---|---|---|
/auth/initialize | GET | Start OAuth flow |
/auth/redirect | GET | OAuth callback handler |
PII Access
Controlled access to personally identifiable information.
| Endpoint | Method | Description |
|---|---|---|
/api/pii/probe | GET | Verify seller's Amazon token is valid |
/api/pii/getPII/:orderId | GET | Fetch customer address for order |
/api/pii/blockPII | POST | Block PII access for order |
/api/pii/completeOrder | POST | Mark order complete |
/api/pii/getFile | GET | Retrieve stored file |
/api/pii/writeFile | PUT | Store file for order |
/api/pii/deleteFile | DELETE | Remove stored file |
Label Proxy
Generate shipping labels through carrier APIs.
| Endpoint | Method | Description |
|---|---|---|
/api/label-proxy/forward | POST | Forward request to carrier with PII injection |
Send labels to Device Hub for printing.
| Endpoint | Method | Description |
|---|---|---|
/api/print/send | POST | Send labels to printer |
Passthrough
Proxy requests to Amazon SP-API.
| Endpoint | Method | Description |
|---|---|---|
/passthrough-api/* | GET/POST/DELETE | Proxy to whitelisted SP-API endpoints |
Notifications
Amazon order change notifications.
| Endpoint | Method | Description |
|---|---|---|
/api/notification/registerNotification | POST | Subscribe to order changes |
Health
System health monitoring.
| Endpoint | Method | Description |
|---|---|---|
/health-check | GET | Check system status |
Response Format
Success Response
{
"success": true,
"data": {
// Response data
}
}
Error Response
{
"is_adb_error": true,
"success": false,
"error": {
"message": "Error description",
"details": "Additional context (optional)"
}
}
Rate Limits
| Scope | Limit | Window |
|---|---|---|
| OAuth endpoints | 5 requests | 10 seconds per IP |
| PII access | 1 request | 1 hour per order |
| File operations | 50 requests | 24 hours per tenant |
| General API | Adaptive | Per IP (WAF) |
HTTP Status Codes
| Code | Meaning |
|---|---|
| 200 | Success |
| 204 | Success (no content) |
| 302 | Redirect (OAuth flows) |
| 400 | Bad request (validation error) |
| 401 | Unauthorized (invalid token) |
| 403 | Forbidden (access denied) |
| 404 | Not found |
| 429 | Rate limited |
| 500 | Server error |