Stores use categories to group and display similar products. Categories can be nested. Products can be assigned to one or more categories.

Categories in a store

​Use the Categories API to retrieve category information, as well as to update, replace, create, and delete categories.

Fields

The following table shows all fields that exist for this API, those that are returned when you retrieve a list, those that are required for PUT and POST, and those that are changeable using PATCH and PUT. All fields are returned when you retrieve a single item.

Name Description Type List Required Changeable
user_id The unique ID of the authenticated user string X
site_id ID of a Weebly site, unique to the currently authenticated user​ string X
url ​Direct URL to the category's page. string
category_id ​Unique ID (to the store) of the category. string X
name ​Name of the category. string X X X
seo_page_title ​The SEO title for the category. Site owners can create a title as a meta tag used by search engines. string X
seo_page_description ​The SEO description for the category. Site owners can create a title as a meta tag used by search engines. string X
product_ids ​The unique ID (to the store) of all products associated with this category. array of strings X
images An array of images to display for this category. Use the API to work with images. array of image objects X
parent_category_id For nested categories, ​ID of the category that is the parent to this category. string X X
created_date Date the Unix GMT Timestamp X

updated_date Date the Unix GMT Timestamp X

GET
Retrieve a List of Categories

GET /v1/user/sites/{SITE_ID}/store/categories

Returns all categories for the given site. Only list fields are returned.


scope: read:store

Query Parameters

Returned values are paginated. You can further filter results using these parameters:

Parameter Description Type
page Which page of results to return. Start is 1. integer
limit Number of results per page to return. Default is 25.
Max is 200.
integer
filterby Field name to set a filter on. string
filterfor ​Value to search the filterby field for. You can use the URL encoded characters for following operators:
  • < use %3C
  • > use %3E
  • <= use %3C%3D
  • >= use %3E%#D
string

Example CURL request returning all categories:

curl --request GET \
--url https://api.weebly.com/v1/user/sites/987654321/store/categories \
--header 'accept: application/vnd.weebly.v1+json' \
--header 'content-type: application/json' \
--header 'x-weebly-access-token: [YOUR_TOKEN]"

Example filtered request:

curl --request GET \
--url https://api.weebly.com/v1/user/sites/987654321/store/categories?filterby=parent_category_id&filterfor=1 \
--header 'accept: application/vnd.weebly.v1+json' \
--header 'content-type: application/json' \
--header 'x-weebly-access-token: [YOUR_TOKEN]"

Example response:

[
    {
        "user_id": "123456",
        "site_id": "987654321",
        "category_id": "1",
        "name": "Featured Products",
        "images": [],
        "parent_category_id": null
    },
    {
        "user_id": "123456",
        "site_id": "987654321",
        "category_id": "7",
        "name": "Fruit",
        "images": [
            {
                "url": "http://654321.weebly.com/uploads/5/4/9/1/54914441/s242778913223969860_c7.jpeg",
                "user_id": "123456",
                "site_id": "987654321",
                "category_id": "7",
                "category_image_id": 1,
            }
        ],
        "parent_category_id": "1"
    },
    {
        "user_id": "123456",
        "site_id": "987654321",
        "category_id": "8",
        "name": "Berries",
        "images": [
            {
                "url": "http://654321.weebly.com/uploads/5/4/9/1/54914441/s242778913.jpeg",
                "user_id": "123456",
                "site_id": "987654321",
                "category_id": "8",
                "category_image_id": 1,
                "user_id": "123456"
            }
        ],
        "parent_category_id": "1"
    },
    {
        "user_id": "123456",
        "site_id": "987654321",
        "category_id": "9",
        "name": "Citrus",
        "images": [
            {
                "url": "http://654321.weebly.com/uploads/5/4/9/1/54914441/s242778913223969860_c9.jpeg",
                "user_id": "123456",
                "site_id": "987654321",
                "category_id": "9",
                "category_image_id": 1,
                "user_id": "123456"
            }
        ],
        "parent_category": "1"
    }
]

GET
Retrieve the Quantity of Categories

GET /v1/user/sites/{SITE_ID}/store/categories/count

Returns the number categories in the store.


scope: read:store-catalog

Example CURL request:

curl --request GET \
--url https://api.weebly.com/v1/user/sites/987654321/store/categories/count \
--header 'accept: application/vnd.weebly.v1+json' \
--header 'content-type: application/json' \
--header 'x-weebly-access-token: [YOUR_TOKEN]"

Example response:

{
    "count": 6
}

GET
Retrieve Details for a Category

GET /v1/user/sites/{SITE_ID}/store/categories/{CATEGORY_ID}

Returns all fields for the given category.


scope: read:store-catalog

Example CURL request:

curl --request GET \
--url https://api.weebly.com/v1/user/sites/987654321/store/categories/7 \
--header 'accept: application/vnd.weebly.v1+json' \
--header 'content-type: application/json' \
--header 'x-weebly-access-token: [YOUR_TOKEN]"

Example response:

See Fields table. All fields for the category are returned.

