Parsel Shipping API: Happy Path Integration

This guide describes the typical integration flow for shipping with Parsel's API, including rate shopping, purchasing a rate, canceling a shipment, and registering for webhook tracking updates.

---

1. Rate Shop (Get Shipping Rates)

Purpose:
Create a shipment and retrieve available shipping rates.

Endpoint:
POST /shipments

Request Example:

{
  "origin": {
    "name": "John Doe",
    "street1": "313 Nelson Street Southwest",
    "city": "Atlanta",
    "state": "GA",
    "zip": "30313",
    "country": "US",
    "company": "Acme Inc.",
    "email": "john.doe@example.com",
    "phone": "+1234567890"
  },
  "destination": {
    "name": "Jill",
    "street1": "169 Madison Avenue",
    "city": "New York",
    "state": "NY",
    "zip": "10016",
    "country": "US",
    "company": "Acme Inc.",
    "phone": "+1234567890",
    "email": "jane.doe@example.com"
  },
  "parcel": {
    "height": 1.1,
    "length": 1.1,
    "width": 1.1,
    "length_unit": "IN",
    "weight": 1.1,
    "weight_unit": "OZ"
  }
}

Response Example:

{
  "id": "02ef9c5f-29e6-48fc-9ec3-7ed57ed351f6",
  "status": "OPEN",
  "shipping_rates": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "carrier": "UPS",
      "service": "Ground",
      "price": { "amount": 10, "currency": "USD" },
      "estimated_delivery_date": "2025-03-14T00:00:00Z",
      "estimated_delivery_days": 3
    }
    // ... more rates
  ]
  // ... other shipment fields
}

---

2. Buy Rate (Purchase a Shipping Label)

Purpose:
Purchase a specific shipping rate for a shipment and generate a shipping label.

Endpoint:
POST /shipments/{shipment_id}/rates/{shipping_rate_id}

Request Example:
No body required.

Response Example:

{
  "id": "02ef9c5f-29e6-48fc-9ec3-7ed57ed351f6",
  "status": "SHIPPING_LABEL_PURCHASED",
  "shipping_label": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "PRE_TRANSIT",
    "label_url": "https://example.com/labels/123.pdf",
    "tracking_code": "1Z999AA10123456784",
    "created_at": "2025-03-10T00:00:00Z",
    "updated_at": "2025-03-10T00:00:00Z"
  }
  // ... other shipment fields
}

---

3. Cancel Shipment

Purpose:
Cancel a shipment if no shipping rate has been purchased or its shipping label is not yet in transit.

Endpoint:
PUT /shipments/{shipment_id}/cancel

Request Example:
No body required.

Response Example:

{
  "id": "02ef9c5f-29e6-48fc-9ec3-7ed57ed351f6",
  "status": "CANCELLED"
  // ... other shipment fields
}

---

4. Register for Webhook Tracking Updates

Purpose:
Receive real-time updates about shipment status changes (e.g., label purchased, tracking updates).

Endpoint:
POST /webhooks

Request Example:

{
  "url": "https://yourapp.com/webhook",
  "topic": "LABEL_TRACKING_UPDATED"
}

Response Example:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "url": "https://yourapp.com/webhook",
  "topic": "LABEL_TRACKING_UPDATED",
  "is_active": true,
  "created_at": "2023-04-01T12:00:00Z",
  "updated_at": "2023-04-01T12:00:00Z"
}

---

Summary Flow

1. Rate Shop: Create a shipment and get available rates.
2. Buy Rate: Purchase a rate to generate a shipping label.
3. Cancel Shipment: Cancel if needed (before label is in transit).
4. Register Webhook: Subscribe to tracking updates.