Octoship
v1 · API reference

The Octoship API.

Rates, shipments, labels and tracking over REST and JSON. Typed requests, signed events, and examples you can run.

Getting started

Create an API key in your developer settings. Choose test mode and the read and ship scopes to quote a shipment. Send requests to https://api.octoship.com/v1. Amounts are integers in the currency’s smallest unit, and resource IDs are UUIDs.

curlQuote a test shipment
export OCTOSHIP_API_KEY='your-test-key'
# Generate once per logical operation; retain this value for retries.
export IDEMPOTENCY_KEY="$(uuidgen)"

curl -X POST 'https://api.octoship.com/v1/rates' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "from_address": {
    "name": "Octoship sender",
    "line1": "1 Market St",
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94105",
    "country": "US",
    "phone": "+14155550100"
  },
  "to_address": {
    "name": "Test recipient",
    "line1": "350 5th Ave",
    "city": "New York",
    "region": "NY",
    "postal_code": "10118",
    "country": "US",
    "phone": "+12125550100"
  },
  "parcel": {
    "weight": {
      "value": 12,
      "unit": "oz"
    }
  }
}'

Label purchases and billing require API access to be enabled for your account. Test keys cannot access connected-store orders or apply shipping rules to them. Shared addresses, package presets and rule settings belong to the store.

Authentication & retries

Send Authorization: Bearer your-key. Keys beginning os_test_ or os_live_ select one store and mode. Keep keys on your server. Creation and authorized retries with the same idempotency key return the secret for 24 hours; subsequent list requests omit it. Revoked, expired or suspended-store credentials stop working immediately.

Every POST, PUT, PATCH and DELETE requires an Idempotency-Key: 1–255 visible ASCII characters. Generate a unique value for a new action and reuse it with the same body on retries. Completed responses are retained for 24 hours. Reuse with a different request or caller returns 409; pending requests also return 409 with Retry-After.

Scopes are read, ship, orders, webhooks, billing and * (all public operations). New keys default to read. Balance, billing, payment and report access requires billing scope, including reads; only captains can grant billing or all-operation scopes. The orders scope also covers shared address, preset, rule and store-connection settings. Limits use rolling windows shared across API replicas for your key, store and IP. Rate-limited requests return 429 with Retry-After; wait for that interval before retrying. Key responses also report X-RateLimit-Limit and X-RateLimit-Remaining.

TypeScript SDK & Postman

Download the standalone TypeScript client and import it into a Fetch-compatible runtime. Request and response types come from the same OpenAPI document as this reference. The client requires an idempotency key for mutations and does not retry automatically.

jsTypeScript · quote and buy a test label
import { createOctoshipClient } from "./octoship";
import { randomUUID } from "node:crypto";

const api = createOctoshipClient({ apiKey: process.env.OCTOSHIP_API_KEY! });
const quote = await api.quoteRates({
  idempotencyKey: randomUUID(),
  body: {
    from_address: { line1: "1 Market St", city: "San Francisco",
      region: "CA", postal_code: "94105", country: "US", phone: "+14155550100" },
    to_address: { line1: "350 5th Ave", city: "New York",
      region: "NY", postal_code: "10118", country: "US", phone: "+12125550100" },
    parcel: { weight: { value: 12, unit: "oz" } }
  }
});
const rate = quote.rates[0];
if (!rate) throw new Error("No rates available");
// Requires label purchases to be enabled for your account.
const purchaseKey = randomUUID(); // Persist alongside your order for retries.
const label = await api.createLabel({
  idempotencyKey: purchaseKey,
  body: { rate_id: rate.id, format: "pdf", size: "4x6" }
});
console.log(label.id, label.status);

In Postman, set api_key and base_url, then replace the sample IDs and fields. Each mutation retains its idempotency variable for retries. Clear that operation’s idempotency variable before starting a new action. A Python SDK is planned.

shipping rules

POST/v1/shipping_rules/apply

Apply rules to orders

Re-evaluates rules for orders awaiting shipment (or the ones given) and records each decision on the order. Orders are also evaluated automatically when imported or edited.

ParameterInTypeRequired
idempotency-keyheaderstringYes

JSON body

order_ids
string[]

Defaults to every order awaiting shipment

curlApply rules to orders
curl -X POST 'https://api.octoship.com/v1/shipping_rules/apply' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'
Success responses & schemas

200 · ShippingRuleApplication

object required
shipping_rule_application
evaluated required
integer
matched required
integer

Orders a rule matched; the rest use the default (cheapest rate)

POST/v1/shipping_rules

Create a shipping rule

Added at `position` (default: last); later rules shift down.

ParameterInTypeRequired
idempotency-keyheaderstringYes

JSON body

name required
string
position
integer
enabled
boolean
conditions required
ShippingRuleCondition[]
action required
ShippingRuleAction
curlCreate a shipping rule
curl -X POST 'https://api.octoship.com/v1/shipping_rules' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "name": "string",
  "conditions": [
    {
      "field": "weight",
      "op": "eq",
      "value": "string"
    }
  ],
  "action": {}
}'
Success responses & schemas

201 · ShippingRule

id required
string

UUIDv7

object required
shipping_rule
name required
string
position required
integer

Evaluation order; first match wins

enabled required
boolean
conditions required
ShippingRuleCondition[]

All must match (AND). Empty = matches every order.

action required
ShippingRuleAction
version required
integer

Bumped when the rule definition is edited; orders record the version that matched

created_at required
string

RFC 3339 timestamp

updated_at required
string

RFC 3339 timestamp

DELETE/v1/shipping_rules/{id}

Delete a shipping rule

ParameterInTypeRequired
idpathstringYes
idempotency-keyheaderstringYes
curlDelete a shipping rule
curl -X DELETE 'https://api.octoship.com/v1/shipping_rules/YOUR_id' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"
Success responses & schemas

200 · object

id required
string

UUIDv7

object required
shipping_rule
deleted required
true
GET/v1/shipping_rules/{id}

Retrieve a shipping rule

ParameterInTypeRequired
idpathstringYes
curlRetrieve a shipping rule
curl -X GET 'https://api.octoship.com/v1/shipping_rules/YOUR_id' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · ShippingRule

