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!`	Yes	Unique ID for tracking this shipment request
`package`	PackageShipmentInput!	Yes	Full shipment details (addresses, packaging, weight, contents)
`override_service_spec`	RateAndShipServiceSpecs	No	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	No	Ship Date, and any other metadata for the shipment will be added here
`carrier_specific`	ShipmentCarrierInput	No	Carrier specific information, used for information not all carriers accept
`order_info`	OrderInfo	No	Tracking subscriptions, order references, custom metadata

`PackageShipmentInput`

Defines the physical package and routing info for the shipment.

Field	Type	Required	Description
`packaging`	Packaging!	Yes	Type of package: custom box, softpack, or carrier packaging
`weight`	WeightInput!	Yes	Total weight of the shipment
`content_description`	`String!`	Yes	Short description of the package contents
`ship_to`	AddressInput!	Yes	Recipient address
`ship_from`	AddressInput!	Yes	Origin address
`return_address`	AddressInput	No	Optional return address
`extra_services`	ExtraService	No	Insurance, signature, etc.
`hazmat`	HazmatInfo	No	Required for lithium batteries, dry ice, etc.
`customs`	CustomsInput	No	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 or FedEx Envelope)

The available carrier-provided packaging codes are listed in Carrier-Provided Packaging and can be queried with shipping.carrier_packaging.

`RateAndShipServiceSpecs`

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

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

`RateAndShipService`

Field	Type	Required	Description
`carrier`	CarrierCode!	Yes	Carrier to use (e.g. `UPS`, `USPS`, `FedEx`)
`service_code`	`String!`	Yes	Specific carrier service (e.g. `GND`, `PRIORITY_MAIL`)
`account_number`	`String`	No	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": "b23e9f16-4a75-4d92-8c60-3e18b7a05d24",
                    "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": "f80c47d3-1e69-4b52-9a37-6c05e2b81f9d",
    "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

Searching →