This checklist is comprehensive and flexible. Complete the sections that apply to your specific integration needs.
Initial Setup & Authentication
Environment Setup
Environment Setup
1
Create Sandbox Account
- Sign up for sandbox account
- Validate email address to activate account
- Confirm access to ShipBob sandbox dashboard
2
Add Test Payment Method
- Navigate to Finances > Payment Methods
- Add test credit card:
4111 1111 1111 1111 - Verify payment method is active
- Test that orders don’t go On-Hold due to payment issues
3
Authentication
- Generate Personal Access Token (PAT) or set up OAuth 2.0
- Test authentication with GET
/2025-07/channelendpoint - Retrieve and save your
channel_idwith write access - Verify all required scopes are present
4
API Configuration
- Configure correct base URL:
https://sandbox-api.shipbob.com - Set up proper headers (Authorization,
shipbob_channel_id) - Implement rate limiting (150 requests/minute)
- Handle 429 responses with exponential backoff
- Monitor
x-remaining-callsandx-retry-afterheaders for rate limits
Product Management
Product Creation & Management
Product Creation & Management
1
Product Creation
- Create a simple product with required fields (name, reference_id)
- Verify product created successfully via GET products endpoint
- Confirm
inventory_idis returned and stored - Add barcode to product (recommended for receiving)
- Set packaging preferences (
requirement_id,material_type_id) - Add customs information for international shipments (optional)
2
Bundle Products
- Decide on bundle handling strategy (deconstruct vs. ShipBob-managed)
- If deconstructing: Test sending component SKUs separately
- If ShipBob-managed: Create bundle in UI and test with bundle SKU
- Verify bundle inventory calculations work correctly
- Test order creation with bundle SKU
- Confirm fulfillment returns correct component
inventory_ids
3
Product Retrieval
- GET all products with pagination
- Filter products by SKU (
reference_id) - Retrieve single product by
product_id - Test product search functionality
Inventory Management
Inventory Sync & Tracking
Inventory Sync & Tracking
1
Inventory Retrieval
- Fetch all inventory levels using GET
/2025-07/inventory - Map
inventory_idto your product SKUs - Test pagination for large inventory datasets
- Implement inventory sync schedule (recommended: every 15-30 minutes)
2
Inventory Calculations
- Calculate sellable inventory correctly
- Handle bundle inventory (calculate based on component quantities)
- Implement buffer/reserve stock logic (optional)
- Test with inactive inventory items
- Handle digital products (skip or set to 0)
3
Multi-Location Inventory
- Retrieve inventory by fulfillment center
- Test inventory allocation across multiple locations
- Verify location-specific inventory updates
4
Inventory History
- Track inventory changes over time
- Monitor inventory adjustments
- Review inventory movement logs
Order Processing
Order Creation & Fulfillment
Order Creation & Fulfillment
1
Basic Order Creation
- Create order with required fields (shipping_method, recipient, products, reference_id)
- Verify unique
reference_idvalidation works - Include optional
order_numberfield - Confirm
shipbob_channel_idheader is included
2
Recipient Information
- Test with complete address (address1, city, country, state, zip)
- Use ISO Alpha-2 country codes
- Include recipient name, email, and phone number
- Test address validation
- Test with address2 field
- Test international addresses (optional)
3
Order Tags
- Add custom tags with name/value pairs
- Test automation rule triggers with specific tag names
- Verify tags appear in order details
- Test multiple tags on single order
4
Order Retrieval
- GET order by order_id
- GET order by reference_id
- List all orders with pagination
- Filter orders by date range
5
Order Status Tracking
- Track order from creation to shipment
- Monitor shipment status changes
- Handle split shipments (multiple packages)
- Track tracking numbers
6
Order Modifications
- Test order cancellation before fulfillment
- Cancel specific shipments
- Verify cancellation restrictions
7
Edge Cases
- Test order with out-of-stock items (should go to Exception)
- Test order with invalid address (should go On-Hold)
- Test order without payment method (should go On-Hold)
- Handle orders split across multiple fulfillment centers
- Test hazmat/restricted products (optional)
Warehouse Receiving Orders (WRO)
Inbound Inventory
Inbound Inventory
1
Pre-WRO Setup
- Verify all products exist in ShipBob with inventory_ids
- Create missing products before WRO creation
- Set customs information for international products (optional)
2
WRO Creation
- Create WRO
- Include all required inventory items with quantities
- Specify correct
fulfillment_centerid - Add tracking numbers if available
3
WRO Tracking
- Monitor WRO status (Awaiting → In Transit → Processing → Completed)
- Poll for completed WROs (recommended: every 15-30 minutes)
- Retrieve WRO details and received quantities
- Handle discrepancies between expected and received quantities
4
Post-Receiving
- Update inventory in your system after WRO completion
- Mark WRO as synced in your system
Returns Management
Return Processing
Return Processing
1
Return Creation
- Create basic return with inventory_id and quantity
- Include unique
reference_id - Specify fulfillment_center id
- Add tracking_number if available
- Link to original_shipment_id when applicable
- Set requested_action (Default, Restock, Dispose)
2
Lot-Tracked Returns
- Identify lot-tracked inventory items
- Include lot_number for lot-tracked returns
- Include lot_date for lot-tracked returns
- Verify lot information matches original shipment
3
Multi-Item Returns
- Create return with multiple inventory items
- Test different quantities per item
- Test different requested_actions per item
4
Return Status Tracking
- Monitor return status progression
- Track when return is received at warehouse
- Monitor processing status
- Verify completion status
5
Return Retrieval
- GET return by return_id
- GET return by reference_id
- List all returns with pagination
- Filter returns by status
6
Return Actions
- Verify inventory restocked correctly (if applicable)
- Handle refund processing in your system
- Track disposed items
- Monitor return completion webhooks
Webhooks
Webhook Setup & Testing
Webhook Setup & Testing
1
Webhook Configuration
- Set up webhook endpoint URL (must be publicly accessible)
- Implement HTTPS endpoint (required)
- Return 2XX response for successful receipt
- Subscribe to webhooks via POST
/2025-07/webhookor create webhooks in ShipBob dashboard
2
Order Webhooks
- Subscribe to
order.shippedevent - Subscribe to
order.shipment.deliveredevent - Subscribe to
order.shipment.exceptionevent - Subscribe to
order.shipment.on_holdevent - Subscribe to
order.shipment.cancelledevent - Test each webhook fires correctly
3
Return Webhooks
- Subscribe to
return.createdevent - Subscribe to
return.updatedevent - Subscribe to
return.completedevent - Verify webhook payloads contain expected data
4
Webhook Reliability
- Test webhook retry mechanism (fail to return 2XX)
- Implement idempotency (handle duplicate webhooks)
- Log webhook-timestamp and x-request-id headers
5
Webhook Management
- List all webhook subscriptions
- Update webhook subscription URLs
- Delete/unsubscribe from webhooks
Sandbox Simulations
Testing Fulfillment Flow
Testing Fulfillment Flow
1
Shipment Preparation
- Ensure product has inventory in Cicero (IL) or Moreno Valley (CA)
- Set packaging preferences in Merchant App or when creating product
- Add customs info for international orders
- Verify shipment is not On-Hold, Exception, or Cancelled
- Confirm test payment method is active
2
Ship Order Simulation
- Use POST
/2.0/simulate/shipmentendpoint - Simulate “ShipOrder” action
- Verify shipment moves to Shipped status
- Confirm tracking number is generated
- Check
order.shippedwebhook fires
3
Deliver Order Simulation
- Simulate “DeliverOrder” action
- Test with delay parameter (e.g., 10 minutes)
- Verify shipment moves to Delivered status
- Check
order.shipment.deliveredwebhook fires
4
Simulation Monitoring
- Track simulation_id returned in response
- Monitor background simulation completion
- Handle simulation failures/errors
Error Handling & Edge Cases
Robust Integration Testing
Robust Integration Testing
1
Rate Limiting
- Implement rate limit handling (150 requests/minute)
- Handle 429 TooManyRequests responses
- Implement exponential backoff
- Monitor rate limit headers
2
Authentication Errors
- Handle 401 Unauthorized responses
- Test expired OAuth tokens (refresh flow)
- Validate PAT token before making requests
- Handle missing or invalid
channel_id
3
Validation Errors
- Test with missing required fields
- Test with invalid data types
- Test with duplicate reference_ids
- Handle invalid address data
- Test with non-existent product/inventory IDs
- Validate ISO country codes
4
Business Logic Errors
- Handle insufficient inventory scenarios
- Test order creation with inactive products
- Handle cancelled shipment modifications
- Test returns for non-existent shipments
- Validate fulfillment center availability
5
Data Consistency
- Reconcile order status between systems
- Handle inventory sync discrepancies
- Test webhook vs. polling data consistency
- Implement data validation on webhook payloads
Performance & Scalability
Production Readiness
Production Readiness
1
API Efficiency
- Minimize API calls using bulk endpoints
- Implement pagination correctly
- Use filtering to reduce response sizes
- Batch operations when possible
2
Webhook vs. Polling
- Prefer webhooks over polling for real-time updates
- Implement polling as backup for critical data
- Set appropriate polling intervals (15-30 minutes)
- Monitor webhook delivery reliability
3
Logging & Monitoring
- Log all API requests/responses
- Track API response times
- Monitor error rates by endpoint
- Set up alerts for critical failures
- Track rate limit usage patterns
4
Load Testing
- Test concurrent order creation
- Simulate high-volume inventory syncs
- Test webhook endpoint under load
Pre-Production Checklist
Go-Live Preparation
Go-Live Preparation
- Complete all sandbox testing scenarios
- Document all API integration points
- Set up production monitoring and alerts
- Configure production API credentials
- Update base URL to
https://api.shipbob.com - Test with small volume in production (pilot)
- Verify webhook endpoints are production-ready
- Confirm inventory sync accuracy
- Test order fulfillment end-to-end
- Validate return processing workflow
- Train support team on integration troubleshooting
Additional Resources
Sandbox Setup
Set up your testing environment
Simulations
Test fulfillment workflows
API Reference
Complete API documentation
Webhooks Guide
Real-time event notifications
For additional support or to report issues during integration testing, contact ShipBob Tech Specialists at [email protected].