{ "openapi": "3.1.0", "info": { "title": "ParcelParcel API", "version": "1.0", "summary": "Compare shipping options, book shipments, get labels, track parcels and estimate duties and taxes.", "description": "The partners API of ParcelParcel, for accounts of ParcelParcel Netherlands B.V. and ParcelParcel Belgium BV. You get the prices of your own account, and every shipment you create shows up in MyParcelParcel.\n\nAuthentication: send your API key and secret in the `X-PP-API` header as `{YourAPIKey}@{YourAPISecret}`. Find them in MyParcelParcel under Settings > Developers > API keys. A sandbox key (starts with `sbx_`) uses live rates and tracking but never sends bookings to the carrier.\n\nMost responses have the shape `{\"errors\": false, \"message\": \"...\", \"data\": ...}`. A missing or wrong `X-PP-API` header returns the plain text `X-PP-API header not valid`.\n\nHuman-readable docs: https://www.parcelparcel.com/api-docs/", "contact": { "name": "ParcelParcel integrations", "email": "integrations@italogistics.com", "url": "https://www.parcelparcel.com/api-docs/support/" } }, "externalDocs": { "description": "ParcelParcel API docs", "url": "https://www.parcelparcel.com/api-docs/" }, "servers": [ { "url": "https://services.parcelparcel.com/partners-api/v1", "description": "Production (live and sandbox keys)" } ], "security": [ { "ppApiKey": [] } ], "tags": [ { "name": "Account", "description": "Check your credentials." }, { "name": "Rates", "description": "Shipping options with prices and transit times." }, { "name": "Shipments", "description": "Create, book, cancel, list shipments and get labels." }, { "name": "Tracking", "description": "Tracking events of a shipment." }, { "name": "Customs", "description": "Dutiable routes and duties and taxes." }, { "name": "Webhooks", "description": "Get a POST on your own URL when a shipment is booked." } ], "paths": { "/me": { "get": { "tags": [ "Account" ], "operationId": "getMe", "summary": "Check your API key", "description": "Returns the account your API key belongs to. The live key and the sandbox key return the same account.", "externalDocs": { "url": "https://www.parcelparcel.com/api-docs/me/" }, "responses": { "200": { "description": "Your credentials work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeResponse" }, "examples": { "example-response": { "summary": "Example response", "value": { "errors": false, "message": "Query processed successfully", "data": { "username": "shipping@yourcompany.com" } } } } } } } } } }, "/rates": { "post": { "tags": [ "Rates" ], "operationId": "compareShippingOptions", "summary": "Compare shipping options", "description": "Returns the shipping options for your account, cheapest first, with price (EUR, excluding VAT) and transit time. Use a `productId` as `preferredShippingOption` when you create a shipment.", "externalDocs": { "url": "https://www.parcelparcel.com/api-docs/compare-shipping-options/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RatesRequest" }, "examples": { "get-shipping-options-for-a-parcel-shipment-from-the-netherlands-to-the-united-states": { "summary": "Get shipping options for a parcel shipment from the Netherlands to the United States", "value": { "parcels": [ { "type": "NONDOC", "weight": "1.5", "height": "10", "width": "10", "length": "10", "count": "1" } ], "fromCountry": "NL", "fromZipcode": "1411 AT", "fromCity": "Naarden", "toCountry": "US", "toZipcode": "10001", "toCity": "New York", "insured": true, "totalValue": 100 } }, "get-shipping-options-for-a-document-shipment-from-the-netherlands-to-the-united-states": { "summary": "Get shipping options for a document shipment from the Netherlands to the United States", "value": { "parcels": [ { "type": "DOC", "count": "1" } ], "fromCountry": "NL", "fromZipcode": "1411 AT", "fromCity": "Naarden", "toCountry": "US", "toZipcode": "10001", "toCity": "New York", "insured": false, "totalValue": 100 } }, "get-shipping-options-for-a-pallet-shipment-from-the-netherlands-to-the-united-states": { "summary": "Get shipping options for a pallet shipment from the Netherlands to the United States", "value": { "parcels": [ { "type": "PALLET", "weight": "80", "height": "120", "width": "120", "length": "100", "count": "1", "stackable": false } ], "recipientType": "business", "fromCountry": "NL", "fromZipcode": "1411 AT", "fromCity": "Naarden", "toCountry": "NL", "toZipcode": "1052LP", "toCity": "Amsterdam", "insured": false, "totalValue": 100 } } } } } }, "responses": { "201": { "description": "The shipping options.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RatesResponse" }, "examples": { "get-shipping-options-for-a-parcel-shipment-from-the-netherlands-to-the-united-states": { "summary": "Get shipping options for a parcel shipment from the Netherlands to the United States", "value": { "errors": false, "message": "Rates successfully processed", "data": [ { "carrier": "DHL", "product": "DHL Express Worldwide", "productId": 74, "price": 84.08, "minEstimatedTransitTimeInWorkingsDays": 6, "maxEstimatedTransitTimeInWorkingsDays": 7, "priceBreakdown": [ { "item": "DHL Express Worldwide", "amount": 84.08 } ] }, { "carrier": "FedEx", "product": "FedEx Economy", "productId": 79, "price": 90, "minEstimatedTransitTimeInWorkingsDays": 8, "maxEstimatedTransitTimeInWorkingsDays": 9, "priceBreakdown": [ { "item": "FedEx Economy", "amount": 90 } ] }, { "carrier": "FedEx", "product": "FedEx Priority", "productId": 80, "price": 94.36, "minEstimatedTransitTimeInWorkingsDays": 3, "maxEstimatedTransitTimeInWorkingsDays": 4, "priceBreakdown": [ { "item": "FedEx Priority", "amount": 94.36 } ] }, { "carrier": "DHL", "product": "DHL Express 12:00", "productId": 78, "price": 112.88, "minEstimatedTransitTimeInWorkingsDays": 5, "maxEstimatedTransitTimeInWorkingsDays": 6, "priceBreakdown": [ { "item": "DHL Express 12:00", "amount": 112.88 } ] }, { "carrier": "TNT", "product": "TNT Express", "productId": 95, "price": 130.55, "minEstimatedTransitTimeInWorkingsDays": 6, "maxEstimatedTransitTimeInWorkingsDays": 7, "priceBreakdown": [ { "item": "TNT Express", "amount": 130.55 } ] }, { "carrier": "DHL", "product": "DHL Express 10:30", "productId": 113, "price": 134.54, "minEstimatedTransitTimeInWorkingsDays": 5, "maxEstimatedTransitTimeInWorkingsDays": 6, "priceBreakdown": [ { "item": "DHL Express 10:30", "amount": 134.54 } ] } ] } }, "get-shipping-options-for-a-document-shipment-from-the-netherlands-to-the-united-states": { "summary": "Get shipping options for a document shipment from the Netherlands to the United States", "value": { "errors": false, "message": "Rates successfully processed", "data": [ { "carrier": "DHL", "product": "DHL Express 12:00", "productId": 78, "price": 55.27, "minEstimatedTransitTimeInWorkingsDays": 7, "maxEstimatedTransitTimeInWorkingsDays": 8, "priceBreakdown": [ { "item": "DHL Express 12:00", "amount": 55.27 } ] }, { "carrier": "DHL", "product": "DHL Express Worldwide", "productId": 74, "price": 59.98, "minEstimatedTransitTimeInWorkingsDays": 7, "maxEstimatedTransitTimeInWorkingsDays": 8, "priceBreakdown": [ { "item": "DHL Express Worldwide", "amount": 59.98 } ] }, { "carrier": "FedEx", "product": "FedEx Priority", "productId": 80, "price": 65.61, "minEstimatedTransitTimeInWorkingsDays": 5, "maxEstimatedTransitTimeInWorkingsDays": 6, "priceBreakdown": [ { "item": "FedEx Priority", "amount": 65.61 } ] }, { "carrier": "TNT", "product": "TNT Express", "productId": 95, "price": 66.68, "minEstimatedTransitTimeInWorkingsDays": 5, "maxEstimatedTransitTimeInWorkingsDays": 6, "priceBreakdown": [ { "item": "TNT Express", "amount": 66.68 } ] }, { "carrier": "DHL", "product": "DHL Express 10:30", "productId": 113, "price": 68.06, "minEstimatedTransitTimeInWorkingsDays": 7, "maxEstimatedTransitTimeInWorkingsDays": 8, "priceBreakdown": [ { "item": "DHL Express 10:30", "amount": 68.06 } ] } ] } }, "get-shipping-options-for-a-pallet-shipment-within-the-netherlands-domestic": { "summary": "Get shipping options for a pallet shipment within the Netherlands (domestic)", "value": { "errors": false, "message": "Rates successfully processed", "data": [ { "carrier": "DSV", "product": "DSV Road Domestic", "productId": 114, "price": 67.05, "minEstimatedTransitTimeInWorkingsDays": 1, "maxEstimatedTransitTimeInWorkingsDays": 2, "priceBreakdown": [ { "item": "DSV Road Domestic", "amount": 67.05 } ] }, { "carrier": "TNT", "product": "TNT Express domestic", "productId": 102, "price": 300.02, "minEstimatedTransitTimeInWorkingsDays": 5, "maxEstimatedTransitTimeInWorkingsDays": 6, "priceBreakdown": [ { "item": "TNT Express domestic", "amount": 300.02 } ] }, { "carrier": "TNT", "product": "TNT Domestic 12:00", "productId": 103, "price": 312.51, "minEstimatedTransitTimeInWorkingsDays": 5, "maxEstimatedTransitTimeInWorkingsDays": 6, "priceBreakdown": [ { "item": "TNT Domestic 12:00", "amount": 312.51 } ] }, { "carrier": "DHL", "product": "DHL Express Domestic", "productId": 105, "price": 948.58, "minEstimatedTransitTimeInWorkingsDays": 5, "maxEstimatedTransitTimeInWorkingsDays": 6, "priceBreakdown": [ { "item": "DHL Express Domestic", "amount": 948.58 } ] }, { "carrier": "DHL", "product": "DHL Express 12:00", "productId": 78, "price": 1156.87, "minEstimatedTransitTimeInWorkingsDays": 5, "maxEstimatedTransitTimeInWorkingsDays": 6, "priceBreakdown": [ { "item": "DHL Express 12:00", "amount": 1156.87 } ] } ] } } } } } }, "400": { "description": "The request body is not valid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": {} } } } } }, "422": { "description": "Not enough data to calculate rates, for example `insured` without `totalValue`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/shipments": { "post": { "tags": [ "Shipments" ], "operationId": "createShipment", "summary": "Create a (draft) shipment", "description": "Creates a draft shipment in API shipments in MyParcelParcel, or books it directly with `bookShipment: true` (you also get the labels). With a sandbox key a booking is never sent to the carrier: you get a sample label, tracking number `SANDBOX` and `\"sandbox\": true`.", "externalDocs": { "url": "https://www.parcelparcel.com/api-docs/create-shipment/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShipmentRequest" }, "examples": { "parcel-shipment-from-the-netherlands-to-france": { "summary": "Parcel shipment from the Netherlands to France", "value": { "parcels": [ { "type": "NONDOC", "weight": "20", "height": "10", "width": "74", "length": "84", "count": "1" } ], "contentItems": [ { "description": "This is a description of an content item", "quantity": "1", "price": "1600.00", "country": "NL" }, { "description": "This is a description of an content item", "quantity": "1", "price": "1600.00", "country": "NL", "hsCode": "61091000" } ], "reasonForExport": "commercial", "reference": "#123126", "currency": "EUR", "incoterms": "DAP", "pickupAddress": { "countryCode": "NL", "companyName": "ParcelParcel", "contactPerson": "John Doe", "email": "info@parcelparcel.com", "phone": "+31858771656", "addressLine1": "Energiestraat 14E", "addressLine2": "Extra details-", "zipcode": "1411 AT", "city": "Naarden" }, "destinationAddress": { "countryCode": "FR", "companyName": "Company x", "contactPerson": "John Croissant", "email": "johncroissant@hotmail.com", "phone": "+5218112278399", "addressLine1": "Rue de Baquette 34", "addressLine2": "Dans la rue", "zipcode": "75001", "vatNumber": "0000", "city": "Paris" }, "schedulePickup": 1, "pickupDate": "2026-11-05", "pickupTimeFrom": "12:00", "pickupTimeTo": "16:00", "pickupInstructions": "Ring the bell", "insured": 0 } }, "parcel-shipment-from-the-netherlands-to-the-united-states": { "summary": "Parcel shipment from the Netherlands to the United States", "value": { "parcels": [ { "type": "NONDOC", "weight": "9.6", "height": "10", "width": "74", "length": "84", "count": "1" } ], "contentItems": [ { "description": "Awesome Product", "quantity": "1", "price": "69.00", "hsCode": "61091000", "country": "NL" } ], "reasonForExport": "commercial", "reference": "#123126", "currency": "EUR", "incoterms": "DAP", "pickupAddress": { "countryCode": "NL", "companyName": "CompanyOne", "contactPerson": "John Doe 1", "email": "johndow@example.com", "phone": "+31858771656", "addressLine1": "street Name ...", "addressLine2": "extra details", "zipcode": "3542 AB", "city": "Utrecht" }, "destinationAddress": { "countryCode": "US", "companyName": "CompanyTwo", "contactPerson": "John Doe", "email": "johndow@example.com", "phone": "+31858771656", "addressLine1": "street Name ...", "addressLine2": "Dover market", "zipcode": "10001", "vatNumber": "0000", "city": "New York" }, "schedulePickup": 1, "pickupDate": "2026-11-05", "pickupTimeFrom": "12:00", "pickupTimeTo": "16:00", "pickupInstructions": "Ring the bell", "insured": 0 } }, "parcel-shipment-booked-directly-from-the-netherlands-to-the-united-states": { "summary": "Parcel shipment (booked directly) from the Netherlands to the United States", "value": { "parcels": [ { "type": "NONDOC", "weight": "9.6", "height": "10", "width": "74", "length": "84", "count": "1" } ], "contentItems": [ { "description": "Awesome Product", "quantity": "1", "price": "69.00", "hsCode": "61091000", "country": "NL" } ], "reasonForExport": "commercial", "reference": "#123126", "currency": "EUR", "incoterms": "DAP", "pickupAddress": { "countryCode": "NL", "companyName": "CompanyOne", "contactPerson": "John Doe 1", "email": "johndow@example.com", "phone": "+31858771656", "addressLine1": "street Name ...", "addressLine2": "extra details", "zipcode": "3542 AB", "city": "Utrecht" }, "destinationAddress": { "countryCode": "US", "companyName": "CompanyTwo", "contactPerson": "John Doe", "email": "johndow@example.com", "phone": "+31858771656", "addressLine1": "street Name ...", "addressLine2": "Dover market", "zipcode": "10001", "vatNumber": "0000", "city": "New York" }, "insured": 0, "bookShipment": true } } } } } }, "responses": { "201": { "description": "The draft was created, or the shipment was booked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShipmentResponse" }, "examples": { "parcel-shipment-from-the-netherlands-to-france": { "summary": "Parcel shipment from the Netherlands to France", "value": { "errors": false, "message": "Your draft shipment is successfully created in your API shipments section", "data": { "id": 1 } } }, "parcel-draft-shipment-from-the-netherlands-to-the-united-states": { "summary": "Parcel draft shipment from the Netherlands to the United States", "value": { "errors": false, "message": "Your draft shipment is successfully created in your API shipments section", "data": { "id": 1 } } }, "parcel-shipment-booked-directly-from-the-netherlands-to-the-united-states": { "summary": "Parcel shipment (booked directly) from the Netherlands to the United States", "value": { "errors": [], "message": "Your shipment has been booked", "data": { "id": 1588448, "status": "created_at_carrier", "carrier": "FedEx", "product": "FedEx - FedEx Economy", "productId": 79, "price": 86.41, "trackingNumber": "6516516533", "trackingUrl": "https://www.fedex.com/apps/fedextrack/?action=track&trackingnumber=6516516533&cntry_code=nl&locale=nl_NL", "labels": "=== base64 encoded label ===" } } } } } } }, "422": { "description": "The shipment is not valid, for example a missing required field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Shipments" ], "operationId": "listShipments", "summary": "List your shipments", "description": "All shipments on your account, filtered with query parameters. All parameters are optional and can be combined.", "externalDocs": { "url": "https://www.parcelparcel.com/api-docs/list-shipments/" }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "perPage", "in": "query", "schema": { "type": "integer", "default": 25, "maximum": 100 } }, { "name": "status", "in": "query", "description": "Leave out to return all active statuses.", "schema": { "$ref": "#/components/schemas/ShipmentStatus" } }, { "name": "shipmentId", "in": "query", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "description": "Search by reference or tracking number.", "schema": { "type": "string" } }, { "name": "carrier", "in": "query", "description": "Carrier ID, for example DHL, FEDEX or UPS.", "schema": { "type": "string" } }, { "name": "bookedFrom", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "bookedTo", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "originCountry", "in": "query", "description": "ISO 3166-1 alpha-2.", "schema": { "$ref": "#/components/schemas/CountryCode" } }, { "name": "destinationCountry", "in": "query", "description": "ISO 3166-1 alpha-2.", "schema": { "$ref": "#/components/schemas/CountryCode" } } ], "responses": { "200": { "description": "A page of shipments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentListResponse" }, "examples": { "example-response": { "summary": "Example response", "value": { "errors": false, "message": "Query processed successfully", "data": [ { "id": 387766, "status": "created_at_carrier", "trackingNumber": "1ZG2237K6804083920", "trackingUrl": "https://www.ups.com/track?loc=en_US&tracknum=1ZG2237K6804083920", "trackingStatus": "in_transit", "labelsUrl": "https://services.parcelparcel.com/partners-api/v1/shipments/387766/labels", "reference": "my-order-ref-123", "carrier": "UPS", "product": "UPS Standard", "price": 57.23, "pickupAddress": { "company": "My Company", "contactPerson": "John Doe", "phone": "0201234567", "email": "john@example.com", "addressLine1": "Teststreet 1", "addressLine2": null, "zipcode": "1057 BN", "city": "Amsterdam", "stateOrProvince": null, "country": "NL", "vatNumber": null, "eoriNumber": null }, "destinationAddress": { "company": null, "contactPerson": "Jane Smith", "phone": "12312312311", "email": "jane@example.com", "addressLine1": "123 Main St", "addressLine2": null, "zipcode": "75001", "city": "Dallas", "stateOrProvince": "TX", "country": "US", "vatNumber": null, "eoriNumber": null }, "createdAt": "2026-04-13T09:12:00+00:00", "bookedAt": "2026-04-13T09:14:32+00:00" } ], "meta": { "total": 1, "page": 1, "perPage": 25 } } } } } } } } } }, "/shipments/{shipmentId}/cancel": { "post": { "tags": [ "Shipments" ], "operationId": "cancelShipment", "summary": "Cancel a (draft) shipment", "description": "Cancels a draft or a booked shipment. A booked shipment can only be cancelled until the carrier has picked it up or scanned it.", "externalDocs": { "url": "https://www.parcelparcel.com/api-docs/cancel-shipment/" }, "parameters": [ { "$ref": "#/components/parameters/ShipmentId" } ], "responses": { "200": { "description": "Cancelled, or it was already cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelResponse" }, "examples": { "shipment-cancelled-200": { "summary": "Shipment cancelled (200)", "value": { "cancelled": true, "message": "Shipment was cancelled" } }, "shipment-already-cancelled-200": { "summary": "Shipment already cancelled (200)", "value": { "cancelled": true, "message": "Shipment was already cancelled" } } } } } }, "404": { "description": "Shipment not found on your account.", "content": { "application/json": { "schema": { "type": "string", "const": "Shipment not found" }, "examples": { "shipment-not-found-404": { "summary": "Shipment not found (404)", "value": "Shipment not found" } } } } }, "409": { "description": "Not cancelled: the parcel is in transit or the carrier refused. See `message`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelResponse" }, "examples": { "shipment-already-in-transit-409": { "summary": "Shipment already in transit (409)", "value": { "cancelled": false, "message": "Shipment is already in transit and can no longer be cancelled" } } } } } } } } }, "/shipments/{shipmentId}/labels": { "get": { "tags": [ "Shipments" ], "operationId": "getShippingDocuments", "summary": "Get the shipping documents (labels)", "description": "The complete shipping documentation of a booked shipment as base64 (PDF). Sandbox shipments return a sample label.", "externalDocs": { "url": "https://www.parcelparcel.com/api-docs/shipping-documents/" }, "parameters": [ { "$ref": "#/components/parameters/ShipmentId" } ], "responses": { "200": { "description": "The labels.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelsResponse" }, "examples": { "example-response": { "summary": "Example response", "value": { "data": { "labels": "=== base64 encoded label ===" } } } } } } }, "404": { "description": "No labels for this shipment." } } } }, "/track/{trackingNumber}": { "get": { "tags": [ "Tracking" ], "operationId": "trackShipment", "summary": "Track a shipment", "description": "Tracking status and events of a shipment booked through MyParcelParcel. `123456789` is a dummy tracking number you can use to try it.", "externalDocs": { "url": "https://www.parcelparcel.com/api-docs/track-shipment/" }, "parameters": [ { "name": "trackingNumber", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123456789" } ], "responses": { "200": { "description": "Tracking status and events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackingResponse" }, "examples": { "example-response": { "summary": "Example response", "value": { "status": "in_transit", "pod": false, "checkpoints": [ { "time": "2025-06-12T01:15:30-05:00", "code": "OC", "message": "Label created", "description": "Shipment information sent to FedEx", "location": "", "signedBy": "" }, { "time": "2025-06-12T11:33:00+02:00", "code": "PU", "message": "Picked up", "description": "Picked up", "location": "6662, ELST, Netherlands (Holland)", "signedBy": "" }, { "time": "2025-06-12T14:32:00+02:00", "code": "CC", "message": "In transit", "description": "International shipment release - Export", "location": "6662, ELST, Netherlands (Holland)", "signedBy": "" } ] } } } } } }, "404": { "description": "Shipment not found on your account.", "content": { "application/json": { "schema": { "type": "string", "const": "Shipment not found" } } } } } } }, "/dutiable-route/{countryFrom}/{countryTo}/{parcelType}": { "get": { "tags": [ "Customs" ], "operationId": "checkDutiableRoute", "summary": "Check if a shipment goes through customs", "description": "`dutiable` is true when at least one of the two countries is outside the EU (according to ParcelParcel's country list, so e.g. IC, EA, GP, MQ, RE, GF, YT and AX count as outside) and the parcel type is not DOC. For a dutiable shipment, `reasonForExport` and `incoterms` are required when you create it.", "externalDocs": { "url": "https://www.parcelparcel.com/api-docs/dutiable-route/" }, "parameters": [ { "name": "countryFrom", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/CountryCode" }, "example": "NL" }, { "name": "countryTo", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/CountryCode" }, "example": "US" }, { "name": "parcelType", "in": "path", "required": true, "description": "Upper or lower case.", "schema": { "type": "string", "enum": [ "DOC", "NONDOC", "PALLET", "doc", "nondoc", "pallet" ] }, "example": "NONDOC" } ], "responses": { "200": { "description": "Whether the shipment is dutiable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DutiableResponse" }, "examples": { "example-response": { "summary": "Example response", "value": { "errors": false, "message": "Query processed successfully", "data": { "dutiable": true } } } } } } }, "422": { "description": "Unknown country code or parcel type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/duties-taxes-estimate": { "post": { "tags": [ "Customs" ], "operationId": "estimateDutiesTaxes", "summary": "Estimate duties/taxes", "description": "Estimates the import duties and taxes per tax type, the total, and the HS code used. The duties and taxes charged by customs may differ.", "externalDocs": { "url": "https://www.parcelparcel.com/api-docs/estimate-duties-taxes/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DutiesRequest" }, "examples": { "estimate-duties-taxes-for-a-parcel-shipment-from-the-netherlands-to-the-united-kingdom": { "summary": "Estimate duties & taxes for a parcel shipment from the Netherlands to the United Kingdom", "value": { "fromCountry": "NL", "toCountry": "GB", "fromCity": "Eindhoven", "fromZipcode": "5643TW", "toCity": "Gillingham", "toZipcode": "ME8 0RU", "contentItems": [ { "description": "Cylinder head for compression-ignition diesel engine", "numberOfItems": 9, "cost": 800, "tariff": "84099900", "originCountry": "NL" } ] } } } } } }, "responses": { "200": { "description": "The estimate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DutiesResponse" }, "examples": { "estimate-duties-taxes-for-a-parcel-shipment-from-the-netherlands-to-the-united-kingdom": { "summary": "Estimate duties & taxes for a parcel shipment from the Netherlands to the United Kingdom", "value": { "hasErrors": false, "taxDetails": [ { "harmonizedCode": "840999001000", "name": "MFN [Most Favored Nation Applied Duty]", "amount": 146.32, "description": "" }, { "harmonizedCode": "840999001000", "name": "VAT [Value Added Tax; ; ]", "amount": 1492.48, "description": "" } ], "estimate": 1638.8, "hsCode": "8409990010" } } } } } }, "400": { "description": "The input is not valid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/hooks/subscribe": { "post": { "tags": [ "Webhooks" ], "operationId": "subscribeWebhook", "summary": "Subscribe to booked shipments", "description": "Registers a URL for the `shipment_booked` event: we POST the shipment (see the `WebhookPayload` schema) once, as soon as a shipment on your account is booked, also when it was booked in MyParcelParcel. No retries. Sandbox shipments don't trigger it.", "externalDocs": { "url": "https://www.parcelparcel.com/api-docs/webhooks/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "hookUrl" ], "properties": { "hookUrl": { "type": "string", "format": "uri" } } }, "examples": { "subscribe-to-booked-shipments": { "summary": "Subscribe to booked shipments", "value": { "hookUrl": "https://example.com/parcelparcel/webhook" } } } } } }, "responses": { "201": { "description": "Subscribed. Keep the id to unsubscribe.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" } } } } } } } } }, "/hooks/{hookId}": { "delete": { "tags": [ "Webhooks" ], "operationId": "unsubscribeWebhook", "summary": "Unsubscribe a webhook", "externalDocs": { "url": "https://www.parcelparcel.com/api-docs/webhooks/" }, "parameters": [ { "name": "hookId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Unsubscribed." }, "404": { "description": "No webhook with this id on your account." } } } }, "/hooks/examples": { "get": { "tags": [ "Webhooks" ], "operationId": "getWebhookExamples", "summary": "Get example webhook payloads", "description": "The payloads of up to 5 of your most recent booked shipments, or a fixed example when you haven't booked anything yet.", "externalDocs": { "url": "https://www.parcelparcel.com/api-docs/webhooks/" }, "responses": { "200": { "description": "Example payloads.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookPayload" } }, "examples": { "example-payload": { "summary": "Example payload", "value": [ { "Shipment ID": 1588448, "Pickup date": { "date": "2026-11-05 12:00:00.000000", "timezone_type": 3, "timezone": "Europe/Amsterdam" }, "Reference": "#123126", "Pick-up Country": "Netherlands", "Destination Country": "United States", "Carrier": "FEDEX", "Product": "FedEx Economy", "Shipping costs (ex. VAT)": 86.41, "Tracking number": "6516516533", "Tracking number url": "https://www.fedex.com/apps/fedextrack/?action=track&trackingnumber=6516516533&cntry_code=nl&locale=nl_NL", "Import/Export": "Export", "Draft Shipment": false, "Incoterms": "DAP", "Dimensions": "84 X 74 X 10 cm + 9.6 kg (1)", "dutiable": "yes", "description": "Awesome Product" } ] } } } } } } } } }, "components": { "securitySchemes": { "ppApiKey": { "type": "apiKey", "in": "header", "name": "X-PP-API", "description": "`{YourAPIKey}@{YourAPISecret}` from MyParcelParcel, Settings > Developers > API keys. Sandbox keys start with `sbx_`." } }, "parameters": { "ShipmentId": { "name": "shipmentId", "in": "path", "required": true, "description": "The `id` you got when you created the shipment.", "schema": { "type": "integer" } } }, "schemas": { "CountryCode": { "type": "string", "pattern": "^[A-Za-z]{2}$", "description": "ISO 3166-1 alpha-2 country code, for example NL or US.", "examples": [ "NL" ] }, "ShipmentStatus": { "type": "string", "enum": [ "waiting_for_booking", "progress", "created_at_carrier", "done", "cancelled" ] }, "TrackingStatus": { "type": "string", "enum": [ "info_received", "in_transit", "exception", "delivered" ] }, "Error": { "type": "object", "properties": { "errors": {}, "message": { "type": "string" } } }, "MeResponse": { "type": "object", "properties": { "errors": { "type": "boolean", "const": false }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "username": { "type": "string", "description": "Email address of the ParcelParcel account." } } } } }, "Parcel": { "type": "object", "required": [ "type", "count" ], "description": "Weight and dimensions are required for NONDOC and PALLET. You can't combine types in one shipment.", "properties": { "type": { "type": "string", "enum": [ "NONDOC", "DOC", "PALLET" ], "description": "NONDOC = parcel, DOC = documents, PALLET = pallet." }, "weight": { "type": [ "string", "number" ], "description": "Kilograms, 1 decimal, for example \"15.2\"." }, "length": { "type": [ "string", "integer" ], "description": "Centimetres." }, "width": { "type": [ "string", "integer" ], "description": "Centimetres." }, "height": { "type": [ "string", "integer" ], "description": "Centimetres." }, "count": { "type": [ "string", "integer" ], "description": "Number of identical parcels." }, "stackable": { "type": "boolean", "description": "Only for PALLET." } } }, "RatesRequest": { "type": "object", "required": [ "parcels", "fromCountry", "toCountry" ], "properties": { "parcels": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/Parcel" } }, "fromCountry": { "$ref": "#/components/schemas/CountryCode" }, "fromZipcode": { "type": "string", "description": "Without zipcode or city we use the capital." }, "fromCity": { "type": "string" }, "toCountry": { "$ref": "#/components/schemas/CountryCode" }, "toZipcode": { "type": "string" }, "toCity": { "type": "string" }, "insured": { "type": "boolean", "description": "If true, `totalValue` is required." }, "totalValue": { "type": "number", "description": "Total value in EUR, used for the insurance costs." }, "recipientType": { "type": "string", "enum": [ "individual", "business" ], "description": "Required for PALLET." } } }, "PriceBreakdownItem": { "type": "object", "properties": { "item": { "type": "string", "description": "The product, a surcharge, Insurance or Discount." }, "amount": { "type": "number" }, "reason": { "type": "string", "description": "For surcharges: why it applies." } } }, "ShippingOption": { "type": "object", "properties": { "carrier": { "type": "string" }, "product": { "type": "string" }, "productId": { "type": "integer", "description": "Use as `preferredShippingOption` when you create the shipment." }, "price": { "type": "number", "description": "EUR excluding VAT, 2 decimals. Includes insurance if `insured` was true. Some surcharges depend on the exact address." }, "minEstimatedTransitTimeInWorkingsDays": { "type": "integer" }, "maxEstimatedTransitTimeInWorkingsDays": { "type": "integer" }, "priceBreakdown": { "type": "array", "items": { "$ref": "#/components/schemas/PriceBreakdownItem" } } } }, "RatesResponse": { "type": "object", "properties": { "errors": { "type": "boolean", "const": false }, "message": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ShippingOption" }, "description": "Cheapest first." } } }, "ContentItem": { "type": "object", "required": [ "description", "quantity", "price", "country" ], "properties": { "description": { "type": "string", "description": "Describe the item well, for example \"100% cotton white T-shirt male\"." }, "quantity": { "type": [ "string", "integer" ] }, "price": { "type": [ "string", "number" ], "description": "Price per item, 2 decimals." }, "country": { "$ref": "#/components/schemas/CountryCode", "description": "Country where the item is made." }, "hsCode": { "type": "string" } } }, "Address": { "type": "object", "required": [ "countryCode", "contactPerson", "email", "phone", "addressLine1", "zipcode", "city" ], "properties": { "countryCode": { "$ref": "#/components/schemas/CountryCode" }, "companyName": { "type": "string" }, "contactPerson": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "addressLine1": { "type": "string", "description": "addressLine1 and addressLine2 are joined and split again at the carrier's maximum length." }, "addressLine2": { "type": "string" }, "zipcode": { "type": "string" }, "city": { "type": "string" }, "vatNumber": { "type": "string", "description": "Required for shipments to a company in the US and/or above EUR 2300." }, "sendNotification": { "type": "boolean", "default": false, "description": "Only on destinationAddress: email the recipient with the tracking link once the shipment is in transit." } } }, "CreateShipmentRequest": { "type": "object", "required": [ "currency", "contentItems", "pickupAddress", "destinationAddress" ], "properties": { "reference": { "type": "string" }, "currency": { "type": "string", "enum": [ "EUR", "USD" ] }, "insured": { "type": [ "boolean", "integer" ], "default": false, "description": "Insure the shipment. true/false (1/0 also works)." }, "preferredShippingOption": { "type": "integer", "description": "A `productId` from /rates. Without it we pick the cheapest option." }, "schedulePickup": { "type": [ "boolean", "integer" ], "default": false, "description": "Let the carrier pick up the shipment. The pickup fields are only used when this is true. true/false (1/0 also works)." }, "pickupDate": { "type": "string", "format": "date", "description": "YYYY-MM-DD. Default: today." }, "pickupTimeFrom": { "type": "string", "description": "For example \"12:00\". Default \"12:00\"." }, "pickupTimeTo": { "type": "string", "description": "For example \"16:00\". Default \"17:30\"." }, "pickupInstructions": { "type": "string" }, "reasonForExport": { "type": "string", "enum": [ "commercial", "replacement", "sample", "gift", "repair", "return", "personal_use", "personal_effect", "intercompany", "exhibition" ], "description": "Required for a dutiable shipment (see /dutiable-route)." }, "incoterms": { "type": "string", "enum": [ "DAP", "DDP" ], "description": "Required for a dutiable shipment." }, "parcels": { "type": "array", "items": { "$ref": "#/components/schemas/Parcel" } }, "contentItems": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ContentItem" } }, "pickupAddress": { "$ref": "#/components/schemas/Address" }, "destinationAddress": { "$ref": "#/components/schemas/Address" }, "bookShipment": { "type": "boolean", "default": false, "description": "true books the shipment at the carrier (with a sandbox key: never sent to the carrier)." }, "inlineLabel": { "type": "boolean", "default": true, "description": "Only with bookShipment: return the labels as base64 in the response." } } }, "CreateShipmentResponse": { "type": "object", "properties": { "errors": { "description": "false or [] on success; may contain a warning such as 'Preferred shipping option was not available, cheapest option selected.'" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The shipment id, also used in the webhook payload." }, "status": { "$ref": "#/components/schemas/ShipmentStatus" }, "carrier": { "type": "string" }, "product": { "type": "string" }, "productId": { "type": [ "integer", "null" ] }, "price": { "type": "number" }, "trackingNumber": { "type": "string" }, "trackingUrl": { "type": [ "string", "null" ] }, "labels": { "type": "string", "description": "base64 with inlineLabel, otherwise the labels path." }, "sandbox": { "type": "boolean", "description": "Only present for sandbox bookings." } } } } }, "CancelResponse": { "type": "object", "properties": { "cancelled": { "type": "boolean" }, "message": { "type": "string" } } }, "LabelsResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "labels": { "type": "string", "contentEncoding": "base64", "contentMediaType": "application/pdf" } } } } }, "ShipmentAddress": { "type": "object", "properties": { "company": { "type": [ "string", "null" ] }, "contactPerson": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "addressLine1": { "type": [ "string", "null" ] }, "addressLine2": { "type": [ "string", "null" ] }, "zipcode": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "stateOrProvince": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "vatNumber": { "type": [ "string", "null" ] }, "eoriNumber": { "type": [ "string", "null" ] } } }, "ShipmentSummary": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "$ref": "#/components/schemas/ShipmentStatus" }, "trackingNumber": { "type": [ "string", "null" ] }, "trackingUrl": { "type": [ "string", "null" ] }, "labelsUrl": { "type": [ "string", "null" ], "description": "Needs the same X-PP-API header." }, "trackingStatus": { "oneOf": [ { "$ref": "#/components/schemas/TrackingStatus" }, { "type": "null" } ] }, "reference": { "type": [ "string", "null" ] }, "carrier": { "type": [ "string", "null" ] }, "product": { "type": [ "string", "null" ] }, "price": { "type": "number", "description": "EUR excluding VAT." }, "pickupAddress": { "$ref": "#/components/schemas/ShipmentAddress" }, "destinationAddress": { "$ref": "#/components/schemas/ShipmentAddress" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "bookedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "ShipmentListResponse": { "type": "object", "properties": { "errors": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ShipmentSummary" } }, "meta": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "perPage": { "type": "integer" } } } } }, "TrackingResponse": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/TrackingStatus" }, "pod": { "type": "boolean", "description": "Whether a signed proof of delivery is available." }, "checkpoints": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time" }, "code": { "type": "string", "description": "Code from the carrier." }, "message": { "type": "string" }, "description": { "type": "string" }, "location": { "type": "string" }, "signedBy": { "type": "string" } } } } } }, "DutiableResponse": { "type": "object", "properties": { "errors": { "type": "boolean", "const": false }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "dutiable": { "type": "boolean" } } } } }, "DutiesContentItem": { "type": "object", "required": [ "description", "numberOfItems", "cost" ], "properties": { "description": { "type": "string" }, "numberOfItems": { "type": "integer" }, "cost": { "type": "number", "description": "Value per item in EUR." }, "tariff": { "type": "string", "description": "HS code. Without it we pick one from the description." }, "originCountry": { "$ref": "#/components/schemas/CountryCode" } } }, "DutiesRequest": { "type": "object", "required": [ "contentItems", "fromCountry", "toCountry" ], "properties": { "contentItems": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/DutiesContentItem" } }, "fromCountry": { "$ref": "#/components/schemas/CountryCode" }, "fromZipcode": { "type": "string" }, "fromCity": { "type": "string" }, "toCountry": { "$ref": "#/components/schemas/CountryCode" }, "toZipcode": { "type": "string" }, "toCity": { "type": "string" } } }, "DutiesResponse": { "type": "object", "properties": { "hasErrors": { "type": "boolean" }, "taxDetails": { "type": "array", "items": { "type": "object", "properties": { "harmonizedCode": { "type": "string" }, "name": { "type": "string" }, "amount": { "type": "number" }, "description": { "type": "string" } } } }, "estimate": { "type": "number", "description": "Total in EUR, the sum of taxDetails." }, "hsCode": { "type": "string" } } }, "WebhookPayload": { "type": "object", "description": "POSTed as JSON to your hookUrl for the shipment_booked event.", "properties": { "Shipment ID": { "type": "integer" }, "Pickup date": { "description": "Object with date, timezone_type and timezone, or the string \"No pickup\"." }, "Reference": { "type": [ "string", "null" ] }, "Pick-up Country": { "type": "string" }, "Destination Country": { "type": "string" }, "Carrier": { "type": "string", "description": "Carrier ID, for example FEDEX." }, "Product": { "type": "string" }, "Shipping costs (ex. VAT)": { "type": "number" }, "Tracking number": { "type": "string" }, "Tracking number url": { "type": "string" }, "Import/Export": { "type": "string", "enum": [ "Import", "Export" ] }, "Draft Shipment": { "type": "boolean" }, "Incoterms": { "type": "string" }, "Dimensions": { "type": "string", "description": "One line per parcel: \"L X W X H cm + kg (count)\"." }, "dutiable": { "type": "string", "enum": [ "yes", "no" ] }, "description": { "type": "string" } } } } } }