Menu

Product Tags API Routes

A tag is another way of organizing a product. Each tag has a name and a value.

Products are organized into the same tag if they have the same value.

These API routes allow admin users to manage product tags.

GET /admin/product-tags#

List Product Tags

Retrieve a list of product tags. The product tags can be filtered by fields such as id. The product tags can also be sorted or paginated.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.
offsetnumberOptional
The number of items to skip when retrieving a list.
limitnumberOptional
Limit the number of items returned in the list.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
qstringOptional
Search term to filter the product tag's searchable properties.
idstring | string[]Optional
Filter by a product tag's ID.
valuestring | string[]Optional
Filter by a product tag's value.
created_atobjectOptional
Filter by the tag's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by the tag's update date. Accepts the filter operators.
deleted_atobjectOptional
Filter by the tag's deletion date. Accepts the filter operators.
$andobject[]Optional
Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
$orobject[]Optional
Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
with_deletedbooleanOptional
Whether to include deleted records in the result.
external_idstring | string[]Optional
Filter by an external ID.

Request examples

Responses

200 OK

limitnumber
The maximum number of items returned.
offsetnumber
The number of items skipped before retrieving the returned items.
countnumber
The total number of items.
product_tagsobject[]
The list of product tags.
estimate_countnumberOptional
The estimated count retrieved from the PostgreSQL query planner, which may be inaccurate.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/product-tags#

Create Product Tag

Create a product tag.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

valuestring
The product tag's value.
metadataobjectOptional
The product tag's metadata, used to store custom key-value pairs. Learn more in the Manage Metadata section.
external_idstringOptional
The ID of the product tag in an external or third-party system.

Request examples

Responses

200 OK

product_tagobject
The product tag's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • product-tag.created: Emitted when product tags are created.

GET /admin/product-tags/{id}#

Get a Product Tag

Retrieve a product tag by its ID. You can expand the product tag's relations or select the fields that should be returned.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The product tag's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request examples

Responses

200 OK

product_tagobject
The product tag's details.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/product-tags/{id}#

Update a Product Tag

Update a product tag's details.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The product tag's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

valuestringOptional
The product tag's value.
metadataobjectOptional
The product tag's metadata. Can hold custom key-value pairs. Learn more in the Manage Metadata section.
external_idstringOptional
The product tag's external ID used to link it with external systems.

Request examples

Responses

200 OK

product_tagobject
The product tag's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • product-tag.updated: Emitted when product tags are updated.

DELETE /admin/product-tags/{id}#

Delete a Product Tag

Delete a product tag. This doesn't delete products using the tag.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The product tag's ID.

Request examples

Responses

200 OK

idstring
The product tag's ID.
objectstring
The name of the deleted object.

Default: "product_tag"

deletedboolean
Whether the product tag was deleted.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • product-tag.deleted: Emitted when product tags are deleted.
Found a problem with this page?Report Issue
Edited Nov 14·Edit this page