> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whop.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Shipment

A Shipment attaches a carrier tracking number to a payment and follows the package from label creation to delivery, exposing the current delivery status and a customer-facing tracking URL.

Use the Shipments API to list an account's shipments, retrieve one by its id or the payment it fulfills, attach a tracking number to a payment, and update the tracking number on an existing shipment.

## Endpoints

| Endpoint | Request |
| - | - |
| [List Shipments](/api-reference/beta/shipments/list-shipments) | <Badge color="blue" size="sm" stroke>GET</Badge> `/shipments` |
| [Retrieve Shipment](/api-reference/beta/shipments/retrieve-shipment) | <Badge color="blue" size="sm" stroke>GET</Badge> `/shipments/{id}` |
| [Create Shipment](/api-reference/beta/shipments/create-shipment) | <Badge color="green" size="sm" stroke>POST</Badge> `/shipments` |
| [Update Shipment](/api-reference/beta/shipments/update-shipment) | <Badge color="orange" size="sm" stroke>PATCH</Badge> `/shipments/{id}` |

## Attributes

<Columns cols={2}>
  <Column>
    <ResponseField name="id" type="string" required>
      Shipment ID, prefixed `ship_`.
    </ResponseField>

    <ResponseField name="account_id" type="string" required>
      The account that owns this shipment, prefixed `biz_`.
    </ResponseField>

    <ResponseField name="carrier" type="string | null" required>
      The shipping carrier detected for this shipment. Null until a tracking update
      identifies it.
    </ResponseField>

    <ResponseField name="checkpoints" type="object[]" required>
      Carrier scan history for this shipment, oldest scan first. Empty until the carrier reports its first scan.

      <Accordion title="Properties" defaultOpen={true}>
        <ResponseField name="location" type="string | null" required>
          Where the carrier recorded the scan, such as `PHILADELPHIA, PA`. Null when the
          carrier sent none.
        </ResponseField>

        <ResponseField name="message" type="string | null" required>
          Carrier's description of the scan, such as `Departed USPS Regional Facility`.
          Null when the carrier sent none.
        </ResponseField>

        <ResponseField name="status" type="string" required>
          Delivery status this carrier scan maps to.

          Available options: `unknown`, `pre_transit`, `in_transit`, `out_for_delivery`, `delivered`, `available_for_pickup`, `return_to_sender`, `failure`, `cancelled`, `error`
        </ResponseField>

        <ResponseField name="timestamp" type="string | null" required>
          When the carrier recorded the scan, as an ISO 8601 timestamp. Null when the carrier sent no scan time.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="created_at" type="string" required>
      The datetime the shipment was created (ISO 8601).
    </ResponseField>

    <ResponseField name="payment_id" type="string" required>
      The payment this shipment fulfills, prefixed `pay_`.
    </ResponseField>

    <ResponseField name="status" type="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`
    </ResponseField>

    <ResponseField name="tracking_number" type="string" required>
      The carrier-assigned tracking number used to look up shipment progress.
    </ResponseField>

    <ResponseField name="tracking_url" type="string" required>
      A customer-facing URL to track this shipment's progress.
    </ResponseField>

    <ResponseField name="updated_at" type="string" required>
      The datetime the shipment was last updated (ISO 8601).
    </ResponseField>
  </Column>

  <Column>
    <div className="api-resource-sticky-example">
      ```json Shipment theme={null}
      {
      	"id": "ship_xxxxxxxxxxxxxx",
      	"account_id": "biz_xxxxxxxxxxxxxx",
      	"payment_id": "pay_xxxxxxxxxxxxxx",
      	"carrier": "ups",
      	"tracking_number": "1Z999AA10123456784",
      	"tracking_url": "https://track.aftership.com/xxxxxxxxxxxxxxxxxx",
      	"status": "in_transit",
      	"checkpoints": [
      		{
      			"status": "in_transit",
      			"message": "Picked up",
      			"location": "PHILADELPHIA, PA",
      			"timestamp": "2026-09-15T16:42:00.000Z"
      		}
      	],
      	"created_at": "2026-09-15T14:30:00.000Z",
      	"updated_at": "2026-09-15T16:45:10.000Z"
      }
      ```
    </div>
  </Column>
</Columns>


## Related topics

- [Shipment](/api-reference/shipments/shipment.md)
- [Shipment created](/api-reference/shipments/shipment-created.md)
- [Shipment updated](/api-reference/shipments/shipment-updated.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.