External IDs

Each record stored in the Loaded system via this API can be uniquely identified by it's record type in combination with either an external ID or the Loaded ID automatically generated.

You can use an external ID to query for any record type in this API instead of using the Loaded IDs that get generated. The main use of external IDs is to ease synchronisation with an external system that has it's own record identifiers. An external ID can be any string value up to a maximum of 255 characters.

An external ID, when used in a url, starts with the prefix eid:, for example eid:12345678.

When creating or updating records you can supply an external ID by using the externalId field - there is no need to use the eid prefix here.

tip

The explanation here is a bit hard to digest coming in cold, hopefully the worked example shows the value this capability provides to a client.

Example

In this example we're going to create an Order that references a Cheeseburger menu item. There are a few steps to this, first we need to create the Item on the API, and then we create an Order that references that Item we've created.

We want to avoid the client from having to care about what id the Loaded system gives to the item we create - after all the POS system will already have it's own reference for the menu item in the order. To achieve this we'll attach an externalId to the Item that we create in Loaded, and then use this same externalId value to refer to what Item we want in the Order we create.

info

In this example we're assuming there is already a Category created that has the externalId value of my-pos-food-category-id.

Creating the item

We send a POST request to the /pos/items endpoint to create a new Item to represent the Cheeseburger we want to order.

The JSON object we send looks like the following:

{
  "categoryExternalId": "my-pos-food-category-id",
  "externalId": "abc-123",
  "name": "Cheeseburger",
  "price": 20
}

the value of the externalId property, abc-123 is just an example value - for your integration you'd use the ID value of the Cheeseburger menu item in your own database.

Here's the actual request used to create the item:

curl \
  -X POST \
  -d '{ "categoryExternalId": "my-pos-food-category-id", "externalId": "abc-123", "name": "Cheeseburger", "price": 20 }' \
  -H "Content-Type: application/json" \
  -H '"Authorization=Bearer {token}"' \
  https://api.loadedreports.com/v1/pos/items

Creating the order

Now we've got a Cheeseburger in the Loaded system we can create an Order for that product. This is done by sending a POST to the /pos/orders endpoint, we'll reference the Cheeseburger in the items property of the Order.

The JSON object we send to create the Order looks like the following:

{
  "externalId": "xyz-789",
  "createdAt": "2023-07-01T01:30:00Z",
  "status": "Created",
  "items": [
    {
      "externalId": "abc-123",
      "quantity": 1,
      "unitPrice": 20,
      "unitTax": 2.61
    }
  ],
}

Notice how in the item object we use the externalId value attached to the Cheeseburger. We don't need to worry about any ID that the Loaded system might use to refer to this item at all.

Here's the actual request used to create the order for a Cheeseburger:

curl \
  -X POST \
  -d '{ "externalId": "xyz-789", "createdAt": "2023-07-01T01:30:00Z", "status": "Created", "items": [ { "externalId": "abc-123", "quantity": 1, "unitPrice": 20, "unitTax": 2.61 } ], }' \
  -H "Content-Type: application/json" \
  -H '"Authorization=Bearer {token}"' \
  https://api.loadedreports.com/v1/pos/orders