Collection

Version 1.0

Serves as the foundation for managing collections. Collections are essential entities that group and organize various products or items in a structured manner.

# Endpoints
POST
/v1/collections# Create a single collection
GET
/v1/collections# Retrieve all collections
GET
/v1/collections/123456789# Retrieve a single collection
PATCH
/v1/collections/123456789# Update a single collection
DELETE
/v1/collections/123456789# Delete a single collection
GET
/v1/collections/123456789/products# Retrieve all products in a collection
POST
/v1/collections/123456789/products# Create a single product in a collection
DELETE
/v1/collections/123456789/products/123456789# Delete a single product in a collection

Collection Entity

  • Name
    id
    Type
    string
    Required
    Description

    Every collection is assigned a unique identifier - an unsigned 64-bit integer known as the Collection ID. This specific number is exclusive and distinct across the entire Qooly platform, ensuring an unparalleled level of uniqueness.

  • Name
    name
    Type
    string
    Required
    Description

    The name of the collection.

  • Name
    status
    Type
    varchar(16)
    Default: DRAFT
    Description

    This property indicates the status of the collection.

    DraftThe collection is in draft mode. This is the default status for new collections.
    EnabledThe collection is enabled. This means that the collection is available for purchase through channels.
    DisabledThe collection is disabled. This means that the collection is not available for purchase through channels.
    ArchivedThe collection is archived for future reference.
  • Name
    image_id
    Type
    string
    Description

    This property indicates the image ID of the collection. This is a foreign ID referring to the Asset Entity.

  • Name
    product_inclusion_rules
    Type
    json
    Description

    This property indicates the product inclusion rules of the collection. This is a JSON object.

  • Name
    match_all_rules
    Type
    boolean
    Description

    This property indicates whether the collection should match all rules or any rule.

  • Name
    sort_by
    Type
    string
    Description

    This property indicates the sort by of the collection.

  • Name
    product_count
    Type
    integer
    Description

    This property indicates the product count of the collection.

  • Name
    created_at
    Type
    timestamp
    Description

    This property indicates the time in ISO_8601 when the collection was created.

  • Name
    updated_at
    Type
    timestamp
    Description

    This property indicates the time in ISO_8601 when the collection was last updated.

  • Name
    created_by
    Type
    foreignId
    Description

    This property indicates the user who created the collection.

  • Name
    updated_by
    Type
    foreignId
    Description

    This property indicates the user who recently updated the collection.

The Collection Entity

JSON
{
  "id": "123456789",
  "name": "Example Collection",
  "status": "DRAFT",
  "image_id": "123456789",
  "product_inclusion_rules": {
    "rules": [
      {
        "type": "product_type",
        "value": "Gadget"
      },
      {
        "type": "product_category",
        "value": "Electronics"
      }
    ]
  },
  "match_all_rules": true,
  "sort_by": "name",
  "product_count": 2,
  "created_at": "2024-01-07T12:30:00Z",
  "updated_at": "2024-01-07T14:45:00Z",
  "created_by": "123456789",
  "updated_by": "123456789"
}

Create a Single Collection

This endpoint allows you to create a single collection.

Required Fields

  • Name
    name
    Type
    string
    Required
    Description

Examples

Create a single collection

POST
/v1/collections
curl --request POST \
  --url https://api.qooly.io/v1/collections \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Example Collection",
    "status": "DRAFT",
    "image_id": "123456789",
    "product_inclusion_rules": {
      "rules": [
        {
          "type": "product_type",
          "value": "Gadget"
        },
        {
          "type": "product_category",
          "value": "Electronics"
        }
      ]
    },
    "match_all_rules": true,
    "sort_by": "name"
  }'

Create a single collection

POST
/v1/collections
curl --request POST \
  --url https://api.qooly.io/v1/collections \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Example Collection"
  }'
JSON
{
    "id": "123456789",
    "name": "Example Collection",
    "status": "DRAFT",
    "image_id": "123456789",
    "product_inclusion_rules": {
    "rules": [
        {
        "type": "product_type",
        "value": "Gadget"
        },
        {
        "type": "product_category",
        "value": "Electronics"
        }
    ]
    },
    "match_all_rules": true,
    "sort_by": "name",
    "product_count": 0,
    "created_at": "2024-01-07T12:30:00Z",
    "updated_at": "2024-01-07T14:45:00Z",
    "created_by": "123456789",
    "updated_by": "123456789"
}

