***

title: Checklist
sidebarTitle: Checklist
description: Use this checklist as you build your integration
last-updated: 'February 24, 2026'
---------------------------------

Use this comprehensive checklist to ensure your ShipBob API integration is production-ready. Test each component thoroughly in the sandbox environment before going live.

<Note>
  This checklist is comprehensive and flexible. Complete the sections that apply to your specific integration needs.
</Note>

***

## Initial Setup & Authentication

<AccordionGroup>
  <Accordion title="Environment Setup" icon="gear">
    <Steps>
      <Step title="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
      </Step>

      <Step title="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
      </Step>

      <Step title="Authentication">
        * [ ] Generate Personal Access Token (PAT) or set up OAuth 2.0
        * [ ] Test authentication with GET `/2025-07/channel` endpoint
        * [ ] Retrieve and save your `channel_id` with write access
        * [ ] Verify all required scopes are present
      </Step>

      <Step title="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
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

***

## Product Management

<AccordionGroup>
  <Accordion title="Product Creation & Management" icon="box">
    <Steps>
      <Step title="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)
      </Step>

      <Step title="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`
      </Step>

      <Step title="Product Retrieval">
        * [ ] GET all products with pagination
        * [ ] Filter products by SKU (`reference_id`)
        * [ ] Retrieve single product by `product_id`
        * [ ] Test product search functionality
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

***

## Inventory Management

<AccordionGroup>
  <Accordion title="Inventory Sync & Tracking" icon="warehouse">
    <Steps>
      <Step title="Inventory Retrieval">
        * [ ] Fetch all inventory levels using GET `/2025-07/inventory`
        * [ ] Map `inventory_id` to your product SKUs
        * [ ] Test pagination for large inventory datasets
        * [ ] Implement inventory sync schedule (recommended: every 15-30 minutes)
      </Step>

      <Step title="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)
      </Step>

      <Step title="Multi-Location Inventory">
        * [ ] Retrieve inventory by fulfillment center
        * [ ] Test inventory allocation across multiple locations
        * [ ] Verify location-specific inventory updates
      </Step>

      <Step title="Inventory History">
        * [ ] Track inventory changes over time
        * [ ] Monitor inventory adjustments
        * [ ] Review inventory movement logs
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

***

## Order Processing

<AccordionGroup>
  <Accordion title="Order Creation & Fulfillment" icon="truck">
    <Steps>
      <Step title="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
      </Step>

      <Step title="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)
      </Step>

      <Step title="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
      </Step>

      <Step title="Order Retrieval">
        * [ ] GET order by order\_id
        * [ ] GET order by reference\_id
        * [ ] List all orders with pagination
        * [ ] Filter orders by date range
      </Step>

      <Step title="Order Status Tracking">
        * [ ] Track order from creation to shipment
        * [ ] Monitor shipment status changes
        * [ ] Handle split shipments (multiple packages)
        * [ ] Track tracking numbers
      </Step>

      <Step title="Order Modifications">
        * [ ] Test order cancellation before fulfillment
        * [ ] Cancel specific shipments
        * [ ] Verify cancellation restrictions
      </Step>

      <Step title="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)
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

***

## Warehouse Receiving Orders (WRO)

<AccordionGroup>
  <Accordion title="Inbound Inventory" icon="pallet-boxes">
    <Steps>
      <Step title="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)
      </Step>

      <Step title="WRO Creation">
        * [ ] Create WRO
        * [ ] Include all required inventory items with quantities
        * [ ] Specify correct `fulfillment_center` id
        * [ ] Add tracking numbers if available
      </Step>

      <Step title="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
      </Step>

      <Step title="Post-Receiving">
        * [ ] Update inventory in your system after WRO completion
        * [ ] Mark WRO as synced in your system
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

***

## Returns Management

<AccordionGroup>
  <Accordion title="Return Processing" icon="rotate-left">
    <Steps>
      <Step title="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)
      </Step>

      <Step title="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
      </Step>

      <Step title="Multi-Item Returns">
        * [ ] Create return with multiple inventory items
        * [ ] Test different quantities per item
        * [ ] Test different requested\_actions per item
      </Step>

      <Step title="Return Status Tracking">
        * [ ] Monitor return status progression
        * [ ] Track when return is received at warehouse
        * [ ] Monitor processing status
        * [ ] Verify completion status
      </Step>

      <Step title="Return Retrieval">
        * [ ] GET return by return\_id
        * [ ] GET return by reference\_id
        * [ ] List all returns with pagination
        * [ ] Filter returns by status
      </Step>

      <Step title="Return Actions">
        * [ ] Verify inventory restocked correctly (if applicable)
        * [ ] Handle refund processing in your system
        * [ ] Track disposed items
        * [ ] Monitor return completion webhooks
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