id required
string

UUIDv7

object required
shipping_rule
name required
string
position required
integer

Evaluation order; first match wins

enabled required
boolean
conditions required
ShippingRuleCondition[]

All must match (AND). Empty = matches every order.

action required
ShippingRuleAction
version required
integer

Bumped when the rule definition is edited; orders record the version that matched

created_at required
string

RFC 3339 timestamp

updated_at required
string

RFC 3339 timestamp

GET/v1/shipping_rules

List shipping rules

Every rule in evaluation order (first match wins; no match → cheapest rate). Not paginated (at most 200 rules).

curlList shipping rules
curl -X GET 'https://api.octoship.com/v1/shipping_rules' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · ShippingRuleList

object required
list
data required
ShippingRule[]
has_more required
boolean
next_cursor required
string | null
POST/v1/shipping_rules/reorder

Reorder shipping rules

Send every rule id in the new order.

ParameterInTypeRequired
idempotency-keyheaderstringYes

JSON body

ids required
string[]

Every rule id, in the new evaluation order

curlReorder shipping rules
curl -X POST 'https://api.octoship.com/v1/shipping_rules/reorder' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "ids": [
    "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
  ]
}'
Success responses & schemas

200 · ShippingRuleList

object required
list
data required
ShippingRule[]
has_more required
boolean
next_cursor required
string | null
PATCH/v1/shipping_rules/{id}

Update a shipping rule

ParameterInTypeRequired
idpathstringYes
idempotency-keyheaderstringYes

JSON body

name
string
enabled
boolean
conditions
ShippingRuleCondition[]
action
ShippingRuleAction
curlUpdate a shipping rule
curl -X PATCH 'https://api.octoship.com/v1/shipping_rules/YOUR_id' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'
Success responses & schemas

200 · ShippingRule

id required
string

UUIDv7

object required
shipping_rule
name required
string
position required
integer

Evaluation order; first match wins

enabled required
boolean
conditions required
ShippingRuleCondition[]

All must match (AND). Empty = matches every order.

action required
ShippingRuleAction
version required
integer

Bumped when the rule definition is edited; orders record the version that matched

created_at required
string

RFC 3339 timestamp

updated_at required
string

RFC 3339 timestamp

store connections

POST/v1/store_connections

Start connecting a store

Returns the platform's approval URL. After the merchant approves, they're sent to `return_url` with `?store_connection=<id>` and recent orders start importing; if they cancel, with `?error=access_denied`. The URL expires after 10 minutes.

ParameterInTypeRequired
idempotency-keyheaderstringYes

JSON body

object | object

curlStart connecting a store
curl -X POST 'https://api.octoship.com/v1/store_connections' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "platform": "shopify",
  "shop_domain": "salty-goods.myshopify.com",
  "return_url": "https://example.com/webhooks"
}'
Success responses & schemas

200 · StoreConnectionAuthorization

object required
store_connection_authorization
platform required
shopify | woocommerce
authorize_url required
string

Send the merchant here to approve the connection

expires_at required
string

RFC 3339 timestamp

DELETE/v1/store_connections/{id}

Disconnect a store

Stops importing orders and revokes our access to the store. Orders already imported stay.

ParameterInTypeRequired
idpathstringYes
idempotency-keyheaderstringYes
curlDisconnect a store
curl -X DELETE 'https://api.octoship.com/v1/store_connections/YOUR_id' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"
Success responses & schemas

200 · object

id required
string

UUIDv7

object required
store_connection
deleted required
true
GET/v1/store_connections/{id}

Retrieve a store connection

ParameterInTypeRequired
idpathstringYes
curlRetrieve a store connection
curl -X GET 'https://api.octoship.com/v1/store_connections/YOUR_id' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · StoreConnection

id required
string

UUIDv7

object required
store_connection
platform required
StorePlatform
shop_name required
string
shop_domain required
string | null
status required
active | paused | error | disconnected
last_synced_at required
string | null

RFC 3339 timestamp

last_error required
string | null
created_at required
string

RFC 3339 timestamp

GET/v1/store_connections

List connected stores

Stores and marketplaces orders are imported from. Use `getOrderCounts?store_connection_id=` for per-store order counts.

ParameterInTypeRequired
limitqueryintegerNo
cursorquerystringNo
platformqueryStorePlatformNo
include_disconnectedquerytrue | falseNo
curlList connected stores
curl -X GET 'https://api.octoship.com/v1/store_connections' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · StoreConnectionList

object required
list
data required
StoreConnection[]
has_more required
boolean
next_cursor required
string | null
POST/v1/store_connections/{id}/sync

Sync orders now

Queues an import of orders changed since the last sync. Orders also arrive in real time through platform webhooks.

ParameterInTypeRequired
idpathstringYes
idempotency-keyheaderstringYes
curlSync orders now
curl -X POST 'https://api.octoship.com/v1/store_connections/YOUR_id/sync' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"
Success responses & schemas

202 · StoreConnection

id required
string

UUIDv7

object required
store_connection
platform required
StorePlatform
shop_name required
string
shop_domain required
string | null
status required
active | paused | error | disconnected
last_synced_at required
string | null

RFC 3339 timestamp

last_error required
string | null
created_at required
string

RFC 3339 timestamp

addresses

POST/v1/addresses

Save an address

With `is_default_from: true` it becomes the store's default ship-from address, replacing the previous one.

ParameterInTypeRequired
idempotency-keyheaderstringYes

JSON body

name
string | null
company
string | null
line1 required
string
line2
string | null
city required
string
region
string | null

State / province / county

postal_code
string | null
country required
string

ISO 3166-1 alpha-2

phone
string | null
email
string | null
residential
boolean | null
label
string | null
is_default_from
boolean
curlSave an address
curl -X POST 'https://api.octoship.com/v1/addresses' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "line1": "string",
  "city": "string",
  "country": "US"
}'
Success responses & schemas

201 · Address

name
string | null
company
string | null
line1 required
string
line2
string | null
city required
string
region
string | null

State / province / county

postal_code
string | null
country required
string

ISO 3166-1 alpha-2

