Sign in
Shipments

Create Shipment

Attaches a carrier tracking number to a payment and begins tracking it.

post/shipments

Headers

Idempotency-Keystring
Example:d9105228-4a08-46b1-8b91-42fed586d383

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

Request body

account_idstring

The unique identifier of the account, prefixed biz_.

payment_idstring required

The payment to attach the shipment to, prefixed pay_.

tracking_numberstring required

The carrier-assigned tracking number.

Example request

{
  "account_id": "biz_xxxxxxxxxxxxxx",
  "payment_id": "pay_xxxxxxxxxxxxxx",
  "tracking_number": "1Z999AA10123456784"
}

Response

shipment created

account_idstring required

The account that owns this shipment, prefixed biz_.

carrierstring nullable required

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

created_atstring required

The datetime the shipment was created (ISO 8601).

idstring required

Shipment ID, prefixed ship_.

payment_idstring required

The payment this shipment fulfills, prefixed pay_.

status'unknown' | 'pre_transit' | 'in_transit' | 'out_for_delivery' | 'delivered' | 'available_for_pickup' | 'return_to_sender' | 'failure' | 'cancelled' | 'error' required

The current delivery status of this shipment.

tracking_numberstring required

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

tracking_urlstring required

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

updated_atstring required

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

Example response

{
  "account_id": "biz_xxxxxxxxxxxxxx",
  "carrier": "ups",
  "checkpoints": [
    {
      "location": "PHILADELPHIA, PA",
      "message": "Picked up",
      "status": "in_transit",
      "timestamp": "2026-01-01T12:00:00.000Z"
    }
  ],
  "created_at": "2026-01-01T12:00:00.000Z",
  "id": "ship_xxxxxxxxxxxxxx",
  "payment_id": "pay_xxxxxxxxxxxxxx",
  "status": "in_transit",
  "tracking_number": "1Z999AA10123456784",
  "tracking_url": "https://track.aftership.com/xxxxxxxxxxxxxxxxxx",
  "updated_at": "2026-01-01T12:00:00.000Z"
}

Changes

Changed in 5 of the 74 revisions of this API.3814

  • ae20b30817de1See the full diff
    • ○

      added the non-success response with the status

      response-non-success-status-added

  • db0883548bc51See the full diff
    • ○

      added the required property to the response with the status

      response-required-property-added

  • f1020c3ecda43See the full diff
    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    This revision also has 9 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 099fdc3be422289See the full diff
    • ▲

      added the new required request property

      new-required-request-property

    • ▲

      removed the success response with the status

      response-success-status-removed

    • ●

      removed the request property

      request-property-removed

    • ●

      removed the request property

      request-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ○

      the security scope payment:basic:read was removed from the endpoint's security scheme bearerAuth

      api-security-scope-removed

    • ○

      added the new optional header request parameter Api-Version-Date to all path's operations

      new-optional-request-default-parameter-to-existing-path

    • ○

      added the new optional header request parameter Idempotency-Key

      new-optional-request-parameter

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      removed the non-success response with the status

      response-non-success-status-removed

    • ○

      removed the non-success response with the status

      response-non-success-status-removed

    • ○

      removed the non-success response with the status

      response-non-success-status-removed

    • ○

      removed the non-success response with the status

      response-non-success-status-removed

    • ○

      added the success response with the status

      response-success-status-added

    This revision also has 4 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 60bbb4a6ffbc1See the full diff
    • ▲

      removed the required property from the response with the status

      response-required-property-removed

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Of the 74 revisions, 1 has no diff computed.