DOCS
Ctrl K

API reference

Batches

Groups of purchased shipments, for example one day's orders, with merged labels.

Endpoints

List batches

GET /v1/batches

Batches on the account, newest first.

Query parameters

  • status string
  • limit integer

    Most results to return.

Response in data

  • items • Required array of objects
    Each item · 14
    • batchNumber • Required string
    • createdAt • Required timestamp
    • draftCount • Required integer
    • id • Required uuid
    • name • Required string
    • shipmentCount • Required integer
    • source • Required string

      Where the shipment came from. Leave out (it becomes manual) or name your integration, e.g. api.

    • status • Required string
    • updatedAt • Required timestamp
    • userId • Required uuid
    • branchId uuid
    • notes string

      Free-text notes.

    • sourceName string
    • storeId uuid
GET /v1/batches 
curl "https://api.parcelhub.ca/v1/batches" \
  -H "Authorization: Bearer $TOKEN"
Response 
{
  "ok": true,
  "data": {
    "items": [
      {
        "batchNumber": "string",
        "branchId": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
        "createdAt": "2026-10-31T15:04:05Z",
        "draftCount": 1,
        "id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
        "name": "Alex Martin",
        "notes": "string",
        "shipmentCount": 1,
        "source": "manual",
        "sourceName": "string",
        "status": "string",
        "storeId": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
        "updatedAt": "2026-10-31T15:04:05Z",
        "userId": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f"
      }
    ]
  },
  "request_id": "01JBX7Q2…"
}

Create a batch

POST /v1/batches

Starts a new, open batch.

Request body

  • name • Required string
  • branch_id uuid

    Leave out.

  • notes string

    Notes for the batch.

  • source string

    Where the shipment came from. Leave out (it becomes manual) or name your integration, e.g. api.

  • source_name string

    A name for that source, e.g. your app's name.

  • store_id uuid

    Leave out.

Response in data

  • batchNumber • Required string
  • createdAt • Required timestamp
  • draftCount • Required integer
  • id • Required uuid
  • name • Required string
  • shipmentCount • Required integer
  • source • Required string

    Where the shipment came from. Leave out (it becomes manual) or name your integration, e.g. api.

  • status • Required string
  • updatedAt • Required timestamp
  • userId • Required uuid
  • branchId uuid
  • notes string

    Free-text notes.

  • sourceName string
  • storeId uuid
POST /v1/batches 
curl -X POST "https://api.parcelhub.ca/v1/batches" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Alex Martin",
  "notes": "string",
  "source": "manual",
  "source_name": "string"
}'
Response 
{
  "ok": true,
  "data": {
    "batchNumber": "string",
    "branchId": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "createdAt": "2026-10-31T15:04:05Z",
    "draftCount": 1,
    "id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "name": "Alex Martin",
    "notes": "string",
    "shipmentCount": 1,
    "source": "manual",
    "sourceName": "string",
    "status": "string",
    "storeId": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "updatedAt": "2026-10-31T15:04:05Z",
    "userId": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f"
  },
  "request_id": "01JBX7Q2…"
}

Get a batch

GET /v1/batches/{id}

One batch with its totals.

Path parameters

  • id • Required string

Response in data

  • batchNumber • Required string
  • createdAt • Required timestamp
  • draftCount • Required integer
  • id • Required uuid
  • name • Required string
  • shipmentCount • Required integer
  • source • Required string

    Where the shipment came from. Leave out (it becomes manual) or name your integration, e.g. api.

  • status • Required string
  • updatedAt • Required timestamp
  • userId • Required uuid
  • branchId uuid
  • notes string

    Free-text notes.

  • sourceName string
  • storeId uuid
GET /v1/batches/{id} 
curl "https://api.parcelhub.ca/v1/batches/3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f" \
  -H "Authorization: Bearer $TOKEN"
Response 
{
  "ok": true,
  "data": {
    "batchNumber": "string",
    "branchId": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "createdAt": "2026-10-31T15:04:05Z",
    "draftCount": 1,
    "id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "name": "Alex Martin",
    "notes": "string",
    "shipmentCount": 1,
    "source": "manual",
    "sourceName": "string",
    "status": "string",
    "storeId": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "updatedAt": "2026-10-31T15:04:05Z",
    "userId": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f"
  },
  "request_id": "01JBX7Q2…"
}

Update a batch

PATCH /v1/batches/{id}

Renames a batch, changes its notes, or closes it (status: "closed"). A closed batch takes no new shipments.

Path parameters

  • id • Required string

Request body

  • name string
  • notes string

    Free-text notes.

  • status string

    open or closed.

Response in data

  • batchNumber • Required string
  • createdAt • Required timestamp
  • draftCount • Required integer
  • id • Required uuid
  • name • Required string
  • shipmentCount • Required integer
  • source • Required string

    Where the shipment came from. Leave out (it becomes manual) or name your integration, e.g. api.

  • status • Required string
  • updatedAt • Required timestamp
  • userId • Required uuid
  • branchId uuid
  • notes string

    Free-text notes.

  • sourceName string
  • storeId uuid
PATCH /v1/batches/{id} 
curl -X PATCH "https://api.parcelhub.ca/v1/batches/3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Alex Martin",
  "notes": "string",
  "status": "open"
}'
Response 
{
  "ok": true,
  "data": {
    "batchNumber": "string",
    "branchId": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "createdAt": "2026-10-31T15:04:05Z",
    "draftCount": 1,
    "id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "name": "Alex Martin",
    "notes": "string",
    "shipmentCount": 1,
    "source": "manual",
    "sourceName": "string",
    "status": "string",
    "storeId": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "updatedAt": "2026-10-31T15:04:05Z",
    "userId": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f"
  },
  "request_id": "01JBX7Q2…"
}