phone
string | null
email
string | null
residential
boolean | null
id required
string

UUIDv7

object required
address
label required
string | null
is_default_from required
boolean
validated_at required
string | null

RFC 3339 timestamp

created_at required
string

RFC 3339 timestamp

DELETE/v1/addresses/{id}

Delete a saved address

ParameterInTypeRequired
idpathstringYes
idempotency-keyheaderstringYes
curlDelete a saved address
curl -X DELETE 'https://api.octoship.com/v1/addresses/YOUR_id' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"
Success responses & schemas

200 · object

id required
string

UUIDv7

object required
address
deleted required
true
GET/v1/addresses/{id}

Retrieve a saved address

ParameterInTypeRequired
idpathstringYes
curlRetrieve a saved address
curl -X GET 'https://api.octoship.com/v1/addresses/YOUR_id' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · Address

name
string | null
company
string | null
line1 required
string
line2
string | null
city required
string
region
string | null

State / province / county

postal_code
string | null
country required
string

ISO 3166-1 alpha-2

phone
string | null
email
string | null
residential
boolean | null
id required
string

UUIDv7

object required
address
label required
string | null
is_default_from required
boolean
validated_at required
string | null

RFC 3339 timestamp

created_at required
string

RFC 3339 timestamp

GET/v1/addresses

List saved addresses

The default ship-from address first, then newest first.

ParameterInTypeRequired
limitqueryintegerNo
cursorquerystringNo
default_fromquerytrue | falseNo
curlList saved addresses
curl -X GET 'https://api.octoship.com/v1/addresses' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · AddressList

object required
list
data required
Address[]
has_more required
boolean
next_cursor required
string | null
PATCH/v1/addresses/{id}

Update a saved address

Shipments keep the address as it was when they were created.

ParameterInTypeRequired
idpathstringYes
idempotency-keyheaderstringYes

JSON body

name
string | null
company
string | null
line1
string
line2
string | null
city
string
region
string | null
postal_code
string | null
country
string

ISO 3166-1 alpha-2

phone
string | null
email
string | null
residential
boolean | null
label
string | null
is_default_from
boolean
curlUpdate a saved address
curl -X PATCH 'https://api.octoship.com/v1/addresses/YOUR_id' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'
Success responses & schemas

200 · Address

name
string | null
company
string | null
line1 required
string
line2
string | null
city required
string
region
string | null

State / province / county

postal_code
string | null
country required
string

ISO 3166-1 alpha-2

phone
string | null
email
string | null
residential
boolean | null
id required
string

UUIDv7

object required
address
label required
string | null
is_default_from required
boolean
validated_at required
string | null

RFC 3339 timestamp

created_at required
string

RFC 3339 timestamp

POST/v1/addresses/validate

Validate an address

Checks one address and returns suggested corrections for review. Does not save or change an address or shipment. Availability depends on the store's shipping origin and mode.

ParameterInTypeRequired
idempotency-keyheaderstringYes

JSON body

address required
object
curlValidate an address
curl -X POST 'https://api.octoship.com/v1/addresses/validate' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "address": {
    "line1": "string",
    "city": "string",
    "country": "US"
  }
}'
Success responses & schemas

200 · AddressValidationResult

object required
address_validation
status required
verified | unverified | warning | error
normalized_address required
object | null

Suggested address only. Apply it explicitly after review; saved addresses and shipments are unchanged.

messages required
object[]

batches

POST/v1/batches

Buy a batch of labels

Queues up to 1,000 distinct shipment rates in your current mode. Each label is metered separately. Poll the batch and its items for progress and partial failures. Uncertain purchases remain pending with their holds intact; retries never authorize a new charge.

ParameterInTypeRequired
idempotency-keyheaderstringYes

JSON body

rate_ids required
string[]
format
pdf
size
4x6 | letter | a4
name
string | null
curlBuy a batch of labels
curl -X POST 'https://api.octoship.com/v1/batches' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "rate_ids": [
    "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d"
  ]
}'
Success responses & schemas

202 · Batch

id required
string

UUIDv7

object required
batch
mode required
Mode
name required
string | null
status required
pending | processing | completed | partial | failed
format required
pdf
size required
4x6 | letter | a4
total_count required
integer
pending_count required
integer
purchased_count required
integer
failed_count required
integer
document_status required
pending | ready | unavailable | not_required
url required
string | null

Short-lived link to the combined PDF of successful labels; null while unavailable or in event payloads.

url_expires_at required
string | null

RFC 3339 timestamp

created_at required
string

RFC 3339 timestamp

updated_at required
string

RFC 3339 timestamp

completed_at required
string | null

RFC 3339 timestamp

GET/v1/batches/{id}

Retrieve batch progress

Includes counts and a fresh combined-PDF link when ready. Completion requires every purchase to reach an authoritative final outcome.

ParameterInTypeRequired
idpathstringYes
curlRetrieve batch progress
curl -X GET 'https://api.octoship.com/v1/batches/YOUR_id' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · Batch

id required
string

UUIDv7

object required
batch
mode required
Mode
name required
string | null
status required
pending | processing | completed | partial | failed
format required
pdf
size required
4x6 | letter | a4
total_count required
integer
pending_count required
integer
purchased_count required
integer
failed_count required
integer
document_status required
pending | ready | unavailable | not_required
url required
string | null

Short-lived link to the combined PDF of successful labels; null while unavailable or in event payloads.

url_expires_at required
string | null

RFC 3339 timestamp

created_at required
string

RFC 3339 timestamp

updated_at required
string

RFC 3339 timestamp

completed_at required
string | null

RFC 3339 timestamp

GET/v1/batches

List label batches

ParameterInTypeRequired
limitqueryintegerNo
cursorquerystringNo
statusquerypending | processing | completed | partial | failedNo
curlList label batches
curl -X GET 'https://api.octoship.com/v1/batches' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · BatchList

object required
list
data required
Batch[]
has_more required
boolean
next_cursor required
string | null
GET/v1/batches/{id}/items

List batch results

Returns each selected rate, its label when allocated, and a customer-safe failure when applicable.

