Rate

Shipping rate offered by the carrier for the shipment

  • from_address
    Type: object
    required

    The origin address

    • country
      Type: string
      required

      ISO 3166 country code for the country the address is located in

    • state
      Type: string
      required

      State or province the address is located in

    • zip
      Type: string
      required

      ZIP or postal code the address is located in

    • city
      Type: string

      City the address is located in

    • company
      Type: string | null

      Name of the organization. Both name and company can be included

    • email
      Type: string | nullFormat: email

      Email to reach the person or organization

    • name
      Type: string | null

      Name of the person. Both name and company can be included

    • phone
      Type: string

      Phone number to reach the person or organization

    • residential
      Type: boolean | null

      Whether or not this address would be considered residential

    • street1
      Type: string

      First line of the address. Note: For U.S. and CA addresses, if street1 exceeds 35 characters, street2 is empty, and the end of street1 contains a recognized unit number format (e.g., “Apt 10”, or “Unit #99833”), the unit number is moved to street2

    • street2
      Type: string

      Second line of the address. Note: May be automatically populated if a unit number is moved from street1 during address verification

  • to_address
    Type: object
    required

    The destination address

    • country
      Type: string
      required

      ISO 3166 country code for the country the address is located in

    • state
      Type: string
      required

      State or province the address is located in

    • zip
      Type: string
      required

      ZIP or postal code the address is located in

    • city
      Type: string

      City the address is located in

    • company
      Type: string | null

      Name of the organization. Both name and company can be included

    • email
      Type: string | nullFormat: email

      Email to reach the person or organization

    • name
      Type: string | null

      Name of the person. Both name and company can be included

    • phone
      Type: string

      Phone number to reach the person or organization

    • residential
      Type: boolean | null

      Whether or not this address would be considered residential

    • street1
      Type: string

      First line of the address. Note: For U.S. and CA addresses, if street1 exceeds 35 characters, street2 is empty, and the end of street1 contains a recognized unit number format (e.g., “Apt 10”, or “Unit #99833”), the unit number is moved to street2

    • street2
      Type: string

      Second line of the address. Note: May be automatically populated if a unit number is moved from street1 during address verification

  • carrier
    Type: string | null

    Carrier to use for the shipment. If both carrier and carrier_accounts are omitted, all carriers are considered.

  • carrier_accounts
    Type: array string[] | null

    List of specific carrier account IDs to use when rating or buying a shipment. If both carrier and carrier_accounts are omitted, all carriers are considered.

  • is_return
    Type: boolean | null

    Set true to create as a return.

  • options
    Type: object | null

    Additional shipment options.

    Notes (enforced by server/business logic, not schema):

    • If carrier_accounts and service are both present and options.create_and_buy is not explicitly false, the server treats create_and_buy as true.
    • create_and_buy and create_and_buy_cheapest are mutually exclusive.
    • additional_handling
      Type: boolean | null

      Whether the package requires additional handling

    • carbon_neutral
      Type: boolean | null

      Request carbon neutral delivery

    • carrier_insurance_amount
      Type: number | null

      Declared insurance value for the carrier

    • commercial_invoice_letterhead
      Type: string | null

      Header text for the commercial invoice

    • commercial_invoice_signature
      Type: string | null

      Signature for the commercial invoice

    • create_and_buy
      Type: boolean | null

      Immediately buy a label. Mutually exclusive with create_and_buy_cheapest

    • create_and_buy_cheapest
      Type: boolean | null

      Automatically buy the cheapest rate. Mutually exclusive with create_and_buy

    • delivery_confirmation
      Type: string | nullenum

      Delivery confirmation type

      values
      • NO_SIGNATURE
      • SIGNATURE
      • SIGNATURE_RESTRICTED
      • ADULT_SIGNATURE
      • ADULT_SIGNATURE_RESTRICTED
    • dropoff_max_datetime
      Type: string | nullFormat: date_time

      Latest acceptable drop-off time

    • dropoff_type
      Type: string | null

      Dropoff type (e.g., REGULAR_PICKUP, SCHEDULED_PICKUP)

    • duty_payment
      Type: object | null

      Duties/taxes billing information

    • duty_payment_account
      Type: string | null

      Account ID to use for duty/tax payment

    • endorsement
      Type: string | null

      Return instruction (e.g., RETURN_SERVICE_REQUESTED)

    • fetch_express_delivery_date
      Type: boolean | null

      Request express delivery date from carrier

    • hazmat
      Type: string | nullenum

      Indicates hazardous material

      values
      • PRIMARY_CONTAINED
      • PRIMARY_PACKED
      • PRIMARY
      • SECONDARY_CONTAINED
      • SECONDARY_PACKED
    • incoterm
      Type: string | null

      Incoterm for the shipment (e.g., DDP, DAP)

    • is_return
      Type: boolean | null

      Indicates whether the shipment is a return

    • label_date
      Type: string | nullFormat: date

      Date to appear on the shipping label

    • label_format
      Type: string | null

      Label file format (e.g., PDF, ZPL)

    • label_request_source
      Type: string | null

      Source of the label request (e.g., api)

    • label_size
      Type: string | nullenum

      Label size (e.g., 4x6)

      values
      • 4x6
      • 8.5x11
      • LETTER
    • machinable
      Type: boolean | null

      Whether the parcel is machinable (USPS)

    • parcels_response
      Type: boolean | null

      Whether to include parcels in the response

    • payment
      Type: object | null

      Postage billing information

    • pickup_max_datetime
      Type: string | nullFormat: date_time

      Latest acceptable pickup time

    • pickup_min_datetime
      Type: string | nullFormat: date_time

      Earliest acceptable pickup time

    • postage_label_inline
      Type: boolean | null

      Whether to return the label inline in the response

    • print_custom
      Type: string | null

      Custom print field (carrier-specific)

    • print_custom_1
      Type: string | null

      Custom print field 1

    • print_custom_2
      Type: string | null

      Custom print field 2

    • print_custom_3
      Type: string | null

      Custom print field 3

    • saturday_delivery
      Type: boolean | null

      Request Saturday delivery

    • special_rates_eligibility
      Type: string | null

      Special rate plan (e.g., usps.connect)

    • suppress_etd
      Type: boolean | null

      Whether to suppress estimated delivery time

  • parcel
    Type: object

    The dimensions and weight of the package. Business rule: parcel and parcels MUST NOT both be present.

    • height
      Type: number | null

      Height of the parcel (optional; must be sent with length + width if sent)

    • id
      Type: string | null

      Unique parcel identifier (required if weight is not provided)

    • items
      Type: array object[] | null · LineItem[]

      Line items inside the parcel

      Individual item contained within a parcel

    • length
      Type: number | null

      Length of the parcel (optional; must be sent with width + height if sent)

    • predefined_package
      Type: string | nullenum

      Carrier-specific predefined package type

      values
      • CARD
      • FEDEX10KGBOX
      • FEDEX25KGBOX
      • FEDEXENVELOPE
      • FEDEXEXTRALARGEBOX
    • weight
      Type: number | null

      Total package weight (required unless id is provided)

    • width
      Type: number | null

      Width of the parcel (optional; must be sent with length + height if sent)

  • parcels
    Type: array object[] | null · Parcel[]

    Array of parcels. Business rule: parcel and parcels MUST NOT both be present.

    The dimensions and weight of the package.

    Rules (not enforced by JSON schema):

    • You may either: • Provide only id • OR omit id and provide weight (dimensions optional)
    • If any of length, width, or height is provided, all three must be provided.
    • height
      Type: number | null

      Height of the parcel (optional; must be sent with length + width if sent)

    • id
      Type: string | null

      Unique parcel identifier (required if weight is not provided)

    • items
      Type: array object[] | null · LineItem[]

      Line items inside the parcel

      Individual item contained within a parcel

    • length
      Type: number | null

      Length of the parcel (optional; must be sent with width + height if sent)

    • predefined_package
      Type: string | nullenum

      Carrier-specific predefined package type

      values
      • CARD
      • FEDEX10KGBOX
      • FEDEX25KGBOX
      • FEDEXENVELOPE
      • FEDEXEXTRALARGEBOX
    • weight
      Type: number | null

      Total package weight (required unless id is provided)

    • width
      Type: number | null

      Width of the parcel (optional; must be sent with length + height if sent)