Skip to main content

​
Welcome

Our API is currently in Beta and is not yet available to the wider public. More functionality will be added in the near future as we continuously build out our API. If you’d like to request access, offer feedback, or have any inquiries about the API, don’t hesitate to contact us at support@beachdepository.com.

SDKs

Install the TypeScript client and call the API from Node.

Quickstart

How an inbound shipment, an outbound request, an outbound shipment, and a transfer move.

Entities

The shape of each object the API returns.

Webhooks

Signatures, event types, and which status changes fire an event.

Permissions

The scopes on a key, and what each one allows.

​
Base URL

Paths in this reference are relative to /v1. GET / on the host root returns the service name, version, and environment.

​
Authorization

Create an API key in the dashboard under Settings > API Keys. Each key belongs to one organization, so requests do not take an organization id. Send the API key as a Bearer token.
Keys use the prefix pv_live_, then 64 hex characters. Each key has permission scopes. A request without the required scope returns 403. Disable a key to pause it, or revoke it to invalidate it permanently. Disabled and revoked keys return 401.

​
Idempotency

These creates accept an optional Idempotency-Key header, any unique string up to 255 characters: FBO accounts, addresses, aliases, inbound shipments, outbound requests, transfers, and webhooks. Cancel, label quote, and every other POST ignore the header. Retrying a keyed create within 24 hours returns the original response. Replayed responses include Idempotency-Replayed: true. Reusing a key while the first request is still in progress returns 409. Reusing it on a different endpoint returns 422.

​
Rate limits

Each key is allowed 60 requests per minute by default. The limit is configurable per key in the dashboard. The window is a fixed minute and resets at the start of each minute. A request over the limit returns 429:

​
Pagination

List endpoints take page and limit. page defaults to 1. limit defaults to 25 and cannot exceed 100. Both must be positive integers. page times limit cannot exceed 10,000. A value outside those rules returns 422. The response wraps the rows in data and adds pagination:
hasMore is true when another page exists. There is no total count. Request the next page by incrementing page. Webhooks, addresses, and aliases return the full list and do not use these parameters.

​
Errors

Failed requests return a JSON body: