Skip to main content
PATCH
/
v1
/
shipments
/
{id}
/
purchase
Purchase
curl --request PATCH \
  --url https://{defaultHost}/v1/shipments/{id}/purchase \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "shipment": {
    "rate_id": "rate_1",
    "label_file_type": "PDF"
  }
}
'
{
  "id": "df8506a2-83b5-49a6-bc95-4be4b17a920e",
  "object": "shipment",
  "status": "purchased",
  "live_mode": true,
  "label_url": "https://deliver.goshippo.com/1e3adda1934443079737edb336067106.pdf?Expires=1806494587&Signature=YcAo0uG7lvxdwCmD8KPOui7O~u7KGPKWQszBtrLcdfQg5hdRZlfabsM4zSa69zRVgpEH8Omon0ktgRETyPPoIP9WOyW4CvKa7tEKyoOMi04YQ7JLCNZJXybHoJ9Z31gYqfd5RYfn1SoFTaFUDjQ17Id9RMTGG-JICM7a8fbsKFBoaGEE6zme~POyX~KX2rhlv2XiQFfmXhoJn1tF1yeh0gTJ4Ayefno4u34AeiS2XipX1anBqYyrtsxIXa7gG8NC-QufLNSgBUMcnkDLT04aa8-XXvI7IsVAkml1QqzAHq2Ur-2HVYaxYhA1V3VUjkwv8E6LwkyS~23jEysytNbdNw__&Key-Pair-Id=APKAJRICFXQ2S4YUQRSQ",
  "label_file_type": "PDF",
  "tracking_number": "9234690396055702568186",
  "tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=9234690396055702568186",
  "tracking_status": null,
  "eta": null,
  "weight": "2.0",
  "weight_unit": "lb",
  "shipping_date": 1775174400,
  "carrier": "USPS",
  "dimensions": {
    "length": 10,
    "width": 8,
    "height": 5,
    "unit": "in"
  },
  "rates": [
    {
      "id": "rate_1",
      "amount": 550,
      "currency": "usd",
      "provider": "USPS",
      "service_name": "Priority",
      "estimated_days": 3,
      "tags": [
        "bestvalue"
      ],
      "duration_terms": null,
      "provider_logo_url": "https://example.com/usps.png"
    }
  ],
  "selected_rate": {
    "id": "rate_1",
    "amount": 550,
    "currency": "usd",
    "provider": "USPS",
    "service_name": "Priority",
    "estimated_days": 3,
    "tags": [
      "bestvalue"
    ],
    "duration_terms": null,
    "provider_logo_url": "https://example.com/usps.png"
  },
  "fulfillment": "14999bec-6631-46b5-adc6-619aa671bbb6",
  "shipping_provider": "718d5e4e-2ab4-4809-9466-bb8f1dcea3d8",
  "from_contact": "be23ea53-2aec-472f-ba57-b2681f36aadb",
  "to_contact": "0406b899-ce85-4a72-85a6-9e125e308920",
  "parcel_template": null,
  "created_at": 1775219013,
  "updated_at": 1775219013
}

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

id
string
required

Body

application/json
shipment
object

Response

200 - application/json

Success

id
string | null

The UUID of the specific object.

object
string

A string describing the object type returned.

label_file_type
string

The file type for the shipping label – one of PDF, PDF_A4, PDF_A6, PDF_4x6, PDF_4x8, PNG, ZPLII.

parcel_template
string

Expandable – The associated parcel template ID.

weight
string | null

The weight of the parcel.

weight_unit
string | null

The unit of the weight – one of g, kg, lb, oz.

inherit_weight
boolean

When true, inherit the weight from the fulfillment.

shipping_date
integer

The date the shipment will be tendered to the carrier. Measured in seconds since the Unix epoch.

dimensions
object

The dimensions of the parcel.

status
string

The current status of this shipment – one of draft, quoted, purchased, voided.

live_mode
boolean

Whether or not this shipment was created in live mode.

label_url
string | null

The URL for the purchased shipping label.

tracking_number
string | null

The tracking number for this shipment.

tracking_url
string | null

The URL to track this shipment.

carrier
string | null

The shipping carrier for this shipment.

carrier_messages
object[] | null

Messages from carriers about this shipment.

tracking_status
string | null

The current tracking status – one of unknown, pre_transit, in_transit, delivered, returned, failure.

eta
string | null

The estimated time of arrival.

rates
object[]

The available shipping rates for this shipment.

selected_rate
object

The selected shipping rate for this shipment.

fulfillment

Expandable – The associated fulfillment ID.

shipping_provider

Expandable – The associated shipping provider ID.

from_contact

Expandable – The associated contact ID.

to_contact

Expandable – The associated contact ID.

created_at
integer | null

Time at which the object was created. Measured in seconds since the Unix epoch.

updated_at
integer | null

Time at which the object was last updated. Measured in seconds since the Unix epoch.