Hydra is now in beta|Get started free|Follow our journey on X.com

Collections API
On this page

Collections

Collections let you organize products into curated groups for storefront display. A collection can be manual (products added explicitly) or automatic (products matched by conditions). Each collection has a unique handle for URL routing and supports SEO metadata.

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

Endpoints

Method Path Auth Description
GET /v1/collections Publishable List collections
POST /v1/collections Secret Create a collection
GET /v1/collections/tree Publishable Get collection tree
PATCH /v1/collections/reorder Secret Reorder collections
GET /v1/collections/{id} Publishable Get a collection
PATCH /v1/collections/{id} Secret Update a collection
DELETE /v1/collections/{id} Secret Delete a collection (soft)
POST /v1/collections/{id}/products Secret Add products to a collection
DELETE /v1/collections/{id}/products/{product_id} Secret Remove a product from a collection
PATCH /v1/collections/{id}/products/reorder Secret Reorder products in a collection

List collections

GET /v1/collections

Returns a paginated list of collections. Supports search, filtering by type and status, and sparse fieldsets.

Query parameters

Parameter Type Default Description
limit integer 25 Results per page (1-100)
cursor string - Pagination cursor from a previous response
sort string created_at Sort field: created_at, updated_at, title
order string desc Sort direction: asc, desc
type string - Filter by type: manual, automatic
status string - Filter by status: active, draft
search string - Full-text search with typo correction
product_id string - Filter collections containing this product
fields string - Comma-separated fields to return

Request

curl https://api.hydrajs.dev/v1/collections?status=active&limit=10 \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

Response 200

{
	"data": [
		{
			"id": "col_abc123",
			"title": "Summer Sale",
			"handle": "summer-sale",
			"description": "Hot deals for the summer season.",
			"type": "manual",
			"status": "active",
			"image": "https://cdn.hydrajs.dev/stores/store_xxx/summer-banner.webp",
			"seo": {
				"title": "Summer Sale | Up to 50% Off",
				"description": "Shop our curated summer collection with discounts on seasonal favorites."
			},
			"product_count": 24,
			"conditions": [],
			"condition_match": "all",
			"created_at": "2026-05-01T08:00:00Z",
			"updated_at": "2026-08-10T12:30:00Z"
		}
	],
	"pagination": {
		"cursor": "eyJ0IjoiMjAyNi...",
		"has_more": true,
		"total": 8
	}
}

ℹPagination

All list endpoints use cursor-based pagination. Pass the cursor value from the response to fetch the next page.

Get a collection

GET /v1/collections/{id}

Returns a single collection by ID. Use expand to include the list of products in the collection.

Query parameters

Parameter Type Description
expand string Comma-separated: products
fields string Comma-separated fields to return

Request

curl https://api.hydrajs.dev/v1/collections/col_abc123?expand=products \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

Response 200

{
	"data": {
		"id": "col_abc123",
		"title": "Summer Sale",
		"handle": "summer-sale",
		"description": "Hot deals for the summer season.",
		"type": "manual",
		"status": "active",
		"image": "https://cdn.hydrajs.dev/stores/store_xxx/summer-banner.webp",
		"seo": {
			"title": "Summer Sale | Up to 50% Off",
			"description": "Shop our curated summer collection with discounts on seasonal favorites."
		},
		"product_count": 3,
		"conditions": [],
		"condition_match": "all",
		"products": [
			{
				"id": "prod_abc123",
				"title": "Classic T-Shirt",
				"handle": "classic-t-shirt",
				"status": "active",
				"created_at": "2026-01-15T10:30:00Z",
				"updated_at": "2026-08-01T14:22:00Z"
			},
			{
				"id": "prod_def456",
				"title": "Linen Shorts",
				"handle": "linen-shorts",
				"status": "active",
				"created_at": "2026-03-20T09:00:00Z",
				"updated_at": "2026-07-15T11:00:00Z"
			},
			{
				"id": "prod_ghi789",
				"title": "Canvas Tote Bag",
				"handle": "canvas-tote-bag",
				"status": "active",
				"created_at": "2026-04-10T14:00:00Z",
				"updated_at": "2026-06-28T16:45:00Z"
			}
		],
		"created_at": "2026-05-01T08:00:00Z",
		"updated_at": "2026-08-10T12:30:00Z"
	}
}

Create a collection

POST /v1/collections

Creates a new collection. Returns the created collection with 201.

Request body

Field Type Required Description
title string Yes Collection title (1-255 chars)
handle string No URL slug. Auto-generated from title if omitted
description string No Markdown description (max 10,000 chars)
type string No manual (default) or automatic
status string No draft (default) or active
image string No Image URL (max 2,048 chars)
seo object No SEO metadata: title, description
conditions object[] No Automatic collection rules (max 20). Each: field, operator, value
condition_match string No all (default) or any. Whether products must match all conditions (AND) or any condition (OR)

ℹAutomatic collections

Automatic collections use conditions to match products dynamically. Supported fields: product_type, tag, price, brand, inventory_quantity. Supported operators: is_same_as, is_not, more_than, less_than. Text fields (product_type, tag, brand) only support is_same_as and is_not.

Request

curl -X POST https://api.hydrajs.dev/v1/collections \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Summer Sale",
    "description": "Hot deals for the summer season.",
    "status": "active",
    "seo": {
      "title": "Summer Sale | Up to 50% Off",
      "description": "Shop our curated summer collection."
    }
  }'

