Skip to main content
POST
JavaScript

Authorizations

Authorization
string
header
required

An Account API key, account-scoped JWT, App API key, or user OAuth token. Prepend the key or token with Bearer, for example Bearer ***************************.

Headers

Idempotency-Key
string

A unique key that makes this request safe to retry. See Idempotent requests.

Maximum string length: 255
Example:

"d9105228-4a08-46b1-8b91-42fed586d383"

Api-Version-Date
string

Pins the request to a dated API version.

Example:

"2026-08-13"

Body

application/json
payment_id
string
required

The payment to attach the shipment to, prefixed pay_.

Example:

"pay_xxxxxxxxxxxxxx"

tracking_number
string
required

The carrier-assigned tracking number.

Example:

"1Z999AA10123456784"

account_id
string

The unique identifier of the account, prefixed biz_.

Example:

"biz_xxxxxxxxxxxxxx"

Response

shipment created

account_id
string
required

The account that owns this shipment, prefixed biz_.

Example:

"biz_xxxxxxxxxxxxxx"

carrier
string | null
required

The shipping carrier detected for this shipment. Null until a tracking update identifies it.

Example:

"ups"

checkpoints
object[]
required
created_at
string
required

The datetime the shipment was created (ISO 8601).

Example:

"2026-01-01T12:00:00.000Z"

id
string
required

Shipment ID, prefixed ship_.

Example:

"ship_xxxxxxxxxxxxxx"

payment_id
string
required

The payment this shipment fulfills, prefixed pay_.

Example:

"pay_xxxxxxxxxxxxxx"

status
enum<string>
required

The current delivery status of this shipment.

Available options:
unknown,
pre_transit,
in_transit,
out_for_delivery,
delivered,
available_for_pickup,
return_to_sender,
failure,
cancelled,
error
Example:

"in_transit"

tracking_number
string
required

The carrier-assigned tracking number used to look up shipment progress.

Example:

"1Z999AA10123456784"

tracking_url
string
required

A customer-facing URL to track this shipment's progress.

Example:

"https://track.aftership.com/xxxxxxxxxxxxxxxxxx"

updated_at
string
required

The datetime the shipment was last updated (ISO 8601).

Example:

"2026-01-01T12:00:00.000Z"