Orderchamp - Build the future of Wholesale

# Getting Started

The GraphQL API only has one endpoint, to which you will send all your queries.

POST https://api.orderchamp.com/v1/graphql

Tip: use our online GraphiQL client to test your queries (opens new window).
(you need a supplier account to use the API. Register here (opens new window))

# Your first API call

We recommend you download and use the GraphQL App (opens new window) or an API GUI like Paw (opens new window).
You can also use our online GraphiQL client (opens new window).

Once you've installed the app, you can test it by running the following query:

POST https://api.orderchamp.com/v1/graphql
Authorization: Bearer {token}

query {
  account {
    name
    type
    slug
  }
}

A successful query results in a response similar to the following:

{
  "data": {
    "account": {
      "name": "Little Champs",
      "type": "SUPPLIER",
      "slug": "little-champs"
    }
  }
}

Congratulations, you’ve made your first call to the GraphQL API!

# Authentication

The API requires an access token for making authenticated requests. You can obtain an access token either by creating a private app and using that app's API password, or by following the OAuth authorization process.

# Private app

  1. Go to the API page in the Orderchamp back office (opens new window) to retrieve a private token
  2. Enter this token in your header Authorization: Bearer {token}

# Public apps

If you are developing an app which multiple Orderchamp users can install, you will need to fetch different token for every user, which the user themselves needs to approve. This follows the OAuth authorization flow.

# Query the GraphQL API

You can access the GraphQL API endpoint using cURL or any other HTTP client. For the following examples, make sure to replace ACCESS_TOKEN with the token you generated in the Authentication section.

Note

If you are using an HTTP client to query the API, then you need to set Content-Type to application/json.

# curl

To make a query to the using curl, send a POST request with your query as the JSON payload.

curl -X POST \
"https://api.orderchamp.com/v1/graphql" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d @- <<'GQL'
{ "query": "

query {
  products(first: 5) {
    edges {
      node {
        id
        title 
      } 
    } 
    pageInfo { 
      hasNextPage 
    } 
  } 
}

"}
GQL

# Example Queries

In GraphQL, queries are the equivalent of REST’s GET action verb. They generally begin with one of the objects listed under QueryRoot and can get data from any connections that object has. Even though a POST is being sent to the GraphQL endpoint, if the body only contains queries, data will only be retrieved and not modified.

Query the inventory levels of the first ten variants.

query {
  productVariants(first: 10) {
    edges {
      node {
        title
        sku
        inventoryQuantity
      }
    }
  }
}

# Example Mutations

Mutations are the equivalent of REST’s data-modifying action verbs.

Create a product.

mutation {
  productCreate(input: {title: "Durable product", brand: "Brand"}) {
    product {
      id
      variants(first: 1) {
        edges {
          node {
            sku
          }
        }
      }
    }
  }
}

# User errors

It is important that for every mutation you execute, you also request the userErrors object, which may optionally contain errors which have occurred while executing your mutation.

For example lets try to leave the brand field empty

mutation {
  productCreate(input: {
    brand:"",
    title:"test",
  }) {
    product {
      id
    }
    userErrors {
      field
      message
    }
  }
}

In the response, we'll see error message

{
  "data": {
    "productCreate": {
      "product": null,
      "userErrors": [
        {
          "field": [
            "brand"
          ],
          "message": "The brand field is required."
        }
      ]
    }
  }
}

# Using webhooks

Webhooks are a useful tool for apps that want to stay in sync with Orderchamp or execute code after a specific event occurs on an account, for example, when a supplier creates a new product in the Orderchamp admin, or a customer places an order.

To create a webhook, you register both an HTTP endpoint on your app as a webhook receiver and an event that triggers a request to that endpoint. Orderchamp sends you a JSON payload when your selected event occurs, with a copy of the relevant object.

Data about orders, products, or customers can change often, and receiving webhooks is much more efficient than continuously polling for changes to every resource. If your app needs to stay in sync with Orderchamp, then always replace your local copy of any data with the webhook payload.

Common webhook use cases include the following:

Sending notifications to IM clients and pagers

  • Collecting data for data-warehousing
  • Integrating with accounting software
  • Filtering order items and informing shipping companies about orders
  • Removing customer data from a database for app uninstalls

# Configuring webhooks

You can configure a webhook using the API or in the Orderchamp admin (opens new window).

# Configure a webhook using the API

You can configure a webhook by making doing a Mutation Query to the GraphQL API. Check out the full Webhooks reference.

# Testing Webhooks

When testing webhooks, you can run a local server or use a publicly available service such as Beeceptor (opens new window). If you decide to run a server locally, then you need to make it publicly available using a service such as Pagekite (opens new window) or ngrok (opens new window). The following URLS do not work as endpoints for webhooks:

  • Localhost
  • Any URL ending in the word "internal". For example, example.com/internal
  • Domains like www.example.com

# Responding to a webhook

Your webhook acknowledges that it received data by sending a 200 OK response. Any response outside of the 200 range, including 3XX HTTP redirection codes, indicates that you did not receive the webhook. Orderchamp does not follow redirects for webhook notifications and considers them to be an error response.

# Frequency

Orderchamp has implemented a five second timeout period and a retry period for subscriptions. Orderchamp waits five seconds for a response to each request to a webhook. If there is no response, or an error is returned, then Orderchamp retries the connection 19 times over the next 48 hours. A webhook is deleted if there are 19 consecutive failures.

Caution

If the webhook subscription was created through the API, then notifications about pending deletions are sent to the support email associated with the app. If the webhook was created using Orderchamp admin, then notifications are sent to the account owner's email address.

To avoid timeouts and errors, consider deferring app processing until after the webhook response has been successfully sent.

# Verifying webhooks

Webhooks created through the API by an Orderchamp App are verified by calculating a digital signature. Each webhook request includes a X-Orderchamp-Signature header, which is generated using the app's shared secret along with the data sent in the request.

To verify that the request came from Orderchamp, compute the HMAC digest according to the following algorithm and compare it to the value in the X-Orderchamp-Signature header. If they match, then you can be sure that the webhook was sent from Orderchamp.

# PHP Code example

Verifying in basic laravel controller

<?php
namespace App\Http\Controllers;

use Illuminate\Http\Request;

class WebhooksController extends Controller
{
  public function incoming(Request $request) {
    $signature = $request->header('X-Orderchamp-Signature');    
    $computedSignature = hash_hmac('sha256', $request->getContent(), ORDERCHAMP_CLIENT_SECRET);
    
    if (hash_equals($signature, $computedSignature)) {
      // authentic webhook received
    }
    return ['OK'];
  }
}

API Reference →