# Create a shipment

**POST** `/v1/shipments`

Base URL: `https://api.parcel-events.example`

Tags: `Shipments`

## Authorization

Any ONE of the following options authorizes this operation; every scheme listed within an option is required together.

| Option | Scheme | Type | Sent as | Scopes |
| --- | --- | --- | --- | --- |
| Option 1 | `ApiKey` | `apiKey` | header `Parcel-API-Key` | — |
| Option 2 | `BearerToken` | `http` | `Authorization: Bearer <token>` (opaque) | — |

## Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | `string` (uuid) | Yes | — |

## Request body

Required. Media type: `application/json`

### Example request body

```json
{
  "delivery_instructions": "Leave with the synthetic reception desk",
  "metadata": {
    "additionalProp1": "string"
  },
  "parcels": [
    {
      "contents": [
        {
          "customs_code": "610910",
          "description": "Synthetic cotton shirt",
          "quantity": 2,
          "unit_value": {
            "amount": "12.50",
            "currency": "XTS"
          }
        }
      ],
      "height_cm": 12,
      "length_cm": 30.5,
      "weight_grams": 1750,
      "width_cm": 20
    }
  ],
  "recipient": {
    "city": "Exampleton",
    "company": "Northstar Supplies",
    "country": "ZZ",
    "line1": "14 Fictional Quay",
    "line2": "Unit 7",
    "name": "Rowan Example",
    "phone": "+00000000000",
    "postal_code": "EX4 2PL",
    "region": "Test Province"
  },
  "reference": "synthetic-order-1042",
  "sender": {
    "city": "Exampleton",
    "company": "Northstar Supplies",
    "country": "ZZ",
    "line1": "14 Fictional Quay",
    "line2": "Unit 7",
    "name": "Rowan Example",
    "phone": "+00000000000",
    "postal_code": "EX4 2PL",
    "region": "Test Province"
  },
  "service": "economy"
}
```

## Responses

| Status | Description | Media type |
| --- | --- | --- |
| `201` | Shipment created | `application/json` |
| `400` | Request syntax or parameters are invalid | `application/problem+json` |
| `409` | Current resource state prevents the operation | `application/problem+json` |

### Example response: 201 — Shipment created

```json
{
  "created_at": "2026-09-04T08:15:30Z",
  "delivery_instructions": "string",
  "id": "shp_00000000000000000001",
  "metadata": {
    "additionalProp1": "string"
  },
  "object": "shipment",
  "parcels": [
    {
      "contents": [
        {
          "customs_code": "610910",
          "description": "Synthetic cotton shirt",
          "quantity": 2,
          "unit_value": {
            "amount": "12.50",
            "currency": "XTS"
          }
        }
      ],
      "height_cm": 12,
      "length_cm": 30.5,
      "weight_grams": 1750,
      "width_cm": 20
    }
  ],
  "recipient": {
    "city": "Exampleton",
    "company": "Northstar Supplies",
    "country": "ZZ",
    "line1": "14 Fictional Quay",
    "line2": "Unit 7",
    "name": "Rowan Example",
    "phone": "+00000000000",
    "postal_code": "EX4 2PL",
    "region": "Test Province"
  },
  "reference": "synthetic-order-1042",
  "sender": {
    "city": "Exampleton",
    "company": "Northstar Supplies",
    "country": "ZZ",
    "line1": "14 Fictional Quay",
    "line2": "Unit 7",
    "name": "Rowan Example",
    "phone": "+00000000000",
    "postal_code": "EX4 2PL",
    "region": "Test Province"
  },
  "service": "economy",
  "status": "canceled",
  "tracking_number": "PE-000000000001",
  "updated_at": "2026-09-04T08:16:12Z"
}
```

### Example response: 400 — Request syntax or parameters are invalid

```json
{
  "request_id": "req_00000000000000000001",
  "status": 400,
  "title": "Synthetic request is invalid",
  "type": "https://parcel-events.example/problems/bad-request"
}
```

### Example response: 409 — Current resource state prevents the operation

```json
{
  "request_id": "req_00000000000000000005",
  "status": 409,
  "title": "Synthetic resource state conflicts",
  "type": "https://parcel-events.example/problems/conflict"
}
```

## Related pages

- [Buy and render a shipping label](./createlabel.md)
- [Cancel a pickup](./cancelpickup.md)
- [Cancel a shipment before handoff](./cancelshipment.md)
- [Delete a webhook endpoint](./deletewebhookendpoint.md)
- [Labels](./tags/labels.md)
- [List scheduled pickups](./listpickups.md)
- [List shipments](./listshipments.md)
- [List tracking events for a shipment](./listshipmentevents.md)
- [List webhook endpoints](./listwebhookendpoints.md)
- [Parcel Events Sandbox API](../../api.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.