Skip to main content

API Reference

The Pack3D REST API is a programmatic gateway to our global 4PL network. Designed for logistical integrity, this interface allows you to orchestrate physical assets with digital precision.

API_STATUS
OPERATIONAL
All nodes reporting 99.98% uptime
BASE_URL
api.pack3d.io/v1
Stable Production Build
PILLAR_01 // DATA_INTEGRITY

Registry

Registry logic begins with the standardisation of physical dimensions and node eligibility. To define your assets and establish systemic routing constraints, interface with the Catalog API.

PILLAR_02 // LOGIC_ENGINE

Orchestration

Orchestration transforms static data into active movement. Use the Order and Inbound collections to trigger fulfillment logic, manage stock ingestion, and automate multi-node routing.

PILLAR_03 // SYSTEM_VISIBILITY

Telemetry

Telemetry bridges the gap between physical execution and digital visibility. Subscribe to the Webhook stream and query the Shipment endpoints for high-fidelity final-mile instrumentation.

EXTENDED_CAPABILITIES // REVERSE_LOG

Reverse Logistics

Automating the reverse loop as a critical system state through logic-driven asset disposition.

EXTENDED_CAPABILITIES // COMPLIANCE

Compliance

A programmatic bridge that transforms digital instructions into carrier-compliant physical assets and customs paperwork.

EXTENDED_CAPABILITIES // LISTS

Asset Grouping (Lists)

A transactional staging area for SKUs. Lists allow teams to aggregate demand or supply over time, providing a "waiting room" for data before it is committed to live logistics.

SECURITY_PROTOCOL // AUTH_v1

Technical Security & Integrity

All requests to the Pack3D Control Tower must be authenticated. We support OAuth 2.0 with PKCE for public clients (web/mobile) and Client Credentials for secure server-to-server integrations. This dual-protocol approach ensures that system logic is never compromised, regardless of the integration environment.

PROTOCOL: REST_HTTPS // AUTH: OAUTH_2.0_PKCE // FORMAT: JSON

While this documentation is publicly accessible to maintain architectural transparency, access to production data is restricted to authorised credentials and encrypted via TLS 1.3.

COLLECTION // CATALOG

Define Network Constraints

Global mapping of SKU-to-Node compatibility and routing rules.

GET /v1/catalog

List

Retrieve the registry of node eligibility and routing constraints.

ParameterTypeDescription
node_idOptional string

Filter by a specific distribution node.

skuOptional string

Filter by a specific item identifier.

sortOptional string

Sort by priority_score or last_sync.

pageOptional integer

Pagination index for large registries.

limitOptional integer

Results per page (Max: 100).

SAMPLE_REQUEST //
?node_id=NYC-01&limit=20&page=1

Query-based request. No payload body required.

SAMPLE_RESPONSE //
HTTP_200
{
    "data": [
        {
            "id": "CAT-1",
            "sku": "P3D-99",
            "node": "NYC-01",
            "eligible": true
        }
    ]
}
HTTP_400
{
    "error": "INVALID_FILTER",
    "message": "The provided node_id is not registered."
}
POST /v1/catalog

Create

Authorize a SKU for fulfillment at a specific distribution node.

ParameterTypeDescription
skuRequired string

Unique SKU identifier to be authorized.

node_idRequired string

The target warehouse node ID.

eligibility_statusRequired boolean

Enable/disable immediate fulfillment eligibility.

priority_scoreOptional integer

Routing weight (1-10). Defaults to 5.

buffer_stock_levelOptional integer

Safety stock threshold for this node.

SAMPLE_REQUEST //
POST /v1/catalog
{
    "sku": "P3D-99-BLK",
    "node_id": "NYC-01",
    "eligibility_status": true,
    "priority_score": 10,
    "buffer_stock_level": 25
}
SAMPLE_RESPONSE //
HTTP_201
{
    "id": "CAT-P3D99BLK-NYC01",
    "status": "authorized",
    "sku": "P3D-99-BLK",
    "node_id": "NYC-01",
    "eligibility_status": true,
    "created_at": "2026-01-07T11:15:00Z"
}
HTTP_409
{
    "error": "DUPLICATE_ASSOCIATION",
    "message": "This SKU is already authorized for NYC-01. Use PUT to modify existing constraints.",
    "existing_id": "CAT-P3D99BLK-NYC01"
}
PUT /v1/catalog/{id}

Update

Modify specific routing permissions for a node association.