Retrieve all Collections

This endpoint allows you to retrieve all collections.

Examples

Retrieve all collections

GET
/v1/collections
curl --request GET \
  --url https://api.qooly.io/v1/collections

Retrieve a single collection

GET
/v1/collections
curl --request GET \
  --url https://api.qooly.io/v1/collections
JSON
[
    {
        "id": "123456789",
        "name": "Example Collection",
        "status": "DRAFT",
        "image_id": "123456789",
        "product_inclusion_rules": {
        "rules": [
            {
            "type": "product_type",
            "value": "Gadget"
            },
            {
            "type": "product_category",
            "value": "Electronics"
            }
        ]
        },
        "match_all_rules": true,
        "sort_by": "name",
        "product_count": 2,
        "created_at": "2024-01-07T12:30:00Z",
        "updated_at": "2024-01-07T14:45:00Z",
        "created_by": "123456789",
        "updated_by": "123456789"
    },
    {
        "id": "987654321",
        "name": "Example Collection 2",
        "status": "DRAFT",
        "image_id": "123456789",
        "product_inclusion_rules": {
        "rules": [
            {
            "type": "product_category",
            "value": "Home"
            },
        ]
        },
        "match_all_rules": false,
        "sort_by": "name",
        "product_count": 5,
        "created_at": "2024-01-07T12:30:00Z",
        "updated_at": "2024-01-07T14:45:00Z",
        "created_by": "123456789",
        "updated_by": "123456789"
    }
]

Retrieve a Single Collection

This endpoint allows you to retrieve a single collection.

Required Parameters

  • Name
    id
    Type
    string
    Required
    Description

Examples

Retrieve a single collection

GET
/v1/collections/123456789
curl --request GET \
  --url https://api.qooly.io/v1/collections/123456789

Retrieve a single collection

GET
/v1/collections/123456789
curl --request GET \
  --url https://api.qooly.io/v1/collections/123456789
JSON
{
    "id": "123456789",
    "name": "Example Collection",
    "status": "DRAFT",
    "image_id": "123456789",
    "product_inclusion_rules": {
    "rules": [
        {
        "type": "product_type",
        "value": "Gadget"
        },
        {
        "type": "product_category",
        "value": "Electronics"
        }
    ]
    },
    "match_all_rules": true,
    "sort_by": "name",
    "product_count": 2,
    "created_at": "2024-01-07T12:30:00Z",
    "updated_at": "2024-01-07T14:45:00Z",
    "created_by": "123456789",
    "updated_by": "123456789"
}

Update a Single Collection

This endpoint allows you to update a single collection.

Required Parameters

  • Name
    id
    Type
    string
    Required
    Description

Examples

Update a single collection

PATCH
/v1/collections/123456789
curl --request PATCH \
  --url https://api.qooly.io/v1/collections/123456789 \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "New Collection Name"
  }'

Update a single collection

PATCH
/v1/collections/123456789
curl --request PATCH \
  --url https://api.qooly.io/v1/collections/123456789 \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "New Collection Name"
  }'
JSON
{
    "id": "123456789",
    "name": "New Collection Name",
    "status": "DRAFT",
    "image_id": "123456789",
    "product_inclusion_rules": {
    "rules": [
        {
        "type": "product_type",
        "value": "Gadget"
        },
        {
        "type": "product_category",
        "value": "Electronics"
        }
    ]
    },
    "match_all_rules": true,
    "sort_by": "name",
    "product_count": 2,
    "created_at": "2024-01-07T12:30:00Z",
    "updated_at": "2024-01-07T14:45:00Z",
    "created_by": "123456789",
    "updated_by": "123456789"
}

Delete a Single Collection

This endpoint allows you to delete a single collection.

Required Parameters

  • Name
    id
    Type
    string
    Required
    Description

Examples

Delete a single collection

DELETE
/v1/collections/123456789
curl --request DELETE \
  --url https://api.qooly.io/v1/collections/123456789