Batch drafts

GET /v1/batches/{id}/drafts

Drafts waiting to join this batch: they join when their label is bought.

Path parameters

  • id • Required string

Response in data

  • items • Required array of objects
    Each item · 8
    • created_at • Required timestamp

      When it was created (ISO 8601, UTC).

    • id • Required uuid
    • package_count • Required integer
    • step • Required string
    • updated_at • Required timestamp

      When it last changed (ISO 8601, UTC).

    • to_city string
    • to_country string

      Ship-to country code.

    • to_name string
GET /v1/batches/{id}/drafts 
curl "https://api.parcelhub.ca/v1/batches/3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f/drafts" \
  -H "Authorization: Bearer $TOKEN"
Response 
{
  "ok": true,
  "data": {
    "items": [
      {
        "created_at": "2026-10-31T15:04:05Z",
        "id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
        "package_count": 1,
        "step": "string",
        "to_city": "string",
        "to_country": "string",
        "to_name": "string",
        "updated_at": "2026-10-31T15:04:05Z"
      }
    ]
  },
  "request_id": "01JBX7Q2…"
}

Download all labels

GET /v1/batches/{id}/labels

One merged PDF of every label in the batch (short-lived link). skipped lists shipments whose label could not be included.

Path parameters

  • id • Required string

Response in data

  • skipped • Required array of uuids
  • url • Required string
GET /v1/batches/{id}/labels 
curl "https://api.parcelhub.ca/v1/batches/3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f/labels" \
  -H "Authorization: Bearer $TOKEN"
Response 
{
  "ok": true,
  "data": {
    "skipped": [
      "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f"
    ],
    "url": "https://…"
  },
  "request_id": "01JBX7Q2…"
}

Batch shipments

GET /v1/batches/{id}/shipments

Purchased shipments in a batch.

Path parameters

  • id • Required string

Response in data

  • items • Required array of objects
    Each item · 10
    • carrier • Required string

      Carrier code, as returned with each rate.

    • createdAt • Required timestamp
    • currency • Required string

      Three-letter currency code, e.g. CAD.

    • finalRateCents • Required integer
    • id • Required uuid
    • orderNumber • Required string
    • service • Required string
    • status • Required string
    • toAddress • Required any
    • trackingNumber string
GET /v1/batches/{id}/shipments 
curl "https://api.parcelhub.ca/v1/batches/3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f/shipments" \
  -H "Authorization: Bearer $TOKEN"
Response 
{
  "ok": true,
  "data": {
    "items": [
      {
        "carrier": "ups",
        "createdAt": "2026-10-31T15:04:05Z",
        "currency": "CAD",
        "finalRateCents": 1,
        "id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
        "orderNumber": "string",
        "service": "string",
        "status": "string",
        "toAddress": null,
        "trackingNumber": "string"
      }
    ]
  },
  "request_id": "01JBX7Q2…"
}

Add to a batch

POST /v1/batches/{id}/shipments

Adds one or more purchased shipments to an open batch.

Path parameters

  • id • Required string

Request body

  • shipment_id uuid

    One shipment to add.

  • shipment_ids array of uuids

    Several shipments to add.

Response in data

  • batchNumber • Required string
  • createdAt • Required timestamp
  • draftCount • Required integer
  • id • Required uuid
  • name • Required string
  • shipmentCount • Required integer
  • source • Required string

    Where the shipment came from. Leave out (it becomes manual) or name your integration, e.g. api.

  • status • Required string
  • updatedAt • Required timestamp
  • userId • Required uuid
  • branchId uuid
  • notes string

    Free-text notes.

  • sourceName string
  • storeId uuid
POST /v1/batches/{id}/shipments 
curl -X POST "https://api.parcelhub.ca/v1/batches/3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f/shipments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
Response 
{
  "ok": true,
  "data": {
    "batchNumber": "string",
    "branchId": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "createdAt": "2026-10-31T15:04:05Z",
    "draftCount": 1,
    "id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "name": "Alex Martin",
    "notes": "string",
    "shipmentCount": 1,
    "source": "manual",
    "sourceName": "string",
    "status": "string",
    "storeId": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "updatedAt": "2026-10-31T15:04:05Z",
    "userId": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f"
  },
  "request_id": "01JBX7Q2…"
}

Remove from a batch

DELETE /v1/batches/{id}/shipments

Takes shipments out of a batch. The shipments and their labels are not changed.

Path parameters

  • id • Required string

Request body

  • shipment_id uuid

    One shipment to remove.

  • shipment_ids array of uuids

    Several shipments to remove.

Response in data

  • batchNumber • Required string
  • createdAt • Required timestamp
  • draftCount • Required integer
  • id • Required uuid
  • name • Required string
  • shipmentCount • Required integer
  • source • Required string

    Where the shipment came from. Leave out (it becomes manual) or name your integration, e.g. api.

  • status • Required string
  • updatedAt • Required timestamp
  • userId • Required uuid
  • branchId uuid
  • notes string

    Free-text notes.

  • sourceName string
  • storeId uuid
DELETE /v1/batches/{id}/shipments 
curl -X DELETE "https://api.parcelhub.ca/v1/batches/3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f/shipments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
Response 
{
  "ok": true,
  "data": {
    "batchNumber": "string",
    "branchId": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "createdAt": "2026-10-31T15:04:05Z",
    "draftCount": 1,
    "id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "name": "Alex Martin",
    "notes": "string",
    "shipmentCount": 1,
    "source": "manual",
    "sourceName": "string",
    "status": "string",
    "storeId": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "updatedAt": "2026-10-31T15:04:05Z",
    "userId": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f"
  },
  "request_id": "01JBX7Q2…"
}