AvailableShippingMethodsQuery

Description

Retrieves available shipping methods for a cart. This page documents the checkoutShippingMethods operation registered in CheckoutShippingMethodsQuery.

Endpoint

query checkoutShippingMethods($cartId: String!, $country_code: String, $site_id: Int) {
  checkoutShippingMethods(cartId: $cartId, country_code: $country_code, site_id: $site_id) {
    # Return fields
  }
}

Arguments

Argument	Type	Required	Description
cartId	String	Yes	The unique identifier of the cart for which to retrieve shipping methods. This ID is obtained from createGuestCart or createCustomerCart mutations.
country_code	String	No	The country code to use for determining available shipping methods. If not provided, the store's default country will be used.
site_id	Int	No	The site ID to use for determining available shipping methods. If not provided, the current site ID will be used.

Return Values

The query returns an array of ShippingMethod objects with the following fields:

Field	Type	Description
id	Int	The unique identifier for the shipping method.
carrier_code	String	The code of the shipping carrier (e.g., "flatrate", "freeshipping").
carrier_title	String	The display name of the shipping carrier.
method_code	String	The code of the specific shipping method.
method_title	String	The display name of the shipping method.
instructions	String	Any special instructions or information about the shipping method.
amount	Money	The cost of the shipping method.
selected	Boolean	Indicates whether this shipping method is currently selected for the cart.
available	Boolean	Indicates whether this shipping method is available for the cart.
free_shipping_threshold	Float	Optional threshold amount for free shipping eligibility.
icon	String	Optional icon URL or identifier configured for the method.
page	String	Optional linked informational page for the method.

Money Structure

The amount field uses the Money structure:

Field	Type	Description
value	Float!	The numerical value of the amount.
currency	String!	The currency code (e.g., "USD").

Usage Example

query {
  checkoutShippingMethods(
    cartId: "abc123",
    country_code: "US"
  ) {
    id
    carrier_code
    carrier_title
    method_code
    method_title
    instructions
    amount {
      value
      currency
    }
    selected
    available
  }
}

Example Response

{
  "data": {
    "checkoutShippingMethods": [
      {
        "id": 1,
        "carrier_code": "flatrate",
        "carrier_title": "Flat Rate",
        "method_code": "flatrate",
        "method_title": "Fixed",
        "instructions": "Flat rate shipping",
        "amount": {
          "value": 5.00,
          "currency": "USD"
        },
        "selected": true,
        "available": true
      },
      {
        "id": 2,
        "carrier_code": "freeshipping",
        "carrier_title": "Free Shipping",
        "method_code": "freeshipping",
        "method_title": "Free",
        "instructions": "Free shipping for orders over $100",
        "amount": {
          "value": 0.00,
          "currency": "USD"
        },
        "selected": false,
        "available": true
      }
    ]
  }
}

Notes

• The available shipping methods may vary based on the cart contents, shipping address, and store configuration.
• The selected field indicates which shipping method is currently selected for the cart. This can be useful for pre-selecting the appropriate method in your UI.
• The available field indicates whether the shipping method can be used for the current cart. Methods that are not available should not be selectable in your UI.
• To set a shipping method on the cart, use the setShippingMethodOnCheckout mutation.
• The shipping cost may affect the total cost of the order, as shipping costs are added to the cart total.
• The country code should be a valid two-letter ISO country code (e.g., "US", "GB", "DE").
• If country_code or site_id is omitted, plugin defaults are used.