ParameterTypeDescription
eligibility_statusRequired boolean

Enable/disable fulfillment for this path.

priority_scoreOptional integer

Routing weight (1-10).

status_noteOptional string

Audit comment for the change.

SAMPLE_REQUEST //
PUT /v1/catalog/{id}
{
    "eligibility_status": true,
    "priority_score": 8,
    "status_note": "Priority increased for Q1 fulfillment"
}
SAMPLE_RESPONSE //
HTTP_200
{
    "id": "CAT-1",
    "updated": true,
    "new_priority": 8
}
HTTP_422
{
    "error": "VALIDATION_FAILED",
    "message": "Priority score must be between 1 and 10."
}
GET /v1/catalog/search

Catalog search

Real-time search for SKUs eligible for fulfillment at a specific node.

ParameterTypeDescription
qRequired string

Search query (name, SKU, or category).

node_idRequired string

Filter results to a specific warehouse.

limitOptional integer

Results per page. Defaults to 10.

in_stockOptional boolean

Only show items with available inventory.

SAMPLE_REQUEST //
?q=protective+case&node_id=NYC-01&limit=5&in_stock=1

Query-based request. No payload body required.

SAMPLE_RESPONSE //
HTTP_200
{
    "results": [
        {
            "sku": "P3D-ACC-05",
            "name": "Rugged Protective Case",
            "price": 25,
            "currency": "USD",
            "image_url": "https:\/\/cdn.p3d.io\/assets\/acc-05.jpg",
            "inventory_status": "instock"
        }
    ],
    "metadata": {
        "total_found": 1,
        "warehouse": "NYC-01"
    }
}
HTTP_404
{
    "error": "SKU_NOT_REGISTERED",
    "message": "The provided SKU identifier does not exist within the Pack3D Registry.",
    "sku": "UNKNOWN-ID-999"
}
COLLECTION // PRODUCTS

Sync Master Data

Management of physical asset attributes and volumetric signatures.

POST /v1/products

Upsert

Create or update physical dimensions.

ParameterTypeDescription
skuRequired string

Unique SKU identifier.

length_mmRequired integer

Length in millimeters.

width_mmRequired integer

Width in millimeters.

height_mmRequired integer

Height in millimeters.

weight_gRequired integer

Total mass in grams.

image_urlOptional string

URL for item visual reference.

SAMPLE_REQUEST //
POST /v1/products
{
    "sku": "P3D-99",
    "length_mm": 300,
    "width_mm": 200,
    "height_mm": 150,
    "weight_g": 1200,
    "hs_code": "4202.12.00"
}
SAMPLE_RESPONSE //
HTTP_201
{
    "sku": "P3D-99",
    "status": "synchronized"
}
HTTP_400
{
    "error": "MALFORMED_DATA",
    "message": "Weight must be a positive integer in grams."
}
POST /v1/products/batch

Batch

Asynchronous bulk ingestion for high-volume SKU registration.

ParameterTypeDescription
dataRequired array

Array of product objects.

batch_idOptional string

Client-side reference ID.

SAMPLE_REQUEST //
POST /v1/products/batch
{
    "batch_id": "BCH-2026-Q1-INIT",
    "data": [
        {
            "sku": "P3D-99-BLK",
            "length_mm": 300,
            "weight_g": 1200
        },
        {
            "sku": "P3D-99-WHT",
            "length_mm": 300,
            "weight_g": 1200
        }
    ]
}
SAMPLE_RESPONSE //
HTTP_202
{
    "job_id": "JOB-66721-P3D",
    "status": "queued",
    "estimated_completion_ms": 4500,
    "links": {
        "check_status": "\/v1\/products\/batch\/JOB-66721-P3D"
    }
}
HTTP_413
{
    "error": "PAYLOAD_TOO_LARGE",
    "message": "Batch size exceeds the 500-item limit."
}
GET /v1/products/batch/{job_id}

Status

Check the processing status and error log of a specific batch.

ParameterTypeDescription
job_idRequired string

The system-generated ID returned during upload.

SAMPLE_REQUEST //
?job_id=JOB-66721-P3D&include_details=1

Query-based request. No payload body required.

SAMPLE_RESPONSE //
HTTP_200
{
    "job_id": "JOB-66721-P3D",
    "status": "completed",
    "metrics": {
        "total_records": 2,
        "successful": 2,
        "failed": 0
    },
    "completed_at": "2026-01-06T18:40:00Z"
}
HTTP_404
{
    "error": "JOB_NOT_FOUND",
    "message": "The requested Job ID does not exist or has expired from the log."
}
PATCH /v1/products/{sku}/metadata

