canonical: https://jentic.com/apis/parcelparcel.com/api

# ParcelParcel API

Jentic publishes the only available OpenAPI specification for ParcelParcel API, keeping it validated and agent-ready. The ParcelParcel API provides shipping rate comparison and shipment management for international and domestic parcel delivery across multiple carriers (FedEx, DHL, TNT, DPD, DSV, Skynet). It powers e-commerce shipping, rate shopping, label generation, and tracking workflows.

## For AI agents

Compare shipping rates, create shipments, track parcels, and retrieve labels across 4 endpoints with multi-carrier support.

## Scope

Does not handle address validation, customs forms, or warehouse management - use for rate comparison, booking, tracking, and label retrieval only.

## Capabilities

- Compare shipping options with rates and transit times from multiple carriers
- Create draft shipments or book directly with carriers
- Track shipments by tracking number across carriers
- Retrieve shipping labels and documents (PDF, PNG, ZPL formats)
- Calculate insurance costs for insured shipments
- Support document, parcel, and pallet shipment types
- Handle international and domestic shipping with country and postal code support

## Use cases

### Multi-Carrier Rate Shopping

Compare shipping rates and transit times from multiple carriers (FedEx, DHL, TNT, DPD, DSV, Skynet) in a single request. POST /rates accepts parcels array, origin/destination (country, zipcode, city), insurance flag, and totalValue, returning sorted shipping options with price, estimatedTransitTimeInWorkingDays, and priceBreakdown.

Example prompt: POST /rates with parcels, fromCountry, toCountry, and optional insurance/totalValue to compare rates

### Shipment Creation with Labels

Create draft or confirmed shipments with label generation. POST /shipments accepts productId (from rates), from/to addresses, parcels array, and optional reference number, returning shipmentId, trackingNumber, carrier, and status. Retrieve labels via GET /documents/{shipmentId}.

Example prompt: POST /shipments with productId and addresses, then GET /documents/{shipmentId} for PDF/PNG/ZPL labels

### Shipment Tracking

Track shipments across carriers by tracking number. GET /tracking/{trackingNumber} returns carrier, status, and events array with timestamp, location, and description for each tracking update. Essential for customer notifications and delivery monitoring.

Example prompt: GET /tracking/{trackingNumber} to retrieve status and event timeline

### Pallet and Document Shipping

Support multiple parcel types (NONDOC for parcels, DOC for documents, PALLET for pallets) with type-specific requirements. PALLET requires weight, dimensions, stackable flag, and recipientType (individual/business). DOC type requires only count. NONDOC requires weight and dimensions.

Example prompt: POST /rates with parcels[type=PALLET] including weight, dimensions, stackable, and recipientType

### Agent-Driven Shipping Automation via Jentic

An AI agent managing e-commerce fulfillment can compare rates, book shipments, and track deliveries through Jentic without exposing the X-PP-API key in agent context. Jentic resolves intents like 'get cheapest shipping' to the right ParcelParcel endpoint.

Example prompt: Search Jentic for 'compare shipping rates', load the POST /rates schema, and execute

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /rates | Compare shipping options with rates and transit times |
| POST | /shipments | Create draft shipment or book with carrier |
| GET | /tracking/{trackingNumber} | Track shipment by tracking number |
| GET | /documents/{shipmentId} | Get shipping labels and documents |

## Key resources

- **ShippingOption** — Carrier service with price, transit time, and price breakdown
- **Shipment** — Shipment with tracking number, carrier, and status
- **TrackingEvent** — Tracking event with timestamp, location, and description
- **Label** — Shipping label document in PDF, PNG, or ZPL format

## Why Jentic

- **Setup:** Wiring the ParcelParcel API by hand means formatting its X-PP-API header as api-key@api-secret, shaping the rate, shipment, and tracking routes, and handling retries yourself. Through Jentic you install once, import ParcelParcel from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** ParcelParcel identifies rates and shipments in the request body, so scoping is by operation: limit the agent to the operations it needs, such as comparing rates and tracking shipments. You choose the operations it may call, so booking a shipment is not included unless you add it.
- **Credential handling:** Your ParcelParcel X-PP-API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'compare shipping rates' or 'track a shipment', and Jentic returns the matching ParcelParcel operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Easyship API** — Global shipping platform with rates, labels, tracking, and customs documentation
- **FedEx API** — Direct FedEx integration for advanced features and negotiated rates

## FAQ

### Why is there no official OpenAPI spec for ParcelParcel API?

ParcelParcel does not publish a complete OpenAPI specification for their Partners API. Jentic generates and maintains this spec so that AI agents and developers can call ParcelParcel API via structured tooling. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the ParcelParcel API use?

ParcelParcel API uses an API key passed in the X-PP-API header in format: api-key@api-secret. Through Jentic, the key is stored in the encrypted vault and injected at execution time so it never enters the agent's prompt context.

### Which carriers does ParcelParcel support?

ParcelParcel supports FedEx, DHL, TNT, DPD, DSV, and Skynet. POST /rates returns options from all available carriers for the specified route, enabling multi-carrier rate comparison in a single request.

### How does insurance work?

Set insured=true and provide totalValue (in euros) in POST /rates to include insurance costs in the returned prices. The price field includes insurance if applicable, and priceBreakdown shows insurance as a separate component.

### What parcel types are supported?

ParcelParcel supports three parcel types: NONDOC (parcels with weight and dimensions), DOC (documents with count only), and PALLET (pallets requiring weight, dimensions, stackable flag, and recipientType).

### What label formats are available?

GET /documents/{shipmentId} returns shipping labels in PDF, PNG, or ZPL formats. ZPL is for thermal printers, PDF for standard printers, and PNG for web display or printing.

### Can I limit what my agent is allowed to do with the ParcelParcel API?

Yes. Because you run Jentic One yourself, your own rules decide which ParcelParcel operations the agent may call, so you can grant read-only actions like comparing rates with POST /rates and tracking a parcel with GET /tracking/{trackingNumber} while withholding others. If you do not want the agent booking shipments, you simply leave POST /shipments and the GET /documents/{shipmentId} label retrieval out of its allowed set. The X-PP-API credential is held by your instance and injected at execution time, so the agent only ever reaches the operations you have scoped for it.