How to work with IDs

In this example we take you through how to work with IDs using the Operator API

3 minute read

What you’ll learn

In this article you’ll learn:

How Object IDs are formatted in the GraphQL API
What Legacy IDs are
What External IDs are

GraphQL IDs

Performing a simple query to return all Sellers via GraphQL, (and ensuring that you include the ID attribute in your requested result set), will look similar to the following:

GraphQL Seller Search Results

The IDs returned for the Sellers, (as is the case for all object IDs in GraphQL), are in base64, for example:

U2VsbGVyLTc4

Using a conversion tool to decode from Base64, (e.g. https://www.base64decode.net/) will yield the following:

Seller-78

A non-exhaustive list of examples for other object types are given below:

Object	Converted ID
Advert	`Advert-100008594`
Order	`Order-10033`
Invoice	`Invoice-10056`
Seller	`Seller-78`
Variant	`Variant-4959`
LineItem	`LineItem-64`
Shipment	`Shipment-13`

So typically:

GraphQL Object IDs should be used to uniquely identify objects in the Marketplacer GraphQL-based APIs
The LegacyID available on most GraphQL objects should be used as the “human-readable” id for that object, this value can also be used to cross-reference resources returned from the Legacy (REST-based) Seller API

Note

Base64 decoding IDs into their non-base64 format should not be relied upon by API consumers as Marketplacer reserves the right to change the unencoded composition at any time.

Legacy IDs

The LegacyID attribute is available on some GraphQL objects, e.g.:

Advert
Variant
Taxon
Invoice

This attribute can be used to retrieve the ID of the object as it would appear in the REST API without having to resort to any type of conversion:

Legacy IDs Retrieval

So just to compare and contrast the ID in the above example:

GraphQL ID (Base64)	GraphQL ID (Converted)	REST ID
QWR2ZXJ0LTEwMDAwODU5Nw==	Advert-100008597	100008597

External IDs

When creating objects with GraphQL you may want to provide an “External ID”. This ID will typically map to the ID of another (3rd party) system that manages representations of the same type of object.

E.g. you may track “order” objects in your own ERP System, so when you come to create an Order in Marketplacer via the GraphQL API, you may want to associate the ERP Order ID with the Order you create in Marketplacer.

External ID’s can therefore be retrieved, (queried), as shown in the example below, where we created an order with an External ID:

External IDs Retrieval

You can see that the External ID in this instance is comprised of:

Key: The “name” of the Key, e.g. ERP_Order_ID
Value: The actual value of the external id

ExternalIds Vs ExternalId

There is currently an additional ExternalID, (singular), attribute that is exposed via GraphQL, this attribute is typically used by:

The REST API
Integrations Manager (the tool that loads data from 3rd party eCom providers e.g. Shopify)

When working with GraphQL you should typically use only the ExternalIds (plural) variant, reserving ExternalId to read operations only.