Update metadata

Append or update multiple tags and attributes for a specific SKU.

ParameterTypeDescription
skuRequired string

The SKU identifier.

tagsRequired object

Key-value pairs (e.g., {"season": "winter"}).

modeOptional string

Values: "merge" or "replace".

SAMPLE_REQUEST //
PATCH /v1/products/{sku}/metadata
{
    "mode": "merge",
    "tags": {
        "client_tier": "enterprise_gold",
        "storage_notes": "keep_away_from_heat",
        "seasonal_tag": "winter_2026",
        "fragile": "true"
    }
}
SAMPLE_RESPONSE //
HTTP_200
{
    "sku": "P3D-99-BLK",
    "status": "success",
    "last_modified": "2026-01-08T01:25:00Z",
    "metadata": {
        "client_tier": "enterprise_gold",
        "storage_notes": "keep_away_from_heat",
        "seasonal_tag": "winter_2026",
        "fragile": "true",
        "created_at": "2025-11-15T09:00:00Z",
        "origin_id": "OMS-SYST-01"
    }
}
HTTP_422
{
    "error": "INVALID_METADATA_FORMAT",
    "message": "The tags parameter must be a flat key-value object of strings.",
    "tip": "Check for nested arrays or non-string values in your tags object."
}
GET /v1/products

Get List

List products with multi-tag filtering or specific SKU batch retrieval.

ParameterTypeDescription
skuOptional string

Comma-separated SKUs for batch lookup (e.g., SKU1,SKU2).

tagOptional string

Filter by associated metadata tags.

limitOptional integer

Results per page.

pageOptional integer

Pagination offset.

SAMPLE_REQUEST //
?sku=P3D-99-BLK%2CP3D-CORE-01%2CP3D-ACC-05&limit=3

Query-based request. No payload body required.

SAMPLE_RESPONSE //
HTTP_200
{
    "count": 3,
    "products": [
        {
            "sku": "P3D-99-BLK",
            "name": "Premium Glassware Kit",
            "weight": {
                "value": 450,
                "unit": "g"
            },
            "tags": [
                "fragile",
                "glass"
            ]
        },
        {
            "sku": "P3D-CORE-01",
            "name": "Industrial Base Plate",
            "weight": {
                "value": 1200,
                "unit": "g"
            },
            "tags": [
                "heavy",
                "core"
            ]
        },
        {
            "sku": "P3D-ACC-05",
            "name": "Rugged Protective Case",
            "weight": {
                "value": 200,
                "unit": "g"
            },
            "tags": [
                "accessory"
            ]
        }
    ],
    "metadata": {
        "batch_mode": true,
        "total_weight_requested_g": 1850
    }
}
COLLECTION // NODES

Audit Distribution Points

Registry and performance monitoring of physical nodes.

GET /v1/nodes

List

Fetch status and service capabilities of all nodes.

ParameterTypeDescription
statusOptional string

Filter by: active, maintenance, offline.

regionOptional string

Geographic filter (e.g., UK-SOUTH).

SAMPLE_REQUEST //
?status=active®ion=UK-SOUTH

Query-based request. No payload body required.

SAMPLE_RESPONSE //
HTTP_200
{
    "nodes": [
        {
            "node_code": "p3d-shoreham-hq",
            "name": "Pack3D Primary Distribution Centre",
            "status": "active",
            "region": "UK-SOUTH"
        }
    ]
}
HTTP_503
{
    "error": "SERVICE_UNAVAILABLE",
    "message": "The requested feature or service is currently unavailable. Please check back later."
}
GET /v1/nodes/{node_code}/status

Status

Operational health and real-time status telemetry.

SAMPLE_REQUEST //

Query-based request. No payload body required.

SAMPLE_RESPONSE //
HTTP_200
{
    "node_code": "p3d-shoreham-hq",
    "status": "HEALTHY",
    "operational": true,
    "verified": true
}
HTTP_404
{
    "error": "ENDPOINT_NOT_FOUND",
    "message": "The requested fulfillment node code is invalid or could not be located."
}
GET /v1/nodes/{node_code}/products

Products

Fetch sorted and filtered product catalogue for a specific node.

ParameterTypeDescription
searchOptional string

