Customs Packages API

Use it when you already know the customs package ID and want the current package record plus artifact inventory.

Machine-readable contract:

• /docs/api/openapi

Related docs:

• /docs/concepts/primitives
• /docs/concepts/artifacts
• /docs/concepts/broker-submission
• /docs/api/exports
• /docs/guides/first-export
• /docs/guides/warehouse-integration

#Where this endpoint fits

Customs packages are downstream execution objects.

Typical flow:

1. call POST /api/exports/plan
2. call POST /api/exports/execute
3. read customs_package_id from the execute response
4. either inspect the export with GET /api/exports/{id} or fetch the package directly with GET /api/customs-packages/{id}

If you need the full export state, use inspect.

If you only need package-level artifact metadata and package status, use this endpoint.

#Authentication

Send a bearer API key:

Authorization: Bearer <api-key>

The package must belong to the authenticated account scope through its related export batch.

#GET /api/customs-packages/{id}

#Purpose

Return the current stable public customs package record plus artifact metadata.

This endpoint is intentionally narrower than the internal persistence model. It documents the stable fields clients should rely on.

#Path parameter

#cURL example

curl http://localhost:3000/api/customs-packages/cp_123 \
  -H "authorization: Bearer shpbndl_live_..."

#Success response

Stable fields:

Per artifact:

#JSON response example

{
  "id": "cp_123",
  "exportBatchId": "batch_123",
  "packageNumber": "cp_ch123456",
  "state": "sent_to_broker",
  "createdAt": "2026-03-11T16:10:00.000Z",
  "artifacts": [
    {
      "artifact_type": "cci_human_readable",
      "filename": "commercial_customs_invoice.html",
      "generated_at": "2026-03-11T16:10:00.000Z"
    },
    {
      "artifact_type": "cci_csv",
      "filename": "commercial_customs_invoice.csv",
      "generated_at": "2026-03-11T16:10:00.000Z"
    },
    {
      "artifact_type": "cci_json",
      "filename": "commercial_customs_invoice.json",
      "generated_at": "2026-03-11T16:10:00.000Z"
    },
    {
      "artifact_type": "packing_list",
      "filename": "packing_list.json",
      "generated_at": "2026-03-11T16:10:00.000Z"
    },
    {
      "artifact_type": "manifest",
      "filename": "manifest.json",
      "generated_at": "2026-03-11T16:10:00.000Z"
    }
  ]
}

#Error response example

Not found:

{
  "errorCode": "NOT_FOUND",
  "message": "Customs package not found."
}

#Artifact types

The current protocol exposes five artifact types:

These are the same artifact categories you see in execute and inspect responses.

#How broker-facing documents are accessed

The core public contract currently exposes artifact metadata, not a standardized artifact download endpoint.

That means:

• execute tells you that artifacts were generated
• inspect shows those artifacts in the broader export state
• customs package lookup returns the package-level artifact inventory
• actual file-byte retrieval is deployment-specific unless separately documented

For broker-facing workflows today:

• use execute or inspect to confirm brokerSubmission
• use this endpoint or inspect to enumerate artifact metadata
• treat any deployment-specific download path as outside the stable core protocol unless it is separately documented

#Behavioral notes

#Relationship to inspect

• If you need package-only state, use this endpoint.
• If you need package state plus export state, notifications, broker submission, and events, use GET /api/exports/{id}.

#Retry guidance

• This is a read endpoint, so ordinary safe retries are fine.
• If a package is unexpectedly missing, inspect the export first to confirm the current execution state and package ID.

#Notes for AI agents and automation clients

• Treat customs_package_id from execute as the durable pointer to this resource.
• Use inspect for canonical workflow reconciliation, but use this endpoint for package-specific artifact indexing.
• Do not assume that artifact metadata implies a public download URL in the core contract.