Response 201

{
	"data": {
		"id": "col_jkl012",
		"title": "Summer Sale",
		"handle": "summer-sale",
		"description": "Hot deals for the summer season.",
		"type": "manual",
		"status": "active",
		"image": null,
		"seo": {
			"title": "Summer Sale | Up to 50% Off",
			"description": "Shop our curated summer collection."
		},
		"product_count": 0,
		"conditions": [],
		"condition_match": "all",
		"created_at": "2026-08-17T09:00:00Z",
		"updated_at": "2026-08-17T09:00:00Z"
	}
}

Update a collection

PATCH /v1/collections/{id}

Partially updates a collection. Send only the fields you want to change. Returns the updated collection.

Request body

All fields from Create a collection are accepted (including condition_match), and all are optional. Additional fields:

Field Type Description
create_redirect boolean If true and handle changed, creates a URL redirect from the old handle

Request

curl -X PATCH https://api.hydrajs.dev/v1/collections/col_abc123 \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Summer Clearance",
    "handle": "summer-clearance",
    "create_redirect": true
  }'

Response 200

{
	"data": {
		"id": "col_abc123",
		"title": "Summer Clearance",
		"handle": "summer-clearance",
		"description": "Hot deals for the summer season.",
		"type": "manual",
		"status": "active",
		"image": "https://cdn.hydrajs.dev/stores/store_xxx/summer-banner.webp",
		"seo": {
			"title": "Summer Sale | Up to 50% Off",
			"description": "Shop our curated summer collection with discounts on seasonal favorites."
		},
		"product_count": 24,
		"conditions": [],
		"condition_match": "all",
		"created_at": "2026-05-01T08:00:00Z",
		"updated_at": "2026-08-17T10:00:00Z"
	}
}

Delete a collection

DELETE /v1/collections/{id}

Soft-deletes a collection. The collection is hidden from all queries and its handle is freed for reuse. Permanently purged after 30 days.

Request

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

Response 204

Empty body.

Add products to a collection

POST /v1/collections/{id}/products

Adds one or more products to a manual collection. Products are appended at the end of the collection. Duplicate product IDs are silently ignored.

Request body

Field Type Required Description
product_ids string[] Yes Array of product IDs to add (1-100)

Request

curl -X POST https://api.hydrajs.dev/v1/collections/col_abc123/products \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_ids": ["prod_abc123", "prod_def456", "prod_ghi789"]
  }'

Response 200

Returns the updated collection object (same shape as Get a collection).

⚠Products must exist

All product IDs must belong to the same project and must not be soft-deleted. If any product is not found, the request fails with a 400 error listing the missing IDs.

Remove a product from a collection

DELETE /v1/collections/{id}/products/{product_id}

Removes a single product from a collection.

Request

curl -X DELETE https://api.hydrajs.dev/v1/collections/col_abc123/products/prod_abc123 \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 204

Empty body.

Get collection tree

GET /v1/collections/tree

Returns all collections as a nested tree structure, ordered by position. Each node includes a children array with its direct subcollections. Useful for rendering collection navigation on storefronts.

Request

curl https://api.hydrajs.dev/v1/collections/tree \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

Response 200

{
	"data": [
		{
			"id": "col_abc123",
			"title": "Apparel",
			"handle": "apparel",
			"status": "active",
			"type": "manual",
			"product_count": 12,
			"children": [
				{
					"id": "col_def456",
					"title": "T-Shirts",
					"handle": "t-shirts",
					"status": "active",
					"type": "manual",
					"product_count": 8,
					"children": []
				}
			]
		}
	]
}

Reorder collections

PATCH /v1/collections/reorder

Updates the position and parent of multiple collections. Used to rearrange the collection tree hierarchy.

Request body

Field Type Required Description
collections object[] Yes Array of { id, position, parent_id } objects

Request

curl -X PATCH https://api.hydrajs.dev/v1/collections/reorder \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collections": [
      { "id": "col_abc123", "position": 0, "parent_id": null },
      { "id": "col_def456", "position": 1, "parent_id": "col_abc123" }
    ]
  }'

Response 204

Empty body.

Reorder products in a collection

PATCH /v1/collections/{id}/products/reorder

Updates the display position of products within a manual collection. Only applies when the collection sort_order is manual.

Request body

Field Type Required Description
products object[] Yes Array of { id, position } objects

Request

curl -X PATCH https://api.hydrajs.dev/v1/collections/col_abc123/products/reorder \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      { "id": "prod_ghi789", "position": 0 },
      { "id": "prod_abc123", "position": 1 },
      { "id": "prod_def456", "position": 2 }
    ]
  }'

Response 204

Empty body.

The collection object

Field Type Description
id string Unique ID (prefix: col_)
title string Collection title
handle string URL-safe slug
description string | null Markdown-formatted text
type string manual or automatic
status string active or draft
image string | null Image URL
seo object title, description
product_count integer Number of products in the collection
conditions object[] Automatic collection rules (empty for manual)
condition_match string all or any — whether all conditions must match (AND) or any (OR)
products object[] Expanded with ?expand=products
created_at string ISO 8601 timestamp
updated_at string ISO 8601 timestamp