Skip to content
Veeqo, An Amazon company Developers
Login Signup

Book a shipment

POST
/shipping/api/v1/shipments

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

Section titled “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"
    }
  ]
}

Responses

Section titled “ Responses ”

200

Section titled “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
{
  "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
  }
}
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
    }
  },
  "failed": {}
}

400

Section titled “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

Section titled “404 ”

Shipment not found

object
error_messages
required

List of error messages

Array<string>
[
  "to_address is required"
]
{
  "error_messages": [
    "Invalid request parameters"
  ]
}