✉️ Creating a Shipment

Generate a shipping label and track it — all in one step

📘 Overview

Use the rate_and_ship mutation to create a shipment, generate a label, and assign it to a batch.
This operation returns structured pricing, carrier service info, label file links, and payment handling (if required).

🛠 Mutation Format

mutation rate_and_ship($request: [RateAndShipInput!]!, $service_spec: RateAndShipServiceSpecs!) {
  rate_and_ship(request: $request, service_spec: $service_spec) {
    batch_id
    batch {
      id
      created_at
      batch_pdf_url
      payment_details {
        total_billed
        total_collected
        paid
      }
    }
    shipments {
      ... on Shipment {
        id
        tracking_number
        label {
          png {
            url
          }
        }
      }
      ... on ShipmentPaymentRequired {
        payment_link
        expires_at
      }
      ... on ShipmentError {
        code
        message
      }
    }
  }
}

📥 Required Input

The rate_and_ship mutation requires two inputs:

request: [[RateAndShipInput!]!](/developer/api-reference/type/RateAndShipInput) – one or more full shipment definitions
service_spec: [RateAndShipServiceSpecs](/developer/api-reference/type/RateAndShipServiceSpecs) – how to rate and select a carrier

🧾 `RateAndShipInput`

Each object in the request array must include:

Field	Type	Required	Description
`transaction_id`	`UUID!`	✅	Unique ID for tracking this shipment request
`package`	PackageShipmentInput!	✅	Full shipment details (addresses, packaging, weight, contents)
`override_service_spec`	RateAndShipServiceSpecs	⛔️	🧾 Rate and Ship Service Specs Defines which carrier services to rate, how to prioritize the results, and any filters to apply. This overrides the root service_spec for the specified package
`additional`	AdditionalInfoInput	⛔️	Ship Date, and any other metadata for the shipment will be added here
`carrier_specific`	ShipmentCarrierInput	⛔️	Carrier specific information, used for information not all carriers accept
`order_info`	OrderInfo	⛔️	Tracking subscriptions, order references, custom metadata

📦 `PackageShipmentInput`

Defines the physical package and routing info for the shipment.

Field	Type	Required	Description
`packaging`	Packaging!	✅	Type of package: custom box, softpack, or carrier packaging
`weight`	WeightInput!	✅	Total weight of the shipment
`content_description`	`String!`	✅	Short description of the package contents
`ship_to`	AddressInput!	✅	Recipient address
`ship_from`	AddressInput!	✅	Origin address
`return_address`	AddressInput	⛔️	Optional return address
`extra_services`	ExtraService	⛔️	Insurance, signature, etc.
`hazmat`	HazmatInfo	⛔️	Required for lithium batteries, dry ice, etc.
`customs`	CustomsInput	⛔️	Required for international shipments

📦 `Packaging`

Specifies the type of container used for the shipment.
This is a @oneOf input — only one of the following fields can be set:

Field	Type	Description
`custom_box`	BoxDimensions	Rigid box with `length`, `width`, `height`
`custom_bag`	BagDimensions	Softpack/bag with `length`, `girth`, `width`, `height`
`carrier_specific`	CarrierSpecificPackaging	Predefined packaging code from a carrier (e.g. USPS Flat Rate Envelope)

🚚 `RateAndShipServiceSpecs`

Defines which carrier services to consider and how to choose the best one.

Field	Type	Required	Description
`services`	[RateAndShipService!]!	✅	List of carriers and services to rate
`priority`	RateAndShipPriority!	✅	How to select the final rate (`CHEAPEST` or `FASTEST`)
`filters`	RateAndShipFilters	⛔️	Optional rules (e.g. max price, guaranteed delivery)

🏷️ `RateAndShipService`

Field	Type	Required	Description
`carrier`	CarrierCode!	✅	Carrier to use (e.g. `UPS`, `USPS`, `FedEx`)
`service_code`	`String!`	✅	Specific carrier service (e.g. `GND`, `PRIORITY_MAIL`)
`account_number`	`String`	⛔️	Shipper account to use for rating. Omit to use platform default (if allowed)

🔍 `RateAndShipFilters`

Optional filters to restrict which services can be selected.

Field	Type	Description
`max_cost`	`Decimal`	Exclude any rates above this value
`shipping_time`	ShippingTimeFilter	Specify a max number of days or deadline date
`shipping_time_guarantee`	ShippingTimeGuaranteeLevel	Require either estimated or guaranteed delivery

📝 `OrderInfo`

Optional metadata to associate with the shipment.

