Trade state, as an API.

Connect your marketplace or procurement system to the same rules and evidence used in the TradeShip Pay workspace.

Developer preview

Create a key in Developer API and send Authorization: Bearer tsp_trial_… to endpoints under /api/v1/trial. These keys are separate from workspace keys below. Every new workspace gets 25 credits; no credit card is required.

Endpoint costs and global coverage · Authenticated playground · Provider connection requirements

Trial status requests require an organization-owned provider connection. Never send carrier credentials as TradeShip API authentication. Public context is reference data; only authorized status observations can represent real shipment events. Trial evaluation is stateless and never moves funds.

Authentication

Metered requests accept Idempotency-Key and return credits charged and remaining. Retry the same body with the same key for up to 24 hours to replay the original result without a second lookup or charge. Invalid input and known local configuration failures cost zero; upstream failures are refunded.

For persisted decisions, send an optional tradeId with a status request using your workspace session. The production carrier reference must match the attached shipment. HMRC requires a matching MRN in the trade external reference; DUCR/UCR responses remain separate declaration observations and cannot be attached as one clearance. Trial keys can query and evaluate, but cannot write trade state. Refresh connected evidence within 24 hours before settlement evaluation.

Accepted terms may include releasePlan version 1 with unique tranches totaling 10,000 basis points. Supported milestones are export clearance, import clearance, and delivery after inspection. Evaluate returns stagedEligibility with stable tranche keys, current eligible percentages, and hold reasons. These are eligibility snapshots; external execution must deduplicate by trade, terms version, and tranche and refund only unexecuted portions.

Create a key in workspace settings. Include Authorization: Bearer tsp_live_…. Read operations require trades:read; writes also require trades:write. Key management, simulation, dispute resolution, and execution require an owner/admin session.

curl https://tradeshippay.com/api/v1/trades \
  -H "Authorization: Bearer $TRADESHIP_API_KEY"

Create a trade

tsp_live_ identifies this deployed environment; tsp_test_ identifies local demo mode. Neither prefix enables real financial execution. For local development only, use http://localhost:3000/api/v1.

Use integer minor currency units and uppercase ISO country/currency codes. Two decimal currencies use cents; JPY has zero and KWD has three minor digits. The request creates a versioned agreement with the creating party’s acceptance.

{
  "title": "5-axis spindle assembly",
  "amountMinor": 1725000,
  "currency": "EUR",
  "originCountry": "DE",
  "destinationCountry": "US",
  "counterpartyName": "Kern Precision GmbH",
  "counterpartyEmail": "seller@example.test",
  "counterpartyCountry": "DE",
  "terms": {
    "inspectionPeriodHours": 48,
    "importClearanceRequired": true
  }
}

Endpoints

Base URL: /api/v1. Successful responses use {data, requestId}. Errors use {error: {code, message, requestId}}.

Retries & idempotency

Send an Idempotency-Key header on create, shipment, dispute, and evaluation operations. Reusing the key with different input returns 409. Invitation secrets are shown only in the first response; replay omits the link. Generate a fresh invitation when needed.

Signed outgoing webhooks

Register an HTTPS destination in settings after allowing its exact hostname on the server. Events include trade creation/acceptance, shipment updates, decision changes, dispute opening/resolution, and mock settlement completion.

signature = HMAC_SHA256(secret, timestamp + "." + rawBody)

X-TradeShip-Signature: v1=<hex signature>
X-TradeShip-Timestamp: <Unix seconds>
X-TradeShip-Id: <delivery UUID>

Reject stale timestamps, compare signatures in constant time, and deduplicate by event ID. Delivery is at least once, with five bounded attempts. The Worker retries on its five-minute schedule; local testing can use “Deliver pending” in settings.

Provider boundary

Escrow-release infrastructure for cross-border trade. Authorized provider evidence, versioned decisions, and optional staged eligibility. Funds remain with your external provider. Carrier adapter modules are interfaces without live implementations. Tracking attachment stores a reference and does not start polling. Production mock mutations and execution are disabled. Local demo mode supports mock events and mock settlement only.

Email verification, password recovery delivery, billing, membership invitations, and complete account deletion are not implemented.

Counterparty acceptance links are expiring bearer capabilities tied to an agreement version; possession is not identity verification. Share them privately.

Trade lists return up to 20 records per page. Use ?attention=true for disputed, customs-hold, and manual-review records, ordered by oldest unresolved update, with a total across all pages. Authentication failures return 401, forbidden roles/scopes 403, missing tenant resources 404, conflicting state or idempotency 409, and invalid input 422.