Currently viewing services in North America. Change region?

SDKs & Guides

ShipPack maintains one OpenAPI contract for the public server-to-server surface and a first server-side TypeScript SDK source package generated and tested against that contract.

Registration, dashboard sessions, application management, API-key management, webhook configuration, and production review remain HTTP and Postman workflows rather than secret-key SDK operations.

SDK availability

No language SDK package is publicly released yet. PHP, Python, JavaScript browser, mobile, and other language packages are deliberately deferred. The TypeScript source must pass its release gates before npm publication as @shippack/sdk.

OpenAPI Contract

The machine-readable contract is the source of truth for generated client types and operations.

openapi/shippack-developer-api.json
  • Uses OpenAPI 3.1.
  • Covers credentials, package sizes, delivery types, delivery options, shipments, cancellation, and sandbox simulation.
  • Defines the signed outbound shipment webhook payload and headers.
  • Excludes registration, dashboard sessions, application/key management, and admin review.

Contract integrity

An SDK release must not be published when its generated operations differ from the committed OpenAPI specification.

TypeScript SDK Source

The first server-side SDK is maintained at:

sdks/typescript

Current capabilities

  • Typed credential resource.
  • Typed package-size, delivery-type, and delivery-option catalogs.
  • Typed shipment list, create, retrieve, cancel, and sandbox simulation resources.
  • Structured API errors and trace IDs.
  • Request timeouts and bounded retries for eligible GET requests.
  • Timing-safe webhook signature verification.

Release gates

  1. Pass the SDK Docker build.
  2. Pass the complete SDK test suite.
  3. Pass OpenAPI operation-coverage verification.
  4. Confirm generated code matches the committed contract.
  5. Publish to npm as @shippack/sdk only after every gate passes.

Raw HTTP Setup

Until the SDK package is published, call the developer surface from a secure backend.

Base URL

https://dev.api.theshippack.com/api/v1/developer

Relative paths

With this full base configured, request /credentials, /package-sizes, /delivery-types, /delivery-options, and /shipments. Gateway-relative contract paths include the /developer prefix.

Authentication

http
Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
  • Keep keys in server-side secret storage.
  • Use sk_test_ credentials for sandbox work.
  • Do not enable a production workflow until the application is approved.
  • Respect the 120-request-per-minute credential limit.

Catalog-First Shipment Guide

Resolve valid catalog identifiers before creating a shipment.

  1. Call GET /developer/credentials to confirm the application and environment.
  2. Call GET /developer/package-sizes.
  3. Call GET /developer/delivery-types.
  4. Call GET /developer/delivery-options with origin and destination coordinates.
  5. Use returned packageSizeId and deliveryTypeId values in POST /developer/shipments.
http
GET /developer/delivery-options?origins=6.4488,3.472&destinations=9.0765,7.4983

Sandbox Testing Guide

Sandbox is designed for deterministic shipment and webhook testing.

  • No operational shipment is created.
  • No wallet, card, or payment provider is charged.
  • No driver is assigned.
  • Shipment references begin with SPTEST.
  • Tracking IDs begin with TRKTEST.
  • Status changes occur only through the simulation endpoint.

Lifecycle

PENDING → ASSIGNED → PICKED_UP → IN_TRANSIT → OUT_FOR_DELIVERY → DELIVERED

Every non-terminal status may also transition to FAILED.

Webhook Verification Guide

Verify the signature against the exact raw request body before parsing JSON.

Signed value

TIMESTAMP.RAW_REQUEST_BODY

Required headers

http
X-ShipPack-Event: shipment.delivered
X-ShipPack-Delivery: DELIVERY_UUID
X-ShipPack-Timestamp: 1786966200
X-ShipPack-Signature: sha256=HEX_HMAC

Node.js verification

JavaScript
import crypto from "node:crypto";

const signed = timestamp + "." + rawBody;
const expected = "sha256=" + crypto
  .createHmac("sha256", webhookSecret)
  .update(signed)
  .digest("hex");

const valid = crypto.timingSafeEqual(
  Buffer.from(expected),
  Buffer.from(receivedSignature)
);
  • Reject timestamps outside a five-minute tolerance.
  • Return HTTP 2xx quickly and process asynchronously.
  • Deduplicate with payload id or X-ShipPack-Delivery.
  • Rotate a webhook secret through its dashboard endpoint when required.

Error and Retry Handling

API requests

  • Capture the structured SDK error rather than parsing an arbitrary message string.
  • Log the ShipPack trace ID with your request context.
  • Set explicit timeouts.
  • Retry only eligible GET requests and keep retries bounded.
  • Do not automatically replay shipment creation or other mutation requests.

Webhook deliveries

  • ShipPack retries after 30 seconds, 2 minutes, 10 minutes, and 30 minutes.
  • A delivery is failed after five unsuccessful attempts.
  • Inspect the stored status, HTTP response, truncated response body, and last error.
  • Manually retry only non-delivered attempts.

Production Readiness Checklist

  • Developer email and OTP are verified.
  • The application has a working sandbox key.
  • Catalog IDs are loaded dynamically rather than hard-coded.
  • Sandbox create, retrieve, cancel, and simulation flows are tested.
  • Webhook signature, timestamp, and deduplication checks are implemented.
  • Secrets are stored only on the backend and can be rotated.
  • A meaningful production-access reason has been submitted and approved.
  • The production workflow uses only the wallet submission supported by the MVP.

Developer Resources

ResourceLocationPurpose
OpenAPI 3.1openapi/shippack-developer-api.jsonServer-to-server API and outbound webhook contract
TypeScript SDK sourcesdks/typescriptTyped credentials, catalogs, shipments, errors, retries, and webhook verification
Postman collectionRepository collectionAuth, dashboard, key management, webhooks, and production review
Webhook delivery logsDeveloper dashboardCallback status, HTTP response, truncated body, last error, and manual retry