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.

Endpoint

Protocol	Method	Body Encoding	Endpoint URL
HTTPS	POST	application/JSON	https://postapi.shipperhq.com/v3/graphql/label

Request Headers

Header	Description
X-ShipperHQ-Secret-Token	The secret token that you have generated to use the Rates API
X-ShipperHQ-Scope	The 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-Session	This 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.

Examples

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
  }) {
     transactionId
     responseSummary{
        status
    }
    errors {
      errorCode
      internalErrorMessage
      externalErrorMessage
    }
  }
}

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
        }
      ]
    }
}