> 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 #### Environment Setup #### Create Sandbox Account * [ ] Sign up for [sandbox account](https://webstage.shipbob.dev/app/merchant/#/SignUp) * [ ] Validate email address to activate account * [ ] Confirm access to ShipBob sandbox dashboard #### 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 #### Authentication * [ ] Generate Personal Access Token (PAT) or set up OAuth 2.0 * [ ] Test authentication with GET `/2026-07/channel` endpoint * [ ] Retrieve and save your `channel_id` with write access * [ ] Verify all required scopes are present #### 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-calls` and `x-retry-after` headers for rate limits --- ## Product Management #### Product Creation & Management #### Product Creation * [ ] 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) #### 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` #### 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 Retrieval * [ ] Fetch all inventory levels using GET `/2026-07/inventory` * [ ] Map `inventory_id` to your product SKUs * [ ] Test pagination for large inventory datasets * [ ] Implement inventory sync schedule (recommended: every 15-30 minutes) #### 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) #### Multi-Location Inventory * [ ] Retrieve inventory by fulfillment center * [ ] Test inventory allocation across multiple locations * [ ] Verify location-specific inventory updates #### Inventory History * [ ] Track inventory changes over time * [ ] Monitor inventory adjustments * [ ] Review inventory movement logs --- ## Order Processing #### Order Creation & Fulfillment #### Basic Order Creation * [ ] 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 #### 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) #### 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 #### Order Retrieval * [ ] GET order by order\_id * [ ] GET order by reference\_id * [ ] List all orders with pagination * [ ] Filter orders by date range #### Order Status Tracking * [ ] Track order from creation to shipment * [ ] Monitor shipment status changes * [ ] Handle split shipments (multiple packages) * [ ] Track tracking numbers #### Order Modifications * [ ] Test order cancellation before fulfillment * [ ] Cancel specific shipments * [ ] Verify cancellation restrictions #### 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 #### 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) #### WRO Creation * [ ] Create WRO * [ ] Include all required inventory items with quantities * [ ] Specify correct `fulfillment_center` id * [ ] Add tracking numbers if available #### 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 #### Post-Receiving * [ ] Update inventory in your system after WRO completion * [ ] Mark WRO as synced in your system --- ## Returns Management #### Return Processing #### 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) #### 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 #### Multi-Item Returns * [ ] Create return with multiple inventory items * [ ] Test different quantities per item * [ ] Test different requested\_actions per item #### Return Status Tracking * [ ] Monitor return status progression * [ ] Track when return is received at warehouse * [ ] Monitor processing status * [ ] Verify completion status #### Return Retrieval * [ ] GET return by return\_id * [ ] GET return by reference\_id * [ ] List all returns with pagination * [ ] Filter returns by status #### 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 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 `/2026-07/webhook` or create webhooks in ShipBob dashboard #### Order Webhooks * [ ] 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 #### Return Webhooks * [ ] Subscribe to `return.created` event * [ ] Subscribe to `return.updated` event * [ ] Subscribe to `return.completed` event * [ ] Verify webhook payloads contain expected data #### Webhook Reliability * [ ] Test webhook retry mechanism (fail to return 2XX) * [ ] Implement idempotency (handle duplicate webhooks) * [ ] Log webhook-timestamp and x-request-id headers #### Webhook Management * [ ] List all webhook subscriptions * [ ] Update webhook subscription URLs * [ ] Delete/unsubscribe from webhooks --- ## Sandbox Simulations #### Testing Fulfillment Flow #### 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 #### Ship Order Simulation * [ ] Use POST `/2026-07/simulate/shipment` endpoint * [ ] Simulate "ShipOrder" action * [ ] Verify shipment moves to Shipped status * [ ] Confirm tracking number is generated * [ ] Check `order.shipped` webhook fires #### Deliver Order Simulation * [ ] Simulate "DeliverOrder" action * [ ] Test with delay parameter (e.g., 10 minutes) * [ ] Verify shipment moves to Delivered status * [ ] Check `order.shipment.delivered` webhook fires #### Simulation Monitoring * [ ] Track simulation\_id returned in response * [ ] Monitor background simulation completion * [ ] Handle simulation failures/errors --- ## Error Handling & Edge Cases #### Robust Integration Testing #### Rate Limiting * [ ] Implement rate limit handling (150 requests/minute) * [ ] Handle 429 TooManyRequests responses * [ ] Implement exponential backoff * [ ] Monitor rate limit headers #### Authentication Errors * [ ] Handle 401 Unauthorized responses * [ ] Test expired OAuth tokens (refresh flow) * [ ] Validate PAT token before making requests * [ ] Handle missing or invalid `channel_id` #### 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 #### 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 #### 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 #### API Efficiency * [ ] Minimize API calls using bulk endpoints * [ ] Implement pagination correctly * [ ] Use filtering to reduce response sizes * [ ] Batch operations when possible #### 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 #### 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 #### Load Testing * [ ] Test concurrent order creation * [ ] Simulate high-volume inventory syncs * [ ] Test webhook endpoint under load --- ## Pre-Production Checklist #### 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](/sandbox/setup) Set up your testing environment #### [Simulations](/sandbox/simulations) Test fulfillment workflows #### [API Reference](/api) Complete API documentation #### [Webhooks Guide](/webhooks) Real-time event notifications For additional support or to report issues during integration testing, contact ShipBob Tech Specialists at [techspecialists@shipbob.com](mailto:techspecialists@shipbob.com).