Search query matching product name or SKU.

sortOptional string

Sort priority: name_asc, price_asc, price_desc, stock_desc.

tagsOptional string

Filter products by comma-separated tags (e.g., fragile, heavy, eco-friendly).

in_stockOptional boolean

Filter to show in-stock items only.

pageOptional integer

Pagination page index (default: 1).

limitOptional integer

Total inventory items per page limit (default: 24).

SAMPLE_REQUEST //
?search=tape&sort=price_asc&tags=fragile%2Cheavy&in_stock=1&page=1&limit=24

Query-based request. No payload body required.

SAMPLE_RESPONSE //
HTTP_200
{
    "is_valid": true,
    "data": [
        {
            "id": 412,
            "sku": "P3D-TAPE-HD01",
            "name": "Heavy Duty Packing Tape - 50mm",
            "price": 3.49,
            "stock_count": 840,
            "tags": [
                "packaging",
                "adhesive",
                "heavy"
            ]
        }
    ],
    "meta": {
        "fulfillment_node": "p3d-shoreham-hq",
        "current_page": 1,
        "results_per_page": 24
    }
}
HTTP_503
{
    "error": "SERVICE_UNAVAILABLE",
    "message": "The requested feature or service is currently unavailable. Please check back later."
}
COLLECTION // ORDERS

Execute Fulfillment

Triggering the routing logic for outbound demand.

POST /v1/orders

Create

Submit a fulfillment instruction.

ParameterTypeDescription
external_idRequired string

ERP/OMS reference ID.

itemsRequired array

List of SKU/Quantity objects.

recipient_addressRequired object

Validated destination object.

service_levelRequired string

Fulfillment tier.

hold_untilOptional string

ISO-8601 date to delay shipping.

SAMPLE_REQUEST //
POST /v1/orders
{
    "external_id": "PLATFORM_ORD_7728",
    "items": [
        {
            "sku": "P3D-99",
            "qty": 2
        },
        {
            "sku": "P3D-42",
            "qty": 1
        }
    ],
    "recipient_address": {
        "name": "Jane Doe",
        "street": "123 Tech Lane",
        "city": "Brooklyn",
        "region": "NY",
        "postal_code": "11201",
        "country": "US"
    },
    "service_level": "express"
}
SAMPLE_RESPONSE //
HTTP_201
{
    "order_id": "ORD-101",
    "status": "queued_for_routing"
}
HTTP_422
{
    "error": "OUT_OF_STOCK",
    "message": "The requested SKU is unavailable at all authorized nodes."
}
POST /v1/orders/quote

Preview

Predict costs and routing before execution.

ParameterTypeDescription
itemsRequired array

Draft list of SKUs/Quantities.

destination_postal_codeRequired string

Target zip for zone calculation.

carrier_preferenceOptional string

Force specific carrier logic.

SAMPLE_REQUEST //
POST /v1/orders/quote
{
    "items": [
        {
            "sku": "P3D-99",
            "qty": 1
        }
    ],
    "destination_postal_code": "11201"
}
SAMPLE_RESPONSE //
HTTP_200
{
    "estimated_shipping": 12.5,
    "suggested_node": "LON-04"
}
HTTP_400
{
    "error": "INVALID_POSTAL_CODE",
    "message": "Format for destination_postal_code is invalid."
}
POST /v1/orders/{id}/items

Append item

Add items to an existing order before it enters the fulfillment queue.

ParameterTypeDescription
idRequired string

The Order ID to modify.

skuRequired string

The SKU to add.

qtyRequired integer

Quantity to add.

SAMPLE_REQUEST //
POST /v1/orders/{id}/items
{
    "sku": "P3D-ACC-05",
    "qty": 1
}
SAMPLE_RESPONSE //
HTTP_200
{
    "order_id": "P3D-ORD-7790",
    "status": "updated",
    "new_total_weight_g": 1450,
    "shipping_tier": "Standard (Unchanged)",
    "message": "SKU added successfully. Packing instructions updated."
}
HTTP_409
{
    "error": "ORDER_LOCKED",
    "message": "This order is already being picked and can no longer be modified."
}
POST /v1/orders/{id}/settle

Settle delta

Acknowledge payment of a financial delta to release an order from financial hold.

ParameterTypeDescription
idRequired string

The Order ID to settle.

transaction_refRequired string

External payment gateway reference (e.g., Stripe ID).

amount_settledRequired decimal

The currency amount paid.

