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.
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.
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/jsonResponse
{
"name": "east_warehouse"
}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.
- You'll need the
shipment_idof the shipment you wish to tag. - You'll need the tag value of the tag you are adding to the shipment.
If the tag doesn't exist, we will create it for you. You can also create tags in advance manually.
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"
}
}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.
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"
}
]
}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.
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.