GraphQL


The new API is built with GraphQL, making it quite different from previous REST versions, and hopefully, you will find this new version a lot easier and faster.

One of the greatest benefits of GraphQL is its self-documenting nature, which allows the users of the API to be able to navigate through the schema, queries, mutations, and types so you know exactly what can be requested, which parameters to pass and what to expect in return.

There are several apps that can be used to interact with the API and navigate it, the most used ones are: - Playground - Altair - Insomnia

Overview

As in any GraphQL API, you will have queries and mutations, and in both of them, the result will always be an object. In GraphQL, queries or even mutations can return any type of object, even Connection Fields (which are the way to have paginated results), but we have made a design decision to make every operation return a BaseResponse object. This object allows us to include extra information or metadata to the responses, without polluting the resource types (more on this later).

3PLs

When executing queries, you might want to fetch only data for a particular customer. You have two options for this:

1
Requesting a token using your customer credentials and use it in any further operations made on behalf of that customer.
2
Use your 3PL user and specify the customer_account_id parameter on the desired queries, when available.

When executing mutations that will modify your customer's data you have two ways to achieve that:

1
Requesting a token using your customer credentials and making the requests with that token
2
Use your 3PL user and specify the customer account you are operating on behalf of by using the customer_account_id in each mutation's input.

3PL customers

You can always check your customers list by doing:

query { 
    account { 
        customers { 
            edges { 
                node { 
                    id
                }
            }
        }
    }
}
	

or: 

 query { 
    me {
    	id 
        email 
        account { 
            customers { 
                edges { 
                    node { 
			id
                    }
                }
            }
        }
    }
}
	

Queries

When making queries there are two extra parameters that can be defined sort and analyze.

Sort will be applicable only when requesting queries that return multiple results (Connection Fields). Here you can specify a comma-separated list of attributes to sort the results. The default is to sort by ascending, but you can specify different criteria on each field, by pre-pending (+ or -). Ex: sort: "name, -price"

Analyze is a boolean flag and will only compute the complexity of the query, without executing it (For more info check the Rate Limiting section)

The BaseResponse object returned on every query will always have the following fields: - request_id: An unique request identifier - complexity: The complexity of the query - data: The actual results of the query (a Field, List or Connection Field)

Every connection field can be passed the common relay parameters to specify the amount of results to get. If first and last are not passed, a default max of 100 will be applied. You should consider this since the most results you request, the higher the complexity of the query and so more credits from your quota will be consumed.

Getting all products

query { 
    products { 
        complexity 
        request_id 
        data(first: 10) { 
            edges { 
                node { 
                    id 
                    sku 
                    name 
                    warehouse_products { 
                        id 
                        warehouse_id 
                        on_hand
                    }
                }
            }
        }
    }
}
	

Getting a product by SKU

query { 
    product(sku: "some-sku") { 
        complexity 
        request_id 
        data{ 
            id 
            sku 
            name 
            warehouse_products { 
                id 
                warehouse_id 
                on_hand
            }
        }
    }
}
	

Converting legacy ids

If you are dealing with old ids and need to get their corresponding uuid, there's a query for this:

query { 
    uuid(legacy_id: 1234, 
    entity: "Product") { 
        data { 
            legacy_id 
            id
        }
    }
}
	

Note: For backward compatibility, every input expecting an id will also accept the legacy ids. You just need to send them as strings. This will be available for some time until the deprecation of the legacy API is enabled and webhooks are fully ported.

Mutations

For mutations, the same rules apply, but in this case, the result is not called data, it's defined on each mutation, so usually if you create a product, you will have a product field in the response.

Creating a product

mutation { 
    product_create(data: { 
        name: "New Product" 
        sku: "P0001" 
        price: "10.00" 
        value: "2.00" 
        barcode: "000001" 
        warehouse_products: [
            { warehouse_id: "V2FyZWhvdXNlOjExNA==" on_hand: 5 },
            { warehouse_id: "V2FyZWhvdXNlOjEyODg=" on_hand: 15 }
        ]
    }) { 
        request_id 
        complexity 
        product { 
            id 
            name 
            sku 
            warehouse_products { 
                id
            }
        }
    }
}
	

Next steps