External IDs

In order to allow integrations to persist information on which Katalys entities are related to which entities on the integration side we offer the concepts of external IDs and external data.

Products

External IDs can be retrieved with GraphQL queries on products:

JSON

{
  product(id: "44ad5ce9-9c3f-43c5-afab-d0796269d68c") {
    externalId
  }
}

JSON

{
  "data": {
    "product": {
      "externalId": "14"
    }
  }
}

If a product with an external ID is purchased (through the Katalys checkout process) the resulting order’s line item will reference the external ID (the following example assumes that the variant’s external ID is 99):

GRAPHQL

{
  order(id: "235c9162-80c2-4fd4-9eb8-e398ed130329") {
    lineItems {
      productExternalId
      variantExternalId
    }
  }
}

JSON

{
  "data": {
    "order": {
      "lineItems": [
        {
          "productExternalId": "14",
          "variantExternalId": "99"
        }
      ]
    }
  }
}

Orders

Similarly, orders can store external IDs as well. Additionally, they can store external data. This is a field that can store a given JSON. This allows you to treat the Katalys API as a database and store any metadata you might need for your integration.

GRAPHQL

mutation M($id: ID!, $externalId: String, $externalData: JsonString) {
  updateOrder(id: $id, externalId: $externalId, externalData: $externalData) {
    id
    externalId
    externalData
  }
}

JSON

// variables
{
	"id": "235c9162-80c2-4fd4-9eb8-e398ed130329",	
	"externalId": null,
	"externalData": "{\\"myField\\":\\"just an example\\"}"
}

JSON

// result
{
  "data": {
    "updateOrder": {
      "externalData": "{\\"myField\\":\\"just an example\\"}",
      "externalId": "myid-123",
      "id": "235c9162-80c2-4fd4-9eb8-e398ed130329"
    }
  }
}

In order to allow unstructured objects to be passed in externalData we have to encode the JSON as a string.