ParameterInTypeRequired
idpathstringYes
limitqueryintegerNo
cursorquerystringNo
curlList batch results
curl -X GET 'https://api.octoship.com/v1/batches/YOUR_id/items' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · BatchItems

object required
list
data required
BatchItem[]
has_more required
boolean
next_cursor required
string | null
POST/v1/batches/lookup

Recover an accepted batch by its original request key

Read-only POST with read permission. No lookup Idempotency-Key is required and responses use Cache-Control: no-store. Reads an existing batch without creating work, changing a reservation or reopening the original request claim. An unknown result may still commit; retain the original body/key and never start a replacement purchase automatically.

JSON body

request_key required
string

The original batch purchase Idempotency-Key, preserved exactly. Never place it in the URL or replace it with a new purchase key.

curlRecover an accepted batch by its original request key
curl -X POST 'https://api.octoship.com/v1/batches/lookup' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "request_key": "string"
}'
Success responses & schemas

200 · BatchLookup

object | object

billing

POST/v1/billing/card_setup

Start saving a payment card

ParameterInTypeRequired
idempotency-keyheaderstringYes

JSON body

curlStart saving a payment card
curl -X POST 'https://api.octoship.com/v1/billing/card_setup' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'
Success responses & schemas

201 · CardSetup

object required
card_setup
id required
string
client_secret required
string
publishable_key required
string | null
DELETE/v1/billing/payment_methods/{id}

Remove a saved payment card

ParameterInTypeRequired
idpathstringYes
idempotency-keyheaderstringYes
curlRemove a saved payment card
curl -X DELETE 'https://api.octoship.com/v1/billing/payment_methods/YOUR_id' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"
Success responses & schemas

200 · object

id required
string
object required
payment_method
deleted required
true
GET/v1/billing

Retrieve billing settings

curlRetrieve billing settings
curl -X GET 'https://api.octoship.com/v1/billing' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · StoreBillingSettings

object required
billing_settings
currency required
string

ISO 4217

publishable_key
string | null

Publishable payment key for the authenticated mode; null for mock or unconfigured billing. Output only.

default_payment_method_id required
string | null
auto_reload required
object
GET/v1/payments/{id}/receipt

Download a payment receipt

ParameterInTypeRequired
idpathstringYes
curlDownload a payment receipt
curl -X GET 'https://api.octoship.com/v1/payments/YOUR_id/receipt' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · PaymentReceipt

object required
receipt
payment_id required
string

UUIDv7

url required
string
expires_at required
string

RFC 3339 timestamp

GET/v1/billing/payment_methods

List saved payment cards

curlList saved payment cards
curl -X GET 'https://api.octoship.com/v1/billing/payment_methods' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · SavedPaymentMethodList

object required
list
data required
SavedPaymentMethod[]
GET/v1/payments

List payments

ParameterInTypeRequired
limitqueryintegerNo
cursorquerystringNo
curlList payments
curl -X GET 'https://api.octoship.com/v1/payments' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · PaymentList

object required
list
data required
Payment[]
has_more required
boolean
next_cursor required
string | null
PATCH/v1/billing

Update saved card and auto-reload settings

ParameterInTypeRequired
idempotency-keyheaderstringYes

JSON body

default_payment_method_id
string | null
auto_reload
object
curlUpdate saved card and auto-reload settings
curl -X PATCH 'https://api.octoship.com/v1/billing' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'
Success responses & schemas

200 · StoreBillingSettings

object required
billing_settings
currency required
string

ISO 4217

publishable_key
string | null

Publishable payment key for the authenticated mode; null for mock or unconfigured billing. Output only.

default_payment_method_id required
string | null
auto_reload required
object

labels

POST/v1/labels

Buy a label

Buys the label for a rate and charges your balance. Usually completes inline (`201`, status `purchased`, `url` set). If the courier is slow you get `202` with status `purchasing`: poll the label until it settles.

ParameterInTypeRequired
idempotency-keyheaderstringYes

JSON body

rate_id required
string

UUIDv7

format
pdf | png | zpl
size
4x6 | letter | a4
curlBuy a label
curl -X POST 'https://api.octoship.com/v1/labels' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "rate_id": "0193a5c4-6f7e-7d4b-9c1a-3e2f1a0b9c8d",
  "format": "pdf",
  "size": "4x6"
}'
Success responses & schemas

201 · Label

id required
string

UUIDv7

object required
label
mode required
Mode
shipment_id required
string

UUIDv7

rate_id required
string

UUIDv7

status required
purchasing | purchased | void_requested | voided | refunded | failed
tracking_number required
string | null
courier_id required
string
service_code required
string
price required
Money
format required
pdf | png | zpl
size required
4x6 | letter | a4
url required
string | null

Short-lived signed URL to the label file

tracker_id required
string | null

UUIDv7

purchased_at required
string | null

RFC 3339 timestamp

voided_at required
string | null

RFC 3339 timestamp

created_at required
string

RFC 3339 timestamp

202 · Label

id required
string

UUIDv7

object required
label
mode required
Mode
shipment_id required
string

UUIDv7

rate_id required
string

UUIDv7

status required
purchasing | purchased | void_requested | voided | refunded | failed
tracking_number required
string | null
courier_id required
string
service_code required
string
price required
Money
format required
pdf | png | zpl
size required
4x6 | letter | a4
url required
string | null

Short-lived signed URL to the label file

tracker_id required
string | null

UUIDv7

purchased_at required
string | null

RFC 3339 timestamp

voided_at required
string | null

RFC 3339 timestamp

created_at required
string

RFC 3339 timestamp

GET/v1/labels/{id}

Retrieve a label

`url` is a short-lived signed link, issued fresh on every read.

ParameterInTypeRequired
idpathstringYes
curlRetrieve a label
curl -X GET 'https://api.octoship.com/v1/labels/YOUR_id' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · Label

id required
string

UUIDv7

object required
label
mode required
Mode
shipment_id required
string

UUIDv7

rate_id required
string

UUIDv7

status required
purchasing | purchased | void_requested | voided | refunded | failed
tracking_number required
string | null
courier_id required
string
service_code required
string
price required
Money
format required
pdf | png | zpl
size required
4x6 | letter | a4
url required
string | null

