A 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.
(you need a supplier account to use the API. Register here)

Your first API call

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

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

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 API call.

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

The API requires an access token for making authenticated requests. You can obtain an access token either by creating one manually in your supplier backoffice, or by following the OAuth authorization process when creating a public app.

Private app

1. Go to the API page in the Orderchamp back office 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 a unique token for every user, which the user themselves needs to approve. This follows the general oAuth flow.

(While in development its often easier to start with a single token as described in the Private app section)

To get started with building a public app, reach out to tech.support@orderchamp.com to let us register your app and return credentials to you such as the client_id and the client_secret which you need to construct the urls. We also need two urls from your side:

• Application url: To this url we'll send the user when they want to start the installation process. From here you redirect the user back to Orderchamp for the approval
• Redirect url: After the user has either approved or disapproved the installation of your app, we'll return the user to this url with a code (you can exchange the code for an access token)

Installation

When you want to initiate the installation process for a user, simply redirect them to: https://www.orderchamp.com/oauth/authorize?response_type=code&client_id={CLIENT_ID}&scope={SCOPE}&redirect_uri={APP_URL}

• {CLIENT_ID}: Your App's CLIENT_ID
• {SCOPE}: Comma separated list of scopes, for example: scope=account_read,products_read
• {APP_URL}: Redirect URL used as callback to your app
• state: You can add your own custom variable to the url which we will return with the redirect url

When the user has either approved or disapproved the installation, we return them to your redirect_url but with the following parameters: https://example.org/auth/callback/uri?account_id={account_id}&code={authorization_code}&state={state}&timestamp=1570536833&signature=2ea417b02d293a55ea28d22f06658815e359061b054e641a5f627ee81012ea5a

• account_id: The unique orderchamp account id
• code: The code you can exchange for an access token (via the API)
• state: The state you sent us during the authorize url (if any)
• timestamp: Unix timestamp for verification
• signature: A signed HMAC to verify the request has not been tempered with

How to verify the signature:

• First remove the signature from the query string
• Push the remaining query string through a hmac function with sha256 and your client_secret

An example in PHP:

<?php
            $clientSecret = '913760a5668ee588b6089954815ba7b08c0d5fcb';
            parse_str(
              "code=ad670cac0bd678b587ad465acd46aacd&signature=2ea417b02d293a55ea28d22f06658815e359061b054e641a5f627ee81012ea5a&account_id=94949393&state=7657657&timestamp=1337178173", 
              $payload
            );
            
            $signature = $payload['signature'];
            unset($payload['signature']);
            
            $calculated = hash_hmac('sha256', http_build_query($payload), $clientSecret);
            
            hash_equals($calculated, $signature);
            ?>
            

To exchange the code for a permanent access_token use the following API call

POST https://www.orderchamp.com/oauth/access_token

{
  "grant_type": "authorization_code",
  "code": "{CODE}",
  "client_id": "{CLIENT_ID}",
  "client_secret": "{CLIENT_SECRET}"
}

• {CODE}: The authorization code provided in the redirect
• {CLIENT_ID}: The API key for the app
• {CLIENT_SECRET}: The API secret key for the app

The API will respond with the access token and its approved scopes:

{
  "access_token": "dfa540127b8d0abb3b1cf1be93bdefbd35a50b7a",
  "token_type": "bearer",
  "scope": "account_read,orders_read,products_write"
}

After the installation has finished, you can decide to leave the user in your application, or if you prefer to send the user back to their Orderchamp backoffice, simply redirect them to the following url: https://www.orderchamp.com/oauth/finish?client_id={your_app_client_id}

Access scopes

Part of the authorization process requires specifying which parts of an account's data the client would like access to. A client can ask for any of the authenticated or unauthenticated access scopes listed below.

• account_read, account_write: Access to Account
• products_read, products_write: Access to Product, Product Variant, Product Image
• orders_read, orders_write: Access to Orders, Order Product, Invoice, Invoice Item
• fulfillment_read, fulfillment_write: Create or update shipments
• customers_read, customers_write: Read or create customers

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.

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. If you decide to run a server locally, then you need to make it publicly available using a service such as Pagekite or ngrok. 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.

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

Example Webhooks

In this example we are going to register a webhook for product events.

Query:

mutation {
  webhookCreate(input: {
    active: true
    callbackUrl: "https://example.com/orderchamp_webhook"
    events: [PRODUCT_CREATED, PRODUCT_DELETED, PRODUCT_UPDATED]
  }) {
    webhook {
      id
      callbackUrl
      events
      active
    }
  }
}

Response:

{
  "data": {
    "webhookCreate": {
      "webhook": {
        "id": "V2ViaG9vazo1NzEzNDgwMDA4NjYzMDU",
        "callbackUrl": "https://example.com/orderchamp_webhook",
        "events": [
          "PRODUCT_CREATED",
          "PRODUCT_DELETED",
          "PRODUCT_UPDATED"
        ],
        "active": true
      }
    }
  },
}

Using the Orderchamp-client

If you happen to use the Orderchamp/orderchamp-laravel package, you could run this query by using the PHP client

<?php
            $gql = <<GRAPHQL
            mutation ($input: WebhookCreateInput!) {
              webhookCreate(input: $input) {
                webhook {
                  id
                  callbackUrl
                  events
                  active
                }
              }
            }
            GRAPHQL;
            
            $variables = [
              'input' => [
                'active'      => true,
                'callbackUrl' => 'https://example.com/orderchamp_webhook',
                'events'      => ['PRODUCT_CREATED', 'PRODUCT_DELETED', 'PRODUCT_UPDATED'],
              ],
            ];
            
            $response = Orderchamp::api()->graphql($gql, $variables);
            
            var_dump($response);
            

The GraphQL API's limits are based on a calculated cost for each query. Every request is subject to throttling under our general limits.

All requests that are made after the limit has been exceeded are throttled and an {errors: [{ message: "Throttled" }]} error is returned. Requests succeed again after enough space has accumulated in the bucket. Limits are calculated using the leaky bucket algorithm. You can use the GraphQL response to see the status of the throttle.

General API rate limits

The leaky bucket rate limits function like the REST API's rate limiting system, but consider the cost of requests over time, rather than the number of requests. An app is given a bucket of 1000 cost points, with a leak rate of 50 cost points per second. This means that the total cost of your queries cannot exceed 1000 points at any given time, and that room is created in the app's bucket at a rate of 50 points per second. By making simpler, low-cost queries, you can make more queries over time.

The limit uses a combination of the requested and the actual query cost. Before execution begins, the app’s bucket must have enough room for the requested cost of the query. When execution is complete, the bucket is refunded the difference between the requested cost and the actual cost of the query.

