Create a shipment

POST /shipments

Books a shipment and creates its label. Parcelly chooses the carrier based on the destination, weight and service level.

Request body

FieldTypeDescription
to_address object required Where the parcel is going.
to_address.name string required Recipient's full name.
to_address.line1 string required First line of the street address.
to_address.line2 string optional Second line of the street address.
to_address.city string required City or town.
to_address.postal_code string required Postal or ZIP code.
to_address.country string required Two-letter ISO 3166-1 alpha-2 country code.
weight_grams integer required Parcel weight in grams.
service string required Delivery service level. One of: standard, express, overnight.

Example request

curl -X POST "https://api.parcelly.dev/v1/shipments" \
  -H "Authorization: Bearer $PARCELLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to_address": {
      "name": "Sam Sample",
      "line1": "12 Example Street",
      "line2": "Unit 4",
      "city": "Springfield",
      "postal_code": "62704",
      "country": "US"
    },
    "weight_grams": 1200,
    "service": "express"
  }'

Responses

201 The shipment was created.

FieldTypeDescription
id string required Unique identifier of the shipment.
status string required Current state of the shipment. One of: label_created, in_transit, out_for_delivery, delivered, cancelled.
tracking_number string required Carrier tracking number.
carrier string required ID of the carrier handling the shipment.
price number required Shipping price in USD.
created_at string (date-time) required When the shipment was created.
estimated_delivery string (date) optional Estimated delivery date, once known.

Example response

{
  "id": "shp_7Hk2mQ9x",
  "status": "in_transit",
  "tracking_number": "PCL1234567890",
  "carrier": "swiftpost",
  "price": 12.5,
  "created_at": "2026-01-20T09:30:00Z",
  "estimated_delivery": "2026-01-23"
}