External IDs

External IDs (XIDs) let you reference objects in Jungle using identifiers from your own — or other third-party — systems. They can be associated with any object in Jungle, making it easy to link Jungle objects to records in your existing systems and workflows.

Benefits of Using XIDs

1. Flexibility: Use any identifier that makes sense for your business, whether it's a SKU, an order reference, or a GUID from another system.
2. Consistency: Keep identifiers consistent across different systems and processes.
3. Integration: Reference Jungle objects by your own identifiers, so you don't have to store Jungle's IDs everywhere.

Anatomy of an XID

An XID is made up of three parts, plus the type of the object it identifies:

• typename — the kind of Jungle object, e.g. Order, Product, Location.
• namespace — the system or standard the identifier comes from, e.g. oms, shopify, my-domain.com. The jungle* and ape.cafe* namespaces are reserved.
• key — the kind of identifier within that system, e.g. order, sku, email.
• value — the identifier itself, e.g. 145729.

Together these form a single XID string, for example:

xid:jungle/Order:oms/order/145729

Assigning an XID

Assign an XID to an object with the xidAssign mutation. It takes the target object and the XID parts:

mutation {
  xidAssign(
    input: {
      object: { id: "1234", typename: "Order" }
      parts: { typename: "Order", namespace: "oms", key: "order", value: "145729" }
    }
  ) {
    ok
    ... on MutationSuccess {
      objects {
        id
        typename
      }
    }
    ... on MutationFailure {
      code
      reason
    }
  }
}

xidAssign either creates the XID or updates it if it already exists for that object.

Querying an object by its XID

Once assigned, you can use the full XID string anywhere a Jungle id is accepted. For example, fetch an object directly by its XID with the object query — the typename must match the XID's typename:

query {
  object(input: { id: "xid:jungle/Order:oms/order/145729", typename: "Order" }) {
    ... on Order {
      id
    }
  }
}

Reading an object's XIDs

Objects that support external IDs expose an xids field listing the XIDs assigned to them:

query {
  object(input: { id: "1234", typename: "Order" }) {
    ... on Order {
      id
      xids {
        nodes {
          namespace
          key
          value
          xid
        }
      }
    }
  }
}

Uniqueness and conflicts

An XID must be unique within the scope of an account: a given namespace/key/value can only point to one object. If you try to assign an XID that is already in use by a different object, the mutation fails — use the code and reason on MutationFailure to handle the conflict.

Removing an XID

To remove an XID from an object, use the xidUnassign mutation with the same object and parts you assigned.