Field	Type	Description
`tracking_subscriptions`	TrackingSubscription	Email addresses to notify of shipment status
`reference_numbers`	ReferenceNumber	Order numbers, invoice IDs, etc. (earlier values take priority)
`carrier_specific`	CarrierSpecificOrderInfo	Extra metadata supported by specific carriers
`carrier_dependent`	CarrierDependentOrderInfo	May be ignored by some carriers (e.g. delivery notes)

⚙️ `AdditionalInfoInput`

Additional information about the Shipment

Field	Type	Description
`ship_date`	`DateTime`	The DateTime you expect to ship the package

🎯 `ShipmentCarrierInput`

Carrier-specific options that affect how the shipment is processed.
Each field is an optional nested input tailored to a specific carrier.

Field	Type	Description
`usps`	UspsShipmentInput	USPS-specific settings like container type or entry facility
`fedex`	FedExShipmentInput	FedEx-specific preferences like drop-off type or special services
`dhl_exp`	DhlExpShipmentInput	DHL Express options such as duties payment or label format

📦 What You Get Back

The response includes a batch, which contains one or more shipments.
Each shipment will be one of the following:

✅ Shipment: fully purchased with label and tracking
💳 ShipmentPaymentRequired: label is ready, but payment must be completed first
❌ ShipmentError: something went wrong, like an invalid address or unsupported service

✅ Successful Shipment

{
    "data": {
        "rate_and_ship": {
            "batch_id": "5e7a131e-a21e-47f8-a09b-7abb92a2bca7",
            "batch": {
                "id": "5e7a131e-a21e-47f8-a09b-7abb92a2bca7",
                "created_at": "2025-06-24T16:00:00Z",
                "batch_pdf_url": "https://ENV_URL/api/media/label/44a22efd-2440-4758-a7ac-9a2927a67d64.png",
                "payment_details": {
                    "total_billed": 9.21,
                    "total_collected": 9.21,
                    "paid": true
                }
            },
            "shipments": [
                {
                    "__typename": "Shipment",
                    "id": "shp_7a1b4c",
                    "tracking_number": "1Z12345E0205271688",
                    "label": {
                        "png": {
                            "url": "https://ENV_URL/api/media/label/44a22efd-2440-4758-a7ac-9a2927a67d64.png"
                        }
                    }
                }
            ]
        }
    }
}

💳 Payment Required

WARNING

This response only applies to individual (retail) accounts.
Platform or prepaid accounts will never receive this response.

{
  "__typename": "ShipmentPaymentRequired",
  "id": "shp_9de8f3",
  "payment_link": {
    "url": "PAYMENT_LINK"
  },
  "expires_at": "2025-06-24T17:00:00Z"
}

❌ Shipment Error

Returned when the shipment could not be created due to invalid input, rate failure, or carrier restrictions.

{
  "__typename": "ShipmentError",
  "code": "INVALID_ADDRESS",
  "message": "Postal code is required."
}

🧾 Batch Overview

A batch groups multiple shipments into a single label download and payment group.

Field	Description
`id`	Unique ID of the batch
`batch_pdf_url`	Download link for the combined label PDF
`created_at`	When the batch was created
`payment_details`	Amounts and status of batch billing
`shipments`	List of all attempted shipments in the batch

🔄 Shipment Object (on success)

A Shipment object represents a fully purchased label, complete with carrier info, pricing, and file access.

Field	Description
`id`	Unique shipment ID
`carrier`	Carrier
`carrier_service`	CarrierService
`tracking_number`	Carrier-assigned tracking number
`label`	Label download links (PNG, ZPL)
`billing_weight`	Final billed weight (actual or dimensional)
`total_price`	Final total cost
`base_price`	Cost before surcharges and extras
`labelgenius_charge`	Charge owed to ShipGenius
`itemized_charges`	Full charge breakdown (carrier + platform fees)
`warnings`	Optional carrier-level warnings
`disclaimers`	Legal or carrier advisories
`estimated_delivery`	Estimated delivery date
`guaranteed_delivery`	Whether delivery date is guaranteed

🧰 Tips

You can submit multiple shipments at once using request: [RateAndShipInput!]!
Use batch.payment_details to track billing, refunds, and total invoiced
Use batch.batch_pdf_url to download all generated labels in one PDF
ShipmentError responses are non-blocking — other shipments in the same batch may still succeed
Always validate addresses beforehand using the address_validation query to avoid rejections

✉️ Creating a Shipment

📘 Overview

🛠 Mutation Format

📥 Required Input

🧾 RateAndShipInput

📦 PackageShipmentInput

📦 Packaging

🚚 RateAndShipServiceSpecs

🏷️ RateAndShipService

🔍 RateAndShipFilters

📝 OrderInfo

⚙️ AdditionalInfoInput

🎯 ShipmentCarrierInput