{
    "user_id": "123456",
    "site_id": "987654321",
    "url": "https://hf4u.weebly.com/store/c7/Fruit.html",
    "category_id": "7",
    "name": "Fruit",
    "seo_page_title": null,
    "seo_page_description": null,
    "product_ids": [
        "1",
        "7",
        "8",
        "14",
        "16",
        "18",
        "25",
        "28",
        "29",
        "31"
    ],
    "created_date": 1445624678,
    "updated_date": 1445625218,
    "images": [
        {
            "url": "http://654321.weebly.com/uploads/5/4/9/1/54914441/s242778913223969860_c7.jpeg",
            "user_id": "123456",
            "site_id": "987654321",
            "category_id": "7",
            "category_image_id": 1,
        }
    ],
    "parent_category_id": "1"
}

POST
Create a Category

POST /v1/user/sites/{SITE_ID}/store/categories

Creates a category.


scope: write:store-catalog

These fields can be created:

Name Description Type Notes
name ​Name of the category. string Required
seo_page_title ​The SEO title for the category. Site owners can create a title as a meta tag used by search engines. string
seo_page_description ​The SEO description for the category. Site owners can create a title as a meta tag used by search engines. string
product_ids ​The unique ID (to the store) of all products associated with this category. array of strings
parent_category_id For nested categories, ​ID of the category that is the parent to this category. string

Example CURL request:

curl --request POST \
--url https://api.weebly.com/v1/user/sites/987654321/store/categories \
--header 'accept: application/vnd.weebly.v1+json' \
--header 'content-type: application/json' \
--header 'x-weebly-access-token: [YOUR_TOKEN]"
--data '{
            "name": "New Category",
            "parent_category": "1"
        }'

Example response:

{
    "user_id": "123456",
    "site_id": "987654321",
    "url": "https://hf4u.weebly.com/store/c13/new_category.html",
    "category_id": "13",
    "name": "New Category",
    "seo_page_title": null,
    "seo_page_description": null,
    "product_ids": [],
    "created_date": 1476313140,
    "updated_date": 1476313140,
    "images": [],
    "parent_category_id": "1"
}

PUT
Replace a Category

PUT /v1/user/sites/{SITE_ID}/store/categories/{CATEGORY_ID}

Replaces the given category.


scope: write:store-cataglog

These fields can be replaced:

Name Description Type Notes
name ​Name of the category. string Required
seo_page_title ​The SEO title for the category. Site owners can create a title as a meta tag used by search engines. string
seo_page_description ​The SEO description for the category. Site owners can create a title as a meta tag used by search engines. string
product_ids ​The unique ID (to the store) of all products associated with this category. array of strings
parent_category_id For nested categories, ​ID of the category that is the parent to this category. string

Example CURL request:

curl --request PUT \
--url https://api.weebly.com/v1/user/sites/987654321/store/categories/13 \
--header 'accept: application/vnd.weebly.v1+json' \
--header 'content-type: application/json' \
--header 'x-weebly-access-token: [YOUR_TOKEN]"
--data '{
            "name": "New Category",
            "parent_category": "1"
        }'

Example response:

{
    "user_id": "123456",
    "site_id": "987654321",
    "url": "https://hf4u.weebly.com/store/c13/new_category.html",
    "category_id": "13",
    "name": "New Category",
    "seo_page_title": null,
    "seo_page_description": null,
    "product_ids": [],
    "created_date": 1476313140,
    "updated_date": 1476313140,
    "images": [],
    "parent_category_id": "1"
}

PATCH
Update a Category

PATCH /v1/user/sites/{SITE_ID}/store/categories/{CATEGORY_ID}

Updates the given category.


scope: write:store-catalog

These fields can be updated:

Name Description Type
name ​Name of the category. string
seo_page_title ​The SEO title for the category. Site owners can create a title as a meta tag used by search engines. string
seo_page_description ​The SEO description for the category. Site owners can create a title as a meta tag used by search engines. string
product_ids ​The unique ID (to the store) of all products associated with this category. array of strings
parent_category_id For nested categories, ​ID of the category that is the parent to this category. string

Example CURL request:

curl --request PATCH \
--url https://api.weebly.com/v1/user/sites/987654321/store/categories/9 \
--header 'accept: application/vnd.weebly.v1+json' \
--header 'content-type: application/json' \
--header 'x-weebly-access-token: [YOUR_TOKEN]"
--data '{
            "name":"Flowers"
        }'

Example response:

See Fields table. All fields for the category are returned.</p>

{
    "user_id": "123456",
    "site_id": "987654321",
    "url": "https://hf4u.weebly.com/store/c9/Flowers.html",
    "category_id": "9",
    "name": "Flowers",
    "seo_page_title": null,
    "seo_page_description": null,
    "product_ids": [
        "27",
        "30",
        "32",
        "34",
        "35",
        "36"
    ],
    "created_date": 1445624817,
    "updated_date": 1476314995,
    "images": [
        {
            "url": "http://821263702103547270.weebly.com/uploads/5/4/9/1/54914441/s242c9_i1_w3000.jpeg",
            "site_id": "987654321",
            "category_id": "9",
            "category_image_id": 1,
        }
    ],
    "parent_id": "1"
}

DELETE
Delete a Category

DELETE /v1/user/sites/{SITE_ID}/store/categories/{CATEGORY_ID}

Deletes the given category.


scope: write:store-catalog

Example CURL request:

curl --request DELETE \
--url https://api.weebly.com/v1/user/sites/987654321/store/categories/9 \
--header 'accept: application/vnd.weebly.v1+json' \
--header 'content-type: application/json' \
--header 'x-weebly-access-token: [YOUR_TOKEN]"

Response There is no response to a delete request.


Help make these docs better!









Tags: