Backend API
Categories are used to organize products and can be nested, creating a hierarchy that resembles a tree structure. Since categories aren't necessarily tied to store navigation, you may find uses for categories both visible and invisible to customers.
Fields
Unique identifier for the category.
A human-friendly name for the category.
Indicates the category may be visible to customers. Otherwise it will be hidden from view.
Expandable list of child categories.
Date and time the category was created.
Date and time the category was last updated.
Indicates the category is a demo.
A long-form description of the category. Can contain HTML or other markup languages.
Image depicting the category.
Deprecated — use images instead.
An object representing the image's source file.
Unique identifier for the file.
Optional file name.
A reference to the raw file data.
MIME content type of the file.
Date the file was uploaded.
Image height in pixels, if applicable.
Size of the file in bytes.
A set of arbitrary data that is typically used to store custom values.
An MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes.
Indicates whether the file is private.
A public URL to reference the file. Updated automatically if file content changes.
Image width in pixels, if applicable.
List of images depicting the category.
Unique identifier for the object.
A brief description of the image.
An object representing the image file.
Unique identifier for the file.
MIME content type of the file.
A reference to the raw file data.
Date the file was uploaded.
Optional file name.
Image height in pixels, if applicable.
Size of the file in bytes.
An MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes.
A public URL to reference the file. Updated automatically if file content changes.
Image width in pixels, if applicable.
Arbitrary image data, typically used to store custom values. See Frontend API for more details.
Indicates the image is not visible to customers.
Page description used for search engine optimization purposes.
Page keywords used for search engine optimization purposes.
Page title used to override product name in storefronts.
ID of the parent category, if applicable.
Expandable link to the parent category, if applicable.
Expandable list of category products.
Expandable list of products as indexed and sorted by their respective position.
Unique identifier typically used in URLs. Defaults to name converted to lowercase and hyphenated. If the category has a parent, the default slug will be prefixed with the parent slug. Maximum length of 1,000 characters.
Position of the category in a list.
Default product sorting applied when retrieving products using the category or categories filter. Can be one of popularity, price_asc, price_desc, date_asc. date_desc. If not specified, products are sorted by their manually defined sort value.
ID of an alternate theme template used to render this category in a storefront, if applicable.
An object containing custom attribute key/value pairs.
Template of attribute id/value pairs to apply to products added to this category.
Expandable link to the top level category.
ID of the top level category in the hierarchy.
The category model
{
"name": "Luck",
"active": true,
"sorting": null,
"images": [
{
"file": {
"id": "628bb4ba499bba0019b1ab7c",
"date_uploaded": "2022-05-23T16:22:18.978Z",
"length": 52772,
"md5": "82fd851c2edcd4bd7ed941c561e605ea",
"filename": null,
"content_type": "image/gif",
"metadata": null,
"url": "https://cdn.schema.io/launch-storefront/628bb4ba499bba0019b1ab7c/82fd851c2edcd4bd7ed941c561e605ea",
"width": 127,
"height": 127
},
"id": "628bb4be499bba0019b1ab7e"
}
],
"description": "Luck affects all skills a little bit—with the exception of Acrobatics and Athletics.<br>",
"meta_title": "Luck",
"meta_description": "Luck affects all skills a little bit—not including Acrobatics and Athletics.",
"parent_id": "628bae71499bba0019b1aac2",
"slug": "skills-luck",
"top_id": "628bae71499bba0019b1aac2",
"date_created": "2022-05-23T16:06:40.137Z",
"date_updated": "2022-05-23T16:22:22.300Z",
"sort": 7,
"id": "628bb1101869c10019b4205c"Create a new category.
Arguments
A human-friendly name for the category.
Set true to make the category visible to customers in a storefront, otherwise it will be hidden from view.
A long-form description of the category, often containing HTML or other markup languages.
Unique identifier typically used in URLs. Defaults to name converted to lowercase and hyphenated. If the category has a parent, the default slug will be prefixed with the parent slug. Maximum length of 1,000 characters.
List of images depicting the category.
Unique identifier for the object.
A brief description of the image.
An object representing the image file.
Unique identifier for the file.
MIME content type of the file.
A reference to the raw file data.
Date the file was uploaded.
Optional file name.
Image height in pixels, if applicable.
Size of the file in bytes.
An MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes.
A public URL to reference the file. Updated automatically if file content changes.
Image width in pixels, if applicable.
Page description used for search engine optimization purposes.
Page keywords used for search engine optimization purposes.
Page title used to override product name in storefronts.
The id of the parent category, if applicable.
Position of the category in a list.
Default product sorting is applied when retrieving products using the category or categories filter. This can be one of the following: popularity, price_asc, price_desc, date_asc. date_desc. If not specified, products are sorted by their manually defined sort value.
ID of the top level category in the hierarchy.
Expandable link to the top level category.
Expandable link to the parent category, if applicable.
Expandable list of child categories.
Expandable list of category products.
Expandable list of products as indexed and sorted by their respective position.
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');
await swell.post('/categories', {
name: 'Widgets',
active: true,
});
Response
{
"id": "5ca9871f9b14d199072432a1",
"active": false,
"name": "Widgets",
"slug": "widgets",
"date_created": "2019-04-01T00:00:00.000Z"
}Retrieve an existing category using the ID that was returned when created.
Arguments
The id of the category to retrieve.
Expanding link fields and child collections is performed using the expand argument.
- For example, expand=account would return a related customer account if one exists.
When the field represents a collection, you can specify the query limit.
- For example, expand=variants:10 would return up to 10 records of the variants collection.
See expanding for more details.
etails.
Return only the specified fields in the result. For example fields=name,slug would return only the fields name and slug in the response. Supports nested object and array fields using dot-notation, for example, items.product_id. The category id is always returned.
Include one or more arbitrary queries in the response, possibly related to the main query.
See including for more details.
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');
await swell.get('/categories/{id}', {
id: '5ca9871f9b14d199072432a1',
});
Response
{
"id": "5ca9871f9b14d199072432a1",
"active": true,
"name": "Widgets",
"slug": "widgets",
"date_created": "2019-04-01T00:00:00.000Z"
"description": null,
"images": [
{
"id": "5ca24abb9c077817e5fe2b37",
"file": {
"id": "5ca24abb9c077817e5fe2b38",
"date_uploaded": "2019-04-02T00:26:23.399Z",
"length": 66764,
"md5": "99194f53bfdea832553e7fa8ae8fd80f",
"content_type": "image/png",
"url": "http://cdn.swell.store/test/5ca24abb9c077817e5fe2b36/99194f53bfdea832553e7fa8ae8fd80f",
"width": 940,
"height": 600
}
}
],
"meta_title": null,
"meta_keywords": null,
"meta_description": null
}Update an existing category.
Arguments
The unique identifier of the category.
Set true to make the category visible to customers in a storefront, otherwise, it will be hidden from view.
A long-form description of the category, often containing HTML or other markup languages.
Images depicting the category.
A brief description of the image.
An object representing the image file.
Set or overwrite file data. Use the following format when writing a file from binary data (for example an image): data[$binary]=<base64 encoded binary daya>.
Optional file name.
List of images depicting the category.
A human-friendly name for the category.
Price rules to override price and sale_price when conditions match quantity or account group in a cart. Overrides product prices.
Price applied when conditions are met.
Customer account group as a condition to apply price.
Maximum quantity as a condition to apply price.
Minimum quantity as a condition to apply price.
Indicates the variant is on sale and sale_price is used by default when the product is added to a cart. Overrides product sale.
Sale price used by default when sale=true, overriding price. Overrides product sale price.
If specified, shipping is calculated based on this shipping weight. Otherwise, it will assume 1 lb/oz/kg depending on your default weight unit. Overrides product shipping weight.
Stock keeping unit (SKU) used to track inventory in a warehouse.
Unique identifier typically used in URLs. Defaults to name converted to lowercase and hyphenated. If the category has a parent, the default slug will be prefixed with the parent slug. Maximum length of 1,000 characters.
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');
await swell.put('/categories/{id}', {
id: '5ca9871f9b14d199072432a1',
description: 'A bunch of widgets',
active: false
});
Response
{
"id": "5ca9871f9b14d199072432a1",
"active": false,
"name": "Widgets",
"slug": "widgets",
"date_created": "2019-04-01T00:00:00.000Z"
"date_updated": "2019-04-01T00:00:00.000Z",
"description": 'A bunch of widgets',
"images": [
{
"id": "5ca24abb9c077817e5fe2b37",
"file": {
"id": "5ca24abb9c077817e5fe2b38",
"date_uploaded": "2019-04-02T00:26:23.399Z",
"length": 66764,
"md5": "99194f53bfdea832553e7fa8ae8fd80f",
"content_type": "image/png",
"url": "http://cdn.swell.store/test/5ca24abb9c077817e5fe2b36/99194f53bfdea832553e7fa8ae8fd80f",
"width": 940,
"height": 600
}
}
],
"meta_title": null,
"meta_keywords": null,
"meta_description": null
}Return a list of product categories.
Arguments
Expand link fields and child collections by using the expand argument.
- For example, expand=account would return a related customer account if one exists.
When the field represents a collection, you can specify the query limit.
- For example, expand=variants:10 would return up to 10 records of the variants collection.
See expanding for more details.
Returns only the specified fields in the result.
- For example fields=name,slug would return only the fields name and slug in the response.
Supports nested object and array fields using dot-notation.
- For example, items.product_id. The product id is always returned.
Include one or more arbitrary queries in the response which are potentially related to the main query.
See including for more details.
Limit the number of records returned, ranging between 1 and 1000. Defaults to 15.
The page number of results to return given the specified or default limit.
A text search is performed using the search argument. Searchable fields are defined by the model.
- For example, search=red would return records containing the word "red" anywhere in the defined text fields.
See searching for more details.
Expression to sort results by using a format similar to a SQL sort statement.
- For example, sort=name asc would return records sorted by name ascending.
See sorting for more details.
An object with criteria to filter the result.
- For example, active=true would return records containing a field active with the value true.
It's also possible to use query operators, for example, $eq, $ne, $gt, and more.
See querying for more details.
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');
await swell.get('/categories', {
where: {
active: true
},
limit: 25,
page: 1
});
Response
{
"count": 29,
"results": [
{
"name": "Luck",
"active": true,
"sorting": null,
"images": null,
"description": null,
"meta_title": null,
"meta_description": null,
"parent_id": "628bae71499bba0019b1aac2",
"slug": "skills-luck",
"top_id": "628bae71499bba0019b1aac2",
"date_created": "2022-05-23T16:06:40.137Z",
"date_updated": "2022-05-23T16:10:52.946Z",
"sort": 7,
"id": "628bb1101869c10019b4205c"
},
{
"name": "Willpower",
"active": true,
"sorting": null,
"images": null,
"description": null,
"meta_title": null,
"meta_description": null,
"parent_id": "628bae71499bba0019b1aac2",
"slug": "skills-willpower",
"top_id": "628bae71499bba0019b1aac2",
"date_created": "2022-05-23T16:06:33.466Z",
"date_updated": "2022-05-23T16:10:20.092Z",
"sort": 5,
"id": "628bb1091869c10019b4205a"
},
{
"name": "Intelligence",
"active": true,
"sorting": null,
"images": null,
"description": null,
"meta_title": null,
"meta_description": null,
"parent_id": "628bae71499bba0019b1aac2",
"slug": "skills-intelligence",
"top_id": "628bae71499bba0019b1aac2",
"date_created": "2022-05-23T16:06:23.079Z",
"date_updated": "2022-05-23T16:10:20.090Z",
"sort": 6,
"id": "628bb0ff1869c10019b42058"
},
{
"name": "Personality",
"active": true,
"sorting": null,
"images": null,
"description": null,
"meta_title": null,
"meta_description": null,
"parent_id": "628bae71499bba0019b1aac2",
"slug": "skills-personality",
"top_id": "628bae71499bba0019b1aac2",
"date_created": "2022-05-23T16:06:13.645Z",
"date_updated": "2022-05-23T16:10:52.955Z",
"sort": 4,
"id": "628bb0f5499bba0019b1ab25"
},
{
"name": "Agility",
"active": true,
"sorting": null,
"images": null,
"description": null,
"meta_title": null,
"meta_description": null,
"parent_id": "628bae71499bba0019b1aac2",
"slug": "skills-agility",
"top_id": "628bae71499bba0019b1aac2",
"date_created": "2022-05-23T16:06:00.026Z",
"date_updated": "2022-05-23T16:10:52.961Z",
"sort": 3,
"id": "628bb0e81869c10019b42056"
},
{
"name": "Speed",
"active": true,
"sorting": null,
"images": null,
"description": null,
"meta_title": null,
"meta_description": null,
"parent_id": "628bae71499bba0019b1aac2",
"slug": "skills-speed",
"top_id": "628bae71499bba0019b1aac2",
"date_created": "2022-05-23T16:05:50.621Z",
"date_updated": "2022-05-23T16:10:52.953Z",
"sort": 2,
"id": "628bb0de1869c10019b42054"
},
{
"name": "Endurance",
"active": true,
"sorting": null,
"images": null,
"description": null,
"meta_title": null,
"meta_description": null,
"parent_id": "628bae71499bba0019b1aac2",
"slug": "skills-endurance",
"top_id": "628bae71499bba0019b1aac2",
"date_created": "2022-05-23T16:05:41.771Z",
"date_updated": "2022-05-23T16:10:52.941Z",
"sort": 1,
"id": "628bb0d5499bba0019b1ab23"
},
{
"name": "Strength",
"active": true,
"sorting": null,
"images": null,
"description": null,
"meta_title": null,
"meta_description": null,
"parent_id": "628bae71499bba0019b1aac2",
"slug": "strength",
"top_id": "628bae71499bba0019b1aac2",
"date_created": "2022-05-23T16:05:34.393Z",
"date_updated": "2022-05-23T16:10:52.953Z",
"sort": 0,
"id": "628bb0ce499bba0019b1ab21"
},
{
"name": "Speechcraft",
"active": false,
"sorting": null,
"images": null,
"description": null,
"meta_title": null,
"meta_description": null,
"parent_id": "628bb0f5499bba0019b1ab25",
"slug": "skills-speechcraft",
"top_id": "628bae71499bba0019b1aac2",
"date_created": "2022-05-23T16:05:18.864Z",
"date_updated": "2022-05-23T16:10:20.092Z",
"sort": 1,
"id": "628bb0be499bba0019b1ab1f"
},
{
"name": "Mercantile",
"active": false,
"sorting": null,
"images": null,
"description": null,
"meta_title": null,
"meta_description": null,
"parent_id": "628bb0f5499bba0019b1ab25",
"slug": "skills-mercantile",
"top_id": "628bae71499bba0019b1aac2",
"date_created": "2022-05-23T16:05:08.369Z",
"date_updated": "2022-05-23T16:10:20.092Z",
"sort": 0,
"id": "628bb0b4499bba0019b1ab1d"
},
{
"name": "Marksman",
"active": false,
"sorting": null,
"images": null,
"description": null,
"meta_title": null,
"meta_description": null,
"parent_id": "628bb0e81869c10019b42056",
"slug": "skills-marksman",
"top_id": "628bae71499bba0019b1aac2",
"date_created": "2022-05-23T16:04:57.274Z",
"date_updated": "2022-05-23T16:10:20.112Z",
"sort": 2,
"id": "628bb0a91869c10019b42052"
},
{
"name": "Sneak",
"active": false,
"sorting": null,
"images": null,
"description": null,
"meta_title": null,
"meta_description": null,
"parent_id": "628bb0e81869c10019b42056",
"slug": "skills-sneak",
"top_id": "628bae71499bba0019b1aac2",
"date_created": "2022-05-23T16:04:47.385Z",
"date_updated": "2022-05-23T16:10:20.112Z",
"sort": 0,
"id": "628bb09f1869c10019b42050"
},
{
"name": "Security",
"active": false,
"sorting": null,
"images": null,
"description": null,
"meta_title": null,
"meta_description": null,
"parent_id": "628bb0e81869c10019b42056",
"slug": "security",
"top_id": "628bae71499bba0019b1aac2",
"date_created": "2022-05-23T16:04:37.967Z",
"date_updated": "2022-05-23T16:10:20.114Z",
"sort": 1,
"id": "628bb0951869c10019b4204e"
},
{
"name": "Light armor",
"active": false,
"sorting": null,
"images": null,
"description": null,
"meta_title": null,
"meta_description": null,
"parent_id": "628bb0de1869c10019b42054",
"slug": "skills-light-armor",
"top_id": "628bae71499bba0019b1aac2",
"date_created": "2022-05-23T16:04:27.646Z",
"date_updated": "2022-05-23T16:10:20.114Z",
"sort": 2,
"id": "628bb08b499bba0019b1ab1b"
},
{
"name": "Acrobatics",
"active": false,
"sorting": null,
"images": null,
"description": null,
"meta_title": null,
"meta_description": null,
"parent_id": "628bb0de1869c10019b42054",
"slug": "skills-acrobatics",
"top_id": "628bae71499bba0019b1aac2",
"date_created": "2022-05-23T16:04:17.292Z",
"date_updated": "2022-05-23T16:10:20.114Z",
"sort": 1,
"id": "628bb0811869c10019b4204c"
}
],
"page": 1,
"pages": {
"1": {
"start": 1,
"end": 15
},
"2": {
"start": 16,
"end": 29
}
}
}Delete a category.
Arguments
The id of the category to delete.
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');
await swell.delete('/categories/{id}', {
id: '5ca9871f9b14d199072432a1',
});
Response
{
"id": "5ca9871f9b14d199072432a1",
"active": false,
"name": "Widgets",
"slug": "widgets",
"date_created": "2019-04-01T00:00:00.000Z"
"date_updated": "2019-04-01T00:00:00.000Z",
"description": 'A bunch of widgets',
"images": [
{
"id": "5ca24abb9c077817e5fe2b37",
"file": {
"id": "5ca24abb9c077817e5fe2b38",
"date_uploaded": "2019-04-02T00:26:23.399Z",
"length": 66764,
"md5": "99194f53bfdea832553e7fa8ae8fd80f",
"content_type": "image/png",
"url": "http://cdn.swell.store/test/5ca24abb9c077817e5fe2b36/99194f53bfdea832553e7fa8ae8fd80f",
"width": 940,
"height": 600
}
}
],
"meta_title": null,
"meta_keywords": null,
"meta_description": null
}