currencyRequired string

ISO-4217 currency code.

SAMPLE_REQUEST //
POST /v1/orders/{id}/settle
{
    "transaction_ref": "ch_3N4k2L2eZvKYlo2C1",
    "amount_settled": 4.5,
    "currency": "USD"
}
SAMPLE_RESPONSE //
HTTP_200
{
    "order_id": "P3D-ORD-7790",
    "previous_status": "financial_hold",
    "current_status": "ready_for_picking",
    "transaction_verified": true,
    "message": "Payment delta reconciled. Order has been pushed to the fulfillment queue."
}
HTTP_400
{
    "error": "SETTLEMENT_MISMATCH",
    "message": "Amount settled ($4.50) does not cover the required delta ($6.00).",
    "remaining_balance": 1.5
}
COLLECTION // INBOUND

Initialize Replenishment

Managing the ingestion of inventory into the network.

POST /v1/inbound

Create

Register an Advanced Shipping Notice (ASN).

ParameterTypeDescription
node_idRequired string

The target node receiving the stock.

line_itemsRequired array

Quantities and SKUs expected.

expected_dateOptional string

ISO-8601 date for expected arrival.

po_numberOptional string

Associated Purchase Order number.

SAMPLE_REQUEST //
POST /v1/inbound
{
    "node_id": "NYC-01",
    "expected_date": "2026-01-15T09:00:00Z",
    "carrier": "FedEx Freight",
    "line_items": [
        {
            "sku": "P3D-99",
            "qty": 500
        }
    ]
}
SAMPLE_RESPONSE //
HTTP_201
{
    "asn_id": "ASN-552",
    "status": "expected"
}
HTTP_400
{
    "error": "NODE_CAPACITY_FULL",
    "message": "The target node cannot accept new inbound shipments at this time."
}
COLLECTION // INVENTORY

Query Stock Levels

Real-time snapshot and health of available stock.

GET /v1/inventory

Snapshot

Global availability across the network.

ParameterTypeDescription
skuOptional string

Specific SKU filter.

node_idOptional string

Specific warehouse node filter.

include_pendingOptional boolean

Include stock in receiving status.

SAMPLE_REQUEST //
?sku=P3D-99&include_pending=1

Query-based request. No payload body required.

SAMPLE_RESPONSE //
HTTP_200
{
    "sku": "P3D-99",
    "on_hand": 450,
    "available": 420
}
HTTP_404
{
    "error": "SKU_NOT_FOUND",
    "message": "No inventory records found for this SKU."
}
GET /v1/inventory/analytics

Health

Predictive analysis: stock-out risks and turnover velocity.

ParameterTypeDescription
skuRequired string

The SKU for which to calculate velocity.

node_idOptional string

Localized health for a specific node.

SAMPLE_REQUEST //
?sku=P3D-99&node_id=NYC-01

Query-based request. No payload body required.

SAMPLE_RESPONSE //
HTTP_200
{
    "turnover_rate": 4.2,
    "stockout_risk": "low"
}
HTTP_422
{
    "error": "INSUFFICIENT_DATA",
    "message": "Not enough history to calculate turnover velocity."
}
COLLECTION // TRACKING

Track Movement

Unified telemetry for the complete transit chain, integrating pre-shipment warehouse orchestration with real-time carrier instrumentation.

GET /v1/tracking/{reference}

Get

End-to-end visibility from warehouse floor to final delivery.

ParameterTypeDescription
typeOptional string

Force lookup by: "internal" or "carrier".

expand_eventsOptional boolean

Include fulfillment milestones.

SAMPLE_REQUEST //
?reference=P3D778299&type=carrier&expand_events=1&lang=en

Query-based request. No payload body required.

SAMPLE_RESPONSE //
HTTP_200
{
    "tracking_id": "P3D778299",
    "status": "in_transit",
    "carrier": {
        "name": "DHL Express",
        "service": "Next Day"
    },
    "estimated_eta": "2026-05-14T18:00:00Z",
    "current_node": "LHR-SORT-01",
    "milestones": [
        {
            "time": "2026-05-12T10:00:00Z",
            "event": "out_for_delivery",
            "location": "Brighton Hub"
        },
        {
            "time": "2026-05-11T22:00:00Z",
            "event": "arrived_at_facility",
            "location": "London Gateway"
        },
        {
            "time": "2026-05-11T16:45:00Z",
            "event": "dispatched_from_node",
            "location": "NYC-01"
        }
    ]
}
HTTP_404
{
    "error": "TRACKING_NOT_FOUND",
    "message": "The provided carrier reference has not been scanned into the network yet."
}
GET /v1/tracking/{reference}

