PlaceOrder

Description

Converts a cart into an order. This is the final step in the checkout process, which creates an order from the cart and initiates the payment process if necessary.

Endpoint

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

Arguments

Argument	Type	Required	Description
cartId	String	Yes	The unique identifier of the cart to convert to an order. This ID is obtained from createGuestCart or createCustomerCart mutations.
siteId	Int	No	The site ID where the order is placed. Defaults to the store's default site ID if not provided.

Return Values

The mutation returns a PurchaseType object with the following fields:

Field	Type	Description
success	Boolean	Indicates whether the order was successfully placed.
order_number	String	The unique identifier for the newly created order.
redirect_url	String	A URL to redirect to after placing the order. This could be a success page or a payment gateway URL.
form	String	HTML form data for payment processing, if applicable. Only present when a payment gateway requires a form submission.

Usage Example

mutation {
  placeOrder(
    cartId: "abc123"
  ) {
    success
    order_number
    redirect_url
  }
}

Example Response

{
  "data": {
    "placeOrder": {
      "success": true,
      "order_number": "ORD-12345",
      "redirect_url": "https://example.com/checkout/success?order=ORD-12345"
    }
  }
}

Example Response with Payment Gateway Redirect

{
  "data": {
    "placeOrder": {
      "success": true,
      "order_number": "ORD-12345",
      "redirect_url": "https://payment-gateway.com/process",
      "form": "<form id='payment-form' method='post' action='https://payment-gateway.com/process'><input type='hidden' name='orderRef' value='ORD-12345'><input type='hidden' name='amount' value='99.99'></form>"
    }
  }
}

Notes

• Before calling this mutation, ensure that all required information has been set on the cart:
  • Shipping address (using setShippingAddressOnCheckout)
  • Billing address (using setBillingAddressOnCheckout)
  • Shipping method (using setShippingMethodOnCheckout)
  • Payment method (using setPaymentMethodOnCheckout)
  • Guest email (for guest checkouts, using setGuestEmailOnCheckout)
• If the cart has already been converted to an order, an error will be thrown.
• After a successful order placement, the cart will be cleared.
• If payment is required, the redirect_url field will contain a URL to the payment gateway.
• If the payment gateway requires a form submission, the form field will contain the HTML form data.
• Order confirmation emails will be sent automatically if enabled in the store configuration.
• If the order placement fails, an error will be thrown with a descriptive message.