Using Order Tags

Overview

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

Note

This information pertains to the order tags functionality that is part of Shipwell's modern order framework. This is the order framework that is documented in the orders section of the Shipwell Developer Portal. We continue to maintain the strong Orders (Legacy/v2) framework for existing customers that utilize this legacy framework, however functionality documented and described in this orders section does not pertain to Orders (Legacy/v2).

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

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

The following is an example on how to create a tag via API that may be applied to objects like orders after tag creation. In the future, this generalized reusable tag structure will allow you to apply the same tag with the same properties other objects in addition to the order tags that are already supported.

Example request

curljavascriptpythonjava

Copy

Copied

curl -i -X POST \
  'https://sandbox-api.shipwell.com/tags' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
        "name":"example abc",
        "description":"I am an example tag.",
        "status":"ACTIVE",
        "color":"#77F94D"
  }'

Copy

Copied

const payload = {
    "name":"example abc",
    "description":"I am an example tag.",
    "status":"ACTIVE",
    "color":"#77F94D"
};

const basePath = "";
const host = "sandbox-api.shipwell.com"
const targetUrl = `https://${host}${basePath}/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 = ""
host = "sandbox-api.shipwell.com"
target_url = (
    "https://"
    + host
    + base_path
    + "/tags/"
)

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

payload = {
    "name":"example abc",
    "description":"I am an example tag.",
    "status":"ACTIVE",
    "color":"#77F94D"
}

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 = "";
String host = "sandbox-api.shipwell.com";
String targetUrl = "https://" +
  host +
  base_path +
  "/tags/";

String requestBody = "{\"name\":\"example abc\",\"description\":\"I am an example tag.\",\"status\":\"ACTIVE\",\"color\":\"#77F94D\"}";
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)
   "description":"I am an example tag.", // human-readble description
   "status":"ACTIVE", // status of the tag, i.e. active, inactive, or potential future states
   "color":"#77F94D", // hex color code
   "id":"01J9ETHMDYW8B109K2B0TZ16T9", // read only system-generated tag id 
   "slug":"example-123", // read only system-generated url-friendly slug, i.e. for building urls like /something/example-123
   "created_at":"2025-10-05T17:09:57.822415+00:00", // ISO-8601 date/time of tag creation
   "updated_at":"2025-10-05T17:09:57.822415+00:00", // ISO-8601 date/time of tag update
   "deleted_at":null // ISO-8601 date/time of tag delete (not deactive, but delete)
}

Tip

What is a slug? Learn about slugs here.

3. Update Tag

The following is an example API request that updates a tag. Updating the tag name, description, status, etc. will globally update these details for a tag (i.e. you will not need to update each individual order 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/tags/{tag_id}' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
        "name":"example 123",
        "description":"I am an example tag.",
        "status":"ACTIVE",
        "color":"#75FBFD"
  }'

Copy

Copied

const payload = {
    "name":"example 123",
    "description":"I am an example tag.",
    "status":"ACTIVE",
    "color":"#75FBFD"
};

const basePath = "";
const host = "sandbox-api.shipwell.com"
const tagId = "YOUR_TAG_ID";
const targetUrl = `https://${host}${basePath}/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 = ""
host = "sandbox-api.shipwell.com"
tag_id = "YOUR_TAG_ID"
target_url = (
    "https://"
    + host
    + base_path
    + "/tags/" + tag_id
)

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

payload = {
    "name":"example 123",
    "description":"I am an example tag.",
    "status":"ACTIVE",
    "color":"#75FBFD"
}

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 = "";
String host = "sandbox-api.shipwell.com";
String tagId = "YOUR_TAG_ID";
String targetUrl = "https://" +
  host +
  base_path +
  "/tags/" + tagId;

String requestBody = "{\"name\":\"example 123\",\"description\":\"I am an example tag.\",\"status\":\"ACTIVE\",\"color\":\"#75FBFD\"}";
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
   "description":"I am an example tag.", // human-readble description
   "status":"ACTIVE", // status of the tag, i.e. active, inactive, or potential future states
   "color":"#75FBFD", // hex color code
   "id":"01J9ETHMDYW8B109K2B0TZ16T9", // read only system-generated tag id 
   "slug":"example-123", // read only system-generated url-friendly slug, i.e. for building urls like /something/example-123
   "created_at":"2025-10-05T17:09:57.822415+00:00", // ISO-8601 date/time of tag creation
   "updated_at":"2025-10-28T16:55:29.602810+00:00", // ISO-8601 date/time of tag update
   "deleted_at":null // ISO-8601 date/time of tag delete (not deactive, but delete)
}