Cost calculation

Every field in the schema has an integer cost value assigned to it. The cost of a query is the sum of the costs of each field.

Connection fields have a multiplying effect on the cost of their sub-selections based on the first or last arguments.

Requested and actual cost

Orderchamp calculates the cost of a query both before and after query execution. The requested cost is based on the number of fields requested. The actual cost is based on the results returned, since the query can end early due to an object type field returning null, or connection fields can return fewer edges than requested.

Single query limit

A single query to the GraphQL API cannot exceed a cost of 1000. This limit is enforced before a query is executed based on the query's requested cost.

Recommendations to avoid throttling errors

Design your app with API rate limits in mind to best handle request limits and avoid errors. To avoid rate limiting:

• Vary time intervals of requests to avoid sending traffic in spikes.
• Avoid requesting overlapping data.
• Use the query response to balance your requests.

GraphQL response

The response includes information about the cost of the request and the state of the throttle. This data is returned under the extensions key:

"extensions": {
  "throttle": {
    "requestedCost": 0,
    "actualCost": 0,
    "limit": 1000,
    "remaining": 0,
    "restoreRate": 50
  }
}

This section describes how you can create, read, or update products. A product consist of multiple variants, such as Red, Blue, Small or Large. You are free to name the colors, sizes, or other options however you like. We recommend you use our ProductVariantAttributes endpoint to list all the available attributes for a product, since these are dynamic and may change in the future.

Querying products

For information on which fields you can fetch see the Product object type.

query {
              products(first: 10, after: "") {
                nodes {
                  id
                  title
                  description
                  option1
                  option2
                  option3
                  variants (first: 5) {
                    nodes {
                      id
                      color
                      size
                      option
                    }
                  }
                
                  pageInfo {
                    hasNextPage
                    endCursor
                  }
                }
              }
            }
            
            

Fetch a single product

With the query below you can fetch all information for a single product. For information on which fields you can fetch see the Product object type.

