Using Shipment Tags

Overview

Learn the best practices on how to create, update, and annotate shipments with tags.

Steps

1. Authenticate and Receive API Token

Authenticate to the API using these steps.

Note

Authorization HTTP headers in API requests, e.g. Authorization: YOUR_AUTHORIZATION_HEADER, typically take the form of Authorization: Token <user-token>. For more information on API authentication, navigate to the Authenticate documentation.

2. Create Tag

Note

Shipment tags vary from order tags in the API calls needed and best practices, but are similar concepts. See the create shipment tag API reference and the create order tag API reference.

Tags are a way to annotate shipments with shared references (i.e. cold-storage, west-coast, priority) so shipments may be looked up by these tags via API (learn more about querying for shipments here) or in the Shipwell UI. Associate tags to shipment via the create shipmentor update shipment API endpoints by specifying the tags in the payload. These tags have special filters on the shipment dashboard to allow users to find shipments by tag. Tags may be created or updated before adding them to a shipment if the tag did not previously exist by using the create shipment tag or update shipment tag API endpoints.

The following is an example on how to create a shipment tag via API that may be applied to shipments after tag creation.

Example request

Note

The color choices for shipment tags are restricted to these color name values. Shipment tags do not accept hexadecimal colors (i.e. "#77F94D").

Available color aliases/choices for shipment tags include:

Color Alias/Name	Hexadecimal Code
`cherry_bomb`	🔗 #b41d13
`electric_trees`	🔗 #1b7b3b
`faded_white`	🔗 #ffffff
`lake_travis`	🔗 #14592b
`ricky_fowler`	🔗 #df9100
`rock_bottom`	🔗 #838383
`sky_ship`	🔗 #0a6fdb
`so_cirrus`	🔗 #11a2dc
`the_hotness`	🔗 #870058
`well_water`	🔗 #7180ac

curljavascriptpythonjava

Copy

Copied

curl -i -X POST \
  'https://sandbox-api.shipwell.com/v2/shipments/tags/' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
        "name":"example abc",
        "color":"faded_white"
  }'

Copy

Copied

const payload = {
    "name":"example abc",
    "color":"faded_white"
};

const basePath = "/v2";
const host = "sandbox-api.shipwell.com"
const targetUrl = `https://${host}${basePath}/shipments/tags/`;
const resp = await fetch(
  targetUrl,
  {
    method: "POST",
    headers: {
      "Authorization": "YOUR_AUTHORIZATION_HEADER",
      "Content-Type": "application/json"
    },
    body: JSON.stringify(payload)
  }
);

const data = await resp.json();
console.log(data);

Copy

Copied

import requests

base_path = "/v2"
host = "sandbox-api.shipwell.com"
target_url = (
    "https://"
    + host
    + base_path
    + "/shipments/tags/"
)

headers = {
    "Authorization": "YOUR_AUTHORIZATION_HEADER",
    "Content-Type": "application/json",
}

payload = {
    "name":"example abc",
    "color":"faded_white"
}

response = requests.post(target_url, headers=headers, json=payload)
data = response.json()
print(data)

Copy

Copied

import java.io.IOException;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;

OkHttpClient client = new OkHttpClient();
String basePath = "/v2";
String host = "sandbox-api.shipwell.com";
String targetUrl = "https://" +
  host +
  base_path +
  "/shipments/tags/";

String requestBody = "{\"name\":\"example abc\",\"color\":\"faded_white\"}";
Request request = new Request.Builder()
  .url(targetUrl)
  .post(requestBody)
  .header("Authorization", "YOUR_AUTHORIZATION_HEADER")
  .header("Content-Type", "application/json")
  .build();

try (Response response = client.newCall(request).execute()) {
  if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
  response.body().string();
}

Example response

Copy

Copied

{
   "name":"example abc", // human-readable tag name, often this is lowercase, but can be any casing (recommendation: use consistent casing in your tag names)
   "color":"faded_white", // color name / alias
   "id":"6177ce56-defd-4265-af69-9d963df53d6e", // read only system-generated tag id 
   "company":"YOUR_COMPANY_ID_HERE" // UUID
}

3. Update Tag

The following is an example API request that updates a shipment tag. Updating the shipment tag name, etc. will globally update these details for a tag (i.e. you will not need to update each individual shipment that already has the tag applied or any instance of usage of the tag).

Example request

curljavascriptpythonjava

Copy

Copied

curl -i -X PUT \
  'https://sandbox-api.shipwell.com/v2/shipments/tags/{tag_id}' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
        "name":"example 123",
        "color":"electric_trees"
  }'

Copy

Copied

const payload = {
    "name":"example 123",
    "color":"electric_trees"
};

const basePath = "/v2";
const host = "sandbox-api.shipwell.com"
const tagId = "YOUR_TAG_ID";
const targetUrl = `https://${host}${basePath}/shipments/tags/${tagId}`;
const resp = await fetch(
  targetUrl,
  {
    method: "PUT",
    headers: {
      "Authorization": "YOUR_AUTHORIZATION_HEADER",
      "Content-Type": "application/json"
    },
    body: JSON.stringify(payload)
  }
);

const data = await resp.json();
console.log(data);

Copy

Copied

import requests

base_path = "/v2"
host = "sandbox-api.shipwell.com"
tag_id = "YOUR_TAG_ID"
target_url = (
    "https://"
    + host
    + base_path
    + "/shipments/tags/" + tag_id
)

headers = {
    "Authorization": "YOUR_AUTHORIZATION_HEADER",
    "Content-Type": "application/json",
}

payload = {
    "name":"example 123",
    "color":"electric_trees"
}

response = requests.put(target_url, headers=headers, json=payload)
data = response.json()
print(data)

Copy

Copied

import java.io.IOException;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;

OkHttpClient client = new OkHttpClient();
String basePath = "/v2";
String host = "sandbox-api.shipwell.com";
String tagId = "YOUR_TAG_ID";
String targetUrl = "https://" +
  host +
  base_path +
  "/shipments/tags/" + tagId;

String requestBody = "{\"name\":\"example 123\",\"color\":\"electric_trees\"}";
Request request = new Request.Builder()
  .url(targetUrl)
  .put(requestBody)
  .header("Authorization", "YOUR_AUTHORIZATION_HEADER")
  .header("Content-Type", "application/json")
  .build();

try (Response response = client.newCall(request).execute()) {
  if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
  response.body().string();
}

Example response

Copy

Copied

{
   "name":"example 123", // human-readable tag name, often this is lowercase, but can be any casing
   "color":"electric_trees", // color code name or alias
   "id":"6177ce56-defd-4265-af69-9d963df53d6e", // read only system-generated tag id 
   "company":"YOUR_COMPANY_ID_HERE" // UUID
}

4. Find Tags

Shipment tags may be listed and looked up in the API.

Note

Operations that associate tags to objects may require the global shipment tag identifier/id instead of a human-readable alias like the tag name.

Example request

About This Request

This is an example of listing all shipment tags in an account.
The list endpoint for shipment tags is not paginated and all shipment tags are returned (there are typically very few shipment tags in an account).
You may also request code samples in other programming languages by utilizing Shipwell's AI-powered developer chatbot on the developer portal. Ask the chatbot to "Translate the following code sample into programming language X." where X is your desired programming language.

curljavascriptpython

Copy

Copied

curl -i -X GET \
  'https://sandbox-api.shipwell.com/v2/shipments/tags/' \
  -H 'Authorization: YOUR_AUTHORIZATION_HEADER'

Copy

Copied

const basePath = "";
const host = "sandbox-api.shipwell.com";

const resp = await fetch(
  `https://${host}${basePath}/shipments/tags/`,
  {
    method: "GET",
    headers: {
      "Authorization": "YOUR_AUTHORIZATION_HEADER"
    }
  }
);

const data = await resp.json();
console.log(data);

Copy

Copied

import requests

base_path = "/v2"
host = "sandbox-api.shipwell.com"
target_url = "https://" + host + base_path + "/shipments/tags/"

headers = {
    "Accept-Type": "application/json"
}

response = requests.get(target_url, headers=headers)
data = response.json()
print(data)

Example response

Copy

Copied

[
    {
        "id":"6177ce56-defd-4265-af69-9d963df53d6",
        "name": "Example 123",
        // ...
    },
    // ... other tags ...
    // note: shipment tags are not paginated
]

4. Apply Tag(s) To Shipments

When you want to apply a tag or tags to a shipment, look up the tag ids of the shipment tags and prepare to update the shipment with the appropriate tags using the tag ids. The tags of a shipment are a property that is located within the metadata of the shipment.

Once you have the tag ids:

Get the shipment that you wish to update. Learn how to get or retrieve a shipment(s) here .
Modify the tags property of the shipment to set it to an array/list of the tag ids or set it to an empty array [] .
Update a shipment by calling PUT /v2/shipments/{shipment_id} with the updated shipment payload containing the tags. Learn how to update a shipment here .

Example shipment tags

Copy

Copied

// shipment
// ...
"metadata": {
  // ... other metadata properties on the shipment
  "tags": [
    "2c4ef555-073e-4f33-8bab-fd20f07f35b2", // tag id
    "7981460c-05ff-4778-9122-1ce217ffa600" // another tag id
  ]
  // ... other metadata properties on the shipment  
}

5. Find Shipments By Tag

Get shipments by tag using the list/query shipments API endpoint using the tag-related query parameters on the shipments get/list endpoint. Learn how to query shipments here.

Supported parameters for querying for shipments by tag include:

tags
- Includes any shipments that have the specified tag ids(s)
tags_excluded
- Excludes any shipments that have the specified tag id(s)

For example, you may find shipments with a particular tag applied to them by tag id by calling the shipments get/list API endpoint and specifying the tags parameter, e.g. GET /v2/shipments/tags/?tags=2c4ef555-073e-4f33-8bab-fd20f07f35b2.

To query for shipments that contain one of a set of tags (i.e. an OR query), specify the tags parameter multiple times in the URL similar to the transportation mode query example here, e.g. GET /v2/shipments/tags/?tags={tag_id_1}&tags={tag_id_2} (specifying multiple querystring parameter instances for tags results in ORing together and not ANDing the tags query).

Example get multiple shipments by tag(s) request

About This Request

This is an example of querying for shipments by multiple tags using the tag ids.
This example purposefully shows a complex example of ORing together search criteria for tags as this same pattern would be used to query for OR searches for other array search properties on shipment like status , pickup_number , pro_number , etc. See shipment list API reference for other properties or querystring parameters that may be utilized.
Just a reminder that you may also request code samples in other programming languages by utilizing Shipwell's AI-powered developer chatbot on the developer portal. Ask the chatbot to "Translate the following code sample into programming language X." where X is your desired programming language.

curljavascriptpython

Copy

Copied

curl -i -X GET \
  'https://sandbox-api.shipwell.com/v2/shipments?page-size=10&tags=2c4ef555-073e-4f33-8bab-fd20f07f35b2&tags=7981460c-05ff-4778-9122-1ce217ffa600' \
  -H 'Authorization: YOUR_AUTHORIZATION_HEADER'

Copy

Copied

const tagsParamMultiValue = ["2c4ef555-073e-4f33-8bab-fd20f07f35b2", "7981460c-05ff-4778-9122-1ce217ffa600"];
const basePath = "/v2";
const host = "sandbox-api.shipwell.com";

const urlSearchParams = new URLSearchParams({
  "page-size": 10, 
  // ... other parameters
});

tagsParamMultiValue.forEach((x) => urlSearchParams.append("tags", x));
const query = urlSearchParams.toString(); // page-size=10&tags=2c4ef555-073e-4f33-8bab-fd20f07f35b2&tags=7981460c-05ff-4778-9122-1ce217ffa600

const resp = await fetch(
  `https://${host}${basePath}/shipments?${query}`,
  {
    method: "GET",
    headers: {
      "Authorization": "YOUR_AUTHORIZATION_HEADER"
    }
  }
);

const data = await resp.json();
console.log(data);

Copy

Copied

import requests

tags_param_value = "YOUR_tags_PARAMETER"
base_path = "/v2"
host = "sandbox-api.shipwell.com"
target_url = "https://" + host + base_path + "/shipments"

headers = {
    "Accept-Type": "application/json",
    "Authorization": "YOUR_AUTHORIZATION_HEADER"
}

query_params = {
    "tags": tags_param_value,  # "tags": ["2c4ef555-073e-4f33-8bab-fd20f07f35b2", "7981460c-05ff-4778-9122-1ce217ffa600"]
    "page-size": 10
}

response = requests.get(target_url, headers=headers, params=query_params)
data = response.json()
print(data)

Example get multiple shipments by tag(s) response

Copy

Copied

{
  "results": [
      {
        "id":"caaad729-4b6f-49bf-8f93-b9f3de73b6e8",
        "reference_id": "SK799X",
        // ...
      },
    // ... other shipments ...
  ],
  "page-size": 10,
  "total_pages": 100, // number of pages of items based on the page size
  "total_count": 1000 // number of total items that match the query (including the items outside the current page of items/results)
}