4. Find Tags

Tags may be looked up by various criteria like name, slug, etc.

Note

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

Querying for tags is purposefully similar to other list/query API calls in the platform and will be familiar to you if you have queried for objects like orders. You may combine various search or query criteria to filter tags and apply an order_by querystring parameter if you which to sort the orders by a particular property on the tag.

Set limit querystring parameter in the request to restrict the number of results returned from the request. Example: /tags?limit=10 .
Set the page querystring parameter in the request to select a specific page of results (i.e. if there are 20 total items, total_count is 20 in the response body, that match the query and the limit is 10 then ?limit=10&page=2 would return the second page of results which are items 11-20 )
When querying to viewing results by date/times, use the UTC time zone instead of a local time zone.
Date/times are represented as ISO 8601 date/time strings in the UTC time zone (a Z or +00:00 at the end of the date/time string is the indicator for UTC ).
See the tags list API reference for a detailed list of fields or properties for the request and response structures for this operation.

Example request

About This Request

This is an example of querying for tags that contain the text example ( case insensitive ) in the tag name and have the ACTIVE status.
To see the full list of stag statuses see the tag status documentation here .
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/tags?name__contains=example&status=ACTIVElimit=100' \
  -H 'Authorization: YOUR_AUTHORIZATION_HEADER'

Copy

Copied

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

const query = new URLSearchParams({
  name__contains: "example",  
  status: tagStatus,
  limit: 100, 
  // ... other parameters
}).toString();

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

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

Copy

Copied

import requests

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

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

query_params = {
    "name__contains": "example",
    "status": tag_status,
    "limit": 100
}

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

Example response

Copy

Copied

{
  "data": [
      {
        "id":"01J9ETHMDYW8B109K2B0TZ16T9",
        "name": "Example 123",   
        "status":"ACTIVE",
        // ...
      },
    // ... other tags ...
  ],
  "count": 100, // number of items in the "data" array for this response
  "total_count": 1000, // number of total items that match the query
  "links": {
    "next": "https://sandbox-api.shipwell.com/tags?name__contains=example&status=ACTIVE&limit=100&page=2", // next set of results that match the query
    "prev": null, // previous set of results that match the query
    "first": "https://sandbox-api.shipwell.com/tags?name__contains=example&status=ACTIVE&limit=100&page=1", // first set of results that match the query (i.e. first page)
    "last": "https://sandbox-api.shipwell.com/tags?name__contains=example&status=ACTIVE&limit=100&page=10" // last set of results that match the query (i.e. last page)
  }
}

4. Apply Tag(s) To Orders

When you want to apply a tag or tags to an order, look up the tag ids of the tags and prepare to update the order with the appropriate tags using the tag ids.

Once you have the tag ids:

Get the order that you wish to update. Learn how to get or retrieve an order(s) here .
Modify the tags property of the order to set it to an array/list of the tags .
Update an order by calling PUT /orders/{order_id} with the updated order payload containing the tags. Learn how to update an order here .

Example order tags

Copy

Copied

// order
// ...
"tags": [
  {
      "id": "01JANK984HKB7MQR09W4XTDY61",
      "name": "Second Tag",
      "slug": "second-tag",
      "color": "#006BA2"
  },
  {
      "id": "01J9ETHMDYW8B109K2B0TZ16T9",
      "name": "Example Tag",
      "slug": "example-tag",
      "color": "#77F94D"
  }
]

5. Find Orders By Tag

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

Supported parameters for querying for orders by tag include:

tags__slug__in
tags__id__in
tags__slug__not_in
tags__id__not_in

For example, you may find orders with a particular tag applied to them by tag id by calling GET /orders?tags__id__in=01J9ETHMDYW8B109K2B0TZ16T9.

The __in querystring parameters accept a , (comma) delimited list of multiple values if you want find objects/orders that match any of the values, i.e. GET /orders?tags__id__in=abc,123,01JANK984HKB7MQR09W4XTDY61,01J9ETHMDYW8B109K2B0TZ16T9.