query {
  product(id: "UHJvZHVjdDo1Njg0ODk5MjAxNTE1NTM") {
    brand
    title
    description
    option1
    option2
    featuredImage {
      thumbnailUrl(width: 100, height: 100, method: CROP)
      originalUrl
    }
    images(first: 5, sort: POSITION_ASC) {
      edges {
        node {
          thumbnailUrl(width: 100, height: 100, method: CROP)
          originalUrl
        }
      }
    }
    variants (first: 50) {
      edges {
        node {
          title
          option1
          option2
          option3
          sku
          inventoryQuantity
          inventoryPolicy
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

Response

{
  "data": {
    "product": {
      "brand": "Orderchamp",
      "title": "Give food baby bib",
      "description": "A little handmade baby bib in multiple colors, with a funny text.",
      "option1": "Size",
      "option2": "Color",
      "featuredImage": {
        "thumbnailUrl": "https://cdn.orderchamp.com/products/54e6356a-5ade-402b-b099-210db4f0f878_100x100_crop.png?20200407081423",
        "originalUrl": "https://cdn.orderchamp.com/products/54e6356a-5ade-402b-b099-210db4f0f878.png?20200407081423"
      },
      "images": {
        "edges": [
          {
            "node": {
              "thumbnailUrl": "https://cdn.orderchamp.com/products/54e6356a-5ade-402b-b099-210db4f0f878_100x100_crop.png?20200407081423",
              "originalUrl": "https://cdn.orderchamp.com/products/54e6356a-5ade-402b-b099-210db4f0f878.png?20200407081423"
            }
          }
        ]
      },
      "variants": {
        "edges": [
          {
            "node": {
              "title": "0-3 months, Pink",
              "option1": "0-3 months",
              "option2": "Pink",
              "option3": null,
              "sku": "Poepie-monster-romper-1-copy-1",
              "inventoryQuantity": 0,
              "inventoryPolicy": "CONTINUE"
            }
          }
        ],
        "pageInfo": {
          "hasNextPage": true
        }
      }
    }
  }
}

Get the titles of a product's first five variants

query {
  product(id: "UHJvZHVjdDo1Njg0ODk5MjAxNTE1NTM") {
    variants(first: 5) {
      edges {
        node {
          title
        }
      }
    }
  }
}

Response:

{
  "data": {
    "product": {
      "variants": {
        "edges": [
          {
            "node": {
              "title": "0-3 months, Pink"
            }
          },
          {
            "node": {
              "title": "3-6 months, Pink"
            }
          },
          {
            "node": {
              "title": "6-12 months, Pink"
            }
          },
          {
            "node": {
              "title": "0-3 months, Yellow"
            }
          },
          {
            "node": {
              "title": "3-6 months, Yellow"
            }
          }
        ],
        "pageInfo": {
          "hasNextPage": true,
          "endCursor": "W1s4MjczMDA2Nzk0MzQyNDEsIjUiXSwiNzJhMjI4N2UiXQ"
        }
      }
    }
  }
}

Paginating

Fetch products with pagination

When fetching multiple results you always need to specify how many results you want to receive. You will also receive a paginator which tells you if there are more pages available. You can use the cursor to fetch the next page.

This is how you fetch the first page

{
  products(first: 10) {
    edges {
      node {
        title
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

When the hasNextPage returns true you can use the endCursor as the after parameter to fetch the next page.

{
  products(first: 10, after: "WzgyNzMwMDY3NzI3MTU1MywiZTdmNjQzYmEiXQ") {
    edges {
      node {
        title
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Paginate products by their timestamp

If you want to periodically fetch the products based on their updated_at, you can use the startCursor or endCursor. This cursor remembers the position you left off, and gives you the newest results depending on what you sorted on.

For example lets say we sort by the UPDATED_AT_ASC. When we start paginating we receive all the pages sorted from least recently to most recently updated. You keep looping until you reached the last page, marked by the hasNextPage = false. You then remember this endCursor so that next time you can start from there.

# Start by fetching all variants sorted by updated_at ascending
{
  productVariants(sort: UPDATED_AT_ASC, first: 5) {
    nodes {
      id
      inventory
      createdAt
      updatedAt
    }
    pageInfo {
      hasPreviousPage
      hasNextPage
      startCursor
      endCursor
    }
  }
}

Next time, only fetch the results more recent than your endCursor:

{
  productVariants(sort: UPDATED_AT_ASC, after: "W1szNDY1ODYxOTYyODA5MzQ1LCIyMDI1LTA1LTE1IDA2OjU3OjIyIl0sIjI1NmNkMjg1Il0", first: 5) {
    nodes {
      id
      inventory
      createdAt
      updatedAt
    }
    pageInfo {
      hasPreviousPage
      hasNextPage
      startCursor
      endCursor
    }
  }
}

Creating products

A product always consists of one or multiple variants. A variant needs to have either a Color, Size, or Option. Where the values are free to name them how you'd like. This way you can use any color or size, and the option field is free to describe a property that isnt a color or size.

Create a product

You have to send a mutation for every single variant using the Color, Size, or Option fields. You may group multiple variants using the productId or externalProductId.

The externalProductId and externalProductVariantId can be used to send your unique identifier. We will store this value to allow you to easily update the product later on.

Also make sure you request the userErrors to make sure your didn't receive any validation errors. See the userErrors for more information.

mutation {
  productVariantCreate(input: {
    externalProductId: "your-product-id"
    externalProductVariantId: "your-variant-id"
    sku: "12345678"
    color: "Red"
    size: "Small"
    option: "Cotton"
    productTitle: "Handmade baby bib"
    productDescription: "A handmade baby bib in multiple bright colors"
    category: KIDS_BABY_BABY_ESSENTIALS_BIBS
    caseQuantity: 6
    brand: "Your brand name",
    madeIn: NL,
    leadTime: ONE_TO_THREE
    availableAt: "2021-10-31"
    tags: [HANDMADE, ORGANIC]
    price: "4.99"
    msrp: "9.99"
    inventoryQuantity: 10
    inventoryPolicy: CONTINUE
    weight: "100"
    length: "100"
    width: "99.91"
    height: "30.5"
    diameter: "23.3"
    volume: "0.95"
    ean: 123456789
    filterMaterial: [GLASS]
    images: [{
      sourceUrl: "https://placehold.it/100x100"
    }]
  }) {
    productVariant {
      id
      product {
        id
      }
      sku
      color
      size
      productTitle
      productDescription
      category {
        path
      }
      caseQuantity
      brand
      madeIn
      leadTime
      availableAt
      tags
      price
      msrp
      inventoryQuantity
      inventoryPolicy
      weight
      length
      width
      height
      diameter
      volume
      ean
    }
    userErrors {
      field
      message
    }
  }
}

Response

{
  "data": {
    "productVariantCreate": {
      "productVariant": {
        "id": "UHJvZHVjdFZhcmlhbnQ6MTMyNDM5OTAyMTk4MTY5Nw",
        "product": {
          "id": "UHJvZHVjdDoxMzI0Mzk5MDIxMjkzNTY5"
        },
        "sku": "12345678",
        "color": "Red",
        "size": "Small",
        "productTitle": "Handmade baby bib",
        "productDescription": "A handmade baby bib in multiple bright colors",
        "category": {
          "path": "KIDS_BABY_BABY_ESSENTIALS_BIBS"
        },
        "caseQuantity": 6,
        "brand": "Your brand name",
        "madeIn": "NL",
        "leadTime": "ONE_TO_THREE",
        "availableAt": "2021-10-31",
        "tags": [
          "HANDMADE",
          "ORGANIC"
        ],
        "price": "4.99",
        "msrp": "9.99",
        "inventoryQuantity": 10,
        "inventoryPolicy": "CONTINUE",
        "weight": "100.00",
        "length": "100.00",
        "width": "99.91",
        "height": "30.50",
        "diameter": "23.30",
        "volume": "0.95",
        "ean": "123456789"
      },
      "userErrors": []
    }
  }
}

Updating products

When you update a product variant you can either specify the productVariantId we have assigned to the variant, or use your own externalProductVariantId field.

mutation {
  productVariantUpdate(input: {
    id: "UHJvZHVjdFZhcmlhbnQ6MTMyNDM5OTAyMTk4MTY5Nw"
    sku: "12345678"
    color: "Red"
    size: "Small"
    option: "Cotton"
    productTitle: "Handmade baby bib"
    productDescription: "A handmade baby bib in multiple bright colors"
    category: KIDS_BABY_BABY_ESSENTIALS_BIBS
    caseQuantity: 6
    brand: "Your brand name",
    madeIn: NL,
    leadTime: ONE_TO_THREE
    availableAt: "2021-10-31"
    tags: [HANDMADE, ORGANIC]
    price: "4.99"
    msrp: "9.99"
    inventoryQuantity: 10
    inventoryPolicy: CONTINUE
    weight: "100"
    length: "100"
    width: "99.91"
    height: "30.5"
    diameter: "23.3"
    volume: "0.95"
    ean: 123456789
    filterMaterial: [GLASS]
    images: [{
      sourceUrl: "https://placehold.it/100x100"
    }]
  }) {
    productVariant {
      id
      product {
        id
      }
      sku
      color
      size
      productTitle
      productDescription
      category {
        path
      }
      caseQuantity
      brand
      madeIn
      leadTime
      availableAt
      tags
      price
      msrp
      inventoryQuantity
      inventoryPolicy
      weight
      length
      width
      height
      diameter
      volume
      ean
    }
    userErrors {
      field
      message
    }
  }
}

Product properties

This section describes the different properties a product can have, which are:

• Product Options
• Product Category
• Product Lead time
• Product Dimensions
• Product Inventory
• Product Images
• Product Translations

Also check the Enums section to see which categories, tags, or lead times you can use.

Product Options

A product generally exists of multiple variants, although this isnt required. A product can have up to 3 options (a Color, Size, and Option). Every variant can have up to three options, but at least one. For example a T-shirt comes in a variety of Colors and Sizes. The variable table will look something like this:

Product	Color	Size
Variant	Red	S
Variant	Red	M
Variant	Red	L
Variant	Blue	S
Variant	Blue	M
Variant	Blue	L

mutation {
  productVariantCreate(input: {
    sku: "tshirt-red-xs"
    color: "Red"
    size: "XS"
    productTitle: "Tshirt"
    productDescription: "Beautiful t-shirt"
  }) {
    productVariant {
      id
      color
      size
      productTitle
      productDescription
    }
    userErrors {
      field
      message
    }
  }
}

Product Category

Orderchamp works with a pre-defined list of categories. A category is defined by its CategoryPath. Please note that categories are subject to change so it is recommended to often fetch the list of available categories. Preferably even use the ProductVariantAttributes endpoint.

Category tree

You can fetch the entire category tree with the query below.

Accept-Language: nl
query {
  categories {
    path
    name
    depth
    parent {
      path
    }
    translation {
      name
    }
  }
}

The query above will return a flat list of all categories with their children. The tree has 3 levels of depth and products can only be assigned a category with a depth of 2 (sub-sub category). In the example below you can see the category "Home & Living" with subcategory "Pillows & Plaids" and sub-sub-category "Plaids".

{
  "data": {
    "categories": [
      {
        "path": "HOME_LIVING",
        "name": "Home & Living",
        "depth": 0,
        "parent": null,
        "translation": {
          "name": "Home & Living"
        }
      },
      {
        "path": "HOME_LIVING_PILLOWS_PLAIDS",
        "name": "Pillows & Plaids",
        "depth": 1,
        "parent": {
          "path": "HOME_LIVING"
        },
        "translation": {
          "name": "Kussens & Plaids"
        }
      },
      {
        "path": "HOME_LIVING_PILLOWS_PLAIDS_PILLOWS",
        "name": "Pillows",
        "depth": 2,
        "parent": {
          "path": "HOME_LIVING_PILLOWS_PLAIDS"
        },
        "translation": {
          "name": "Kussens"
        }
      },
      ...
    ]
  }
}

Product Lead time

The lead time is the time it will take for this product to be shipped and delivered to the retailer. A brand may configure an average lead time for their products and Orderchamp will automatically determine your average lead time based on your actual delivery time, but you can overwrite this value per product. For example when a product has an exceptionally long delivery time. Visit the lead-time enum to see all the different lead times.

Product Dimensions

The dimensions of a product can be specified either at a product or at a variant level. We recommend specifying them at the product level and only specify per variant when the dimensions are not the same for every variant. Visit the section

mutation {
  productCreate(input: {
    weight: 100,
    length: "100",
    width: "99.91",
    height: "30.5",
    diameter: "23.3",
    volume: "0.95"
  )
}

Product Inventory

A product itself has no inventory. Every variant within a product can hold inventory, along with a policy for when it has sold out. You can "allow backorders" to keep selling the item when inventory is zero. This will result in a negative inventory quantity.

In the example below you can see we use inventoryQuantity and inventoryPolicy. See the InventoryPolicy enum for the options.

mutation {
  productCreate(input: {
    variants: [{
      sku: "tshirt-s-red",
      option1: "S",
      option2: "Red",
      inventoryQuantity: 10,
      inventoryPolicy: CONTINUE,
    }]
  }) {
    product {
      id
    }
    userErrors {
      field
      message
    }
  }
}

Product Images

You can specify a number of product images by giving the source url.

mutation {
  productCreate(input: {
    images: [{
      sourceUrl:"https://placehold.it/100x100"
    }]
  }) {
    product {
      id
      images(first: 10) {
        edges {
          node {
            thumbnailUrl(width: 100, height: 100, method: CROP)
            originalUrl
          }
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

Product Translations

You do not have to specify translations through the API. Instead Orderchamp will automatically translate titles and description to all supported languages, which at the time of writing are English, Dutch, German, and French. We do recommend upload all products in the same language. We only translate products once they enter the marketplace, which happens after it is successfully published.

Within Orderchamp every product consists of one or multiple variants. The product itself doesnt have inventory, only the variants have inventory. Every variant has a unique SKU, its own inventory count, and an inventory policy. The inventory policy describes whether the product is allowed to be sold when out of stock.

For information on which fields you can fetch see the Product object type and the ProductVariant object type.

Fetch the inventory for a product

With the query below you can fetch the inventory for variants in a product. In this example the variant has an inventory of 15, but also a policy which allows it to be backordered (see the ProductVariantInventoryPolicy enum).

query {
  product(id: "UHJvZHVjdDo1Njg0ODk5MjAxNTE1NTM") {
    variants (first: 50) {
      edges {
        node {
          inventoryQuantity
          inventoryPolicy
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

Response

{
  "data": {
    "product": {
      "variants": {
        "edges": [
          {
            "node": {
              "inventoryQuantity": 15,
              "inventoryPolicy": "CONTINUE"
            }
          }
        ],
        "pageInfo": {
          "hasNextPage": true,
          "endCursor": "W1s4MjczMDA0NTIwNTcwODksIjEiXSwiOGRhNWJjNTgiXQ"
        }
      }
    }
  }
}

Update the inventory for one variant

You can choose to update every single variant of a product individually. Or you can update multiple variants at once. For more information on the available fields see the ProductVariantUpdate mutation.

mutation {
  productVariantUpdate(input: {
    id: "UHJvZHVjdFZhcmlhbnQ6ODI3MzAwNDUyMDU3MDg5",
    inventoryQuantity: 10
  }) {
    productVariant {
      id
      inventoryQuantity
    }
    userErrors {
      field
      message
    }
  }
}

Response

{
  "data": {
    "productVariantUpdate": {
      "productVariant": {
        "id": "UHJvZHVjdFZhcmlhbnQ6ODI3MzAwNDUyMDU3MDg5",
        "inventoryQuantity": 10
      },
      "userErrors": []
    }
  }
}

Update inventory for multiple variants

You can update multiple variants at once using inventoryLevelBulkAdjust by SKU or ProductVariantId. The adjustment will increase or decrease the inventory level with the amount, if action: SET is not set. If it is set, it will modify the inventory level with the given amount.

If you have set up multiple warehouse locations in your Orderchamp account, you can set the inventory separately as well by specifying the locationId. For more information on how to get the locationId, see Fetch available warehouses for supplier. If no locationId is set, we will use the primary location by default.

mutation {
  inventoryLevelBulkAdjust(input: {
    inventoryLevels: [{
      # Increase inventory with 10 by SKU
      sku: "A0001"
      adjustment: 10
    }, {
      # Decrease inventory with 10 by ProductVariantId
      productVariantId: "UHJvZHVjdFZhcmlhbnQ6MTQyMDQ3OTkwMzU5NjU0NQ"
      adjustment: -10
    }, {
      # Set inventory to 100
      sku: "A0003"
      adjustment: 100
      action: SET
    }, {
      # Set inventory to 100 for a specific warehouse
      sku: "A0003"
      locationId: "TG9jYXRpb246MTQxMzY4NDU2NTM0NDI1Nw"
      adjustment: 100
      action: SET
      }]
  }) {
    userErrors {
      field
      message
    }
    inventoryLevels {
      quantity
      productVariant {
        id
        inventoryQuantity
      }
      location {
        id
      }
    }
  }
}

Response

{
  "data": {
      "inventoryLevelBulkAdjust": {
          "userErrors": [],
          "inventoryLevels": [
              {
                  "quantity": 52,
                  "productVariant": {
                      "id": "UHJvZHVjdFZhcmlhbnQ6MTQyMDQ3OTkwMzU5NjU0NQ",
                      "inventoryQuantity": 52
                  },
                  "location": {
                      "id": "TG9jYXRpb246MTQxMzY4NDU2NTM0NDI1Nw"
                  }
              },
              {
                  "quantity": 42,
                  "productVariant": {
                      "id": "UHJvZHVjdFZhcmlhbnQ6MTQyMDQ3OTkwMzU5NjU0NQ",
                      "inventoryQuantity": 42
                  },
                  "location": {
                      "id": "TG9jYXRpb246MTQxMzY4NDU2NTM0NDI1Nw"
                  }
              },
              {
                  "quantity": 100,
                  "productVariant": {
                      "id": "UHJvZHVjdFZhcmlhbnQ6MTQyMDQ3OTkyMDk5NjM1Mw",
                      "inventoryQuantity": 100
                  },
                  "location": {
                      "id": "TG9jYXRpb246MTQxMzY4NDU2NTM0NDI1Nw"
                  }
              },
              {
                  "quantity": 100,
                  "productVariant": {
                      "id": "UHJvZHVjdFZhcmlhbnQ6MTQyMDQ3OTkyMDk5NjM1Mw",
                      "inventoryQuantity": 100
                  },
                  "location": {
                      "id": "TG9jYXRpb246MTQxMzY4NDU2NTM0NDI1Nw"
                  }
              }
          ]
      }
  }
}

You can automatically sync orders from Orderchamp to your own fulfilment software.

Contact us at support@orderchamp.com so we can create an API token for you. With this token you can create a webhook which will call your endpoint every time an order is created or updated. We will post a minimal amount of information, you can then fetch the most recent version of the order through the API as shown below.

Create a webhook

To automatically be notified of incoming orders or changes you can use a webhook. Make sure you only look at confirmed orders. Unconfirmed orders can still change and are often not paid. They should not be fulfilled.

mutation {
  webhookCreate(input: {
    active: true
    callbackUrl: "https://example.com/orderchamp_webhook"
    events: [ORDER_CONFIRMED, ORDER_UPDATED, ORDER_CANCELLED]
  }) {
    webhook {
      id
      callbackUrl
      events
      active
    }
  }
}

When a new order is created we'll execute the following request

POST https://example.com/orderchamp_webhook
Content-Type: application/json
X-Orderchamp-Account-Id: QWNjb3VudDo4OTQ0MzQ2NTk1NDkxODU
X-Orderchamp-Event: ORDER_CREATED
X-Orderchamp-Signature: 9d37d8811a80f8bbb1125ed720b0b76702d034a4c5cd74a1ad15c3ae2e6ef6bb
X-Orderchamp-Webhook-Id: V2ViaG9vazo4OTY4MjY3Mzk5MzMxODU

{
  "data": {
    "order": {
      "id": "T3JkZXI6ODk2ODI4MDAxMDkxNTg1",
      "number": "#ORD000001",
      "createdAt": "2020-05-26T11:00:37Z",
      "updatedAt": "2020-05-27T15:33:43Z"
    }
  }
}

Fetch all orders

When fetching orders please make sure you always filter for "confirmed" and "not cancelled" orders only. Confirmed orders are always paid and will generally no longer change.

Use the query below to fetch confirmed and uncancelled orders.

query {
                orders(first: 10, includeUnconfirmed: false, includeCancelled: false, sort: CONFIRMED_AT_DESC) {
                nodes {
                  id
                  isConfirmed
                  isCancelled
                  billingAddress {
                    companyName
                    name
                    street
                    houseNumber
                    postalCode
                    city
                    country
                  }
                  vatNumber
                  shippingAddress {
                    companyName
                    name
                    street
                    houseNumber
                    postalCode
                    city
                    country
                  }
                  products (first: 50) {
                    nodes {
                      id
                      quantity
                      sku
                      unshippedQuantity
                    }
                    pageInfo {
                      hasNextPage
                    }
                  }
                }
              }
            }
            
            

Fetch a single order

You can now fetch this order from the API using the request below. Please only request the fields you actually need.

query {
  order(id: "T3JkZXI6ODk2ODI4MDAxMDkxNTg1") {
    id
    number
    billingAddress {
        companyName
        name
      street
      houseNumber
      postalCode
      city
      country
    }
    shippingAddress {
        companyName
        name
      street
      houseNumber
      postalCode
      city
      country
    }
    currency
    subtotalPrice
    shippingPrice
    taxPrice
    totalPrice
    productsCount
    products(first: 50) {
      nodes {
        brand
        title
        variantTitle
        sku
        ean
        caseQuantity
        quantity
        unitPrice
        subtotalPrice
        taxPrice
        totalPrice
      }
      pageInfo {
        hasNextPage
      }
    }
    status
    isPaid
    isConfirmed
    paidAt
    confirmedAt
    deliveredAt
    cancelledAt
    createdAt
    updatedAt
  }
}

For information on which fields you can fetch see the Order object type.

Manage orders & Fulfilment

You fulfil orders through the API. The order process goes as followed:

• A retailer places an order
• The supplier must confirm the order
  • Confirming an order means you have the requested products on stock
• You create one or multiple shipments for the products
• Per shipment you can choose a shipment method (ship yourself or use Orderchamp shipping)
• The retailer is notified about the shipment
• The order is marked as delivered & completed by the retailer

Find orders to fulfil

You can query our API for the orders in need of fulfilment, by passing the isFulfilled: false parameter.
In the query below we are fetching the most recent unfulfilled orders, and their products with the quantity we still need to ship.

You can also subscribe to the ORDER_CONFIRMED webhook to be automatically notified when an order has been confirmed, which usually means it is ready for fulfilment.

query {
    orders(first: 10, isFulfilled: false, sort: CREATED_AT_DESC) {
    nodes {
      id
      status
      isFulfilled
      isConfirmed
      billingAddress {
        companyName
        name
        street
        houseNumber
        postalCode
        city
        country
      }
      vatNumber
      shippingAddress {
        companyName
        name
        street
        houseNumber
        postalCode
        city
        country
      }
      products (first: 50) {
        nodes {
          id
          quantity
          sku
          unshippedQuantity
        }
        pageInfo {
          hasNextPage
        }
      }
    }
  }
}

Create a shipment

After you have fetched the order and the unshippedQuantity per product, you can now create a shipment.

Note: The products in this request refers to the OrderProduct.ID as returned by the Order query above. Not to the Product.ID as returned by the Product query.

mutation {
  shipmentCreate(input: {
    orderId: "T3JkZXI6MTEyNzg1ODQ4NzE5NzY5Nw",
    products: [{
      id: "T3JkZXJQcm9kdWN0OjExMjc4NTg0ODgxODA3Mzc",
      quantity: 1
    }]
  }) {
    shipment {
      id
    }
    userErrors {
      field
      message
    }
  }
}

Ship a shipment

After creating a shipment you can mark it as shipped and provide tracking details. If you have no tracking details you can use isTracked: false but it may take longer for the supplier to be paid out. You also need to specify the time you estimate it will take for the shipment to arrive at the retailer.

Ship with tracking number

mutation {
  shipmentShipped(input: {
    shipmentId: "U2hpcG1lbnQ6MTE4NjAxMjc5Mjk3OTQ1Nw",
    trackingNumber: "3SBOL12345678"
  }) {
    shipment {
      id
    }
    userErrors {
      field
      message
    }
  }
}

Ship without tracking number

mutation {
  shipmentShipped(input: {
    shipmentId: "U2hpcG1lbnQ6MTE4NjAxMjc5Mjk3OTQ1Nw",
    isTracked: false,
    deliveryTimeframe: ONE_TO_TWO_DAYS
  }) {
    shipment {
      id
    }
    userErrors {
      field
      message
    }
  }
}

Complete the order

After you have placed all the products in a shipment and marked them as shipped, the order.status should now be set to AWAITING_DELIVERY. At this point the order is complete and in a few days will be marked as delivered by the retailer.

Mark as paid

Order Portal only: We generally capture payments automatically via our partner Mollie. If you do capture payments yourself, you can manually mark orders as paid via the backoffice or the API. We do require a brief description on how the payment was captured, for your administration.

mutation {
  orderMarkAsPaid (input: {
    orderId: "T3JkZXI6MzQyMzg0OTQ2OTcwNjI0MQ"
      description: "Received on ABN Ambro Bank, reference OP00012"
  }) {
    order {
      id
    }
    userErrors { field message }
  }
}

Delivery date

We automatically calculate a delivery date based on your lead time, available in order.estimatedDeliveryAt. If you want to update this delivery date you can do this via the backoffice or the API. By default we let the customer know by email.

mutation {
  orderDeliveryDateUpdate (input: {
    orderId: "T3JkZXI6MzQyNDgwNzg2MDQ1MzM3Nw"
    estimatedDeliveryAt: "2025-04-23"
    shouldNotifyRetailer: true
  }) {
    order {
      id
      estimatedDeliveryAt
    }
    userErrors { field message }
  }
}

Invoices

For every fulfilled order we generate a supplier invoice. A supplier invoice is in the name of the supplier towards Orderchamp, for the goods the supplier has sold. This invoice will be paid out by Orderchamp to the supplier on the next settlement.
Some suppliers prefer to generate these invoices themselves. In this scenario, a supplier invoice is generated with the type PURCHASE_ORDER. The supplier can now generate the invoice themselves and upload it in their backoffice, after which we will pay out the invoice.

Fetch supplier invoices

{
  supplierInvoices(first: 10, sort: ID_DESC) {
    nodes {
      number
      currency
      totalPrice
      subtotalPrice
      taxPrice
      isPaid
      isCredit
      isTaxShifted
      taxCountry
      type
      status
      items (first: 10, after: null) {
        nodes {
          title
          type
          totalPrice
          currency
          sku
          caseQuantity
          unitPrice
          subtotalPrice
          taxPrice
          taxRate
          createdAt
          updatedAt
        }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
      issuer {
        companyName
        street
        houseNumber
        postalCode
        city
        country
        vatNumber
      }
      receiver {
        companyName
        street
        houseNumber
        postalCode
        city
        country
        vatNumber
      }
      order {
        number
      }
      createdAt
      updatedAt
    }
  }
}

Fetch available warehouses for supplier

If multiple warehouses are added in Orderchamp, you can use the query below to fetch the locationId.

{
  account {
    locations (first: 5) {
      nodes {
        id
        name
        isPrimary
        isOrderchampFulfilmentCentre
        address {
          street
          houseNumber
        }
      }
    }
  }
}

Reponse

{
  "data": {
      "account": {
          "locations": {
              "nodes": [
                  {
                      "id": "TG9jYXRpb246MTQxMzY4NDU2NTM0NDI1Nw",
                      "name": "Beautiful Brand",
                      "isPrimary": true,
                      "isOrderchampFulfilmentCentre": false,
                      "address": {
                          "street": "Korte Leidsedwarsstraat",
                          "houseNumber": "49-1"
                      }
                  },
                  {
                      "id": "TG9jYXRpb246MTY3Mzk1NTIwNzM0ODIyNQ",
                      "name": "Cool Warehouse",
                      "isPrimary": false,
                      "isOrderchampFulfilmentCentre": false,
                      "address": {
                          "street": "Damstraat",
                          "houseNumber": "1"
                      }
                  }
              ]
          }
      }
  }
}

Customers

When using our Order Portal product, you can import your own customers and invite them to your Order Portal.

Create Customers

Only the companyName, locale, email, and country are required.

mutation {
  portalCustomerUpsert (input: {
    externalId: "your-own-customer-id"
    companyName: "Cool Kids Retail B.V."
    vatNumber: "NL12345678B01"
    cocNumber: "12345678"
    firstName: "Steve"
    lastName: "Kiddy"
    email: "steve@coolkiddy.com"
    portalMinimumOrderAmount: "100"
    portalFreeShippingThreshold: "250"
    phone: "0612345678"
    locale: "nl"
    street: "Hoofdstraat"
    houseNumber: "1"
    postalCode: "1000 AB"
    city: "Amsterdam"
    country: "nl"
    sendInviteMail: true
  }) {
    customer {
      id
    }
    userErrors { field message }
  }
}

Update customers

Simply pass the customer id.

mutation {
  portalCustomerUpsert (input: {
    id: "Q3VzdG9tZXI6MzQyMzg3NDQwMTAwOTY2NQ"
    companyName: "Cool Kids Retail B.V."
  }) {
    customer {
      id
    }
    userErrors { field message }
  }
}

Read customers

All your customers from different sales channels can be read from one unified API. You may specify the channel to filter a specific channel, for example MARKETPLACE, DROPSHIPPING, or PORTAL. If a customer has the channel PORTAL, it will never have additional channels like MARKETPLACE or DROPSHIPPING. This is a data security measure, aimed to protected your private data and customers. Orderchamp will never send marketing material towards your private portal customers.

{
  customers (first: 10, salesChannels: [PORTAL]) {
    edges {
      node {
        id
        externalId
        companyName
        channels
      }
    }
  }
}

Orderchamp maintains many integrations for a smooth dropshipping experience, namely with Shopify, WooCommerce, Lightspeed eCom, and Shopware 6. In case you want to build your own integration with our Dropshipping platform use the guide below.

How it works

1. Sign up as a retailer on www.orderchamp.com/ds
2. Reach out to Orderchamp and ask to build your own dropshipping integration, so we can enable this flow for you
3. When signing up to Dropshipping, a new option should now be available to create a custom integration (API)
4. Enter the required details such as your store's name, url, and a webhook url to which we can send product, order, and fulfilment updates
5. You should now receive your access token, store this safely it wont be visible anymore (you can reset it later)
6. Browse the marketplace and add products to your import list
7. Using the API you can fetch the products on your import list to send them to your eCom store
8. Using the API you can create orders for dropshipping products, and retrieve fulfilment updates

Your first request

Using the access token you received during the signup you can now make API calls as follows:

  POST https://api.orderchamp.com/v1/graphql
  Authorization: Bearer 1562317b0b387ef5739b71597bb1eed63cbabec0
  Content-Type: application/json

{
  "query": "{ account { name } }",
  "variables": {}
}

Channels

Your eCom or POS store is called a Channel in Orderchamp. During the Dropshipping signup we ask for some channel information such as the name, url, and a webhook url for your store. You can alway update this information through the API later.

View your channel

query {
  channels (first: 1) {
    nodes {
      id
      name
      url
    }
  }
}

Publications

Once you have created a Channel through the Dropshipping signup you are ready to pick the products you want to offer in your store.

1. You visit the Dropshipping Marketplace at www.orderchamp.com/ds
2. Add the products to your import list, we call these products Publications
3. We send webhooks about publications to keep you up to date
4. Alternatively you can periodically fetch all your publications

Example webhook (Publication Created)

Headers:
user-agent  Orderchamp/{version}
x-orderchamp-webhook-id V2ViaG9vazoyNjczNDM4NTc1MTk4MjA5
x-orderchamp-signature  fb2ea5e6a6003b95549fcad170b46bd49ca153dc225c861b6132fe799aeddaa6
x-orderchamp-event  PUBLICATION_CREATED
x-orderchamp-account-id QWNjb3VudDoyNjYzMzc1MDA5MTAzODcz

{
  "data": {
    "publication": {
      "id": "UHVibGljYXRpb246MjY3MzQ3MDUwMzQ2OTA1Nw",
      "status": "syncing",
      "listing": {
        "product": {
          "id": "UHJvZHVjdDoyNjU5NDE4NTMwNDk2NTEz"
        }
      },
      "createdAt": "2023-11-02T12:34:49Z",
      "updatedAt": "2023-11-02T12:34:49Z"
    }
  }
}

Fetch a publication
Using the information in the webhook you can fetch the latest version of the publication

query {
  publication (id: "UHVibGljYXRpb246MjY3MzQ3MDUwMzQ2OTA1Nw") {
    id
    status
    listing {
      id
      translations {
        en {
          title
          description
        }
        nl {
          title
          description
        }
      }
      category {
        path
        name
      }
      dropshippingShippingDetails {
        countryGroup
        fixedCosts
        variableCosts
        estimatedShippingDays
      }
      dropshippingReturns
      variants (first: 100) {
        nodes {
          id
          title
          options {
            name
            value
          }
          dropshippingPrice
          msrp
          sku
          ean
          inventoryQuantity
          inventoryPolicy
        }
      }
      images (first: 20, sort: POSITION_ASC) {
        nodes {
            transformedUrl(width: 1200, height: 1200, method: FILL)
        }
      }
    }
  }
}

Fetch all your publications
You can also iterate through all the publications in your import list. Use the pageInfo to paginate.

query {
              publications (first: 100, after: null, sort: ID_DESC) {
                nodes {
                  id
                  status
                  # Add all the fields you want to retrieve
                }
                
                pageInfo {
                  hasNextPage
                  hasPreviousPage
                  endCursor
                }
              }
            }
            

Update status
Whenever you add a product to your import list it will initially be in a "SYNCING" state. After you have successfully created the product in your webshop you should update the status to reflect this. If the sync has failed you can also indicate that.

mutation {
  publicationStatusUpdated(input: {
    id: "UHVibGljYXRpb246MjY3OTAyOTgyNDMwNzIwMQ"
    status: "success" # or failed
    productUrl: "https://domain.com/product-123"
  }) {
    publication {
      status
    }
  }
}

Webhooks

By default we set up a webhook for you using the url you given us during the signup. You can see and update the webhook, or create additional webhooks via the API. We send you events about content updates for which pricing and inventory level are the most important. Updating the webhooks can be done through mutations.

query {
  webhooks (first: 1) {
    nodes {
      id
      events
      callbackUrl
      active
    }
  }
}

Orders

Whenever you receive an order in your webshop containing some dropshipping products you create an order via the API to notify our brands to fulfill these products. The flow is as follows:

1. You receive an order in your webshop
2. You extract the dropshipping products
3. Create an Ingested Order via the API
4. We convert the Ingested Order into a Retailer Order
5. The brand is notified and will fulfill your order as soon as possible
6. We send a webhook with the event ORDER_UPDATED whenever anything changed, such as new shipments or (partial) cancellations
7. You can fetch the tracking details via the API

The Ingested Order and its products all have their own status indicating if the product was found and is available.

Order Status
CONVERTED = The entire order was created successfully
PARTIALLY_CONVERTED = Some products were not available (out of stock or not found)
FAILED = Something went wrong while creating the order, (no availability, invalid shipping country, not approved)

Order Product Status
MATCHED = The product was found and is available
PRODUCT_NOT_FOUND = Could not find a product by its ID or SKU
OUT_OF_STOCK = The product is no longer in stock
NOT_AVAILABLE_FOR_DROPSHIPPING = The supplier has delisted this product
NOT_APPROVED_BY_SUPPLIER = The supplier might have revoked your access to dropship their products
SHIPPING_UNAVAILABLE = The supplier does not ship to the country you requested
CART_ERROR = An unknown issue occurred. If you run into this please contact us

Create an IngestedOrder
When the order was successfully created ensure you store the RetailerOrderId as you'll need this later to fetch order updates and tracking information.
Test orders can be created by adding the isTest: true parameter. This will ensure the order isnt fulfilled by the brand. Test orders are marked as paid automatically and after 10 minutes marked as fulfilled with fake tracking information, to allow you to test the fulfillment flow.

mutation {
    ingestedOrderCreate(input: {
      externalOrderId: "123456678"
      externalOrderNumber: "ORD0002"
      shippingAddress: {
        companyName: "Orderchamp"
        firstName: "Menno"
        lastName: "Wolvers"
        street: "Korte Leidsedwarsstraat"
        houseNumber: "49a"
        postalCode: "1017 PW"
        city: "Amsterdam"
        country: NL
      }
      email: "info@orderchamp.com"
      isTest: true
      products: [{
        listingVariantId: "TGlzdGluZ1ZhcmlhbnQ6MjY3OTAwOTYxODgzNzUwNQ"
        quantity: 2
        title: "Candle"
        sku: "sku-123"
      }]
    }) {
        ingestedOrder {
            id
            status
            retailerOrder {
              id
              status
            }
            products {
              status
            }
        }
        userErrors {
            field
            message
        }
    }
}

Fetch order updates
Whenever you receive an ORDER_UPDATED webhook event you can fetch the most recent version of the order. A Retailer Order consists of multiple Supplier Orders which contain the shipments as sent by the brand.

{
              retailerOrder(id: "UmV0YWlsZXJPcmRlcjoyNjc5MTE3MDA2NzMzMzEz") {
                id
                number
                status
                supplierOrders {
                  id
                  products (first: 100) {
                    nodes {
                      sku
                      quantity
                      listingVariant {
                        id
                      }
                    }
                  }
                  
                shipments (first: 5) {
                    nodes {
                      id
                      trackingNumber
                      trackingUrl
                      products (first: 100) {
                        nodes {
                          quantity
                          sku
                          listingVariant {
                            id
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
            
            

Supplier Order Status
AWAITING_CONFIRMATION = Waiting for the brand to confirm the order
AWAITING_FULFILMENT = Waiting for the brand to create shipments
AWAITING_SHIPMENT = The shipments have been created and are awaiting tracking information
AWAITING_DELIVERY = The shipments have been sent and are awaiting delivery
COMPLETED = All products have been delivered to the retailer
CANCELLED = This order has been cancelled

In this tutorial we are going to set-up a Laravel application that uses the Orderchamp/orderchamp-api-php client. The client can be used stand alone, for the purpose of this tutorial we are going to use the Laravel package Orderchamp/orderchamp-laravel, which is basically a wrapper for the client that can be configured by using environment variables.

Preparing the project

Let's start by creating a bare Laravel application by using Composer.

$ cd ~/Sites
$ composer create-project --prefer-dist laravel/laravel orderchamp-app
$ cd orderchamp-app

Adding the Laravel package

$ composer require Orderchamp/orderchamp-laravel

Updating .env

Open .env file and add the following environment variables:

ORDERCHAMP_CLIENT_ID=ca8bd79cab7987ba8c7ba34
ORDERCHAMP_CLIENT_SECRET=uRc1i3n7s3cr3t097sdf978c987a6
ORDERCHAMP_API_URL=https://api.orderchamp.com/v1
ORDERCHAMP_WEB_URL=https://www.orderchamp.com
ORDERCHAMP_VERIFY=true

Configure permission scope

Create the file config/orderchamp.php to set the proper permissions you need for your app.

<?php
            
            return [
                'scopes' => [
                    'account_read',
                    'products_read',
                    'products_write',
                ],
            ];
            
            

Register Orderchamp Laravel Middleware

Open app/Http/Kernel.php to register the Auth Middleware that comes with the laravel package.

<?php
            namespace App\Http;
            use App\Http\Middleware\OrderchampAuth;
            use Illuminate\Foundation\Http\Kernel as HttpKernel;
            
            class Kernel extends HttpKernel
            {
                //...
            
                protected $routeMiddleware = [
                    'auth'            => \App\Http\Middleware\Authenticate::class,
                    'auth.basic'      => \Illuminate\Auth\Middleware\AuthenticateWithBasicAuth::class,
                    'bindings'        => \Illuminate\Routing\Middleware\SubstituteBindings::class,
                    'cache.headers'   => \Illuminate\Http\Middleware\SetCacheHeaders::class,
                    'can'             => \Illuminate\Auth\Middleware\Authorize::class,
                    'guest'           => \App\Http\Middleware\RedirectIfAuthenticated::class,
                    'signed'          => \Illuminate\Routing\Middleware\ValidateSignature::class,
                    'throttle'        => \Illuminate\Routing\Middleware\ThrottleRequests::class,
                    'verified'        => \Illuminate\Auth\Middleware\EnsureEmailIsVerified::class,
                    'orderchamp.auth' => OrderchampAuth::class,
                ];
            
                //...
            }
            

AuthController and registering route

This route will be used by Orderchamp to be redirected to so the app can validate the authenticated user. Create app/Http/Controllers/AuthController.php

<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Redirect;
use Orderchamp\Laravel\Orderchamp;
class AuthController extends Controller
{
    public function login()
    {
        $url = Orderchamp::api()->authorizationUrl(
            config('orderchamp.scopes'),
            url('auth/callback')
        );
        return Redirect::to($url);
    }
    public function logout(Request $request)
    {
        $request->session()->invalidate();
        return Redirect::to('/');
    }
    public function callback(Request $request)
    {
        $token = Orderchamp::api()->requestToken($request->all());
        $request->session()->put('token', $token);
        return Redirect::to('/');
    }
}

Now register the controller in routes/web.php

<?php
Route::get('auth/login', 'AuthController@login');
Route::get('auth/callback', 'AuthController@callback');
Route::get('auth/logout', 'AuthController@logout');

Note: these URL's are publicly available and used to store the ACCESS_TOKEN inside of a session.

Using protected routes for authenticated users

Use the Laravel Middleware that comes with the orderchamp-laravel package to verify authenticated users in protected routes. It is useful to proxy the GraphQL API so you can make a SPA for your integration.

Bonus: proxy GraphQL

You can proxy the GraphQL API by registering your own graphql endpoint, this endpoint can be consumed by your frontend application. By registering the 'orderchamp.auth' Middleware for this new route, you ensure that this proxy is restricted to authenticated users only. If an unauthenticated user tries to access this URL it will be redirected to the login page.

Create app/Http/Controllers/GraphiqlController.php

<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
use Orderchamp\Laravel\Orderchamp;
class GraphiqlController extends Controller
{
    public function proxy(Request $request)
    {
        $params = $this->validate($request, [
            'query'         => 'required|string',
            'variables'     => 'nullable|array',
            'operationName' => 'nullable|string',
        ]);
        return Orderchamp::api()->graphql(
            $params['query'],
            $params['variables'] ?? [],
            $params['operationName'] ?? null
        );
    }
}

Now register the controller in routes/web.php

<?php
Route::middleware(['orderchamp.auth'])->group(function () {
    Route::post('graphql', 'GraphiqlController@proxy');
});
// ...

This will allow you to post GraphQL requests to https://YOUR_APP_URL/graphql.