{"templateId":"markdown","versions":[{"version":"shipstation-v2","label":"ShipStation V2 API","link":"/apis/shipstation-v2/docs/reference/create-batch","default":true,"active":false,"folderId":"58c9a61d"},{"version":"shipengine","label":"ShipStation API (formerly ShipEngine)","link":"/apis/shipengine/docs/reference/create-batch","default":false,"active":true,"folderId":"58c9a61d"},{"version":"shipstation-v1","label":"ShipStation V1 API","link":"/apis/shipstation-v1/docs/reference/create-batch","default":false,"active":false,"folderId":"58c9a61d"}],"sharedDataIds":{"sidebar":"sidebar-apis/@shipengine/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Create 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":"create-batch","__idx":0},"children":["Create Batch"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Batches allow you to process hundreds or thousands of labels at a time and receive the labels and any related documentation, like customs forms, in a single bulk response."]},{"$$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":"Heading","attributes":{"level":2,"id":"requirements","__idx":1},"children":["Requirements"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$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"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The shipments you add to a batch must use a ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/reference/create-warehouse"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warehouse_id"]}]}," instead of a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ship_from"]}," address."]},{"$$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":2,"id":"request-body","__idx":2},"children":["Request Body"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the request body, you'll can the following (though none of these properties are required when creating the batch):"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_batch_id"]},": A string that uniquely identifies the external batch."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["batch_notes"]},": A custom messages for a particular batch"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment_ids"]},": Array of shipment IDs used in the batch (you can also ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/reference/add-to-batch"},"children":["add shipments to the batch"]}," later)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rate_ids"]},": Array of rate IDs used in the batch (you can also ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/reference/add-to-batch"},"children":["add rates to the batch"]}," later)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example-request--response","__idx":3},"children":["Example Request & Response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["POST /v1/batches/"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /v1/batches HTTP/1.1\nHost: api.shipengine.com\nAPI-Key: __YOUR_API_KEY_HERE__\nContent-Type: application/json\n\n{\n  \"external_batch_id\": \"1daa0c22-0519-46d0-8653-9f3dc62e7d2c\",\n  \"batch_notes\": \"2019-7-25 Morning Shipments\",\n  \"shipment_ids\": [\n    \"se-2102769\"\n  ],\n  \"rate_ids\": []\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response will return the new batch properties, including the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["batch_id"]}," you'll need for ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/reference/add-to-batch"},"children":["adding shipments to the batch"]}," and ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/reference/process-batch"},"children":["processing the batch"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"label_layout\": null,\n  \"label_format\": null,\n  \"batch_id\": \"se-1013790\",\n  \"external_batch_id\": \"1daa0c22-0519-46d0-8653-9f3dc62e7d2c\",\n  \"batch_notes\": \"2019-7-25 Morning Shipments\",\n  \"created_at\": \"2019-07-25T15:24:46.657Z\",\n  \"errors\": 0,\n  \"warnings\": 0,\n  \"completed\": 0,\n  \"forms\": 0,\n  \"count\": 1,\n  \"batch_shipments_url\": {\n    \"href\": \"https://api.shipengine.com/v1/shipments?batch_id=se-1013790\"\n  },\n  \"batch_labels_url\": {\n    \"href\": \"https://api.shipengine.com/v1/labels?batch_id=se-1013790\"\n  },\n  \"batch_errors_url\": {\n    \"href\": \"https://api.shipengine.com/v1/batches/se-1013790/errors\"\n  },\n  \"label_download\": {\n    \"href\": \"https://api.shipengine.com/v1/downloads/1/uths7PctKUqbM4OfmgzXLg/label-1013790.pdf\"\n  },\n  \"form_download\": {\n    \"href\": \"https://api.shipengine.com/v1/downloads/1/xKVZeKA650-bvQB_oriYkQ/form-1013790.pdf\"\n  },\n  \"status\": \"open\"\n}\n","lang":"json"},"children":[]}]},"headings":[{"value":"Create Batch","id":"create-batch","depth":1},{"value":"Requirements","id":"requirements","depth":2},{"value":"Request Body","id":"request-body","depth":2},{"value":"Example Request & Response","id":"example-request--response","depth":2}],"frontmatter":{"seo":{"title":"Create Batch"}},"lastModified":"2026-04-08T10:47:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/apis/shipengine/docs/reference/create-batch","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}