How to work with IDs

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

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 Invoices 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 Invoices, (as is the case for all object IDs in GraphQL), are in base64, for example:

  • SW52b2ljZS0xMzIxOA==

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

  • Invoice-13218

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

ObjectConverted ID
AdvertAdvert-100008594
OrderOrder-10033
InvoiceInvoice-10056
SellerSeller-78
VariantVariant-4959
LineItemLineItem-64
ShipmentShipment-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

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-100008597100008597

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.