SetShippingMethodOnCheckoutMutation

Description

Sets the shipping method on the checkout/cart. This mutation is a required step in the checkout process before placing an order.

Endpoint

mutation setShippingMethodOnCheckout($cartId: String!, $shippingMethod: ShippingMethodInput!, $siteId: Int) {
  setShippingMethodOnCheckout(cartId: $cartId, shippingMethod: $shippingMethod, siteId: $siteId) {
    # Return fields
  }
}

Arguments

Argument	Type	Required	Description
cartId	String	Yes	The unique identifier of the cart to set the shipping method on. This ID is obtained from createGuestCart or createCustomerCart mutations.
shippingMethod	ShippingMethodInput	Yes	The shipping method information to set on the cart.
siteId	Int	No	The site ID where the cart is created. Defaults to the store's default site ID if not provided.

ShippingMethodInput

Field	Type	Required	Description
carrier_code	String	Yes	The code of the shipping carrier to use. This should be a valid shipping carrier code configured in the store.
method_code	String	Yes	The code of the specific shipping method to use. This should be a valid method code for the selected carrier.

Return Values

The mutation returns a CheckoutType object, which is the same as the CartType object returned by the CartQuery. For detailed information about the structure of these fields, refer to the CartQuery documentation.

Usage Example

mutation {
  setShippingMethodOnCheckout(
    cartId: "abc123",
    shippingMethod: {
      carrier_code: "flatrate",
      method_code: "flatrate"
    }
  ) {
    billing_address {
      firstname
      lastname
    }
    shipping_address {
      firstname
      lastname
    }
    selected_shipping_method {
      carrier_code
      method_code
      carrier_title
      method_title
      amount {
        value
        currency
      }
    }
  }
}

Example Response

{
  "data": {
    "setShippingMethodOnCheckout": {
      "billing_address": {
        "firstname": "John",
        "lastname": "Doe"
      },
      "shipping_address": {
        "firstname": "John",
        "lastname": "Doe"
      },
      "selected_shipping_method": {
        "carrier_code": "flatrate",
        "method_code": "flatrate",
        "carrier_title": "Flat Rate",
        "method_title": "Fixed",
        "amount": {
          "value": 5.00,
          "currency": "USD"
        }
      }
    }
  }
}

Notes

• This mutation must be called before attempting to place an order.
• The shipping method codes must be valid shipping methods configured in the store. If an invalid shipping method is provided, an error will be thrown.
• Different shipping methods may have different costs and delivery times. The available shipping methods can be retrieved using the availableShippingMethods query.
• The shipping method may affect the total cost of the order, as shipping costs are added to the cart total.
• If the shipping method is changed, any previously selected shipping method will be replaced.
• The shipping address must be set before calling this mutation, using the setShippingAddressOnCheckout mutation.