Short-lived signed URL to the label file

tracker_id required
string | null

UUIDv7

purchased_at required
string | null

RFC 3339 timestamp

voided_at required
string | null

RFC 3339 timestamp

created_at required
string

RFC 3339 timestamp

GET/v1/labels/{id}/documents

Retrieve customs documents for a label

Returns fresh signed links to carrier-issued customs PDFs. An empty list means no separate forms were supplied; forms may be electronic or included on the label. Does not buy another label or create a declaration.

ParameterInTypeRequired
idpathstringYes
curlRetrieve customs documents for a label
curl -X GET 'https://api.octoship.com/v1/labels/YOUR_id/documents' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · LabelDocuments

object required
label_documents
label_id required
string

UUIDv7

documents required
object[]
GET/v1/labels

List labels

Newest first.

ParameterInTypeRequired
limitqueryintegerNo
cursorquerystringNo
shipment_idquerystringNo
statusquerypurchasing | purchased | void_requested | voided | refunded | failedNo
curlList labels
curl -X GET 'https://api.octoship.com/v1/labels' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · LabelList

object required
list
data required
Label[]
has_more required
boolean
next_cursor required
string | null
POST/v1/labels/{id}/void

Void an unused label

Cancels an unused label. Status becomes `voided` once the courier confirms (often immediately), or `void_requested` while it's pending; the label price is refunded to your balance on confirmation.

ParameterInTypeRequired
idpathstringYes
idempotency-keyheaderstringYes
curlVoid an unused label
curl -X POST 'https://api.octoship.com/v1/labels/YOUR_id/void' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"
Success responses & schemas

200 · Label

id required
string

UUIDv7

object required
label
mode required
Mode
shipment_id required
string

UUIDv7

rate_id required
string

UUIDv7

status required
purchasing | purchased | void_requested | voided | refunded | failed
tracking_number required
string | null
courier_id required
string
service_code required
string
price required
Money
format required
pdf | png | zpl
size required
4x6 | letter | a4
url required
string | null

Short-lived signed URL to the label file

tracker_id required
string | null

UUIDv7

purchased_at required
string | null

RFC 3339 timestamp

voided_at required
string | null

RFC 3339 timestamp

created_at required
string

RFC 3339 timestamp

orders

POST/v1/orders

Create a manual order

ParameterInTypeRequired
idempotency-keyheaderstringYes

JSON body

number
string

Your order number. Generated (M-…) when omitted.

customer_name
string | null
customer_email
string | null
ship_to required
AddressSnapshot
items required
OrderItemCreate[]
total
object
shipping_paid
object
weight
object | null

Total weight. Defaults to the sum of item weights.

requested_service
string | null
tags
string[]
placed_at
string | null

Defaults to now

curlCreate a manual order
curl -X POST 'https://api.octoship.com/v1/orders' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "ship_to": {
    "line1": "string",
    "city": "string",
    "country": "US"
  },
  "items": [
    {
      "title": "string",
      "quantity": 1
    }
  ]
}'
Success responses & schemas

201 · Order

id required
string

UUIDv7

object required
order
store_connection_id required
string | null

UUIDv7

platform required
StorePlatform
external_id required
string | null
number required
string
status required
awaiting | shipped | on_hold | cancelled
customer_name required
string | null
customer_email required
string | null
ship_to required
AddressSnapshot
items required
OrderItem[]
total required
object
shipping_paid required
object
weight required
Weight
requested_service required
string | null
tags required
string[]
shipping_rule required
object | null

Rule decision for this order (null until rules are evaluated)

shipment_id required
string | null

UUIDv7

placed_at required
string | null

RFC 3339 timestamp

created_at required
string

RFC 3339 timestamp

updated_at required
string

RFC 3339 timestamp

GET/v1/orders/{id}

Get an order

ParameterInTypeRequired
idpathstringYes
curlGet an order
curl -X GET 'https://api.octoship.com/v1/orders/YOUR_id' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · Order

id required
string

UUIDv7

object required
order
store_connection_id required
string | null

UUIDv7

platform required
StorePlatform
external_id required
string | null
number required
string
status required
awaiting | shipped | on_hold | cancelled
customer_name required
string | null
customer_email required
string | null
ship_to required
AddressSnapshot
items required
OrderItem[]
total required
object
shipping_paid required
object
weight required
Weight
requested_service required
string | null
tags required
string[]
shipping_rule required
object | null

Rule decision for this order (null until rules are evaluated)

shipment_id required
string | null

UUIDv7

placed_at required
string | null

RFC 3339 timestamp

created_at required
string

RFC 3339 timestamp

updated_at required
string

RFC 3339 timestamp

GET/v1/orders/counts

Order counts by status

ParameterInTypeRequired
platformqueryStorePlatformNo
store_connection_idquerystringNo
curlOrder counts by status
curl -X GET 'https://api.octoship.com/v1/orders/counts' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · OrderCounts

object required
order_counts
awaiting required
integer
shipped required
integer
on_hold required
integer
cancelled required
integer
POST/v1/orders/import

Import orders from CSV

Valid orders are saved; invalid ones are reported per row and skipped. Idempotent per order number.

ParameterInTypeRequired
idempotency-keyheaderstringYes

JSON body

csv required
string

CSV text with a header row. Columns (case-insensitive; common aliases accepted): order_number*, name, email, company, address1*, address2, city*, state, postal_code, country*, phone, sku, item*, quantity, unit_price, currency, weight, weight_unit (oz|lb|g|kg), tags (comma-separated), requested_service, placed_at. Rows sharing an order_number become line items of one order. Re-importing an order number already imported is skipped.

dry_run
boolean

Validate and report without saving

curlImport orders from CSV
curl -X POST 'https://api.octoship.com/v1/orders/import' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "csv": "string"
}'
Success responses & schemas

200 · OrderImportResult

object required
order_import
dry_run required
boolean
rows required
integer
orders_found required
integer
created required
integer
duplicates required
integer

Already imported; left unchanged

failed required
integer
order_ids required
string[]

Ids of created orders (empty on dry runs)

errors required
OrderImportError[]
GET/v1/orders

List orders

