--- title: "List batches" method: GET path: "/v2/batches" tags: ["batches"] --- # List batches `GET /v2/batches`

Products	Plans
Formerly ShipEngine	Free Advanced Enterprise
	Free Starter Standard Premium

List the batches associated with your ShipStation account. ## Query parameters - `status` 'open' | 'queued' | 'processing' | 'completed' | 'completed_with_errors' | 'archived' | 'notifying' | 'invalid' — The possible batch status values - `page` integer - `page_size` integer - `sort_dir` 'asc' | 'desc' — Controls the sort order of queries |Value |Description |:---------|:----------------------------------------------------- |`asc` |Return results in ascending order |`desc` |Return results in descending order - `batch_number` string - `sort_by` 'ship_date' | 'processed_at' | 'created_at' — The possible batches sort by values ## Response `200` The request was a success. - ListBatchesResponseBody — A list batch response body - `batches` Batch[], required — Batch List - `label_layout` '4x6' | 'letter', required — The available layouts (sizes) in which shipping labels can be downloaded. The label format determines which sizes are supported. `4x6` is supported for all label formats, whereas `letter` (8.5" x 11") is only supported for `pdf` format. - `label_format` 'pdf' | 'png' | 'zpl', required — The possible file formats in which shipping labels can be downloaded. We recommend `pdf` format because it is supported by all carriers, whereas some carriers do not support the `png` or `zpl` formats. |Label Format | Supported Carriers |--------------|----------------------------------- |`pdf` | All carriers |`png` | `fedex`
`stamps_com`
`ups`
`usps` |`zpl` | `access_worldwide`
`apc`
`asendia`
`dhl_global_mail`
`dhl_express`
`dhl_express_australia`
`dhl_express_canada`
`dhl_express_worldwide`
`dhl_express_uk`
`dpd`
`endicia`
`fedex`
`fedex_uk`
`firstmile`
`imex`
`newgistics`
`ontrac`
`rr_donnelley`
`stamps_com`
`ups`
`usps` - `batch_id` string, required — A string that uniquely identifies a ShipStation resource, such as a carrier, label, shipment, etc. - `batch_number` string, required — The batch number. - `external_batch_id` string, required — A string that uniquely identifies the external batch - `batch_notes` string, required — Custom notes you can add for each created batch - `created_at` string, date-time, required — An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string that represents a date and time. - `processed_at` string, date-time, required — An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string that represents a date and time. - `errors` integer, required — The number of errors that occurred while generating the batch - `process_errors` Error[], required — The errors associated with the failed API call - `error_source` 'carrier' | 'order_source' | 'ShipStation' | 'shipengine', required — The source of the error, as indicated by the name this informs us if the API call failed because of the carrier, the order source, the ShipStation API itself, or the underlying ShipEngine platform. - `error_type` 'account_status' | 'business_rules' | 'validation' | 'security' | 'system' | 'integrations', required — The type of error - `error_code` 'auto_fund_not_supported' | 'batch_cannot_be_modified' | 'carrier_conflict' | 'carrier_disconnected' | 'carrier_not_connected' | 'carrier_not_supported' | 'confirmation_not_supported' | 'default_warehouse_cannot_be_deleted' | 'field_conflict' | 'field_value_required' | 'forbidden' | 'identifier_conflict' | 'identifiers_must_match' | 'insufficient_funds' | 'invalid_address' | 'invalid_billing_plan' | 'invalid_field_value' | 'invalid_identifier' | 'invalid_status' | 'invalid_string_length' | 'label_images_not_supported' | 'meter_failure' | 'order_source_not_active' | 'rate_limit_exceeded' | 'refresh_not_supported' | 'request_body_required' | 'return_label_not_supported' | 'settings_not_supported' | 'subscription_inactive' | 'terms_not_accepted' | 'tracking_not_supported' | 'trial_expired' | 'unauthorized' | 'unknown' | 'unspecified' | 'verification_failure' | 'warehouse_conflict' | 'webhook_event_type_conflict' | 'customs_items_required' | 'incompatible_paired_labels' | 'invalid_charge_event' | 'invalid_object' | 'no_rates_returned' | 'freight_connection_inactive' | 'freight_provider_id_required' | 'freight_shipment_not_found' | 'freight_tracking_not_available' | 'freight_tracking_not_found' | 'freight_shipment_not_batchable', required — The error code specified for the failed API Call - `message` string, required — An error message associated with the failed API call - `field_name` string — The name of the field that caused the error (only present for validation errors) - `field_value` string — The invalid value that was provided for the field (only present for validation errors) - `warnings` integer, required — The number of warnings that occurred while generating the batch - `completed` integer, required — The number of labels generated in the batch - `forms` integer, required — The number of forms for customs that are available for download - `count` integer, required — The total of errors, warnings, and completed properties - `batch_shipments_url` OptionalLink, required — A link to a related resource, or an empty object if there is no resource to link to - `href` string, url — A URL - `type` string — The type of resource, or the type of relationship to the parent resource - `batch_labels_url` OptionalLink, required — A link to a related resource, or an empty object if there is no resource to link to - `href` string, url — A URL - `type` string — The type of resource, or the type of relationship to the parent resource - `batch_errors_url` OptionalLink, required — A link to a related resource, or an empty object if there is no resource to link to - `href` string, url — A URL - `type` string — The type of resource, or the type of relationship to the parent resource - `label_download` LabelDownload, required — Reference to the various downloadable file formats for the generated label - `href` string, url — A URL - `pdf` string, url — A URL - `png` string, url — A URL - `zpl` string, url — A URL - `form_download` OptionalLink, required — A link to a related resource, or an empty object if there is no resource to link to - `href` string, url — A URL - `type` string — The type of resource, or the type of relationship to the parent resource - `paperless_download` PaperlessDownload, required — The paperless details which may contain elements like `href`, `instructions` and `handoff_code`. - `href` string, url — A URL - `instructions` string — The instructions for the paperless download. - `handoff_code` string — The handoff code for the paperless download. - `status` 'open' | 'queued' | 'processing' | 'completed' | 'completed_with_errors' | 'archived' | 'notifying' | 'invalid', required — The possible batch status values - `total` integer, required — The total number of batches the API call returned - `page` integer, required — The page that is currently being read - `pages` integer, required — The total number of batch pages the API call returned - `links` PaginationLink, required — Helpful links to other pages of results - `first` Link, required — A link to a related resource, or an empty object if there is no resource to link to - `href` string, url — A URL - `type` string — The type of resource, or the type of relationship to the parent resource - `last` Link, required — A link to a related resource, or an empty object if there is no resource to link to - `href` string, url — A URL - `type` string — The type of resource, or the type of relationship to the parent resource - `prev` OptionalLink, required — A link to a related resource, or an empty object if there is no resource to link to - `href` string, url — A URL - `type` string — The type of resource, or the type of relationship to the parent resource - `next` OptionalLink, required — A link to a related resource, or an empty object if there is no resource to link to - `href` string, url — A URL - `type` string — The type of resource, or the type of relationship to the parent resource ## Other responses - `404` — The specified resource does not exist. - `500` — The request was successful. --- [API](https://skmtc.net/shipstation/apis/shipstation-api-v2.md) · [All operations](https://skmtc.net/shipstation/apis/shipstation-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/shipstation/shipstation-api-v2/revisions/d3d8c21cd227/schema)