externalIds

Key Information

Use-Case

The externalIds query allows you to search for objects in Marketplacer that may have had ExternalId(s) attached to them using the externalIdUpsert mutation. ExternalIds are typically used to attach 3rd party system references to Marketplacer objects, e.g. Orders, Invoices and Adverts (aka Products), although many other object types support external Ids.

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 objects
  • The externalIds query relates only to the ExternalIds construct. I.e. you cannot use it to search for the singular externalId field.
• You can search by either key, value or both of these
• As external Ids can be attached to any object type, you need to specify the ownerType as part of your query arguments (e.g. Order, Invoice etc.), likewise to return object values for that concrete object type, you’ll need to specify an inline fragment in your query body, e.g. ... on Invoice
• Sellers can use this query but may experience an object permissions error if their search could bring back objects scoped to other sellers

Availability

• Operator API: Yes
• Seller API: Yes (Scoped to Seller-owned objects only)

Example 1 - Providing a single value

query getInvoicesByExternalId{
  externalIds(
    ownerType: "Invoice"
    key: "SYS1"
    value: "3333"
  ) {
    id
    key
    value
    owner {
    id
      __typename
      ... on Invoice {
        id
        totalCents
        lineItems{
          id
          variantName
        }
        seller{
          businessName
        }
      }
    }
  }
}

Example 2 - Providing multiple values

query {
  externalIds(
    ownerType: "Variant"
    key: "SYS1"
    values: ["11112", "11113", "11114"]
  ) {
    id
    key
    value
    owner {
      id
      __typename
      ... on Variant {
        id
        label
        countOnHand
      }
    }
  }
}

Arguments

Response

Returns [ExternalId!]

Error Responses

Further Reading

• externalIdUpsert Mutation
• How to work with Ids
• Connected Integration Blueprint