externalIdUpsert

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

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

NameType
inputExternalIDUpsertMutationInput

Response

Returns ExternalIDUpsertMutationPayload


Error Responses

HTTP ErrorError MessageMeaning
401UnauthorizedYou don’t have access to the endpoint, likely Basic Authentication credentials are missing
401API Token has expiredYou 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
200Field ’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
200Argument ‘value’ on InputObject ‘ExternalIDUpsertMutationInput’ is required. Expected type String!You have not supplied a value
200Argument ‘key’ on InputObject ‘ExternalIDUpsertMutationInput’ is required. Expected type String!You have not supplied a key
200Argument ‘owner’ on InputObject ‘ExternalIDUpsertMutationInput’ is required. Expected type ID!You have not supplied a owner (id)

Further Reading