---
name: ai-parcels
description: Compares real-time UK parcel shipping prices from Evri, DPD, Royal Mail, UPS, FedEx and more via a single API. Finds nearby drop-off lockers, checks courier service requirements, and creates booking checkout links.
homepage: https://ai.parcels.dotnethelp.co.uk
user-invocable: true
metadata:
  clawdbot:
    emoji: "📦"
    requires:
      env: []
    files: []
---

## Quick Start for AI Agents

Base URL: `https://api.ai.parcels.dotnethelp.co.uk`

No API key required for quoting, dropshops, or requirements endpoints.

**Units — memorise these:**
- Weight → **kg** (float, e.g. `2.5`)
- Dimensions → **cm** (integers)
- Value/prices → **pence** (£5.50 = `550`)
- Country codes → **ISO 2-alpha** (`GB`, `US`, `DE`)
- Address: `property` = house number only (`"10"`); `street` = road name only (`"Downing St"`)

---

## When to Use This Skill

**Trigger phrases** — activate when the user says anything like:
- *"How much to send a parcel to…"*
- *"Get me a shipping quote for…"*
- *"What's the cheapest way to ship a 2kg box?"*
- *"Find me a drop-off locker near SW1A 2AA"*
- *"Book a delivery from London to Edinburgh"*
- *"What customs info do I need to ship with FedEx?"*

**Use cases:**
- Comparing UK parcel prices across multiple couriers
- Finding nearby Evri/DHL/UPS drop-off locations
- Checking required fields before checkout (e.g. phone, customs forms)
- Creating a shipping order and getting a payment link

---

## ⚠️ Critical Data Mapping Rules

1. **Address splitting**: `property` = house number/name ONLY; `street` = road name ONLY.
   - "10 Downing Street" → `property: "10"`, `street: "Downing Street"` ✅
   - `property: "10 Downing Street"` ❌
2. **Currency**: All prices are in **pence**. £5.50 → `550`. Display to users as `£(value/100).toFixed(2)`.
3. **Country codes**: Use ISO 2-alpha (`GB`, `US`, `FR`).

---

## Shipping Workflow (follow in order)

### Step 1 — Get Quotes
```
GET /.api/quote/shipments/{origin}/{destination}
```
**Ask the user for**: weight (kg), dimensions (cm), origin postcode, destination postcode.

### Step 2 — Check Service Requirements *(if booking)*
```
GET /.api/services/{serviceSlug}/{origin}/{destination}/requirements
```
**Why**: Different couriers require different fields (phone number, customs info, etc). Always check before checkout.

### Step 3 — Create Checkout
```
POST /.api/checkout
```
**Critical**: Return the `paymentUrl` from the response to the user. They cannot complete the order without it.

---

## Endpoints & Examples

### 1. Get Shipping Quotes

**`GET /.api/quote/shipments/{origin}/{destination}`**

| Parameter | Location | Type | Required | Notes |
|---|---|---|---|---|
| `origin` | path | string | ✅ | ISO country code, e.g. `GB` |
| `destination` | path | string | ✅ | ISO country code, e.g. `US` |
| `weight` | query | float | ✅ | In kg, e.g. `2.5` |
| `originPostcode` | query | string | recommended | e.g. `SW1A 2AA` |
| `destinationPostcode` | query | string | recommended | e.g. `EH2 2EQ` |
| `length` | query | int | recommended | In cm |
| `width` | query | int | recommended | In cm |
| `height` | query | int | recommended | In cm |
| `valueInUnits` | query | int | optional | In pence |
| `quantity` | query | int | optional | Default `1` |

**Example request:**
```bash
curl -G https://api.ai.parcels.dotnethelp.co.uk/.api/quote/shipments/GB/GB \
  -d "weight=2.0" \
  -d "originPostcode=SW1A 2AA" \
  -d "destinationPostcode=EH2 2EQ" \
  -d "length=25" \
  -d "width=20" \
  -d "height=10" \
  -d "valueInUnits=1500"
```

**Example response (200 OK):**
```json
{
  "quotes": [
    {
      "slug": "myhermes-parcelshop",
      "name": "Evri Parcel Shop",
      "courier": "Evri",
      "price": 349,
      "deliveryDate": "2026-02-26T00:00:00Z"
    },
    {
      "slug": "dpd-next-day",
      "name": "DPD Next Day",
      "courier": "DPD",
      "price": 699,
      "deliveryDate": "2026-02-24T00:00:00Z"
    }
  ]
}
```
**Present quotes to users** as: carrier name, price (`£(price/100).toFixed(2)`), estimated delivery date.

---

### 2. Get Nearby Dropshops

**`GET /.api/shops/geo/{country}/{postcode}`**

| Parameter | Location | Type | Required | Notes |
|---|---|---|---|---|
| `country` | path | string | ✅ | ISO country code, e.g. `GB` |
| `postcode` | path | string | ✅ | UK postcode, e.g. `SW1A 2AA` |
| `tag` | query | string | optional | Filter by carrier, e.g. `evri` |

**Example request:**
```bash
curl "https://api.ai.parcels.dotnethelp.co.uk/.api/shops/geo/GB/SW1A%202AA"
```

**Example response (200 OK):**
```json
{
  "result": {
    "shops": {
      "Evri": [
        {
          "id": "shop-001",
          "name": "Tesco Express",
          "address1": "200 Victoria St",
          "postcode": "SW1E 5NE",
          "distance": 0.3,
          "isLocker": false,
          "printInStoreAvailable": true
        }
      ]
    }
  }
}
```

---

