Updating Order Status and Shipping Method/Carrier

The updateOrders GraphQL mutation provides a way to update order data, programmatically, in a single API call. The mutation allows you to update specific data on the orders your OAuth user has access to.

In the following sections, we will describe how you can authenticate with the API. We will also provide an example mutation, the associated variables and a typical response from the API.

As a fulfiller, you may want to update the shipping carrier and method of an order, after you have received the order data from the platform via a supplier or production integration. In this example we will be using the API to update the shipping carrier and method on an order, and at the same time, change the order status to In Production.

Authentication

The GraphQL API uses OAuth 2.0 authentication.  A request for an OAuth token is made to the OAuth endpoint, which returns an access token.  This token can then be used in requests made to the GraphQL API endpoint.

To make a request for a token, you will require an OAuth user to be set up in the Kornit^X platform. The user will require specific access and permissions depending on the API request. The permissions required for this request can be found in the “OAuth User Requirements” section below.

If you don’t have an OAuth user set up, please contact the support team, who will be happy to help. The support team will set up the OAuth user in the Kornit^X platform for you and supply you with the OAuth user client ID and client secret.  These credentials can then be used to obtain a token from the OAuth token endpoint. 

OAuth Token Endpoint - https://oauth.kornitx.net/token

The OAuth token can be obtained by making a POST to the above endpoint.  The request type for the OAuth token is x-www-form-urlencoded and must include the following form keys and values.

Example Response

{"token_type":"Bearer","expires_in":3600,"access_token":"..."}

OAuth User Requirements

To make the updateOrders request to the GraphQL API, the OAuth user must have:

• Access to the dropship and supplier companies that are related to the order.

• The order-it.order-manager.edit user permission enabled.

The Orders GraphQL Mutation

Now we have the access token, we can now make the updateOrders request.

We will be making a POST request to the https://graphql.kornitx.net endpoint.

The request will have 2 headers listed below.

Content-Type: “application/json” 

Authorization: “Bearer [OAUTH_ACCESS_TOKEN]“

[OAUTH_ACCESS_TOKEN] should be replaced by the access token that was returned when we made the token request to the https://oauth.kornitx.net/token endpoint.

Mutation

In this example, we will be updating the shipping carrier, the shipping method and the status of a single order. We will ask the API to return the following order information.

• Order ID

• Shipping Carrier

• Shipping Method

• Status ID

• Status Name

However, the GraphQL API call can return numerous other pieces of information about the order and its associated order-items, details of which, can be found in the schema here - https://developers-v2.custom-gateway.net/graphql/order.doc.html and here - https://developers-v2.custom-gateway.net/graphql/orderitem.doc.html

Example Mutation

mutation($orders: [OrderInput]) {
	core {
		updateOrders(orders: $orders) {
			id
			shipping_carrier
            shipping_method
            status
            status_name
		}
	}
}

Variables

The mutation contains references to a single variable - $orders. A description of this variable can be found in the table below.

Variable Description

Example Variable

{
    "orders": [
        {
            "id": 46140199,
            "shipping_carrier": "Royal Mail",
            "shipping_method": "Tracked 24",
            "status": 4
        }
    ]
}

Response

A successful request will return a HTTP 200 response and the details we requested from the order. For the example we have been working with, the response data can be viewed below.

Example response

{
    "data": {
        "core": {
            "updateOrders": [
                {
                    "id": 46140199,
                    "shipping_carrier": "Royal Mail",
                    "shipping_method": "Tracked 24",
                    "status": 4,
                    "status_name": "In Production"
                }
            ]
        }
    }
}