Tags

Tags are lightweight labels used to organize and filter products. Each tag has a unique name within a store (case-insensitive). Tags can be managed standalone via this resource, or set directly on products via the tags array field on PATCH /v1/products/{id}.

Base URL: https://api.hydrajs.dev

Endpoints

Method	Path	Auth	Description
GET	/v1/tags	Publishable	List tags
POST	/v1/tags	Secret	Create a tag
PATCH	/v1/tags/{id}	Secret	Update a tag
DELETE	/v1/tags/{id}	Secret	Delete a tag

---

List tags

GET /v1/tags

Returns a paginated list of tags. Each tag includes a product_count indicating how many products use it.

Query parameters

Parameter	Type	Default	Description
limit	integer	25	Results per page (1–250)
cursor	string	-	Pagination cursor from a previous response
sort	string	created_at	Sort field: created_at, updated_at, name
order	string	desc	Sort direction: asc, desc
search	string	-	Filter by name (case-insensitive substring match, max 200 chars)
fields	string	-	Comma-separated fields to return

Request

curl https://api.hydrajs.dev/v1/tags?sort=name&order=asc&limit=50 \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

Response 200

{
	"data": [
		{
			"id": "tag_abc123def456ghij",
			"name": "basics",
			"product_count": 12,
			"created_at": "2026-03-10T08:00:00Z",
			"updated_at": "2026-03-10T08:00:00Z"
		},
		{
			"id": "tag_klm789nop012qrst",
			"name": "cotton",
			"product_count": 8,
			"created_at": "2026-03-12T14:30:00Z",
			"updated_at": "2026-03-12T14:30:00Z"
		},
		{
			"id": "tag_uvw345xyz678abcd",
			"name": "new-arrival",
			"product_count": 5,
			"created_at": "2026-06-01T10:15:00Z",
			"updated_at": "2026-06-01T10:15:00Z"
		}
	],
	"pagination": {
		"cursor": "eyJ0IjoiMjAyNi...",
		"has_more": true,
		"total": 24
	}
}

---

Create a tag

POST /v1/tags

Creates a new tag. Tag names are unique per store (case-insensitive). Returns 409 Conflict if a tag with the same name already exists.

Request body

Field	Type	Required	Description
name	string	Yes	Tag name (1–100 chars)

Request

curl -X POST https://api.hydrajs.dev/v1/tags \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "summer-sale"}'

Response 201

{
	"data": {
		"id": "tag_efg456hij789klmn",
		"name": "summer-sale",
		"product_count": 0,
		"created_at": "2026-08-17T12:00:00Z",
		"updated_at": "2026-08-17T12:00:00Z"
	}
}

Error 409 - duplicate name

{
	"error": {
		"code": "conflict",
		"message": "A tag with name \"summer-sale\" already exists."
	}
}

---

Update a tag

PATCH /v1/tags/{id}

Renames a tag. The new name must not conflict with an existing tag (case-insensitive). Returns the updated tag.

Request body

Field	Type	Required	Description
name	string	Yes	New tag name (1–100 chars)

Request

curl -X PATCH https://api.hydrajs.dev/v1/tags/tag_efg456hij789klmn \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "clearance"}'

Response 200

{
	"data": {
		"id": "tag_efg456hij789klmn",
		"name": "clearance",
		"product_count": 0,
		"created_at": "2026-08-17T12:00:00Z",
		"updated_at": "2026-08-17T12:05:00Z"
	}
}

---

Delete a tag

DELETE /v1/tags/{id}

Permanently deletes a tag and removes it from all associated products. This action cannot be undone.

Request

curl -X DELETE https://api.hydrajs.dev/v1/tags/tag_efg456hij789klmn \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 204

Empty body.

---

The tag object

Field	Type	Description
id	string	Unique ID (prefix: tag_)
name	string	Tag name (unique per store, case-insensitive)
product_count	integer	Number of products using this tag
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp