Skip to content
Guides
/
/
Manage Totes
Last updated

Manage Totes

Totes (also known as bins or containers) are used in warehouse picking and packing operations to organize and transport items. With the /v2/totes endpoint, you can create, list, update, and delete totes, as well as track tote quantities across warehouses.

What are Totes?

Totes are physical containers used in warehouse operations to:

  • Organize items during the picking process
  • Transport products from storage locations to packing stations
  • Group multiple items for batch processing
  • Improve warehouse efficiency and accuracy

Each tote has a unique identifier and can be assigned to a specific warehouse. Totes can also have barcodes for quick scanning and identification.

Tote Properties

PropertyTypeDescription
tote_idstringGenerated automatically when you create a tote. This unique identifier is required to get, update, or delete a specific tote.
inventory_warehouse_idstringThe warehouse where this tote is located. Required when creating or updating a tote. You can also use it as a query parameter when listing totes to filter by warehouse.
tote_namestring (max 100 characters)The name of the tote. This is required when creating or updating a tote and should be unique within the warehouse for easy identification.
tote_barcodestring (max 100 characters)Optional barcode identifier for the tote. Used for scanning during warehouse operations.
created_atstring (date-time)The date and time the tote was created.

List All Totes

Get all totes, optionally filtered by warehouse.

GET /v2/totes

Query Parameters

  • inventory_warehouse_id (optional): Filter totes by a specific warehouse ID

Example Request & Response

curl -i -X GET \
  'https://api.shipstation.com/v2/totes?inventory_warehouse_id=se-28529731' \
  -H 'api-key: YOUR_API_KEY_HERE'

Get Tote Quantities by Warehouse

Get a count of how many totes exist in each warehouse.

GET /v2/totes/quantities

This endpoint is useful for warehouse management and inventory tracking, allowing you to see tote distribution across your warehouses at a glance.

Example Request & Response

curl -i -X GET \
  https://api.shipstation.com/v2/totes/quantities \
  -H 'api-key: YOUR_API_KEY_HERE'

Get a Specific Tote

Retrieve details of a single tote by its ID.

GET /v2/totes/{tote_id}

Example Request & Response

curl -i -X GET \
  https://api.shipstation.com/v2/totes/se-28529731 \
  -H 'api-key: YOUR_API_KEY_HERE'

Create Totes in Batch

Create multiple totes at once. This endpoint accepts an array of totes and returns both successfully created totes and any failures.

POST /v2/totes

Request Body

The request body should contain:

  • totes: An array of tote objects to create, each with:
    • inventory_warehouse_id (required)
    • tote_name (required)
    • tote_barcode (optional)
  • return_succeeded_totes (optional): Set to true if you need print information for labels

Response

The response includes two arrays:

  • succeeded_totes: Totes that were successfully created
  • failed_totes: Totes that failed to create, with error messages explaining why

This allows you to handle partial success scenarios where some totes are created successfully while others fail (e.g., due to duplicate names).

Example Request & Response

curl -i -X POST \
  https://api.shipstation.com/v2/totes \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "totes": [
      {
        "inventory_warehouse_id": "se-789012",
        "tote_name": "Tote-B5",
        "tote_barcode": "TOTE789012"
      }
    ],
    "return_succeeded_totes": false
  }'

Update a Tote

Update the name or barcode of an existing tote.

PUT /v2/totes/{tote_id}

Example Request & Response

curl -i -X PUT \
  https://api.shipstation.com/v2/totes/se-28529731 \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "inventory_warehouse_id": "se-789012",
    "tote_name": "Tote-B5-Updated",
    "tote_barcode": "TOTE789012-NEW"
  }'

Delete a Tote

Delete a tote by its ID.

DELETE /v2/totes/{tote_id}

IMPORTANT

Deleting a tote is permanent and cannot be undone. Ensure the tote is no longer in use before deleting it.

Example Request & Response

curl -i -X DELETE \
  https://api.shipstation.com/v2/totes/se-28529731 \
  -H 'api-key: YOUR_API_KEY_HERE'

Common Use Cases

Setting Up a New Warehouse

When setting up a new warehouse, you can create multiple totes in batch:

  1. Create your warehouse using the /v2/inventory_warehouses endpoint
  2. Use the batch create endpoint to add all totes at once
  3. Assign barcodes to totes for scanning during operations

Tracking Tote Usage

Use the quantities endpoint to monitor tote distribution:

  1. Call GET /v2/totes/quantities to see tote counts per warehouse
  2. Identify warehouses that may need more or fewer totes
  3. Reallocate totes as needed by updating their warehouse assignment

Warehouse Operations

During picking and packing:

  1. Scan a tote barcode and retrieve its details with GET /v2/totes/{tote_id}
  2. Use the tote to organize items during picking
  3. Track which totes are in use for better workflow management
Previous page
Next page