### 3. Get Service Requirements

**`GET /.api/services/{serviceSlug}/{origin}/{destination}/requirements`**

| Parameter | Location | Type | Required |
|---|---|---|---|
| `serviceSlug` | path | string | ✅ |
| `origin` | path | string | ✅ |
| `destination` | path | string | ✅ |

**Example request:**
```bash
curl "https://api.ai.parcels.dotnethelp.co.uk/.api/services/myhermes-parcelshop/GB/GB/requirements"
```

**Example response (200 OK):**
```json
{
  "result": {
    "ruleSets": [
      {
        "key": "destination.phone",
        "required": true,
        "valueType": "string",
        "metadata": {
          "regex": "^[0-9 +()-]{7,20}$",
          "validationMessage": "Please provide a valid phone number"
        }
      }
    ]
  }
}
```
**Action**: Ask the user for any field where `required: true` that you don't already have.

---

### 4. Validate Checkout

**`POST /.api/validate`**

Uses the same JSON body as `POST /.api/checkout` (see below). Returns a `200` with pricing if valid, or a `400` with validation errors. Use before checkout to catch errors early.

---

### 5. Create Checkout

**`POST /.api/checkout`**

**Minimum body for UK domestic:**
```json
{
  "account": {
    "forename": "Jane",
    "surname": "Smith",
    "email": "jane@example.com"
  },
  "billingAddress": {
    "contactName": "Jane Smith",
    "property": "10",
    "street": "Downing St",
    "town": "London",
    "postcode": "SW1A 2AA",
    "country": "GB",
    "email": "jane@example.com",
    "phone": "020 7946 0000"
  },
  "items": [
    {
      "serviceSlug": "myhermes-parcelshop",
      "origin": {
        "contactName": "Sender Name",
        "property": "10",
        "street": "Downing St",
        "town": "London",
        "postcode": "SW1A 2AA",
        "country": "GB",
        "email": "sender@example.com",
        "phone": "020 7946 0000"
      },
      "destination": {
        "contactName": "Recipient Name",
        "property": "1",
        "street": "Princes St",
        "town": "Edinburgh",
        "postcode": "EH2 2EQ",
        "country": "GB",
        "email": "recipient@example.com",
        "phone": "0131 000 0000"
      },
      "parcels": [
        {
          "length": 25,
          "width": 20,
          "height": 10,
          "weight": 2.0,
          "value": 1500,
          "contentSummary": "Books"
        }
      ]
    }
  ]
}
```

**Additional fields for international shipments:**
- Add `customs: { exportReason: "sale", dutyTerms: "ddu" }` to each item.
- Add `contents` array to each parcel: `[{ quantity, description, countryOfManufacture, tariffCode }]`.

**Example success response (200 OK):**
```json
{
  "result": {
    "orderId": "ORD-123456",
    "paymentUrl": "https://www.parcel2go.com/checkout/pay?token=abc123",
    "hash": "a1b2c3d4",
    "total": {
      "gross": 349,
      "net": 291,
      "tax": 58
    }
  }
}
```
⚠️ **Always give `paymentUrl` to the user** — they must visit it to complete payment and receive their label.

---

## Error Codes

| Status | Meaning | AI Action |
|---|---|---|
| `200` | Success | Use the response data |
| `400` | Validation error | Read `error.message`, fix fields, retry |
| `502` | Upstream carrier error | Inform user of temporary unavailability |
| `5xx` | Server error | Retry once; if persists, suggest trying later |

---

## Authentication & Rate Limits

- **Authentication**: None required for `quote`, `shops`, and `requirements` endpoints.
- **Checkout/Validate**: No API key required; account details go in the request body.
- **Rate limits**: No official rate limits for reasonable usage. Avoid hammering the quote endpoint in rapid loops.

---

## Implementation Details

The skill proxies requests to the AI Parcels upstream API. No local binaries or configuration are required.

### API Capabilities
- **Get Quotes**: Real-time prices from 6+ UK carriers for any parcel dimensions.
- **Find Dropshops**: Nearby drop-off locations, lockers, and stores by postcode.
- **Service Requirements**: Exact field constraints for a specific courier service.
- **Validate**: Pre-validate checkout payload without creating an order.
- **Checkout**: Create a shipment order and receive a payment URL.

### OpenAPI Documentation
- **Home**: [AI Parcels Documentation](https://ai.parcels.dotnethelp.co.uk)
- **Interactive UI**: [API Reference](https://ai.parcels.dotnethelp.co.uk/api-reference)
- **Raw OpenAPI Spec**: `https://api.ai.parcels.dotnethelp.co.uk/doc.json`

---

## Security & Privacy

**What leaves the machine:**
- Parcel details (weight, dimensions, origin, destination, postcodes).
- For checkout/validate: account details, billing and physical addresses, parcel contents, optional customs information.
- All data is transmitted securely over HTTPS.

**What doesn't leave the machine:**
- No local files are read or exfiltrated.
- No environment variables or credentials from the user's system are accessed.
- The skill does not execute local shell commands or modify the filesystem.

---

## Model Invocation Note

Autonomous invocation of this skill for shipping inquiries is considered standard. The agent may independently query prices, locate drop-off points, or fetch requirements to assist the user. For manual oversight of all API calls, adjust your agent's permission settings.

---

## Trust Statement

**By using this skill, your shipping queries and order details (including PII such as names, emails, and address lines during checkout) are sent to the external AI Parcels API (`https://api.ai.parcels.dotnethelp.co.uk`). Only use this skill if you trust the AI Parcels API to process this data.**