Internal lookup

High-fidelity fulfillment tracking using internal Order IDs. Required for pre-shipment status and node-context discovery.

ParameterTypeDescription
typeRequired string

Force resolution via internal Order Registry. Must be set to "internal".

include_nodeOptional boolean

Returns metadata for the origin warehouse node (ID, Region) to enable catalog hydration.

expand_eventsOptional boolean

Include granular warehouse milestones (e.g., picking, packing, staging).

SAMPLE_REQUEST //
?reference=ORD-2026-X99&type=internal&include_node=1&expand_events=1

Query-based request. No payload body required.

SAMPLE_RESPONSE //
HTTP_200
{
    "order_id": "ORD-2026-X99",
    "status": "picking_in_progress",
    "node_context": {
        "node_id": "NYC-01",
        "region": "US-EAST",
        "allow_adds": true
    },
    "progress_pct": 45,
    "milestones": [
        {
            "time": "2026-05-12T14:30:00Z",
            "event": "picking_initiated",
            "detail": "Warehouse Robot R-12 assigned."
        },
        {
            "time": "2026-05-12T09:00:00Z",
            "event": "order_verified",
            "detail": "Financial settlement confirmed."
        }
    ],
    "estimated_dispatch": "2026-05-13T10:00:00Z"
}
HTTP_404
{
    "error": "ORDER_NOT_FOUND",
    "message": "No internal fulfillment record matches this reference ID."
}
GET /v1/tracking/probe

Probe

Heuristic identification of a reference string to determine origin (Internal Order vs. Carrier Tracking) and verify existence before security escalation.

ParameterTypeDescription
referenceRequired string

The raw alphanumeric string entered by the user (Order ID or Tracking Number).

SAMPLE_REQUEST //
?reference=ORD-2026-X99

Query-based request. No payload body required.

SAMPLE_RESPONSE //
HTTP_200
{
    "reference": "1234567890",
    "is_valid": true,
    "type": "carrier",
    "requirements": [
        "postcode",
        "carrier"
    ],
    "metadata": {
        "carrier_hint": "FedEx"
    }
}
HTTP_404
{
    "error": "REFERENCE_NOT_FOUND",
    "is_valid": false,
    "message": "This ID does not match our records. It may still be processing."
}
COLLECTION // EXCEPTIONS

Resolve System Deviations

Handling operational anomalies requiring intervention.

GET /v1/exceptions/active

Active

Retrieve unresolved blocks.

ParameterTypeDescription
severityOptional string

low, medium, high, critical.

assigned_toOptional string

Filter by internal team member ID.

SAMPLE_REQUEST //
?severity=critical&category=address_error

Query-based request. No payload body required.

SAMPLE_RESPONSE //
HTTP_200
{
    "exceptions": [
        {
            "id": "EXC-1",
            "type": "address_error"
        }
    ]
}
HTTP_401
{
    "error": "UNAUTHORIZED",
    "message": "Invalid API Key for telemetry access."
}
PATCH /v1/exceptions/{id}/resolve

Resolve

Submit a corrective instruction to clear a system block.

ParameterTypeDescription
resolution_codeRequired string

Identification code for action taken.

payloadOptional object

Corrective data (e.g., new address).

SAMPLE_REQUEST //
PATCH /v1/exceptions/{id}/resolve
{
    "resolution_code": "RETRY_WITH_NEW_ADDRESS",
    "payload": {
        "street": "123 Tech Lane Apt 4B",
        "postal_code": "11201"
    }
}
SAMPLE_RESPONSE //
HTTP_200
{
    "exception_id": "EXC-1",
    "status": "resolved",
    "resolved_at": "2026-01-06T19:00:00Z"
}
HTTP_400
{
    "error": "INVALID_RESOLUTION",
    "message": "Resolution code not applicable for address errors."
}
COLLECTION // WEBHOOKS

Configure Subscriptions

Real-time push notifications for event-driven architecture.

POST /v1/webhooks

Subscribe

Register a listener for real-time system events.

ParameterTypeDescription
urlRequired string

Public HTTPS endpoint to receive data.

event_typesRequired array

order.shipped, exception.created, etc.

secretOptional string

Shared secret for HMAC verification.

