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.
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.
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
/v1/shipping_rules/applyApply 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.
| Parameter | In | Type | Required |
|---|---|---|---|
| idempotency-key | header | string | Yes |
JSON body
- order_ids
- string[]
Defaults to every order awaiting shipment
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)
/v1/shipping_rulesCreate a shipping rule
Added at `position` (default: last); later rules shift down.
| Parameter | In | Type | Required |
|---|---|---|---|
| idempotency-key | header | string | Yes |
JSON body
- name required
- string
- position
- integer
- enabled
- boolean
- conditions required
- ShippingRuleCondition[]
- action required
- ShippingRuleAction
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
/v1/shipping_rules/{id}Delete a shipping rule
| Parameter | In | Type | Required |
|---|---|---|---|
| id | path | string | Yes |
| idempotency-key | header | string | Yes |
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
/v1/shipping_rules/{id}Retrieve a shipping rule
| Parameter | In | Type | Required |
|---|---|---|---|
| id | path | string | Yes |
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
/v1/shipping_rulesList shipping rules
Every rule in evaluation order (first match wins; no match → cheapest rate). Not paginated (at most 200 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
/v1/shipping_rules/reorderReorder shipping rules
Send every rule id in the new order.
| Parameter | In | Type | Required |
|---|---|---|---|
| idempotency-key | header | string | Yes |
JSON body
- ids required
- string[]
Every rule id, in the new evaluation order
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
/v1/shipping_rules/{id}Update a shipping rule
| Parameter | In | Type | Required |
|---|---|---|---|
| id | path | string | Yes |
| idempotency-key | header | string | Yes |
JSON body
- name
- string
- enabled
- boolean
- conditions
- ShippingRuleCondition[]
- action
- ShippingRuleAction
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
/v1/store_connectionsStart 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.
| Parameter | In | Type | Required |
|---|---|---|---|
| idempotency-key | header | string | Yes |
JSON body
object | object
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
/v1/store_connections/{id}Disconnect a store
Stops importing orders and revokes our access to the store. Orders already imported stay.
| Parameter | In | Type | Required |
|---|---|---|---|
| id | path | string | Yes |
| idempotency-key | header | string | Yes |
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
/v1/store_connections/{id}Retrieve a store connection
| Parameter | In | Type | Required |
|---|---|---|---|
| id | path | string | Yes |
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
/v1/store_connectionsList connected stores
Stores and marketplaces orders are imported from. Use `getOrderCounts?store_connection_id=` for per-store order counts.
| Parameter | In | Type | Required |
|---|---|---|---|
| limit | query | integer | No |
| cursor | query | string | No |
| platform | query | StorePlatform | No |
| include_disconnected | query | true | false | No |
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
/v1/store_connections/{id}/syncSync orders now
Queues an import of orders changed since the last sync. Orders also arrive in real time through platform webhooks.
| Parameter | In | Type | Required |
|---|---|---|---|
| id | path | string | Yes |
| idempotency-key | header | string | Yes |
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
/v1/addressesSave an address
With `is_default_from: true` it becomes the store's default ship-from address, replacing the previous one.
| Parameter | In | Type | Required |
|---|---|---|---|
| idempotency-key | header | string | Yes |
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
- string | null
- residential
- boolean | null
- label
- string | null
- is_default_from
- boolean
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
- 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
/v1/addresses/{id}Delete a saved address
| Parameter | In | Type | Required |
|---|---|---|---|
| id | path | string | Yes |
| idempotency-key | header | string | Yes |
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
/v1/addresses/{id}Retrieve a saved address
| Parameter | In | Type | Required |
|---|---|---|---|
| id | path | string | Yes |
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
- 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
/v1/addressesList saved addresses
The default ship-from address first, then newest first.
| Parameter | In | Type | Required |
|---|---|---|---|
| limit | query | integer | No |
| cursor | query | string | No |
| default_from | query | true | false | No |
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
/v1/addresses/{id}Update a saved address
Shipments keep the address as it was when they were created.
| Parameter | In | Type | Required |
|---|---|---|---|
| id | path | string | Yes |
| idempotency-key | header | string | Yes |
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
- string | null
- residential
- boolean | null
- label
- string | null
- is_default_from
- boolean
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
- 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
/v1/addresses/validateValidate 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.
| Parameter | In | Type | Required |
|---|---|---|---|
| idempotency-key | header | string | Yes |
JSON body
- address required
- object
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
/v1/batchesBuy 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.
| Parameter | In | Type | Required |
|---|---|---|---|
| idempotency-key | header | string | Yes |
JSON body
- rate_ids required
- string[]
- format
- pdf
- size
- 4x6 | letter | a4
- name
- string | null
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
/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.
| Parameter | In | Type | Required |
|---|---|---|---|
| id | path | string | Yes |
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
/v1/batchesList label batches
| Parameter | In | Type | Required |
|---|---|---|---|
| limit | query | integer | No |
| cursor | query | string | No |
| status | query | pending | processing | completed | partial | failed | No |
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
/v1/batches/{id}/itemsList batch results
Returns each selected rate, its label when allocated, and a customer-safe failure when applicable.
| Parameter | In | Type | Required |
|---|---|---|---|
| id | path | string | Yes |
| limit | query | integer | No |
| cursor | query | string | No |
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
/v1/batches/lookupRecover 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.
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
/v1/billing/card_setupStart saving a payment card
| Parameter | In | Type | Required |
|---|---|---|---|
| idempotency-key | header | string | Yes |
JSON body
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
/v1/billing/payment_methods/{id}Remove a saved payment card
| Parameter | In | Type | Required |
|---|---|---|---|
| id | path | string | Yes |
| idempotency-key | header | string | Yes |
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
/v1/billingRetrieve 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
/v1/payments/{id}/receiptDownload a payment receipt
| Parameter | In | Type | Required |
|---|---|---|---|
| id | path | string | Yes |
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
/v1/billing/payment_methodsList 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[]
/v1/paymentsList payments
| Parameter | In | Type | Required |
|---|---|---|---|
| limit | query | integer | No |
| cursor | query | string | No |
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
/v1/billingUpdate saved card and auto-reload settings
| Parameter | In | Type | Required |
|---|---|---|---|
| idempotency-key | header | string | Yes |
JSON body
- default_payment_method_id
- string | null
- auto_reload
- object
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
/v1/labelsBuy 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.
| Parameter | In | Type | Required |
|---|---|---|---|
| idempotency-key | header | string | Yes |
JSON body
- rate_id required
- string
UUIDv7
- format
- pdf | png | zpl
- size
- 4x6 | letter | a4
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
/v1/labels/{id}Retrieve a label
`url` is a short-lived signed link, issued fresh on every read.
| Parameter | In | Type | Required |
|---|---|---|---|
| id | path | string | Yes |
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
/v1/labels/{id}/documentsRetrieve 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.
| Parameter | In | Type | Required |
|---|---|---|---|
| id | path | string | Yes |
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[]
/v1/labelsList labels
Newest first.
| Parameter | In | Type | Required |
|---|---|---|---|
| limit | query | integer | No |
| cursor | query | string | No |
| shipment_id | query | string | No |
| status | query | purchasing | purchased | void_requested | voided | refunded | failed | No |
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
/v1/labels/{id}/voidVoid 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.
| Parameter | In | Type | Required |
|---|---|---|---|
| id | path | string | Yes |
| idempotency-key | header | string | Yes |
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
/v1/ordersCreate a manual order
| Parameter | In | Type | Required |
|---|---|---|---|
| idempotency-key | header | string | Yes |
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
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
/v1/orders/{id}Get an order
| Parameter | In | Type | Required |
|---|---|---|---|
| id | path | string | Yes |
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
/v1/orders/countsOrder counts by status
| Parameter | In | Type | Required |
|---|---|---|---|
| platform | query | StorePlatform | No |
| store_connection_id | query | string | No |
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
/v1/orders/importImport orders from CSV
Valid orders are saved; invalid ones are reported per row and skipped. Idempotent per order number.
| Parameter | In | Type | Required |
|---|---|---|---|
| idempotency-key | header | string | Yes |
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
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[]
/v1/ordersList orders
Newest first (by placed date). Filter by status, platform, store connection, destination or a search term.
| Parameter | In | Type | Required |
|---|---|---|---|
| limit | query | integer | No |
| cursor | query | string | No |
| status | query | OrderStatus | No |
| platform | query | StorePlatform | No |
| store_connection_id | query | string | No |
| destination_country | query | string | No |
| q | query | string | No |
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
/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.
| Parameter | In | Type | Required |
|---|---|---|---|
| id | path | string | Yes |
| idempotency-key | header | string | Yes |
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[]
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
/v1/package_presetsCreate a package preset
With `is_default: true` it replaces the store's current default preset.
| Parameter | In | Type | Required |
|---|---|---|---|
| idempotency-key | header | string | Yes |
JSON body
- name required
- string
- type
- box | envelope | poly_mailer | tube | flat_rate | pallet | other
- dimensions
- Dimensions
- weight
- Weight
- is_default
- boolean
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
/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.
| Parameter | In | Type | Required |
|---|---|---|---|
| id | path | string | Yes |
| idempotency-key | header | string | Yes |
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
/v1/package_presets/{id}Retrieve a package preset
| Parameter | In | Type | Required |
|---|---|---|---|
| id | path | string | Yes |
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
/v1/package_presetsList package presets
The default preset first, then by name.
| Parameter | In | Type | Required |
|---|---|---|---|
| limit | query | integer | No |
| cursor | query | string | No |
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
/v1/package_presets/{id}Update a package preset
| Parameter | In | Type | Required |
|---|---|---|---|
| id | path | string | Yes |
| idempotency-key | header | string | Yes |
JSON body
- name
- string
- type
- box | envelope | poly_mailer | tube | flat_rate | pallet | other
- dimensions
- Dimensions
- weight
- Weight
- is_default
- boolean
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
/v1/balance/top_upsTop up the balance
Charges the saved payment method. The balance is credited once the payment succeeds.
| Parameter | In | Type | Required |
|---|---|---|---|
| idempotency-key | header | string | Yes |
JSON body
- amount required
- object
- payment_method_id
- string
Saved payment method; defaults to the store's default
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
/v1/balanceRetrieve the postage balance
Available funds, funds held for labels being purchased, and auto-reload settings, for one currency.
| Parameter | In | Type | Required |
|---|---|---|---|
| currency | query | string | No |
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
/v1/balance/transactionsList balance transactions
Every change to the balance, newest first: top-ups, label charges, refunds, fees and adjustments.
| Parameter | In | Type | Required |
|---|---|---|---|
| limit | query | integer | No |
| cursor | query | string | No |
| currency | query | string | No |
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
/v1/webhook_endpointsCreate 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.
| Parameter | In | Type | Required |
|---|---|---|---|
| idempotency-key | header | string | Yes |
JSON body
- url required
- string
- description
- string | null
- mode required
- test | live
- events required
- EventType[]
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
/v1/webhook_endpoints/{id}Delete a webhook endpoint
| Parameter | In | Type | Required |
|---|---|---|---|
| id | path | string | Yes |
| idempotency-key | header | string | Yes |
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
/v1/webhook_endpoints/{id}Retrieve a webhook endpoint
| Parameter | In | Type | Required |
|---|---|---|---|
| id | path | string | Yes |
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
/v1/webhook_endpoints/{id}/deliveriesList webhook deliveries
| Parameter | In | Type | Required |
|---|---|---|---|
| id | path | string | Yes |
| limit | query | integer | No |
| cursor | query | string | No |
| status | query | pending | succeeded | failed | retrying | No |
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
/v1/webhook_endpointsList webhook endpoints
| Parameter | In | Type | Required |
|---|---|---|---|
| limit | query | integer | No |
| cursor | query | string | No |
| mode | query | test | live | No |
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
/v1/webhook_endpoints/{id}/deliveries/{delivery_id}/replayReplay a webhook delivery
Schedules a new delivery attempt using the original event ID and payload. Receivers must deduplicate by event ID.
| Parameter | In | Type | Required |
|---|---|---|---|
| id | path | string | Yes |
| delivery_id | path | string | Yes |
| idempotency-key | header | string | Yes |
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
/v1/webhook_endpoints/{id}Update a webhook endpoint
| Parameter | In | Type | Required |
|---|---|---|---|
| id | path | string | Yes |
| idempotency-key | header | string | Yes |
JSON body
- url
- string
- description
- string | null
- events
- EventType[]
- status
- enabled | disabled
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
/v1/reports/spend/exportsExport postage spend as CSV
| Parameter | In | Type | Required |
|---|---|---|---|
| idempotency-key | header | string | Yes |
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
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
/v1/reports/spendReport 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.
| Parameter | In | Type | Required |
|---|---|---|---|
| from | query | string | Yes |
| to | query | string | Yes |
| currency | query | string | No |
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
/v1/shipments/{id}Retrieve a shipment
| Parameter | In | Type | Required |
|---|---|---|---|
| id | path | string | Yes |
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
/v1/shipmentsList shipments
Newest first.
| Parameter | In | Type | Required |
|---|---|---|---|
| limit | query | integer | No |
| cursor | query | string | No |
| status | query | draft | rated | purchasing | purchased | voided | failed | No |
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
/v1/trackers/{id}Retrieve a tracker
Includes the full event timeline, oldest first.
| Parameter | In | Type | Required |
|---|---|---|---|
| id | path | string | Yes |
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
/v1/trackersList trackers
Most recently updated first. `events` is empty in list responses; retrieve a tracker for its timeline.
| Parameter | In | Type | Required |
|---|---|---|---|
| limit | query | integer | No |
| cursor | query | string | No |
| status | query | unknown | label_created | in_transit | out_for_delivery | delivered | exception | returned | No |
| tracking_number | query | string | No |
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
/v1/ratesRate 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.
| Parameter | In | Type | Required |
|---|---|---|---|
| idempotency-key | header | string | Yes |
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
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[]
/v1/shipments/{id}/ratesRe-rate a shipment
Fresh rates for an existing shipment (e.g. after its rates expired).
| Parameter | In | Type | Required |
|---|---|---|---|
| id | path | string | Yes |
| idempotency-key | header | string | Yes |
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.completedVerify 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.
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
{
"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.