Newest first (by placed date). Filter by status, platform, store connection, destination or a search term.

ParameterInTypeRequired
limitqueryintegerNo
cursorquerystringNo
statusqueryOrderStatusNo
platformqueryStorePlatformNo
store_connection_idquerystringNo
destination_countryquerystringNo
qquerystringNo
curlList orders
curl -X GET 'https://api.octoship.com/v1/orders' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · OrderList

object required
list
data required
Order[]
has_more required
boolean
next_cursor required
string | null
PATCH/v1/orders/{id}

Update an order

Hold, release or cancel an order, or fix its address, weight or tags. Shipped orders can't be changed.

ParameterInTypeRequired
idpathstringYes
idempotency-keyheaderstringYes

JSON body

status
awaiting | on_hold | cancelled

Orders become `shipped` when a label is bought

customer_name
string | null
customer_email
string | null
ship_to
AddressSnapshot
weight
Weight
requested_service
string | null
tags
string[]
curlUpdate an order
curl -X PATCH 'https://api.octoship.com/v1/orders/YOUR_id' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'
Success responses & schemas

200 · Order

id required
string

UUIDv7

object required
order
store_connection_id required
string | null

UUIDv7

platform required
StorePlatform
external_id required
string | null
number required
string
status required
awaiting | shipped | on_hold | cancelled
customer_name required
string | null
customer_email required
string | null
ship_to required
AddressSnapshot
items required
OrderItem[]
total required
object
shipping_paid required
object
weight required
Weight
requested_service required
string | null
tags required
string[]
shipping_rule required
object | null

Rule decision for this order (null until rules are evaluated)

shipment_id required
string | null

UUIDv7

placed_at required
string | null

RFC 3339 timestamp

created_at required
string

RFC 3339 timestamp

updated_at required
string

RFC 3339 timestamp

package presets

POST/v1/package_presets

Create a package preset

With `is_default: true` it replaces the store's current default preset.

ParameterInTypeRequired
idempotency-keyheaderstringYes

JSON body

name required
string
type
box | envelope | poly_mailer | tube | flat_rate | pallet | other
dimensions
Dimensions
weight
Weight
is_default
boolean
curlCreate a package preset
curl -X POST 'https://api.octoship.com/v1/package_presets' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "name": "string"
}'
Success responses & schemas

201 · PackagePreset

id required
string

UUIDv7

object required
package_preset
name required
string
type required
box | envelope | poly_mailer | tube | flat_rate | pallet | other
dimensions required
Dimensions
weight required
object | null

Empty packaging weight, added to item weight

is_default required
boolean
created_at required
string

RFC 3339 timestamp

DELETE/v1/package_presets/{id}

Delete a package preset

Shipments already created with it keep their dimensions. Rules that pointed at it fall back to the order's own package.

ParameterInTypeRequired
idpathstringYes
idempotency-keyheaderstringYes
curlDelete a package preset
curl -X DELETE 'https://api.octoship.com/v1/package_presets/YOUR_id' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"
Success responses & schemas

200 · object

id required
string

UUIDv7

object required
package_preset
deleted required
true
GET/v1/package_presets/{id}

Retrieve a package preset

ParameterInTypeRequired
idpathstringYes
curlRetrieve a package preset
curl -X GET 'https://api.octoship.com/v1/package_presets/YOUR_id' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · PackagePreset

id required
string

UUIDv7

object required
package_preset
name required
string
type required
box | envelope | poly_mailer | tube | flat_rate | pallet | other
dimensions required
Dimensions
weight required
object | null

Empty packaging weight, added to item weight

is_default required
boolean
created_at required
string

RFC 3339 timestamp

GET/v1/package_presets

List package presets

The default preset first, then by name.

ParameterInTypeRequired
limitqueryintegerNo
cursorquerystringNo
curlList package presets
curl -X GET 'https://api.octoship.com/v1/package_presets' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · PackagePresetList

object required
list
data required
PackagePreset[]
has_more required
boolean
next_cursor required
string | null
PATCH/v1/package_presets/{id}

Update a package preset

ParameterInTypeRequired
idpathstringYes
idempotency-keyheaderstringYes

JSON body

name
string
type
box | envelope | poly_mailer | tube | flat_rate | pallet | other
dimensions
Dimensions
weight
Weight
is_default
boolean
curlUpdate a package preset
curl -X PATCH 'https://api.octoship.com/v1/package_presets/YOUR_id' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'
Success responses & schemas

200 · PackagePreset

id required
string

UUIDv7

object required
package_preset
name required
string
type required
box | envelope | poly_mailer | tube | flat_rate | pallet | other
dimensions required
Dimensions
weight required
object | null

Empty packaging weight, added to item weight

is_default required
boolean
created_at required
string

RFC 3339 timestamp

balance

POST/v1/balance/top_ups

Top up the balance

Charges the saved payment method. The balance is credited once the payment succeeds.

ParameterInTypeRequired
idempotency-keyheaderstringYes

JSON body

amount required
object
payment_method_id
string

Saved payment method; defaults to the store's default

curlTop up the balance
curl -X POST 'https://api.octoship.com/v1/balance/top_ups' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "amount": {
    "amount": 2500,
    "currency": "USD"
  }
}'
Success responses & schemas

201 · Payment

id required
string

UUIDv7

object required
payment
kind required
top_up | auto_reload | refund
status required
pending | succeeded | failed | refunded | disputed
amount required
Money
failure_reason required
string | null
client_secret
string | null

Present on top-up creation when additional card authentication is needed. Never log or share.

receipt_url required
string | null
created_at required
string

RFC 3339 timestamp

GET/v1/balance

Retrieve the postage balance

Available funds, funds held for labels being purchased, and auto-reload settings, for one currency.

ParameterInTypeRequired
currencyquerystringNo
curlRetrieve the postage balance
curl -X GET 'https://api.octoship.com/v1/balance' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · Balance

object required
balance
available required
Money
reserved required
object

Held for labels being purchased

auto_reload required
object | null
GET/v1/balance/transactions

List balance transactions

Every change to the balance, newest first: top-ups, label charges, refunds, fees and adjustments.

