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.
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.