externalIdUpsert

Multiple external IDs can be attached to most Marketplacer GraphQL object types, enabling API consumers to reference objects using their own identifiers.

2 minute read

Key Information

Use-Case

Propagating identifiers between systems is a common use case in a multi-system integration. With this in mind, Marketplacer allows you to attach your own “external Ids” to most Marketplacer object types, so you can work with those ids, principally for object lookup using the externalIds query.

Further Points of Note

We currently have 2 “external id” constructs:
- ExternalId (Singular) - This field is typically used only internally by Marketplacer and only stores 1 externalId value
- ExternalIds (Plural) - This is a collection of key / value pairs, allowing API consumers to attach as many external ids as they like to most Marketplacer object types using this mutation
- The externalIdUpsert mutation relates only to the ExternalIds construct. I.e. you cannot use it to update the singular externalId field found on some Marketplacer object types.

Availability

Operator API: Yes
Seller API: No - Sellers cannot attach externalIds to objects

Example 1 - Single external ID attachment

mutation attachExternalId{
  externalIdUpsert(
    input: 
    { 
      owner: "SW52b2ljZS0xMzIxOA==", 
      key: "SYS99", 
      value: "3333" }
  ) {
    status
    errors {
      field
      messages
    }
  }
}

Example 2 - Multi external ID attachment

mutation {
  a: externalIdUpsert(
    input: 
    { 
      owner: "VmFyaWFudC0yNzUw", 
      key: "SYS1", 
      value: "ABCDE" }
  ) {
    errors {
      field
      messages
    }
  }
  b: externalIdUpsert(
    input: 
    { 
      owner: "VmFyaWFudC0yNzUw", 
      key: "SYS2", 
      value: "12345" }
  ) {
    errors {
      field
      messages
    }
  }
}

Arguments

Name	Type
input	`ExternalIDUpsertMutationInput`

Response

Returns ExternalIDUpsertMutationPayload

Error Responses

HTTP Error	Error Message	Meaning
401	Unauthorized	You don’t have access to the endpoint, likely Basic Authentication credentials are missing
401	API Token has expired	You don’t have access to the endpoint, likely that you are either not supplying an API Key, or the key you are supplying is invalid
200	Field ’externalIdUpsert’ doesn’t exist on type ‘Mutation’	You are not supplying either a valid API key, or an API Key (e.g a Seller API Key) that does not have permission to use this mutation
200	Argument ‘value’ on InputObject ‘ExternalIDUpsertMutationInput’ is required. Expected type String!	You have not supplied a `value`
200	Argument ‘key’ on InputObject ‘ExternalIDUpsertMutationInput’ is required. Expected type String!	You have not supplied a `key`
200	Argument ‘owner’ on InputObject ‘ExternalIDUpsertMutationInput’ is required. Expected type ID!	You have not supplied a `owner` (id)