ParameterInTypeRequired
limitqueryintegerNo
cursorquerystringNo
currencyquerystringNo
curlList balance transactions
curl -X GET 'https://api.octoship.com/v1/balance/transactions' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · BalanceTransactionList

object required
list
data required
BalanceTransaction[]
has_more required
boolean
next_cursor required
string | null

webhooks

POST/v1/webhook_endpoints

Create a webhook endpoint

Only HTTPS destinations are accepted. The signing secret is returned on creation; keep it secure. Endpoint mode must match the authenticated mode.

ParameterInTypeRequired
idempotency-keyheaderstringYes

JSON body

url required
string
description
string | null
mode required
test | live
events required
EventType[]
curlCreate a webhook endpoint
curl -X POST 'https://api.octoship.com/v1/webhook_endpoints' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "url": "https://example.com/webhooks",
  "mode": "test",
  "events": [
    "label.created",
    "tracker.updated"
  ]
}'
Success responses & schemas

201 · WebhookEndpointWithSecret

id required
string

UUIDv7

object required
webhook_endpoint
url required
string
description required
string | null
mode required
test | live
events required
EventType[]
status required
enabled | disabled | auto_disabled
created_at required
string

RFC 3339 timestamp

signing_secret required
string
DELETE/v1/webhook_endpoints/{id}

Delete a webhook endpoint

ParameterInTypeRequired
idpathstringYes
idempotency-keyheaderstringYes
curlDelete a webhook endpoint
curl -X DELETE 'https://api.octoship.com/v1/webhook_endpoints/YOUR_id' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"
Success responses & schemas

200 · object

id required
string

UUIDv7

object required
webhook_endpoint
deleted required
true
GET/v1/webhook_endpoints/{id}

Retrieve a webhook endpoint

ParameterInTypeRequired
idpathstringYes
curlRetrieve a webhook endpoint
curl -X GET 'https://api.octoship.com/v1/webhook_endpoints/YOUR_id' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · WebhookEndpoint

id required
string

UUIDv7

object required
webhook_endpoint
url required
string
description required
string | null
mode required
test | live
events required
EventType[]
status required
enabled | disabled | auto_disabled
created_at required
string

RFC 3339 timestamp

GET/v1/webhook_endpoints/{id}/deliveries

List webhook deliveries

ParameterInTypeRequired
idpathstringYes
limitqueryintegerNo
cursorquerystringNo
statusquerypending | succeeded | failed | retryingNo
curlList webhook deliveries
curl -X GET 'https://api.octoship.com/v1/webhook_endpoints/YOUR_id/deliveries' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · WebhookDeliveryList

object required
list
data required
WebhookDelivery[]
has_more required
boolean
next_cursor required
string | null
GET/v1/webhook_endpoints

List webhook endpoints

ParameterInTypeRequired
limitqueryintegerNo
cursorquerystringNo
modequerytest | liveNo
curlList webhook endpoints
curl -X GET 'https://api.octoship.com/v1/webhook_endpoints' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · WebhookEndpointList

object required
list
data required
WebhookEndpoint[]
has_more required
boolean
next_cursor required
string | null
POST/v1/webhook_endpoints/{id}/deliveries/{delivery_id}/replay

Replay a webhook delivery

Schedules a new delivery attempt using the original event ID and payload. Receivers must deduplicate by event ID.

ParameterInTypeRequired
idpathstringYes
delivery_idpathstringYes
idempotency-keyheaderstringYes
curlReplay a webhook delivery
curl -X POST 'https://api.octoship.com/v1/webhook_endpoints/YOUR_id/deliveries/YOUR_delivery_id/replay' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"
Success responses & schemas

202 · WebhookDelivery

id required
string

UUIDv7

object required
webhook_delivery
endpoint_id required
string

UUIDv7

event_id required
string

UUIDv7

event_type required
EventType
status required
pending | succeeded | failed | retrying
attempts required
integer
last_response_status required
integer | null
next_attempt_at required
string | null

RFC 3339 timestamp

delivered_at required
string | null

RFC 3339 timestamp

created_at required
string

RFC 3339 timestamp

PATCH/v1/webhook_endpoints/{id}

Update a webhook endpoint

ParameterInTypeRequired
idpathstringYes
idempotency-keyheaderstringYes

JSON body

url
string
description
string | null
events
EventType[]
status
enabled | disabled
curlUpdate a webhook endpoint
curl -X PATCH 'https://api.octoship.com/v1/webhook_endpoints/YOUR_id' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'
Success responses & schemas

200 · WebhookEndpoint

id required
string

UUIDv7

object required
webhook_endpoint
url required
string
description required
string | null
mode required
test | live
events required
EventType[]
status required
enabled | disabled | auto_disabled
created_at required
string

RFC 3339 timestamp

reports

POST/v1/reports/spend/exports

Export postage spend as CSV

ParameterInTypeRequired
idempotency-keyheaderstringYes

JSON body

from required
string

First UTC day, inclusive

to required
string

Last UTC day, exclusive; at most 366 days after from

currency
string

ISO 4217

curlExport postage spend as CSV
curl -X POST 'https://api.octoship.com/v1/reports/spend/exports' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "from": "string",
  "to": "string"
}'
Success responses & schemas

201 · SpendReportExport

object required
report_export
url required
string
expires_at required
string

RFC 3339 timestamp

content_type required
text/csv
GET/v1/reports/spend

Report postage spend by carrier, service and week

Ledger-backed totals for the authenticated store and mode. Refunds are reported when settled. All amounts use minor units.

ParameterInTypeRequired
fromquerystringYes
toquerystringYes
currencyquerystringNo
curlReport postage spend by carrier, service and week
curl -X GET 'https://api.octoship.com/v1/reports/spend' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · SpendReport

object required
spend_report
from required
string
to required
string
currency required
string

ISO 4217

totals required
object
groups required
object[]

shipments

GET/v1/shipments/{id}

Retrieve a shipment

ParameterInTypeRequired
idpathstringYes
curlRetrieve a shipment
curl -X GET 'https://api.octoship.com/v1/shipments/YOUR_id' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · Shipment

id required
string

UUIDv7

