Skip to main content

PlaceOrder Mutation

How Rating + Shipping Insights Work with PlaceOrder

Merchants integrate with ShipperHQ's Rates API to provide shipping rate estimates based on contents of a virtual cart. This is done leveraging the Rates API.

Once a customer has finalized their choices at checkout and completes the order, the rating (a quote) needs to be converted into an order so it can stored for use with the Insights API. Usually, multiple quotes are sent by ShipperHQ (for example, in the cart, when the customer changes their address, when they changes delivery options, etc.).

The role of PlaceOrder is to convert one of these quotes into a full-fledge order. Then, the complete quote information can be stored on ShipperHQ order database and later on retrieved via the Insights API.

Most users don't need to use the PlaceOrder mutation

If you are using an eCommerce platform supported by ShipperHQ (Magento/Adobe Commerce, BigCommerce or Shopify): you do not need to use PlaceOrder. In these scenarios, the order creation is done automatically by the platform using ShipperHQ rates and ShipperHQ captures this information automatically so that you can directly use the Insights API. If you are using a native ShipperHQ integration on any other platform, please contact us to register your interest for Shipping Insights on your eCommerce platform.

The specific scenarios where you would need to use PlaceOrder are detailed below.

Do I need to use the PlaceOrder mutation?

You need to use the PlaceOrder mutation if:

  • you use a platform that does not have a native ShipperHQ integration (supported platform list here)
  • you want to capture orders outside the platform (e.g., going headless, building a mobile app, etc.)
  • you want to implement a different order capture mechanism on a supported platform (from your CRM, from an ERP) leveraging the Rates API

To successfully call PlaceOrder, you need to generate rates via the Rates API first.


ProtocolMethodBody EncodingEndpoint URL

Request Headers

X-ShipperHQ-Secret-TokenThe secret token that you have generated to use the Rates API
X-ShipperHQ-ScopeThe configuration Scope for this ShipperHQ Website (accepts LIVE, TEST, DEVELOPMENT, or INTEGRATION). If unsure or if the ShipperHQ account does not support multiple scopes, use LIVE.
X-ShipperHQ-SessionThis identifies the quote that you want to convert to an order. You have to use the exact same value as the Rates API request used to generate this quote.


Example Request

Example Request
query placeOrder {
placeOrder( placeOrderInfo: {
orderNumber: "1234",
totalCharges: 9.85, # totalCharges in Rates API response
carrierCode: "shqusps", # carrierCode in Rates API response
methodCode: "Priority Mail", # methodCode in Rates API response
transId: "SHQ_20220201_1625_5144966" # transactionID from Rates API response
}) {
errors {

Example Response

Example response
“placeOrder: {
“transactionId” : “SHQ_20220212_12345678_BAQ_639272”,
“responseSummary”: {
“status”: 1
“errors”: null

Example Error Response

Error response
“placeOrder: {
“transactionId": “SHQ_20220212_12345678_BAQ_639273”,
“responseSummary”: {
“status”: 0
“errors”: [
"errorCode": 0,
"internalErrorMessage": "Order not found when looking up",
"externalErrorMessage": null