Getting Started

Metadata

If you're using our APIs, you most likely have your own database with your own IDs and naming conventions.

To make working with our data easier, every object that can be modified is able to accept custom metadata.

The metadata are key-value pairs with the following limitations:

1. There is a cap of 25 key-value pairs per object. Generally you're referencing an internal ID or something of the like, so you should never worry about hitting this cap.
2. The maximum length for a key is 100 characters.
3. The maximum length for a value is 500 characters.

# Setting Metadata

Simply send any key value pairs using the metadata property. For example, if you want to add a metadata property to a location object, you can do so like this:

        const body = {
  metadata: {
    my_id: "123",
    something_else: true,
  },
};

fetch("https://api.packagex.io/v1/locations/loc_1u5ZR5pbStheaHuUpci4Ma", {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
});

      

			  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
		  

# Updating Metadata

To update a value, you can simply overwrite it with your new value. For example, if you wanted to overwrite my_id with a different value, the process is the same:

        const body = {
  metadata: {
    my_id: "ABC",
  },
};

fetch("https://api.packagex.io/v1/locations/loc_1u5ZR5pbStheaHuUpci4Ma", {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
});

      

			  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
		  

Note that just because we did not include the key something_else from the previous example does not mean it will be deleted.

# Deleting Metadata

You can only delete metadata by explicitly passing a null or empty string value to either the property you want to unset, or the whole metadata property.

# Delete a single key

        const body = {
  metadata: {
    something_else: null, //This will unset the something_else property
  },
};

      

			  
1
2
3
4
5
		  

# Delete all keys

        const body = {
  metadata: null, //This will unset all metadata properties
};

      

			  
1
2
3
		  

# Cannot do this

        const body = {
  metadata: {}, //This will do nothing
};

      

			  
1
2
3