batches

List batches

Changed on
<aside class="access" aria-label="Endpoint access"> <table class="access__table"> <thead> <tr> <th class="access__table-header">Products</th> <th class="access__table-header">Plans</th> </tr> </thead> <tbody> <tr> <td class="access__table-cell access__product"> <img class="access__logo" src="/static/logos/shipstation-api-logo.svg" alt="ShipStation API Logo" loading="lazy" decoding="async"/> <div class="access__sub">Formerly ShipEngine</div> </td> <td class="access__table-cell access__plans"> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-api-free.md" class="access__plan">Free</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-api-advanced-enterprise.md" class="access__plan">Advanced</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-api-advanced-enterprise.md" class="access__plan">Enterprise</a> </td> </tr> <tr> <td class="access__table-cell"> <img class="access__logo" src="/static/logos/shipstation-logo.svg" alt="ShipStation Logo" loading="lazy" decoding="async"/> </td> <td class="access__table-cell access__plans"> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-free-starter.md" class="access__plan access__plan--off">Free</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-free-starter.md" class="access__plan access__plan--off">Starter</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-standard-premium.md" class="access__plan">Standard</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-standard-premium.md" class="access__plan">Premium</a> </td> </tr> </tbody> </table> <footer class="access__footer"> <a class="access__help" href="/apis/@shipstation-v2/docs/getting-started/products-and-plans.md"> Learn about products and plans <img src="/static/icons/external-link.svg" alt="External Link Icon" style="width: 16px;" loading="lazy" decoding="async"/> </a> </footer> </aside>

List the batches associated with your ShipStation account.

get/v2/batches

Request

  • Base URL
    https://api.shipstation.com
  • URL
    https://api.shipstation.com/v2/batches
  • Auth
    API key in header api-key

Query parameters

status'open' | 'queued' | 'processing' | 'completed' | 'completed_with_errors' | 'archived' | 'notifying' | 'invalid'

The possible batch status values

pageinteger

Return a specific page of results. Defaults to the first page. If set to a number that's greater than the number of pages of results, an empty page is returned.

page_sizeinteger

The number of results to return per response.

sort_dir'asc' | 'desc'

Controls the sort order of queries

ValueDescription
ascReturn results in ascending order
descReturn results in descending order

Controls the sort order of the query.

batch_numberstring

Batch Number

sort_by'ship_date' | 'processed_at' | 'created_at'

The possible batches sort by values

Response

The request was a success.

totalinteger required

The total number of batches the API call returned

pageinteger required

The page that is currently being read

pagesinteger required

The total number of batch pages the API call returned

Example response

{
  "batches": [
    {
      "batch_id": "se-28529731",
      "batch_number": "123456",
      "external_batch_id": "12323aaaar",
      "batch_notes": "Batch for morning shipment",
      "assigned_user": "a2df9fa5-b7ee-467f-be4e-9c660542c187",
      "created_at": "2018-09-23T15:00:00.000Z",
      "processed_at": "2018-09-23T15:00:00.000Z",
      "errors": 2,
      "process_errors": [
        {
          "message": "Body of request cannot be null.",
          "field_name": "inventory_warehouse_id",
          "field_value": "invalid-id"
        }
      ],
      "warnings": 1,
      "completed": 1,
      "forms": 3,
      "count": 2,
      "batch_shipments_url": {
        "href": "https://example.com/resource",
        "type": "child"
      },
      "batch_labels_url": {
        "href": "https://example.com/resource",
        "type": "child"
      },
      "batch_errors_url": {
        "href": "https://example.com/resource",
        "type": "child"
      },
      "label_download": {
        "href": "https://example.com/resource",
        "pdf": "https://example.com/resource",
        "png": "https://example.com/resource",
        "zpl": "https://example.com/resource"
      },
      "packing_slip_download": {
        "href": "https://example.com/resource",
        "type": "child"
      },
      "form_download": {
        "href": "https://example.com/resource",
        "type": "child"
      },
      "paperless_download": {
        "href": "https://example.com/resource",
        "instructions": "any instructions",
        "handoff_code": "122334"
      }
    }
  ],
  "total": 10,
  "page": 1,
  "pages": 10,
  "links": {
    "first": {
      "href": "https://example.com/resource",
      "type": "child"
    },
    "last": {
      "href": "https://example.com/resource",
      "type": "child"
    },
    "prev": {
      "href": "https://example.com/resource",
      "type": "child"
    },
    "next": {
      "href": "https://example.com/resource",
      "type": "child"
    }
  }
}

Changes

  • 4e29670aa28dRevision changes
    • warning

      added the new bring_your_own_label_not_supported enum value to the ///// response property for the response status

    • warning

      added the new bring_your_own_label_not_supported enum value to the // response property for the response status

    • warning

      added the new multiple_sales_orders enum value to the ///// response property for the response status

    • warning

      added the new multiple_sales_orders enum value to the // response property for the response status

    • warning

      added the new sales_order_link_required enum value to the ///// response property for the response status

    • warning

      added the new sales_order_link_required enum value to the // response property for the response status

  • bf3618aaf7e1Revision changes
    • breaking

      the response property /// became nullable for the status

    • breaking

      the response property /// became nullable for the status

    • breaking

      the response property ///// became nullable for the status

    • breaking

      the response property ///// became nullable for the status

    • breaking

      added subschema #2 to the /// response property oneOf list for the response status

    • info

      removed from the /// response property allOf list for the response status