Create Bulk Shipping Labels

Endpoint

POST /v1/bulk_shipping_labels

Starts generating the labels for up to 50 orders, combined into one PDF. The job runs in the background, so the response returns right away with status: pending. Use Get Bulk Shipping Labels to get the file_url once it is done.

Bulk labels are available for live orders only.

Request Body

Field	Type	Required	Description
order_ids	array of string	Yes	1 to 50 Biteship order IDs
settings	object	No	Label settings. Settings you leave out use your default settings from the Biteship dashboard. See Label Settings for the default values
settings.paper_size	string	No	Paper size: a4, 8x10cm, or 10x15cm
settings.template	string	No	Label template: standard
settings.insurance_shown	boolean	No	Show insurance information
settings.insurance_fee_shown	boolean	No	Show the insurance amount
settings.shipping_fee_shown	boolean	No	Show the shipping fee
settings.items_shown	boolean	No	Show the items section
settings.item_description_shown	boolean	No	Show item descriptions
settings.item_sku_shown	boolean	No	Show item SKUs
settings.origin_phone_shown	boolean	No	Show the sender phone
settings.origin_address_shown	boolean	No	Show the sender address
settings.receiver_phone_shown	boolean	No	Show the recipient phone
settings.receiver_address_shown	boolean	No	Show the recipient address
settings.censor_receiver_name	boolean	No	Censor the recipient name

Request

curl --request POST \
  --url https://api.biteship.com/v1/bulk_shipping_labels \
  --header 'authorization: <<YOUR_API_KEY>>' \
  --header 'content-type: application/json' \
  --data '{
    "order_ids": ["<<ORDER_ID_1>>", "<<ORDER_ID_2>>", "<<ORDER_ID_3>>"],
    "settings": {
      "paper_size": "10x15cm",
      "items_shown": true,
      "censor_receiver_name": true
    }
  }'

Response

Returns HTTP 202. If the same orders with the same settings already have a bulk label that is pending, processing, or completed, the response is HTTP 200 with message Bulk shipping label already exists and returns that bulk label instead.

Field	Type	Description
success	boolean	Whether the request succeeded
code	number	Response code
message	string	Response message
bulk_label.id	string	Bulk label ID. Use it to get the bulk label
bulk_label.user_id	string	User ID
bulk_label.organization_id	string	Organization ID
bulk_label.status	string	pending, processing, completed, or failed
bulk_label.order_ids	array of string	Order IDs, with duplicates removed and sorted. Pages in the PDF follow this order
bulk_label.settings	object	Label settings used. Same fields as settings in the request
bulk_label.file_url	string or null	URL of the combined PDF. null until the job is completed
bulk_label.error_message	string or null	Orders that could not be generated, and why
bulk_label.processed_count	number	Number of labels generated so far
bulk_label.order_count	number	Number of orders in the job
bulk_label.created_at	string	Creation timestamp
bulk_label.updated_at	string	Last update timestamp

Response

{
  "success": true,
  "code": 20200000,
  "message": "Bulk shipping labels generation initiated successfully",
  "bulk_label": {
    "id": "69ae6df7b49b9700925c2229",
    "user_id": "5f9a1c2e8b3d4a0012345678",
    "organization_id": "5f9a1c2e8b3d4a0012345679",
    "status": "pending",
    "order_ids": ["69946bae0b2c6f002659f21a", "69946bae0b2c6f002659f21b", "69946bae0b2c6f002659f21c"],
    "settings": {
      "paper_size": "10x15cm",
      "template": "standard",
      "insurance_shown": true,
      "insurance_fee_shown": true,
      "shipping_fee_shown": true,
      "items_shown": true,
      "item_description_shown": true,
      "item_sku_shown": true,
      "origin_phone_shown": true,
      "origin_address_shown": true,
      "receiver_phone_shown": true,
      "receiver_address_shown": true,
      "censor_receiver_name": true
    },
    "file_url": null,
    "error_message": null,
    "processed_count": 0,
    "order_count": 3,
    "created_at": "2026-01-01T00:00:00.000Z",
    "updated_at": "2026-01-01T00:00:00.000Z"
  }
}

Errors

HTTP	Code	When
400	40000000	The request body is invalid. details lists each invalid field and the reason
422	42200002	Your plan does not include the Shipping Label API. See Plans & limits

An order ID that is not found or does not belong to you does not fail the request. That order is skipped and listed in error_message.