SAMPLE_REQUEST //
POST /v1/webhooks
{
    "url": "https:\/\/client-system.io\/webhooks\/p3d",
    "event_types": [
        "order.shipped",
        "exception.created"
    ],
    "secret": "whsec_p3d_772819"
}
SAMPLE_RESPONSE //
HTTP_201
{
    "id": "WH-01",
    "active": true,
    "secret": "whsec_772..."
}
HTTP_400
{
    "error": "URL_NOT_REACHABLE",
    "message": "The provided URL failed the HTTPS handshake."
}
COLLECTION // EVENTS

Audit System Logs

The proactive pull-model for system-wide activity reconciliation.

GET /v1/events

Poll

Retrieve event logs for a specific time range.

ParameterTypeDescription
sinceRequired string

ISO-8601 start timestamp.

untilOptional string

ISO-8601 end timestamp.

event_categoryOptional string

shipment, order, or system logs.

SAMPLE_REQUEST //
?since=2026-01-06T00%3A00%3A00Z&event_category=shipment

Query-based request. No payload body required.

SAMPLE_RESPONSE //
HTTP_200
{
    "events": [
        {
            "id": "EVT-1",
            "type": "order.shipped",
            "timestamp": "2026-01-06T15:00:00Z"
        }
    ]
}
HTTP_400
{
    "error": "TIME_RANGE_EXCEEDED",
    "message": "Poll window limited to 24 hours."
}
COLLECTION // RETURNS

Manage Reverse Flow

Handling the return of assets for inspection or restocking.

POST /v1/returns/rma

Authorize

Generate an RMA and automated routing for reverse transit.

ParameterTypeDescription
original_order_idRequired string

The outbound order ID.

reason_codeRequired string

damaged, unwanted, etc.

customer_noteOptional string

Additional context for return.

SAMPLE_REQUEST //
POST /v1/returns/rma
{
    "original_order_id": "ORD-101",
    "reason_code": "damaged_on_arrival",
    "customer_note": "Outer box crushed"
}
SAMPLE_RESPONSE //
HTTP_201
{
    "rma_id": "RMA-99",
    "label_url": "https:\/\/api.p3d.io\/l\/99.pdf",
    "status": "authorized"
}
HTTP_403
{
    "error": "NON_RETURNABLE",
    "message": "This item is outside the allowed 30-day return window."
}
COLLECTION // DOCUMENTS

Generate Asset Paperwork

Automated generation of carrier labels and customs assets.

GET /v1/documents/customs

Customs

Retrieve commercial invoices and customs forms.

ParameterTypeDescription
shipment_idRequired string

The unique shipment reference.

formatOptional string

pdf or zpl.

SAMPLE_REQUEST //
?shipment_id=SHP-992&format=pdf

Query-based request. No payload body required.

SAMPLE_RESPONSE //
HTTP_200
{
    "url": "https:\/\/api.p3d.io\/d\/5.pdf",
    "format": "pdf",
    "generated_at": "2026-01-06T19:05:00Z"
}
HTTP_400
{
    "error": "DOC_NOT_READY",
    "message": "Customs data still being compiled for this shipment."
}
COLLECTION // LISTS

Manage Asset Grouping

Transactional staging area for grouping SKUs before fulfillment or replenishment.

POST /v1/lists

Create

Initialize a new asset group.

ParameterTypeDescription
nameRequired string

Identifier for the list.

itemsOptional array

Initial set of SKU/Qty objects.

SAMPLE_REQUEST //
POST /v1/lists
{
    "name": "Q1-Restock-London",
    "items": [
        {
            "sku": "P3D-99-BLK",
            "qty": 50
        },
        {
            "sku": "P3D-99-WHT",
            "qty": 25
        }
    ]
}
SAMPLE_RESPONSE //
HTTP_201
{
    "id": "LST-77281",
    "status": "initialized",
    "item_count": 2,
    "created_at": "2026-01-07T22:15:00Z"
}
HTTP_422
{
    "error": "VALIDATION_FAILED",
    "message": "The provided list name is too short or contains illegal characters.",
    "details": {
        "name": "Minimum 3 characters required."
    }
}
GET /v1/lists/{id}

Get

Retrieve list details and current SKU composition.

ParameterTypeDescription
idRequired string

The unique UUID or ID of the list.

SAMPLE_REQUEST //
?expand_items=1&include_metadata=1

Query-based request. No payload body required.

