Reference

Conventions

General patterns and data types used across the entire API. Read this before designing your database schema or writing client code.

Identifiers (IDs)

All resource IDs in the API are returned as strings. This applies to every id, productId,cartonTypeId, invoiceId,workflowId, and any other field that references a resource.

Property	Value
Type	`string`
Max length	`128` characters
Character set	ASCII alphanumeric, hyphens, underscores
Current format	Numeric strings (e.g. `"381285"`)
Stability	Format may change without notice. Treat as opaque.

Database design

Store all 3PLGuys IDs as VARCHAR(128) or equivalent. Do not store them as integers — the format may change to UUIDs, prefixed IDs, or other non-numeric formats in the future.

Do

Correct

// Store as string
const shipmentId: string = response.id;

// Compare as string
if (shipment.id === "381285") { ... }

// Database column
CREATE TABLE synced_shipments (
  threepl_id VARCHAR(128) NOT NULL,
  ...
);

Don't

Incorrect

// Don't parse as number — will break when format changes
const id = parseInt(response.id);

// Don't store as integer
CREATE TABLE synced_shipments (
  threepl_id INT NOT NULL,  -- will break
  ...
);

// Don't assume ordering or structure
const isNewer = parseInt(a.id) > parseInt(b.id);  -- use createdAt instead

Timestamps

All timestamps are returned in ISO 8601 format with UTC timezone.

Example

"createdAt": "2026-02-26T13:22:08.514Z"
"updatedAt": "2026-03-04T10:15:00.000Z"

Monetary Values

All monetary amounts are represented as 64-bit integers in cents (the smallest currency unit). For example, $150.00 is represented as 15000. An ISO 4217 currency code is always provided alongside monetary amounts.

Property	Value
Type	`integer` (format: `int64`)
Unit	Smallest currency unit (cents for USD)
Currency	Always provided as a sibling `currency` field (ISO 4217)
Precision	Exact — never floating point

Example — invoice

{
  "totalAmount": 15000,
  "currency": "USD",
  "items": [
    { "unitCost": 1500, "totalCost": 15000, "quantity": 10 }
  ]
}
// 15000 cents = $150.00
// Items inherit currency from the parent invoice

Example — balance

{
  "balance": 150000,
  "currency": "USD"
}
// 150000 cents = $1,500.00

Database design

Store monetary values as BIGINT — never as FLOAT, DOUBLE, or DECIMAL with scale. Floating-point arithmetic causes rounding errors in financial calculations. In application code, use integer math or a dedicated money library.

Monetary fields in the API

Endpoint	Fields	Currency source
Invoice	`totalAmount`	`currency`
Invoice item	`unitCost`, `totalCost`	Inherited from parent invoice `currency`
Balance	`balance`	`currency`
Transaction	`amount`	`currency`

Metric values are NOT monetary

Fields like weight, length,width, height, and quantity are regular numbers. The int64 and currency rules only apply to monetary values.