externalIds

The externalIds query allows you to retrieve objects by external ids.

Key Information

Use-Case

The externalIds query allows you to search for objects in Marketplacer that may have had ExternalId(s) attached to them. 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.

Sellers can’t typically attach external Ids to objects with the exception of products (adverts) using the advertUpsert mutation.

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, or the operator (e.g. Sellers do not have access to the order object).

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

NameTypeDescription
ownerTypeStringSpecify the object type that the external Id has been attached to, e.g. Invoice, Advert etc.
keyStringThe key component of the external id.
valueStringThe value component of the external id.
values[String!]As an alternative to supplying a single value, you can supply a collection of values.
firstIntLimit the results to the first N values

Response

Returns [ExternalId!]


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
200An object of type <type> was hidden due to permissions.Most likely returned if a Seller is using the query, and the result set could include objects that don’t belong to them

Further Reading