> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer-stage.shipbob.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer-stage.shipbob.dev/_mcp/server. # Checklist > Use this checklist as you build your integration Use this comprehensive checklist to ensure your ShipBob API integration is production-ready. Test each component thoroughly in the sandbox environment before going live. This checklist is comprehensive and flexible. Complete the sections that apply to your specific integration needs. *** ## Initial Setup & Authentication * [ ] Sign up for [sandbox account](https://webstage.shipbob.dev/app/merchant/#/SignUp) * [ ] Validate email address to activate account * [ ] Confirm access to ShipBob sandbox dashboard - [ ] 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 * [ ] Generate Personal Access Token (PAT) or set up OAuth 2.0 * [ ] Test authentication with GET `/2026-01/channel` endpoint * [ ] Retrieve and save your `channel_id` with write access * [ ] Verify all required scopes are present - [ ] 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-calls` and `x-retry-after` headers for rate limits *** ## Product Management * [ ] Create a simple product with required fields (name, reference\_id) * [ ] Verify product created successfully via GET products endpoint * [ ] Confirm `inventory_id` is 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) - [ ] 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` * [ ] GET all products with pagination * [ ] Filter products by SKU (`reference_id`) * [ ] Retrieve single product by `product_id` * [ ] Test product search functionality *** ## Inventory Management * [ ] Fetch all inventory levels using GET `/2026-01/inventory` * [ ] Map `inventory_id` to your product SKUs * [ ] Test pagination for large inventory datasets * [ ] Implement inventory sync schedule (recommended: every 15-30 minutes) - [ ] 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) * [ ] Retrieve inventory by fulfillment center * [ ] Test inventory allocation across multiple locations * [ ] Verify location-specific inventory updates - [ ] Track inventory changes over time - [ ] Monitor inventory adjustments - [ ] Review inventory movement logs *** ## Order Processing * [ ] Create order with required fields (shipping\_method, recipient, products, reference\_id) * [ ] Verify unique `reference_id` validation works * [ ] Include optional `order_number` field * [ ] Confirm `shipbob_channel_id` header is included - [ ] 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) * [ ] 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 - [ ] GET order by order\_id - [ ] GET order by reference\_id - [ ] List all orders with pagination - [ ] Filter orders by date range * [ ] Track order from creation to shipment * [ ] Monitor shipment status changes * [ ] Handle split shipments (multiple packages) * [ ] Track tracking numbers - [ ] Test order cancellation before fulfillment - [ ] Cancel specific shipments - [ ] Verify cancellation restrictions * [ ] 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) * [ ] Verify all products exist in ShipBob with inventory\_ids * [ ] Create missing products before WRO creation * [ ] Set customs information for international products (optional) - [ ] Create WRO - [ ] Include all required inventory items with quantities - [ ] Specify correct `fulfillment_center` id - [ ] Add tracking numbers if available * [ ] 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 - [ ] Update inventory in your system after WRO completion - [ ] Mark WRO as synced in your system *** ## Returns Management * [ ] 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) - [ ] 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 * [ ] Create return with multiple inventory items * [ ] Test different quantities per item * [ ] Test different requested\_actions per item - [ ] Monitor return status progression - [ ] Track when return is received at warehouse - [ ] Monitor processing status - [ ] Verify completion status * [ ] GET return by return\_id * [ ] GET return by reference\_id * [ ] List all returns with pagination * [ ] Filter returns by status - [ ] Verify inventory restocked correctly (if applicable) - [ ] Handle refund processing in your system - [ ] Track disposed items - [ ] Monitor return completion webhooks *** ## Webhooks * [ ] Set up webhook endpoint URL (must be publicly accessible) * [ ] Implement HTTPS endpoint (required) * [ ] Return 2XX response for successful receipt * [ ] Subscribe to webhooks via POST `/2026-01/webhook` or create webhooks in ShipBob dashboard - [ ] Subscribe to `order.shipped` event - [ ] Subscribe to `order.shipment.delivered` event - [ ] Subscribe to `order.shipment.exception` event - [ ] Subscribe to `order.shipment.on_hold` event - [ ] Subscribe to `order.shipment.cancelled` event - [ ] Test each webhook fires correctly * [ ] Subscribe to `return.created` event * [ ] Subscribe to `return.updated` event * [ ] Subscribe to `return.completed` event * [ ] Verify webhook payloads contain expected data - [ ] Test webhook retry mechanism (fail to return 2XX) - [ ] Implement idempotency (handle duplicate webhooks) - [ ] Log webhook-timestamp and x-request-id headers * [ ] List all webhook subscriptions * [ ] Update webhook subscription URLs * [ ] Delete/unsubscribe from webhooks *** ## Sandbox Simulations * [ ] 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 - [ ] Use POST `/2026-01/simulate/shipment` endpoint - [ ] Simulate "ShipOrder" action - [ ] Verify shipment moves to Shipped status - [ ] Confirm tracking number is generated - [ ] Check `order.shipped` webhook fires * [ ] Simulate "DeliverOrder" action * [ ] Test with delay parameter (e.g., 10 minutes) * [ ] Verify shipment moves to Delivered status * [ ] Check `order.shipment.delivered` webhook fires - [ ] Track simulation\_id returned in response - [ ] Monitor background simulation completion - [ ] Handle simulation failures/errors *** ## Error Handling & Edge Cases * [ ] Implement rate limit handling (150 requests/minute) * [ ] Handle 429 TooManyRequests responses * [ ] Implement exponential backoff * [ ] Monitor rate limit headers - [ ] Handle 401 Unauthorized responses - [ ] Test expired OAuth tokens (refresh flow) - [ ] Validate PAT token before making requests - [ ] Handle missing or invalid `channel_id` * [ ] 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 - [ ] Handle insufficient inventory scenarios - [ ] Test order creation with inactive products - [ ] Handle cancelled shipment modifications - [ ] Test returns for non-existent shipments - [ ] Validate fulfillment center availability * [ ] Reconcile order status between systems * [ ] Handle inventory sync discrepancies * [ ] Test webhook vs. polling data consistency * [ ] Implement data validation on webhook payloads *** ## Performance & Scalability * [ ] Minimize API calls using bulk endpoints * [ ] Implement pagination correctly * [ ] Use filtering to reduce response sizes * [ ] Batch operations when possible - [ ] 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 * [ ] 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 - [ ] Test concurrent order creation - [ ] Simulate high-volume inventory syncs - [ ] Test webhook endpoint under load *** ## Pre-Production Checklist * [ ] 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 Set up your testing environment Test fulfillment workflows Complete API documentation Real-time event notifications For additional support or to report issues during integration testing, contact ShipBob Support at [support@shipbob.com](mailto:support@shipbob.com).