SAMPLE_RESPONSE //
HTTP_200
{
    "id": "LST-77281",
    "name": "Q1-Restock-London",
    "items": [
        {
            "sku": "P3D-99-BLK",
            "qty": 50
        },
        {
            "sku": "P3D-99-WHT",
            "qty": 25
        }
    ],
    "metadata": {
        "owner_id": "USR-99",
        "region": "GB-LON"
    }
}
HTTP_404
{
    "error": "LIST_NOT_FOUND",
    "message": "No asset group exists with the provided ID.",
    "id": "LST-XXXXX"
}
PATCH /v1/lists/{id}

Update

Rename the list or modify metadata.

ParameterTypeDescription
idRequired string

The unique ID of the list to update.

nameOptional string

New name for the asset group.

SAMPLE_REQUEST //
PATCH /v1/lists/{id}
{
    "name": "Q1-Restock-London-FINAL"
}
SAMPLE_RESPONSE //
HTTP_200
{
    "id": "LST-77281",
    "name": "Q1-Restock-London-FINAL",
    "updated_at": "2026-01-07T22:20:00Z"
}
HTTP_400
{
    "error": "INVALID_UPDATE_REQUEST",
    "message": "PATCH request must contain at least one modifiable field (e.g., name)."
}
POST /v1/lists/{id}/items

Modify items

Add or update SKUs within the list.

ParameterTypeDescription
idRequired string

The parent List ID.

itemsRequired array

Array of SKUs to add or overwrite.

SAMPLE_REQUEST //
POST /v1/lists/{id}/items
{
    "items": [
        {
            "sku": "P3D-CORE-01",
            "qty": 100
        },
        {
            "sku": "P3D-99-BLK",
            "qty": 75
        }
    ]
}
SAMPLE_RESPONSE //
HTTP_200
{
    "list_id": "LST-77281",
    "action": "upsert",
    "affected_rows": 2,
    "total_items": 3
}
HTTP_422
{
    "error": "SKU_NOT_REGISTERED",
    "message": "One or more SKUs in the request do not exist in the Registry Pillar.",
    "missing_skus": [
        "P3D-UNKNOWN-01"
    ]
}
DELETE /v1/lists/{id}/items/{sku}

Remove item

Remove a specific SKU from the list.

ParameterTypeDescription
idRequired string

The parent List ID.

skuRequired string

The specific SKU to remove from this group.

permanent_deleteOptional boolean

Force removal without archival (Query param).

SAMPLE_REQUEST //
?permanent_delete=1
SAMPLE_RESPONSE //
HTTP_200
{
    "status": "purged",
    "sku": "P3D-99-BLK",
    "list_id": "LST-77281",
    "permanent": true
}
HTTP_404
{
    "error": "SKU_NOT_IN_LIST",
    "message": "The requested SKU was not found within the specified list.",
    "list_id": "LST-77281",
    "sku": "P3D-NOT-HERE"
}
DELETE /v1/lists/{id}

Delete

Permanently remove the list and all associations.

ParameterTypeDescription
idRequired string

The unique ID of the list to be destroyed.

SAMPLE_REQUEST //
SAMPLE_RESPONSE //
HTTP_200
{
    "id": "LST-77281",
    "status": "deleted",
    "message": "Asset group and all associated items removed."
}
HTTP_409
{
    "error": "LIST_LOCKED",
    "message": "This list is currently being committed to an order and cannot be deleted."
}
POST /v1/lists/{id}/commit

Commit to order

Convert a staged list into a live fulfillment order.

ParameterTypeDescription
idRequired string

The List ID to be committed.

destination_nodeRequired string

Target warehouse for fulfillment.

external_idOptional string

Client-side order reference (OMS).

auto_delete_listOptional boolean

Remove the list after successful order creation.

SAMPLE_REQUEST //
POST /v1/lists/{id}/commit
{
    "destination_node": "NYC-01",
    "external_id": "ORD-2026-X99",
    "auto_delete_list": true
}
SAMPLE_RESPONSE //
HTTP_201
{
    "order_id": "P3D-ORD-5501",
    "from_list": "LST-77281",
    "status": "queued_for_fulfillment",
    "node_status": "confirmed_at_NYC-01",
    "items_synced": 12
}
HTTP_422
{
    "error": "INVENTORY_INSUFFICIENT",
    "details": {
        "SKU-P3D-99-BLK": "Requested 50, only 12 available at NYC-01"
    }
}