How to add ExternalIDs

In this example we take you through how to add externalIds to objects using the Operator API

  5 minute read  

What you’ll learn

In this article you’ll learn about adding externalIds to objects that support them, specifically:

  • Adding externalIds at object creation: e.g. with orders or adverts
  • Using externalIdUpsert to add a single externalId to an existing object
  • Using externalIdsUpsert to add one or more externalIds to an existing object
  • Retrieving externalIds on an object
  • Querying objects based on their externalId

What are externalIds?

ExternalIds are a way for API consumers to attach their own identifiers to Marketplacer objects, (e.g. an order) to enable them to cross reference objects across system boundaries. You can also query objects by their externalIds using the Operator API.

There are multiple object types that support the attachment of externalIds, including but not limited to:

  • order
  • invoice
  • seller
  • advert

Adding ExternalIds at object creation

Some mutations such as orderCreate & advertUpsert allow you to supply externalIds at the point when objects are created. An example of how to do this using orderCreate is shown below:

Example: orderCreate

In this example we are adding 2 externalIds with the following keys:

  • ACME_Order_Mgmt
  • ACME_Logistic_sys
    mutation createOrderWithExternalIds{
      orderCreate(input: {
        order: {   
          firstName: "John"
          surname: "Doe"
          phone: "0405123456"
          emailAddress: "john@email.com"
          billingFirstName: "John"
          billingSurname: "Doe"
          messageToSeller: "This is a test order on Wed 19th Feb"
          billingEmailAddress: "john@email.com"
          address: {
            address: "1 Bourke Street"
              city: "Melbourne"
              country: {
                code: "AU"
              }
              postcode: "3000"
              state: {
                name: "victoria"
              }
          }
          externalIds: [{
            key: "ACME_Order_Mgmt"
            value: "ORD_3342"
          },
          {
            key: "ACME_Logistic_sys"
            value: "LOG_1234"
          }
          ]
          termsAndConditionsAccepted: true
          }
        lineItems: [{             
          variantId: "VmFyaWFudC00ODE3"
          quantity: 1
          totalCents: 22500
          postageCents: 1000 
        }]
      })
      {
        order{
          id
        }
      }
    }

As you can see you are able to create any number of key / value pairs as required.

Please refer to the individual docs (e.g. advertUpsert) for more detail on how to add externalIds at object creation.

Upserting on existing objects

In addition to adding externalIds at the point of object creation, you can “upsert” externalIds on existing objects.

Upserting is when you add/insert data when it doesn’t already exist, and update when it does. The owner and key values combined determine the uniqueness of the externalId. E.g. if an owner and key combination already exist, then supplying them again, will result in the update of the value.

Example: externalIdUpsert

This mutation allows you to add 1 externalId to an existing object that supports externalId attachment, you need to supply:

  • The owner (ID) of the object (E.g. order, invoice or advert), that you want to work with
  • The key for the externalId
  • The value for the key

Mutation

mutation upsertExternalIdOnInvoice($input: ExternalIDUpsertMutationInput!) {
 externalIdUpsert(input: $input) {
  errors {
   field
   messages
  }
  externalId {
   key
   value
  }
 }
}

Variables

{
	"input": {
		"owner": "SW52b2ljZS0xMzY4NA==",
		"key": "ORDER_MGMT_SYS",
		"value": "OMS_3346882433"
	}
}

Example: externalIdsUpsert

This mutation allows you to add 1 or more externalIds to an existing object that supports externalId attachment, you need to supply:

  • The owner (ID) of the object (E.g. order, invoice or advert), that you want to work with
    • Note: You can only supply 1 owner
  • The key(s) for the externalId
  • The value(s) for the key(s)

Mutation

mutation upsertExternalIdsOnInvoice($input: ExternalIdsUpsertMutationInput!) {
 externalIdsUpsert(input: $input) {
  errors {
   field
   messages
  }
  externalIds {
   key
   value
  }
 }
}

Variables

{
  "input": {
    "ownerId": "SW52b2ljZS0xMzY4NA==",
    "externalIds": [
      {"key": "ORDER_MGMT_SYS", "value": "OMS_3346882433" },
      {"key": "LOGISTICS_SYS" , "value": "LOG_ZSZF777-999"}
    ]
  }
}

Retrieving externalIds

Returning this data via a GraphQL query is no more complex than any other, an example using the updatedOrders query is illustrated below, but the same syntax would be used for other queries that have externalIds:

query getOrdersWithExternalIds {
 updatedOrders(updatedSince: "2021-02-19", first: 10) {
  nodes {
   id
   externalIds {
     key
     value
   }
  }
 }
}

Querying Objects by externalId

One of the benefits of attaching externalIds to objects is the ability to retrieve those objects by externalId. This is achieved through the use of the externalIds query, an example of which is shown below:

Query

query getInvoiceByExternalId {
 externalIds(
  ownerType: "Invoice"
  key: "ORDER_MGMT_SYS"
  value: "OMS_3346882433"
 ) {
  id
  key
  value
  owner {
   id
   __typename
   ... on Invoice {
    id
    createdAt
    statusFlags
   }
  }
 }
}

Given that we are supplying: ownerType, key and value we’d expect this to return a single result:

{
  "data": {
    "externalIds": [
      {
        "id": "RXh0ZXJuYWxJRC0yNDU=",
        "key": "ORDER_MGMT_SYS",
        "value": "OMS_3346882433",
        "owner": {
          "id": "SW52b2ljZS0xMzY4NA==",
          "__typename": "Invoice",
          "createdAt": "2024-06-19T16:48:02+10:00",
          "statusFlags": [
            "PAID"
          ]
        }
      }
    ]
  }
}

You can for example, omit the value and just query based on the owner and key:

Query

query getInvoicesByExternalIdKey {
 externalIds(ownerType: "Invoice", key: "ORDER_MGMT_SYS", first: 10) {
  id
  key
  value
  owner {
   id
   __typename
   ... on Invoice {
    id
    createdAt
    statusFlags
   }
  }
 }
}

This is more likely to return a collection of objects (invoices in this case) that have externalIds with the specified key, (noting that you should employ pagination when you expect more than 1 result).

{
  "data": {
    "externalIds": [
      {
        "id": "RXh0ZXJuYWxJRC0yNDU=",
        "key": "ORDER_MGMT_SYS",
        "value": "OMS_3346882433",
        "owner": {
          "id": "SW52b2ljZS0xMzY4NA==",
          "__typename": "Invoice",
          "createdAt": "2024-06-19T16:48:02+10:00",
          "statusFlags": [
            "PAID"
          ]
        }
      },
      {
        "id": "RXh0ZXJuYWxJRC0yNDc=",
        "key": "ORDER_MGMT_SYS",
        "value": "OMS_3346882434",
        "owner": {
          "id": "SW52b2ljZS0xMzg2OA==",
          "__typename": "Invoice",
          "createdAt": "2024-09-11T13:12:24+10:00",
          "statusFlags": [
            "PAID"
          ]
        }
      }
    ]
  }
}

Considerations

The use of externalIds as described in this article is intended to be used only within the context of the GraphQL API, i.e.:

  • ExternalIds are not accessible via the Marketplacer Web frontend