***

## Webhooks

<AccordionGroup>
  <Accordion title="Webhook Setup & Testing" icon="webhook">
    <Steps>
      <Step title="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/webhook` or create webhooks in ShipBob dashboard
      </Step>

      <Step title="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
      </Step>

      <Step title="Return Webhooks">
        * [ ] Subscribe to `return.created` event
        * [ ] Subscribe to `return.updated` event
        * [ ] Subscribe to `return.completed` event
        * [ ] Verify webhook payloads contain expected data
      </Step>

      <Step title="Webhook Reliability">
        * [ ] Test webhook retry mechanism (fail to return 2XX)
        * [ ] Implement idempotency (handle duplicate webhooks)
        * [ ] Log webhook-timestamp and x-request-id headers
      </Step>

      <Step title="Webhook Management">
        * [ ] List all webhook subscriptions
        * [ ] Update webhook subscription URLs
        * [ ] Delete/unsubscribe from webhooks
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

***

## Sandbox Simulations

<AccordionGroup>
  <Accordion title="Testing Fulfillment Flow" icon="flask">
    <Steps>
      <Step title="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
      </Step>

      <Step title="Ship Order Simulation">
        * [ ] Use POST `/2.0/simulate/shipment` endpoint
        * [ ] Simulate "ShipOrder" action
        * [ ] Verify shipment moves to Shipped status
        * [ ] Confirm tracking number is generated
        * [ ] Check `order.shipped` webhook fires
      </Step>

      <Step title="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
      </Step>

      <Step title="Simulation Monitoring">
        * [ ] Track simulation\_id returned in response
        * [ ] Monitor background simulation completion
        * [ ] Handle simulation failures/errors
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

***

## Error Handling & Edge Cases

<AccordionGroup>
  <Accordion title="Robust Integration Testing" icon="triangle-exclamation">
    <Steps>
      <Step title="Rate Limiting">
        * [ ] Implement rate limit handling (150 requests/minute)
        * [ ] Handle 429 TooManyRequests responses
        * [ ] Implement exponential backoff
        * [ ] Monitor rate limit headers
      </Step>

      <Step title="Authentication Errors">
        * [ ] Handle 401 Unauthorized responses
        * [ ] Test expired OAuth tokens (refresh flow)
        * [ ] Validate PAT token before making requests
        * [ ] Handle missing or invalid `channel_id`
      </Step>

      <Step title="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
      </Step>

      <Step title="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
      </Step>

      <Step title="Data Consistency">
        * [ ] Reconcile order status between systems
        * [ ] Handle inventory sync discrepancies
        * [ ] Test webhook vs. polling data consistency
        * [ ] Implement data validation on webhook payloads
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

***

## Performance & Scalability

<AccordionGroup>
  <Accordion title="Production Readiness" icon="gauge-high">
    <Steps>
      <Step title="API Efficiency">
        * [ ] Minimize API calls using bulk endpoints
        * [ ] Implement pagination correctly
        * [ ] Use filtering to reduce response sizes
        * [ ] Batch operations when possible
      </Step>

      <Step title="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
      </Step>

      <Step title="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
      </Step>

      <Step title="Load Testing">
        * [ ] Test concurrent order creation
        * [ ] Simulate high-volume inventory syncs
        * [ ] Test webhook endpoint under load
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

***

## Pre-Production Checklist

<AccordionGroup>
  <Accordion title="Go-Live Preparation" icon="rocket">
    * [ ] 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
  </Accordion>
</AccordionGroup>

***

## Additional Resources

<CardGroup cols={2}>
  <Card title="Sandbox Setup" icon="flask" href="/sandbox/setup">
    Set up your testing environment
  </Card>

  <Card title="Simulations" icon="vial" href="/sandbox/simulations">
    Test fulfillment workflows
  </Card>

  <Card title="API Reference" icon="code" href="/api">
    Complete API documentation
  </Card>

  <Card title="Webhooks Guide" icon="webhook" href="/webhooks">
    Real-time event notifications
  </Card>
</CardGroup>

<Note>
  For additional support or to report issues during integration testing, contact ShipBob Tech Specialists at [techspecialists@shipbob.com](mailto:techspecialists@shipbob.com).
</Note>