---
title: "Create or update a collection"
method: PUT
path: "/admin/collections/custom/{custom_collection_id:\\\\d+}.json"
tags: ["Custom Collection"]
---

# Create or update a collection

`PUT /admin/collections/custom/{custom_collection_id:\\d+}.json`

## Request

- Base URL: `https://shop-name.onshopbase.com`
- URL: `https://shop-name.onshopbase.com/admin/collections/custom/{custom_collection_id:\\d+}.json`
- Auth: API key in header `APP_ACCESS_TOKEN`
- TypeScript: <https://skmtc.dev/shopbase/apis/shopbase-internal-api/docs/admin/collections/custom/:custom_collection_id:%5C%5Cd+.json/put.ts> (a function with typed inputs; its response is checked against the schema)

A collection is a grouping of products that merchants can create to make their stores easier to browse.

For example, a merchant might create a collection for a specific type of product that they sell, such as Footwear.

Merchants can create collections by selecting products individually or by defining rules that automatically determine whether products are included.

## Path parameters

- `custom_collection_id` integer, required

## Request body

- CollectionUpdateRequestSwagger
  - `custom_collection` CustomCollectionRequest
    - `body_html` string: The description of the custom collection, complete with HTML markup. Many templates display this on their custom collection pages.
    - `fields` string: Show only certain fields, specified by a comma-separated list of field names.
    - `handle` string: Url of collection
    - `id` integer: A unique numeric identifier for the custom collection. Each id is unique across the ShopBase system. No two custom collection will have the same id, even if they're from different shops.
    - `image` CustomCollectionImageRequest
      - `alt` string: Alternative text that describes the collection image.
      - `attachment` string: An image attached to a custom collection returned as Base64-encoded binary data.
      - `created_at` string: The time and date (ISO 8601 format) when the image was added to the collection.
      - `height` integer: Height of collection image
      - `src` string: The source URL that specifies the location of the image.
      - `width` integer: Width if collection image.
    - `limit` integer: The maximum number of record we want to fetch
    - `metafields` CustomCollectionMetafield[]: An array of meta field value to print in meta tag (for SEO)
      - `key` string: A key string for which meta field we use (description_tag, title_tag,..)
      - `namespace` string: sphere of influence of key
      - `value` string: Value of corresponding key
      - `value_type` string: Type of value
    - `page` integer: The current page
    - `product_id` integer: The unique numeric identifier for the product in the custom collection.
    - `published` boolean: A flag mark custom collection is published or not
    - `published_status` string: A unique numeric identifier for the product variant. Each id is unique across the ShopBase system. No two products variant will have the same id, even if they're from different shops.
    - `sort_order` string: A string repesent sort order of collection
    - `title` string: Title of collection
  - `is_create_redirect` boolean: Flag for create redirect from old custom collection handle to new collection handle or not

## Response `200`

OK

- CollectionUpdateResponseSwagger
  - `body_html` string: The description of the custom collection, complete with HTML markup. Many templates display this on their custom collection pages.
  - `handle` string: A human-friendly unique string for the custom collection automatically generated from its title. This is used in shop themes by the Liquid templating language to refer to the custom collection. (limit: 255 characters)
  - `id` integer: The ID for the custom collection
  - `image` CustomCollectionImage
    - `alt` string: Alternative text that describes the collection image.
    - `created_at` string: The time and date (ISO 8601 format) when the image was added to the collection.
    - `height` integer: The height of the image in pixels.
    - `src` string: The source URL that specifies the location of the image.
    - `width` integer: The width of the image in pixels.
  - `metafields` CustomCollectionMetafield[]
    - `key` string: A key string for which meta field we use (description_tag, title_tag,..)
    - `namespace` string: sphere of influence of key
    - `value` string: Value of corresponding key
    - `value_type` string: Type of value
  - `published` boolean: A flag mark custom collection is published or not
  - `sort_order` string: A string repesent sort order of collection
  - `title` string: The name of the custom collection. (limit: 255 characters)

---

[API](https://skmtc.dev/shopbase/apis/shopbase-internal-api.md) - [All operations](https://skmtc.dev/shopbase/apis/shopbase-internal-api/llms.txt) - [OpenAPI document](https://skmtc.dev/shopbase/apis/shopbase-internal-api/revisions/353ccde6240d?raw)