Delete a single collection

DELETE
/v1/collections/123456789
curl --request DELETE \
  --url https://api.qooly.io/v1/collections/123456789
JSON
{}

Retrieve all Products in a Collection

This endpoint allows you to retrieve all products in a collection. It returns an array of Product Entity.

Required Parameters

  • Name
    id
    Type
    string
    Required
    Description

Examples

Retrieve all products in a collection

GET
/v1/collections/123456789/products
curl --request GET \
  --url https://api.qooly.io/v1/collections/123456789/products

Retrieve all products in a collection

GET
/v1/collections/123456789/products
curl --request GET \
  --url https://api.qooly.io/v1/collections/123456789/products
JSON
[
  {
      "id": "123456789",
      "brand_id": "987654321",
      "metadata_id": "456789012",
      "image_id": "789012345",
      "is_tangible": true,
      "has_details": false,
      "has_pricing": false,
      "is_organized": true,
      "is_published": false,
      "needs_review": true,
      "out_of_sync": false,
      "syncing_paused_at": null,
      "status": "DRAFT",
      "name": "Sample Product",
      "model_type": "Simple",
      "product_code": "ABC123",
      "product_category": "Electronics",
      "product_type": "Gadget",
      "product_lifecycle_status": "Active",
      "weight": "1.5",
      "weight_unit": "kg",
      "size_unit": "cm",
      "length": "10",
      "width": "5",
      "height": "15",
      "country_of_origin": "US",
      "commodity_description": "A high-quality electronic gadget.",
      "taxable": false,
      "tax_code": "TAX123",
      "created_at": "2024-01-07T12:30:00Z",
      "updated_at": "2024-01-07T14:45:00Z",
      "created_by": "789012345",
      "updated_by": "123456789"
  },
  {
      "id": "987654321",
      "brand_id": "987654321",
      "metadata_id": "456789012",
      "image_id": "789012345",
      "is_tangible": true,
      "has_details": false,
      "has_pricing": false,
      "is_organized": true,
      "is_published": false,
      "needs_review": true,
      "out_of_sync": false,
      "syncing_paused_at": null,
      "status": "DRAFT",
      "name": "Sample Product 2",
      "model_type": "Simple",
      "product_code": "123ABC",
      "product_category": "Electronics",
      "product_type": "Gadget",
      "product_lifecycle_status": "Active",
      "weight": "1.5",
      "weight_unit": "kg",
      "size_unit": "cm",
      "length": "10",
      "width": "5",
      "height": "15",
      "country_of_origin": "US",
      "commodity_description": "Another description.",
      "taxable": false,
      "tax_code": "TAX123",
      "created_at": "2024-01-07T12:30:00Z",
      "updated_at": "2024-01-07T14:45:00Z",
      "created_by": "789012345",
      "updated_by": "123456789"
  }
]

Create a Single Product in a Collection

This endpoint allows you to add products in a collection.

Required Parameters

  • Name
    id
    Type
    string
    Required
    Description
  • Name
    product_id
    Type
    string
    Required
    Description

Examples

Create a single product in a collection

POST
/v1/collections/123456789/products
curl --request POST \
  --url https://api.qooly.io/v1/collections/123456789/products \
  --data '{
    "product_id": "123456789"
  }'

Create a single product in a collection

POST
/v1/collections/123456789/products
curl --request POST \
  --url https://api.qooly.io/v1/collections/123456789/products \
  --data '{
    "product_id": "123456789"
  }'
JSON
  {}

Delete a Single Product in a Collection

This endpoint allows you to remove products in a collection.

Required Parameters

  • Name
    id
    Type
    string
    Required
    Description
  • Name
    product_id
    Type
    string
    Required
    Description

Examples

Delete a single product in a collection

DELETE
/v1/collections/123456789/products
curl --request DELETE \
  --url https://api.qooly.io/v1/collections/123456789/products \
  --data '{
    "product_id": "123456789"
  }'

Delete a single product in a collection

DELETE
/v1/collections/123456789/products
curl --request DELETE \
  --url https://api.qooly.io/v1/collections/123456789/products \
  --data '{
    "product_id": "123456789"
  }'
JSON
  {}