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

# overboxShipmentPurchase

> Buy an overbox label: one first-mile label for an outer box that carries your labeled parcels to a consolidator. Seals into the box the parcels labeled for that consolidator from the same ship-from location since its previous overbox. Retry with the same `idempotencyKey` to get the first overbox back instead of buying another. The label is billed to the consolidator's carrier account, not your Redo balance.

**Required scopes:** [`shipping_write`](https://developers.redo.com/docs/api-reference/v3/reference/scopes#scope-shipping_write)

## Arguments

**input** `[OverboxShipmentPurchaseInput!](/docs/api-reference/v3/reference/shipping/overbox-shipment-purchase-input)` *required*

The overbox label to buy.

**fields**

**carrier** `[OverboxCarrier!](/docs/api-reference/v3/reference/shipping/overbox-carrier)` *required*

The first-mile carrier to buy the label on. Must be one `overboxServices` lists for the service.

**idempotencyKey** `String!` *required*

Unique key for this purchase (max 400 characters). Retrying with the same key returns the overbox the first call bought instead of buying another, even when the first call failed with `OVERBOX_NOT_RECORDED` or timed out; a retry while that first call is still running fails with `PURCHASE_IN_PROGRESS`, and the same key with a different request fails with `IDEMPOTENCY_KEY_REUSED`. Always retry a purchase with its own key: if the first call stopped after the label was bought, a retry five minutes later recovers that label instead of buying another. Start a new key only for a new purchase.

**parcel** `[OverboxParcelInput!](/docs/api-reference/v3/reference/shipping/overbox-parcel-input)` *required*

The outer box.

**fields**

**height** `[DimensionInput!](/docs/api-reference/v3/reference/catalog/dimension-input)` *required*

The box's height.

**length** `[DimensionInput!](/docs/api-reference/v3/reference/catalog/dimension-input)` *required*

The box's length.

**weight** `[WeightInput!](/docs/api-reference/v3/reference/catalog/weight-input)` *required*

The packed box's total weight.

**width** `[DimensionInput!](/docs/api-reference/v3/reference/catalog/dimension-input)` *required*

The box's width.

**service** `[OverboxService!](/docs/api-reference/v3/reference/shipping/overbox-service)` *required*

The consolidator to ship the box to. Must be one `overboxServices` lists.

**shipFromLocationId** `ID`

The `Location` the box ships from. It sets the label's from-address and limits the parcels sealed inside to that location's. Omit to ship from your account address and seal parcels from every location.

**shipmentIds** `[ID!]`

The labeled packages to seal into this box (max 200): `CarrierShipmentTracker` ids for labels bought with `purchaseCarrierShipment`, or `Tracker` ids for labels bought in Redo's shipping app. Each must be a label bought on this consolidator, not voided, and not already sealed in another overbox; otherwise nothing is bought and the purchase fails with `SHIPMENT_NOT_FOUND` or `SHIPMENT_NOT_ELIGIBLE`, naming the id. Omit or send an empty list to seal the parcels labeled for this consolidator from the same ship-from location since its previous overbox.

## Returns

**overboxShipmentPurchase** `[OverboxShipment!](/docs/api-reference/v3/reference/shipping/overbox-shipment)` *required*

An overbox: one outer box, with its own first-mile label, that carries many labeled parcels to a consolidator (APC or ePost Global) in one shipment.

**fields**

**carrier** `[OverboxCarrier!](/docs/api-reference/v3/reference/shipping/overbox-carrier)` *required*

The first-mile carrier the overbox label was bought on.

**dimensions** `[Dimensions](/docs/api-reference/v3/reference/catalog/dimensions)`

The outer box's dimensions, as declared on the label.

**fields**

**height** `Float`

The height, in `unit`.

**length** `Float`

The length, in `unit`.

**unit** `[DimensionUnit!](/docs/api-reference/v3/reference/catalog/dimension-unit)` *required*

The unit all three measurements are expressed in.

**width** `Float`

The width, in `unit`.

**fulfillmentCenter** `String!` *required*

The consolidator's induction center the overbox ships to, as configured for your account (e.g. EWR).

**id** `ID!` *required*

The id of this overbox shipment.

**labelUrl** `String!` *required*

URL of the printable overbox label, a 4x6 PDF when rendering succeeds and otherwise the carrier's own label file.

**parcels** `[OverboxShipmentParcelConnection!](/docs/api-reference/v3/pagination)` *required*

The labeled parcels sealed inside the box: those labeled for this consolidator from the same ship-from location since its previous overbox. Empty for a location's first overbox.

**Requires:** [`shipping_read`](https://developers.redo.com/docs/api-reference/v3/reference/scopes#scope-shipping_read)

**fields**

**Arguments**

**after** `String`

Forward pagination cursor — returns parcels after it.

**before** `String`

Backward pagination cursor — returns parcels before it.

**first** `Int`

Forward pagination: returns the first N parcels (max 100, default 25). Use with `after`; mutually exclusive with `last`/`before`.

**last** `Int`

Backward pagination: returns the last N parcels (max 100, default 25). Use with `before`; mutually exclusive with `first`/`after`.

**Fields**

**edges** `[\[OverboxShipmentParcelEdge!\]!](/docs/api-reference/v3/pagination)` *required*

The list of edges (each a node plus its pagination `cursor`).

**fields**

**cursor** `String!` *required*

Opaque cursor for this item; pass to `after`/`before` to page from here.

**node** `[OverboxShipmentParcel!](/docs/api-reference/v3/reference/shipping/overbox-shipment-parcel)` *required*

The item at this edge.

**nodes** `[\[OverboxShipmentParcel!\]!](/docs/api-reference/v3/reference/shipping/overbox-shipment-parcel)` *required*

The nodes in this page, without the edge/cursor wrapper — a convenience over `edges`.

**fields**

**addedAt** `[DateTime!](/docs/api-reference/v3/reference/common/date-time)` *required*

When the parcel was sealed into the overbox.

**trackingNumber** `String!` *required*

The inner parcel's own carrier tracking number.

**pageInfo** `[PageInfo!](/docs/api-reference/v3/pagination)` *required*

Pagination metadata for the current page.

**fields**

**endCursor** `String`

Cursor of the last edge in this page; pass to `after` to page forward.

**hasNextPage** `Boolean!` *required*

Whether more items exist after this page (drives forward pagination with `first`/`after`).

**hasPreviousPage** `Boolean!` *required*

Whether more items exist before this page (drives backward pagination with `last`/`before`).

**startCursor** `String`

Cursor of the first edge in this page; pass to `before` to page backward.

**purchasedAt** `[DateTime!](/docs/api-reference/v3/reference/common/date-time)` *required*

When the overbox label was bought.

**service** `[OverboxService!](/docs/api-reference/v3/reference/shipping/overbox-service)` *required*

The consolidator the overbox ships to.

**status** `[OverboxShipmentStatus!](/docs/api-reference/v3/reference/shipping/overbox-shipment-status)` *required*

Where the overbox label is in its lifecycle.

**trackingNumber** `String!` *required*

The first-mile carrier's tracking number for the box.

**trackingStatus** `[OverboxTrackingStatus](/docs/api-reference/v3/reference/shipping/overbox-tracking-status)`

The first-mile carrier's latest status for the box. Null until the carrier first scans it.

**weight** `[Weight](/docs/api-reference/v3/reference/catalog/weight)`

The outer box's weight, as declared on the label.

**fields**

**unit** `[WeightUnit!](/docs/api-reference/v3/reference/catalog/weight-unit)` *required*

The unit the value is expressed in.

**value** `Float!` *required*

The numeric magnitude of the weight.

## Example

```graphql theme={null}
mutation {
  overboxShipmentPurchase(input: { ... }) {
    carrier
    fulfillmentCenter
    id
    labelUrl
    parcels {
      nodes {
        addedAt
        trackingNumber
      }
      pageInfo { hasNextPage endCursor }
    }
    purchasedAt
    service
    status
    # ...
  }
}
```


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