Last updated

Tag Shipments

Tags are simple text-based flags or identifiers that you can add to shipments. Adding tags to shipments can help you query shipments later. Tags can be a simple label, like Guaranteed_Overnight or Fragile, whatever you need to help you in your workflow.

Create Tags

You can create the tags you wish to use in advance and then add tags to your shipments. However, if you tag a shipment with a tag value that doesn't yet exist, we'll make the tag for you at the same time.

Example Request & Response

In this example, we're creating a tag with the value east_warehouse. We could then add this tag to any shipment we know will ship from that warehouse.

POST /v2/tags/:tag_name

POST /v2/tags/east_warehouse HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

Response

{
 "name": "east_warehouse"
}

Add Tags to Shipments

Once you've created the tags you wish to use, you can add those tags to shipments so you can more easily query those shipments later.

Requirements

  • You'll need the shipment_id of the shipment you wish to tag.
  • You'll need the tag value of the tag you are adding to the shipment.
New Tags

If the tag doesn't exist, we will create it for you. You can also create tags in advance manually.

Example Request & Response

POST /v2/shipments/:shipment_id/tags/:tag_name

POST /v2/shipments/se-2102034/tags/east_warehouse HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__

Response

{
 "shipment_id": "se-2102034",
 "tag": {
   "name": "east_warehouse"
 }
}

List All Tags

Once you've created some tags you can use this call to list them, which can be useful if you want to, for example, have a user choose from a list of available tags to apply to a shipment.

The response will be an array of the tag names available to your account.

Example Request & Response

GET /v2/tags/

GET /v2/tags HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__

Response

{
 "tags": [
   {
     "name": "east_warehouse"
   },
   {
     "name": "west_warehouse"
   }
 ]
}

Remove a Shipment Tag

Use this call to remove a tag from a shipment. You'll need both the shipment_id and tag_name to perform this action successfully.

Example Request & Response

DELETE /v2/shipments/:shipment_id/tags/:tag_name

DELETE /v2/shipments/se-2102034/tags/east_warehouse HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__

If successful, you will receive HTTP 204, No Content in the response.