PII Protection

The core purpose of ShipStream Data Border is to protect Personally Identifiable Information (PII) while enabling your WMS to fulfill Amazon orders efficiently.

The Challenge

Your WMS needs customer data to fulfill orders, but Amazon requires:

• Audit trails for all PII access
• Rate limiting to prevent bulk extraction
• Suspicious activity detection for unusual patterns
• Data minimization - only access what you need

Building this into your WMS is complex and creates compliance risk.

How Data Border Protects PII

1. On-Demand Fetching

PII is never stored in Data Border. When your WMS needs customer data, Data Border fetches it directly from Amazon's SP-API:

sequenceDiagram
    participant WMS
    participant ADB
    participant Amazon as Amazon SP-API
    
    WMS->>ADB: GET /api/pii/getPII/123-456
    ADB->>ADB: Validate access token
    ADB->>ADB: Check rate limits
    ADB->>ADB: Log access attempt
    ADB->>Amazon: Request RDT token
    Amazon->>ADB: Return RDT
    ADB->>Amazon: GET /orders/{id}/address
    Amazon->>ADB: Return PII
    ADB->>ADB: Log successful access
    ADB->>WMS: Return PII data

2. Comprehensive Audit Logging

Every PII access is logged with:

• Order ID - Which order's data was accessed
• Timestamp - When the access occurred
• IP Address - Where the request came from
• User Agent - What made the request
• Success/Failure - Whether access was granted
• Tenant/Seller - Who made the request

This creates a complete audit trail for Amazon compliance reviews.

3. Intelligent Rate Limiting

Data Border prevents bulk PII extraction:

4. Suspicious Activity Detection

Data Border detects and alerts on:

• Accessing PII for already-shipped orders
• Accessing PII for orders not belonging to the seller
• Unusual patterns of PII access (volume, timing)
• Requests for unsupported data types

Using the PII API

Fetch Customer Address

When you genuinely need customer PII (rare cases like returns or customer service):

curl -X GET https://adb.example.com/api/pii/getPII/123-4567890-1234567 \
  -H "x-seller-access-token: YOUR_SELLER_TOKEN" \
  -H "x-amazon-token-secret: YOUR_TOKEN_SECRET"

Response:

{
  "piiData": {
    "ShippingAddress": {
      "Name": "John Doe",
      "AddressLine1": "123 Main Street",
      "City": "Anytown",
      "StateOrRegion": "CA",
      "PostalCode": "12345",
      "CountryCode": "US"
    }
  },
  "piiSignedUrl": "https://storage.example.com/...",
  "piiFileName": "file-123-4567890-1234567"
}

Block PII Access

When you're done with an order, block further PII access:

curl -X POST https://adb.example.com/api/pii/blockPII \
  -H "Content-Type: application/json" \
  -H "x-seller-access-token: YOUR_SELLER_TOKEN" \
  -H "x-amazon-token-secret: YOUR_TOKEN_SECRET" \
  -d '{"orderId": "123-4567890-1234567"}'

Mark Order Complete

Signal that an order is fulfilled:

curl -X POST https://adb.example.com/api/pii/completeOrder \
  -H "Content-Type: application/json" \
  -H "x-seller-access-token: YOUR_SELLER_TOKEN" \
  -H "x-amazon-token-secret: YOUR_TOKEN_SECRET" \
  -d '{"orderId": "123-4567890-1234567"}'

Best Practices

Prefer Label Proxy Over Direct PII Access

In most cases, you don't need direct PII access. Use the Label Proxy instead:

# Step 1: Fetch PII
GET /api/pii/getPII/123-456

# Step 2: Build carrier request with PII
# Step 3: Call carrier API
# Step 4: Store result

# Your WMS now has customer PII!

# Single request with placeholders
POST /api/label-proxy/forward
{
  "to_address": {
    "name": "{{ship_to_name}}",
    "street1": "{{ship_to_address1}}"
  }
}

# Your WMS never sees the PII!

Block Access When Done

Call /api/pii/blockPII or /api/pii/completeOrder as soon as you're done with an order. This:

• Prevents accidental re-access
• Creates a clear audit trail of data lifecycle
• Demonstrates data minimization compliance

Use File Storage for Attachments

If you need to store order-related files (invoices, customs docs), use the PII file endpoints:

# Write a file
PUT /api/pii/writeFile?orderId=123-456&fileName=invoice.pdf

# Read a file
GET /api/pii/getFile?orderId=123-456&fileName=invoice.pdf

# Delete when done
DELETE /api/pii/deleteFile

Files are stored in tenant-isolated S3 storage and subject to the same audit logging.

What's Logged

Every PII operation creates audit records:

{
  "type": "pii_access",
  "orderId": "123-4567890-1234567",
  "sellerId": "seller_abc123",
  "tenantId": "tenant_xyz789",
  "action": "getPII",
  "success": true,
  "ip": "203.0.113.42",
  "userAgent": "WMS-Client/1.0",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

These logs are:

• Retained according to your configured policy
• Searchable by order ID, seller, tenant, or time range
• Available for Amazon compliance reviews
• Forwarded to your SIEM/logging system

Next Steps