object required
shipment
mode required
Mode
status required
draft | rated | purchasing | purchased | voided | failed
from_address required
AddressSnapshot
to_address required
AddressSnapshot
return_address required
object
parcel required
Parcel
options required
ShipmentOptions
customs required
object
order_id required
string | null

UUIDv7

selected_rate_id required
string | null

UUIDv7

label_id required
string | null

UUIDv7

metadata required
Metadata
created_at required
string

RFC 3339 timestamp

updated_at required
string

RFC 3339 timestamp

GET/v1/shipments

List shipments

Newest first.

ParameterInTypeRequired
limitqueryintegerNo
cursorquerystringNo
statusquerydraft | rated | purchasing | purchased | voided | failedNo
curlList shipments
curl -X GET 'https://api.octoship.com/v1/shipments' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · ShipmentList

object required
list
data required
Shipment[]
has_more required
boolean
next_cursor required
string | null

tracking

GET/v1/trackers/{id}

Retrieve a tracker

Includes the full event timeline, oldest first.

ParameterInTypeRequired
idpathstringYes
curlRetrieve a tracker
curl -X GET 'https://api.octoship.com/v1/trackers/YOUR_id' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · Tracker

id required
string

UUIDv7

object required
tracker
mode required
Mode
tracking_number required
string
courier_id required
string
status required
unknown | label_created | in_transit | out_for_delivery | delivered | exception | returned
shipment_id required
string | null

UUIDv7

label_id required
string | null

UUIDv7

estimated_delivery_at required
string | null

RFC 3339 timestamp

delivered_at required
string | null

RFC 3339 timestamp

public_url required
string | null

Branded tracking page

events required
TrackingEvent[]
created_at required
string

RFC 3339 timestamp

updated_at required
string

RFC 3339 timestamp

GET/v1/trackers

List trackers

Most recently updated first. `events` is empty in list responses; retrieve a tracker for its timeline.

ParameterInTypeRequired
limitqueryintegerNo
cursorquerystringNo
statusqueryunknown | label_created | in_transit | out_for_delivery | delivered | exception | returnedNo
tracking_numberquerystringNo
curlList trackers
curl -X GET 'https://api.octoship.com/v1/trackers' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY"
Success responses & schemas

200 · TrackerList

object required
list
data required
Tracker[]
has_more required
boolean
next_cursor required
string | null

rates

POST/v1/rates

Rate a shipment

Saves the shipment (status `rated`) and returns live rates from every courier available at its origin, cheapest first, in your store's currency. Couriers that fail to quote are listed in `messages`; the rest are still returned.

ParameterInTypeRequired
idempotency-keyheaderstringYes

JSON body

from_address
object

Defaults to the store's default ship-from address

to_address required
AddressSnapshot
return_address
object
parcel required
Parcel
options
ShipmentOptions
customs
object
order_id
string | null

UUIDv7

metadata
Metadata
curlRate a shipment
curl -X POST 'https://api.octoship.com/v1/rates' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "from_address": {
    "name": "Octoship sender",
    "line1": "1 Market St",
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94105",
    "country": "US",
    "phone": "+14155550100"
  },
  "to_address": {
    "name": "Test recipient",
    "line1": "350 5th Ave",
    "city": "New York",
    "region": "NY",
    "postal_code": "10118",
    "country": "US",
    "phone": "+12125550100"
  },
  "parcel": {
    "weight": {
      "value": 12,
      "unit": "oz"
    }
  }
}'
Success responses & schemas

200 · RateQuote

object required
rate_quote
shipment required
Shipment
rates required
Rate[]
messages required
RateMessage[]
POST/v1/shipments/{id}/rates

Re-rate a shipment

Fresh rates for an existing shipment (e.g. after its rates expired).

ParameterInTypeRequired
idpathstringYes
idempotency-keyheaderstringYes
curlRe-rate a shipment
curl -X POST 'https://api.octoship.com/v1/shipments/YOUR_id/rates' \
  -H "Authorization: Bearer $OCTOSHIP_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"
Success responses & schemas

200 · RateQuote

object required
rate_quote
shipment required
Shipment
rates required
Rate[]
messages required
RateMessage[]

Verify webhook events

Register an HTTPS endpoint on port 443. Save the signing secret returned on creation. Events contain id, type, mode, created_at and data.object. Respond with a 2xx within 10 seconds; failed deliveries retry with backoff for up to three days. After 50 consecutive failures the endpoint is disabled. Enable it after fixing the receiver and replay failed deliveries.

label.createdlabel.voidedtracker.updatedorder.importedbalance.lowbatch.completed

Verify the Octoship-Signature header against the exact raw bytes and reject timestamps outside a five-minute window. Replays keep the event ID and payload but carry a fresh signing timestamp. Store event IDs durably so retries cannot duplicate your side effects.

jsNode.js · signature verification
import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(rawBody, header, secret) {
  if (typeof header !== "string" || header.length > 2048) return false;
  const parts = header.split(",").map((p) => p.trim());
  const times = parts.filter((p) => p.startsWith("t="));
  if (times.length !== 1 || !/^t=[0-9]{1,12}$/.test(times[0])) return false;
  const timestamp = Number(times[0].slice(2));
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
  const expected = createHmac("sha256", secret)
    .update(timestamp + ".").update(rawBody).digest();
  return parts.filter((p) => /^v1=[a-f0-9]{64}$/.test(p))
    .some((p) => timingSafeEqual(expected, Buffer.from(p.slice(3), "hex")));
}
// Verify the raw request bytes BEFORE JSON parsing.
// After verifying, deduplicate the event id before applying any effects.

Errors & pagination

jsonError envelope
{
  "error": {
    "type": "invalid_request",
    "code": "validation_failed",
    "message": "Invalid request.",
    "request_id": "req_0193a5c46f7e7d4b9c1a3e2f1a0b9c8d"
  }
}

Use the error code to decide what to do next, and include request_id when contacting support. For network failures or 5xx responses, retry with the original idempotency key. A pending or uncertain operation may require reconciliation before it can finish.

List responses contain data, has_more and next_cursor. Pass next_cursor as the next request’s cursor, keeping the same filters and mode. Cursors are opaque; do not construct them yourself.