Manage groups via API

Product Color Swatches app provides RESTful JSON API. The API supports only HTTPS calls. Please note that API is available only on Pro plan. You can use it for free on development stores.

Base URL: https://api.colorswatchesapp.com/v1

Authentication

The API uses Shop Domain and API Token to authenticate requests. They can be found in Settings > API Credentials:

When making a request, pass credentials in Shop-Domain and Authorization headers. API requests without authentication will fail.

Authenticated request:

curl -H "Shop-Domain: $SHOP_DOMAIN" \
  -H "Authorization: Token token=$API_TOKEN" \
  https://api.colorswatchesapp.com/v1/groups.json

Throughout the API docs we provide cURL examples. To try them in your shell set the following env variables with your API credentials:

export SHOP_DOMAIN=PASTE_SHOP_DOMAIN_HERE
export API_TOKEN=PASTE_API_TOKEN_HERE

Errors

The API uses standard HTTP codes. In general, codes in the 2xx  range indicate success. Codes in the 4xx  range indicate the request failed with the information provided. Codes in the 5xx  range indicate an error with our servers.

Example error:

{ "error" "Bad credentials" }

Pagination

The API follows the RFC5988 convention of using the Link  header to provide URLs for the next  page. Follow this convention to retrieve the next page of data.

Example Link header:

Link: <https://api.colorswatchesapp.com/v1/groups.json?page=1>; rel="first", <https://api.colorswatchesapp.com/v1/groups.json?page=1>; rel="last"

Endpoints

List all group

Returns a paginated list of groups.

Endpoint: GET /groups.json

Example request:

curl -H "Shop-Domain: $SHOP_DOMAIN" \
  -H "Authorization: Token token=$API_TOKEN" \
  https://api.colorswatchesapp.com/v1/groups.json

Get single group

Returns single group.

Endpoint: GET /groups/{GROUP_ID}.json

Example request:

curl -H "Shop-Domain: $SHOP_DOMAIN" \
  -H "Authorization: Token token=$API_TOKEN" \
  https://api.colorswatchesapp.com/v1/groups/2.json

Create group

Create group with specified products. Returns created group.

Endpoint: POST /groups.json

Parameters:

• title - group title, for internal use only
• option_name - name, displayed in swatches widget (eg Color, Style, etc.). The field is optional, it will be set to "Color" by default
• products_attributes[] : - array of products
  • shopify_id - Shopify Product ID
  • position - position in swatch (optional)
  • swatch_name - name of swatch
  • swatch_type - available values are: “one_color”, “two_colors”, “custom_image”, “product_image”, "image_with_text", "pill"
  • color_one - first color in HEX format
  • color_two - second color in HEX format, required only when swatch type is set to "two_colors"
  • image_url - public URL to image that should be used in swatch, required only when swatch type is set to “custom_image”

Example request:

curl -H "Shop-Domain: $SHOP_DOMAIN" \
  -H "Authorization: Token token=$API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Backpack", "option_name": "Color", "products_attributes": [{"shopify_id": 7453910991090, "swatch_name": "Black", "swatch_type": "one_color", "color_one": "#000000"}]}' \
  https://api.colorswatchesapp.com/v1/groups.json

Update group

Update group details. Can be used to add/remove products from group. Returns updated group.

Endpoint: PATCH /groups/{GROUP_ID}.json

Parameters:

• title - group title, for internal use only
• option_name - name, displayed in swatches widget (eg Color, Style, etc.). The field is optional, it will be set to "Color" by default
• products_attributes[] : - array of products
  • _destroy - if set to "1" will remove the product from group (optional)
  • id - internal product ID
  • shopify_id - Shopify Product ID
  • position - position in swatch (optional)
  • swatch_name - name of swatch
  • swatch_type - available values are: “one_color”, “two_colors”, “custom_image”, “product_image”, "image_with_text", "pill"
  • color_one - first color in HEX format
  • color_two - second color in HEX format, required only when swatch type is set to "two_colors"
  • image_url - public URL to image that should be used in swatch, required only when swatch type is set to “custom_image”

Example request:

curl -H "Shop-Domain: $SHOP_DOMAIN" \
  -H "Authorization: Token token=$API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "New Title", "option_name": "Color", "products_attributes": [{"shopify_id": 7453911089394, "swatch_name": "White", "swatch_type": "one_color", "color_one": "#ffffff"}]}' \
  -X PATCH https://api.colorswatchesapp.com/v1/groups/9.json

Delete group

Removes group. Returns 200 status code without content.

Endpoint: DELETE /groups/{GROUP_ID}.json

Example request:

curl -H "Shop-Domain: $SHOP_DOMAIN" \
  -H "Authorization: Token token=$API_TOKEN" \
  -X DELETE https://api.colorswatchesapp.com/v1/groups/9.json

Add product to group

Adds product to a group/updates product. The group is identified by a title. If the group doesn't exist it will be created. If the product has already been added to another group - it will be removed from it and added to the specified group. Returns updated group.

Endpoint: POST /shopify_products/{SHOPIFY_ID}/add_to_group.json

Parameters:

• group
  • title - group title, used to identify group
  • option_name - name, displayed in swatches widget (eg Color, Style, etc.). The field is optional, it will be set to "Color" by default. The field used only when new group is created
• position - position in swatch (optional)
• swatch_name - name of swatch
• swatch_type - available values are: “one_color”, “two_colors”, “custom_image”, “product_image”
• color_one - first color in HEX format
• color_two - second color in HEX format, required only when swatch type is set to "two_colors"
• image_url - public URL to image that should be used in swatch, required only when swatch type is set to “custom_image”
• reuse_exiting_swatch - when set to "true" we'll try to find existing swatch by "swatch_name" and only if it's not found then create new swatch. Default to "false"

Example request:

curl -H "Shop-Domain: $SHOP_DOMAIN" \
  -H "Authorization: Token token=$API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"group": {"title": "Backpack"}, "swatch_name": "Black", "swatch_type": "one_color", "color_one": "#000000"}' \
  https://api.colorswatchesapp.com/v1/shopify_products/7453911089394/add_to_group.json

Remove product from group

Remove product from its current group. If there are no products left in the group then the group will be deleted as well. Returns 200 status code without content.

Endpoint: POST /shopify_products/{SHOPIFY_ID}/remove_from_group.json

Example request:

curl -H "Shop-Domain: $SHOP_DOMAIN" \
  -H "Authorization: Token token=$API_TOKEN" \
  -X POST https://api.colorswatchesapp.com/v1/shopify_products/7453911089394/remove_from_group.json