Using the API

All merchant partners will use our API to create orders, add items, and tell Koalafi when items are delivered.


Make sure to review Key Concepts and Getting Started first.

Required Headers

We require two headers for each API query which we provide to you as part of the initial set up process.

  • public-dealer-id
  • private-api-key

API Reference

API Schema and GraphQL Playground

Best Practices

While interacting with the API, always check to see if the corresponding errors array for the mutation/query is empty before looking into the response object. The APIs will always return an error in that array if there was an issue, or an empty errors array if the call was a success. Look at the API Schema for more information on which errors type to check for.

Errors returned always have the same format, here is an example on how to correctly query for errors in a hypothetical mutation:

mutation {
    input: {
      sampleFakeBoolean: true
  ) {
    sampleMutationErrors {
      __typename // include this to get the error type back
      ... on ErrorA { // optional
      ... on ErrorB { // optional

In the above example, we would check the length of sampleMutationErrors. If length is 0, the mutation was a success, and we can use our sampleField. If length > 0, the __typename field can be used to see the type of error returned. Including the optional ... on ErrorA { message } fragment in our query, we can use that message to get more details on the error that occurred. A comprehensive view of possible errors is in our API Schema.