> ## 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.

# purchaseCarrierShipment

> Buy the selected carrier/service/account rate. Returns the single carrier shipment bought, or throws if the purchase failed.

**Required scopes:** [`shipping_write`](/docs/api-reference/v3/reference/scopes#scope-shipping_write)

## Arguments

<ResponseField name="input" type={<a href="/docs/api-reference/v3/reference/shipping/purchase-carrier-shipment-input">PurchaseCarrierShipmentInput!</a>} required>
  The shipment and selected rate to buy.

  <Expandable title="fields" lazyRender>
    <ResponseField name="carrier" type="String!" required>
      Carrier of the selected rate, as returned by the quote.
    </ResponseField>

    <ResponseField name="carrierAccountId" type="String!" required>
      Carrier account the selected rate was quoted on.
    </ResponseField>

    <ResponseField name="idempotencyKey" type="String">
      Unique key for this purchase (max 400 characters). Retrying with the same key returns the original result instead of buying twice. Keys expire; do not reuse one for a new purchase. If omitted, every call buys a new label.
    </ResponseField>

    <ResponseField name="request" type={<a href="/docs/api-reference/v3/reference/shipping/outbound-shipment-request-input">OutboundShipmentRequestInput!</a>} required>
      The shipment to buy a label for.

      <Expandable title="fields" lazyRender>
        <ResponseField name="contentsSummary" type={<a href="/docs/api-reference/v3/reference/shipping/contents-summary-input">ContentsSummaryInput</a>}>
          Total declared contents. Required by carriers that want a declaration even with no customs items.
        </ResponseField>

        <ResponseField name="customs" type={<a href="/docs/api-reference/v3/reference/shipping/outbound-customs-input">OutboundCustomsInput</a>}>
          Customs declaration. Required for international shipments; carriers reject them without one.
        </ResponseField>

        <ResponseField name="deliveredDutyPaid" type="Boolean">
          Assigns who is billed for duties and import taxes: the sender (DDP) or the recipient (DAP). Does not affect the quoted or charged rate — duties are billed separately after the shipment moves. Omit to leave the choice to your carrier configuration.
        </ResponseField>

        <ResponseField name="fromAddress" type={<a href="/docs/api-reference/v3/reference/shipping/outbound-address-input">OutboundAddressInput!</a>} required>
          Ship-from address.
        </ResponseField>

        <ResponseField name="parcels" type={<a href="/docs/api-reference/v3/reference/shipping/outbound-parcel-input">[OutboundParcelInput!]!</a>} required>
          The parcels in the shipment (max 5).
        </ResponseField>

        <ResponseField name="returnAddress" type={<a href="/docs/api-reference/v3/reference/shipping/outbound-address-input">OutboundAddressInput</a>}>
          Return address, if different from the ship-from address.
        </ResponseField>

        <ResponseField name="taxIdentifiers" type={<a href="/docs/api-reference/v3/reference/shipping/tax-identifier-input">[TaxIdentifierInput!]</a>}>
          Tax identifiers for the shipment, e.g. an IOSS number for EU-bound goods.
        </ResponseField>

        <ResponseField name="toAddress" type={<a href="/docs/api-reference/v3/reference/shipping/outbound-address-input">OutboundAddressInput!</a>} required>
          Ship-to address.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="service" type="String!" required>
      Service level of the selected rate, as returned by the quote.
    </ResponseField>
  </Expandable>
</ResponseField>

## Returns

<ResponseField name="purchaseCarrierShipment" type={<a href="/docs/api-reference/v3/reference/shipping/carrier-shipment">CarrierShipment!</a>} required>
  A purchased carrier shipment and its package labels.

  <Expandable title="fields" lazyRender>
    <ResponseField name="carrier" type="String!" required>
      Carrier the label was bought from.
    </ResponseField>

    <ResponseField name="rate" type={<a href="/docs/api-reference/v3/reference/common/money">Money!</a>} required>
      Total price charged for the whole shipment. Carriage only — duties, import taxes, and customs fees are not included.

      <Expandable title="fields" lazyRender>
        <ResponseField name="amount" type={<a href="/docs/api-reference/v3/reference/common/decimal">Decimal!</a>} required>
          The exact amount as a decimal string (e.g. "19.99").
        </ResponseField>

        <ResponseField name="currency" type="String!" required>
          ISO 4217 currency code (e.g. USD).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="service" type="String!" required>
      Carrier service level bought.
    </ResponseField>

    <ResponseField name="shipmentId" type="ID!" required>
      The id of this shipment.
    </ResponseField>

    <ResponseField name="shipmentPackages" type={<a href="/docs/api-reference/v3/reference/shipping/outbound-shipment-package">[OutboundShipmentPackage!]!</a>} required>
      The packages and their labels.

      <Expandable title="fields" lazyRender>
        <ResponseField name="labelUrl" type="String!" required>
          URL of the printable label.
        </ResponseField>

        <ResponseField name="trackingNumber" type="String!" required>
          Carrier tracking number for this package.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

```graphql theme={null}
mutation {
  purchaseCarrierShipment(input: { ... }) {
    carrier
    service
    shipmentId
  }
}
```


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