Book a shipment

POST

/shipping/api/v1/shipments

Veeqo API Production Server

Create a shipping label using a previously retrieved rate quote. You can include optional services by passing the key from shipping_service_options with a selected value.

Request Body^required

object

label_format

Label format (optional, determines the format of label_url in response)

string

default: PDF

Allowed values: PDF PNG ZPL JPEG

request_token

Optional request token from rates response for validation

string

token-abc-def-123

shipments

required

Required array of shipments to book. Must be an array even when booking a single shipment.

Example for single shipment:

{
  "shipments": [
    { "remote_shipment_id": "prb123", "rate_id": "rate-abc-123" }
  ]
}

Array<object>

>= 1 items

object

remote_shipment_id

required

Remote shipment ID from rates response

string

prb851f578f

rate_id

required

Required rate/quote ID from the rates response. Use the ‘name’ field from the quote object.

string

amazon_shipping_v2-8412d3d9-24be-42be-8fb9-e7280b3beb9d

custom_messages

Optional custom messages to print on the shipping label

Array<string>

[
  "CUSTOM MESSAGE 1",
  "CUSTOM MESSAGE 2"
]

label_format

Override the default label format for this specific shipment

string

Allowed values: PDF PNG ZPL JPEG

ZPL

key

additional properties

Additional optional services can be included using keys from the shipping_service_options array in the rates response.

Value-added services use the pattern value_added_service__* (e.g., value_added_service__VAS_GROUP_ID_CONFIRMATION)

Additional inputs use the pattern additional_input__* (e.g., additional_input__SHIPMENT_DESCRIPTION)

Common examples:

value_added_service__VAS_GROUP_ID_CONFIRMATION: “SIGNATURE” or “DELIVERY_CONFIRMATION”
liability_amount: 100.00 (insurance amount)
additional_input__SHIPMENT_DESCRIPTION: “Fragile electronics”

The available options and their valid values are returned in the shipping_service_options array from the rates endpoint.

Examples

Basic booking with PDF label

{
  "label_format": "PDF",
  "shipments": [
    {
      "remote_shipment_id": "prb8a99eb17",
      "rate_id": "amazon_shipping_v2-df3f52c6-643e-4959-b802-f60ca1df42bb"
    }
  ]
}

Booking with signature confirmation

{
  "label_format": "PDF",
  "shipments": [
    {
      "remote_shipment_id": "prb851f578f",
      "rate_id": "amazon_shipping_v2-8412d3d9-24be-42be-8fb9-e7280b3beb9d",
      "value_added_service__VAS_GROUP_ID_CONFIRMATION": "DELIVERY_CONFIRMATION"
    }
  ]
}

Booking multiple shipments at once

{
  "label_format": "PDF",
  "shipments": [
    {
      "remote_shipment_id": "prb8a99eb17",
      "rate_id": "amazon_shipping_v2-df3f52c6-643e-4959-b802-f60ca1df42bb",
      "custom_messages": [
        "Handle with care",
        "Fragile items"
      ]
    },
    {
      "remote_shipment_id": "prb851f578f",
      "rate_id": "amazon_shipping_v2-8412d3d9-24be-42be-8fb9-e7280b3beb9d",
      "value_added_service__VAS_GROUP_ID_CONFIRMATION": "SIGNATURE",
      "label_format": "ZPL"
    },
    {
      "remote_shipment_id": "prbc7d8e9f0",
      "rate_id": "amazon_shipping_v2-a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "liability_amount": 100
    }
  ]
}

Responses

200

Shipment booked successfully

object

successful

Successfully booked shipments keyed by remote_shipment_id

object

key

additional properties

object

remote_shipment_id

Remote shipment ID (may be null)

string

nullable

tracking_number

Tracking number

string

9341920111411169517859

carrier_id

Carrier identifier

string

USPS

service_carrier

Service carrier code

string

usps

service_name

Service name

string

USPS Bound Printed Matter

service_id

Service identifier

string

USPS_PTP_BPM

signature_type

Signature/confirmation type

string

DELIVERY_CONFIRMATION

label_format

Label format

string

PDF

label_content

Base64 encoded label content

string

JVBERi0xLjQKJeLjz9MKMyAwIG9iago8P...

total_charge

object

value

number format: double

4.04

unit

string

USD

charges

Array<object>

object

chargeId

string

BASE_RATE

chargeType

string

MANDATORY

value

number format: double

4.039999961853027

linked_account

Whether a linked account was used

boolean

external_shipment_id

External shipment ID from carrier

string

MSS3da64049-1f98-4113-8287-28d1c043c1a8

to_address_id

To address ID

string

78722344-3738-48f7-857e-e6dff79db84e

from_address_id

From address ID

string

b8b3e7b6-3adc-417f-963b-dd9851947ac2

customer_reference

Customer reference number

string

112-4737182-6879466

inbound

Whether this is an inbound shipment

boolean

documents

Shipping documents returned by the carrier (e.g., commercial invoices, customs forms). Only present when the carrier returns documents alongside the label.

Array<object>

A shipping document returned in the book response with base64-encoded content

object

type

Document type identifier from the carrier

string

COMMERCIAL_INVOICE

