{ "openapi": "3.0.3", "info": { "title": "Parcelly API", "version": "1.0.0", "description": "Create, track and cancel parcel shipments with a single REST API. Parcelly picks the carrier, prints the label and keeps you up to date until the parcel arrives." }, "servers": [ { "url": "https://api.parcelly.dev/v1" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Shipments", "description": "Create, retrieve, list and cancel shipments." }, { "name": "Carriers", "description": "Carriers Parcelly can ship with." } ], "paths": { "/shipments": { "post": { "operationId": "createShipment", "tags": [ "Shipments" ], "summary": "Create a shipment", "description": "Books a shipment and creates its label. Parcelly chooses the carrier based on the destination, weight and service level.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentCreate" } } } }, "responses": { "201": { "description": "The shipment was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" } } } } } }, "get": { "operationId": "listShipments", "tags": [ "Shipments" ], "summary": "List shipments", "description": "Returns your shipments, most recently created first, optionally filtered by status.", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Only return shipments with this status.", "schema": { "type": "string", "enum": [ "label_created", "in_transit", "out_for_delivery", "delivered", "cancelled" ] }, "example": "in_transit" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of shipments to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "example": 20 } ], "responses": { "200": { "description": "A page of shipments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentList" } } } } } } }, "/shipments/{shipment_id}": { "get": { "operationId": "getShipment", "tags": [ "Shipments" ], "summary": "Get a shipment", "description": "Retrieves a single shipment by its ID.", "parameters": [ { "name": "shipment_id", "in": "path", "required": true, "description": "Unique identifier of the shipment.", "schema": { "type": "string" }, "example": "shp_7Hk2mQ9x" } ], "responses": { "200": { "description": "The requested shipment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" } } } }, "404": { "description": "No shipment exists with this ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/shipments/{shipment_id}/cancel": { "post": { "operationId": "cancelShipment", "tags": [ "Shipments" ], "summary": "Cancel a shipment", "description": "Cancels a shipment that the carrier has not yet collected.", "parameters": [ { "name": "shipment_id", "in": "path", "required": true, "description": "Unique identifier of the shipment.", "schema": { "type": "string" }, "example": "shp_7Hk2mQ9x" } ], "responses": { "200": { "description": "The shipment was cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shipment" } } } }, "409": { "description": "The shipment can no longer be cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/carriers": { "get": { "operationId": "listCarriers", "tags": [ "Carriers" ], "summary": "List carriers", "description": "Returns the carriers Parcelly currently supports.", "responses": { "200": { "description": "The supported carriers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CarrierList" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Send your secret API key as `Authorization: Bearer `." } }, "schemas": { "Address": { "type": "object", "description": "A postal address.", "required": [ "name", "line1", "city", "postal_code", "country" ], "properties": { "name": { "type": "string", "description": "Recipient's full name.", "example": "Sam Sample" }, "line1": { "type": "string", "description": "First line of the street address.", "example": "12 Example Street" }, "line2": { "type": "string", "description": "Second line of the street address.", "example": "Unit 4" }, "city": { "type": "string", "description": "City or town.", "example": "Springfield" }, "postal_code": { "type": "string", "description": "Postal or ZIP code.", "example": "62704" }, "country": { "type": "string", "description": "Two-letter ISO 3166-1 alpha-2 country code.", "example": "US" } } }, "ShipmentCreate": { "type": "object", "description": "The details needed to create a shipment.", "required": [ "to_address", "weight_grams", "service" ], "properties": { "to_address": { "type": "object", "description": "Where the parcel is going.", "allOf": [ { "$ref": "#/components/schemas/Address" } ] }, "weight_grams": { "type": "integer", "description": "Parcel weight in grams.", "example": 1200 }, "service": { "type": "string", "enum": [ "standard", "express", "overnight" ], "description": "Delivery service level.", "example": "express" } } }, "Shipment": { "type": "object", "description": "A parcel shipment.", "required": [ "id", "status", "tracking_number", "carrier", "price", "created_at" ], "properties": { "id": { "type": "string", "description": "Unique identifier of the shipment.", "example": "shp_7Hk2mQ9x" }, "status": { "type": "string", "enum": [ "label_created", "in_transit", "out_for_delivery", "delivered", "cancelled" ], "description": "Current state of the shipment.", "example": "in_transit" }, "tracking_number": { "type": "string", "description": "Carrier tracking number.", "example": "PCL1234567890" }, "carrier": { "type": "string", "description": "ID of the carrier handling the shipment.", "example": "swiftpost" }, "price": { "type": "number", "description": "Shipping price in USD.", "example": 12.5 }, "created_at": { "type": "string", "format": "date-time", "description": "When the shipment was created.", "example": "2026-01-20T09:30:00Z" }, "estimated_delivery": { "type": "string", "format": "date", "description": "Estimated delivery date, once known.", "example": "2026-01-23" } } }, "ShipmentList": { "type": "object", "description": "A page of shipments.", "required": [ "data", "has_more" ], "properties": { "data": { "type": "array", "description": "The shipments on this page.", "items": { "$ref": "#/components/schemas/Shipment" } }, "has_more": { "type": "boolean", "description": "Whether more shipments exist beyond this page.", "example": false } } }, "Carrier": { "type": "object", "description": "A carrier Parcelly can ship with.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "Unique identifier of the carrier.", "example": "swiftpost" }, "name": { "type": "string", "description": "Display name of the carrier.", "example": "SwiftPost" } } }, "CarrierList": { "type": "object", "description": "The list of supported carriers.", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "The supported carriers.", "items": { "$ref": "#/components/schemas/Carrier" } } } }, "Error": { "type": "object", "description": "An API error.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code.", "example": "shipment_not_found" }, "message": { "type": "string", "description": "Human-readable explanation of the error.", "example": "No shipment exists with this ID." } } } } } }