{"templateId":"markdown","versions":[{"version":"shipstation-v2","label":"ShipStation V2 API","link":"/apis/shipstation-v2/docs/reference/process-batch","default":true,"active":false,"folderId":"58c9a61d"},{"version":"shipengine","label":"ShipStation API (formerly ShipEngine)","link":"/apis/shipengine/docs/reference/process-batch","default":false,"active":true,"folderId":"58c9a61d"},{"version":"shipstation-v1","label":"ShipStation V1 API","link":"/apis/shipstation-v1/docs/reference/process-batch","default":false,"active":false,"folderId":"58c9a61d"}],"sharedDataIds":{"sidebar":"sidebar-apis/@shipengine/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Process Batch","keywords":"shipping, labels, shipstation, documentation, api","siteUrl":"https://docs.shipstation.com","lang":"en-US","llmstxt":{"hide":false,"title":"ShipStation API LLM Docs","description":"Find links and references to all markdown documentation for use with LLMs","excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"process-batch","__idx":0},"children":["Process Batch"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Processing a batch means you'll be creating and purchasing the labels for the shipments included in that batch. Once processed, you can then ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/reference/get-batch-by-id"},"children":["get the batch details by batch ID"]}," to download the batch labels and forms as well as check that batch status and the review any errors that may have occurred."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you are new to batches in ShipStation API, be sure to read the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/labels/bulk"},"children":["Label Batches"]}," overview first."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To use batches successfully, you should also understand how to ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/shipping/create-a-shipment"},"children":["create a shipment"]},", how to ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/rates/get-shipment-rates"},"children":["get shipping rates"]},", and the basics around ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/reference/list-carriers"},"children":["carrier services"]},"."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["TIP:"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"use-webhooks","__idx":1},"children":["Use Webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/tracking/webhooks"},"children":["Setting up webhooks"]}," will improve your batch experience since a webhook will be called when a batch is completed."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"requirements","__idx":2},"children":["Requirements"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["batch_id"]}," for the batch you wish to process."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["All shipments in a batch, whether added with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment_id"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rate_id"]}," must have a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carrier_id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["service_code"]},". If the shipments included in the batch do not explicitly specify their carrier and service, you'll recieve an error."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["All shipments in a batch must be ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/shipping/ship-from-a-warehouse"},"children":["shipped from the same warehouse"]},". This means all shipments in a batch ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["must"]}," be assigned the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warehouse_id"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"specifying-a-label-format--layout","__idx":3},"children":["Specifying a Label Format & Layout"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You may optionally specify a ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/labels/formats"},"children":["format and layout"]}," for all the labels created with a batch. Unless otherwise specified, labels will be generated as 4x6 PDFs."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example-request","__idx":4},"children":["Example Request"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["POST /v1/batches/:batch_id/process/labels"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this example request, we specify label layout, format, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ship_date"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /v1/batches/se-1010644/process/labels HTTP/1.1\nHost: api.shipengine.com\nAPI-Key: __YOUR_API_KEY_HERE__\nContent-Type: application/json\n\n{\n  \"ship_date\": \"2019-07-25T05:00:00.000Z\",\n  \"label_layout\": \"4x6\",\n  \"label_format\": \"pdf\"\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling","__idx":5},"children":["Error Handling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Errors in batches must be handled differently from synchronous requests. You must retrieve the status of your batch by ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/reference/get-batch-by-id"},"children":["getting a batch"]}," and getting an overview of the statuses, or by ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/reference/list-batch-errors"},"children":["listing the batch errors"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"invalid-or-completed-with-errors","__idx":6},"children":["Invalid or Completed with Errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the batch enters an Invalid or Completed with Errors state, you cannot re-use the batch."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/reference/list-batch-errors"},"children":["List the batch errors"]}," to extract the shipments and the reasons why they failed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Correct the errors in the shipments by ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/reference/update-shipment"},"children":["updating the shipment"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/reference/create-batch"},"children":["Create a new batch"]}," for the shipments and rates in the invalid or error state."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/reference/process-batch"},"children":["Process the new batch"]},"."]}]}]},"headings":[{"value":"Process Batch","id":"process-batch","depth":1},{"value":"Use Webhooks","id":"use-webhooks","depth":3},{"value":"Requirements","id":"requirements","depth":2},{"value":"Specifying a Label Format & Layout","id":"specifying-a-label-format--layout","depth":3},{"value":"Example Request","id":"example-request","depth":2},{"value":"Error Handling","id":"error-handling","depth":2},{"value":"Invalid or Completed with Errors","id":"invalid-or-completed-with-errors","depth":3}],"frontmatter":{"seo":{"title":"Process Batch"}},"lastModified":"2026-04-08T10:47:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/apis/shipengine/docs/reference/process-batch","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}