For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
DocumentationAPI Reference
DocumentationAPI Reference
  • Get Started
    • Introduction
    • Quickstart
    • Authentication
    • Rate Limit
      • Setup
      • Simulations
      • Checklist
    • Webhooks
  • Integration Guides
    • Overview
    • Tracking
    • Receiving
    • Returns
    • Billing
  • Other
    • Concepts
    • Status Reference
    • Errors
    • FAQ
LogoLogo
On this page
  • Initial Setup & Authentication
  • Product Management
  • Inventory Management
  • Order Processing
  • Warehouse Receiving Orders (WRO)
  • Returns Management
  • Webhooks
  • Sandbox Simulations
  • Error Handling & Edge Cases
  • Performance & Scalability
  • Pre-Production Checklist
  • Additional Resources
Get StartedSandbox

Checklist

||View as Markdown|
Was this page helpful?

Last updated February 24, 2026

Previous

Sandbox Simulations

Next

Webhooks

Built with

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
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 /2026-01/channel endpoint
  • Retrieve and save your channel_id with 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-calls and x-retry-after headers for rate limits

Product 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_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)
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
1

Inventory Retrieval

  • 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)
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
1

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
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
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_center id
  • 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
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
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 /2026-01/webhook or create webhooks in ShipBob dashboard
2

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
3

Return Webhooks

  • Subscribe to return.created event
  • Subscribe to return.updated event
  • Subscribe to return.completed event
  • 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
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 /2026-01/simulate/shipment endpoint
  • Simulate “ShipOrder” action
  • Verify shipment moves to Shipped status
  • Confirm tracking number is generated
  • Check order.shipped webhook 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.delivered webhook 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
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
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
  • 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 support@shipbob.com.