content

Base64-encoded document content (typically PDF)

string

JVBERi0xLjQKJeLjz9MKMyAwIG9iago8P...

{
  "prb851f578f": {
    "tracking_number": "9341920111411169517859",
    "carrier_id": "USPS",
    "service_carrier": "usps",
    "service_name": "USPS Bound Printed Matter",
    "service_id": "USPS_PTP_BPM",
    "signature_type": "DELIVERY_CONFIRMATION",
    "label_format": "PDF",
    "label_content": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8P...",
    "total_charge": {
      "value": 4.04,
      "unit": "USD"
    },
    "charges": [
      {
        "chargeId": "BASE_RATE",
        "chargeType": "MANDATORY",
        "value": 4.039999961853027
      }
    ],
    "linked_account": false,
    "external_shipment_id": "MSS3da64049-1f98-4113-8287-28d1c043c1a8",
    "to_address_id": "78722344-3738-48f7-857e-e6dff79db84e",
    "from_address_id": "b8b3e7b6-3adc-417f-963b-dd9851947ac2",
    "customer_reference": "112-4737182-6879466",
    "inbound": false,
    "documents": [
      {
        "type": "COMMERCIAL_INVOICE",
        "content": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8P..."
      }
    ]
  }
}

failed

Failed shipments keyed by remote_shipment_id

object

key

additional properties

object

errors

Array<string>

Examples

Single shipment booked successfully

{
  "successful": {
    "prb851f578f": {
      "tracking_number": "9341920111411169517859",
      "carrier_id": "USPS",
      "service_carrier": "usps",
      "service_name": "USPS Bound Printed Matter",
      "service_id": "USPS_PTP_BPM",
      "signature_type": "DELIVERY_CONFIRMATION",
      "label_format": "PDF",
      "label_content": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8P...",
      "total_charge": {
        "value": 4.04,
        "unit": "USD"
      },
      "charges": [
        {
          "chargeId": "BASE_RATE",
          "chargeType": "MANDATORY",
          "value": 4.039999961853027
        }
      ],
      "linked_account": false,
      "external_shipment_id": "MSS3da64049-1f98-4113-8287-28d1c043c1a8",
      "to_address_id": "78722344-3738-48f7-857e-e6dff79db84e",
      "from_address_id": "b8b3e7b6-3adc-417f-963b-dd9851947ac2",
      "customer_reference": "112-4737182-6879466",
      "inbound": false,
      "documents": [
        {
          "type": "COMMERCIAL_INVOICE",
          "content": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8P..."
        }
      ]
    }
  },
  "failed": {}
}

Multiple shipments with mixed success

{
  "successful": {
    "prb8a99eb17": {
      "tracking_number": "9205590164917312345678",
      "carrier_id": "USPS",
      "service_carrier": "usps",
      "service_name": "USPS Priority Mail",
      "service_id": "USPS_PTP_PRI",
      "label_format": "PDF",
      "label_content": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8P...",
      "total_charge": {
        "value": 12.45,
        "unit": "USD"
      },
      "charges": [
        {
          "chargeId": "BASE_RATE",
          "chargeType": "MANDATORY",
          "value": 12.45
        }
      ],
      "linked_account": false,
      "external_shipment_id": "MSS1234-5678-90ab-cdef",
      "to_address_id": "78722344-3738-48f7-857e-e6dff79db84e",
      "from_address_id": "b8b3e7b6-3adc-417f-963b-dd9851947ac2",
      "customer_reference": "ORDER-12345",
      "inbound": false
    },
    "prb851f578f": {
      "tracking_number": "1Z999AA10123456784",
      "carrier_id": "UPS",
      "service_carrier": "ups",
      "service_name": "UPS Ground",
      "service_id": "UPS_PTP_GRND",
      "signature_type": "SIGNATURE",
      "label_format": "ZPL",
      "label_content": "XlhBCk5eTEs0MDAsNDAKXkZPMTAwLDEwMF5BQk4sMzYs...",
      "total_charge": {
        "value": 15.99,
        "unit": "USD"
      },
      "charges": [
        {
          "chargeId": "BASE_RATE",
          "chargeType": "MANDATORY",
          "value": 15.99
        }
      ],
      "linked_account": false,
      "external_shipment_id": "1ZUPS9876543210",
      "to_address_id": "78722344-3738-48f7-857e-e6dff79db84e",
      "from_address_id": "b8b3e7b6-3adc-417f-963b-dd9851947ac2",
      "customer_reference": "ORDER-12345",
      "inbound": false
    }
  },
  "failed": {
    "prbc7d8e9f0": {
      "errors": [
        "Rate quote has expired. Please request new rates."
      ]
    }
  }
}

400

Bad request - invalid parameters or expired quote

object

error_messages

required

List of error messages

Array<string>

[
  "to_address is required"
]

{
  "error_messages": [
    "Invalid request parameters"
  ]
}

404

Shipment not found

object

error_messages

required

List of error messages

Array<string>

[
  "to_address is required"
]

{
  "error_messages": [
    "Invalid request parameters"
  ]
}

Book a shipment

Request Body required

Examples

Responses

200

Examples

400

404

Request Body^required