API SuperCollection

From Spiffy Stores Knowledge Base

Revision as of 11:25, 22 August 2018 by Admin (talk | contribs) (→‎Optional Parameters)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

A super collection is a grouping of products that you can create to help organize the items you have for sale and to help customers find your products. You create a super collection and then configure a set of conditions that define which products end up in the super collection.

If you want to specifically select which products should be added to a collection, then you should use a standard collection. For more information, see StandardCollection.

Accessing a Super Collection

If you want to refer to a single Super Collection, then you will need to use the unique super collection id that has been assigned to that collection. These collection ids are returned when you request a list of the super collections that belong to your store.

The super collection ids are internally generated by the software and cannot be created or assigned.

Alternatively, you may specify the super collection handle in place of the super collection id when requesting access to a collection. The super collection handle is the unique character string that is assigned to every collection when it is created. The handle is used in the URL to display the collection page.

For example, you may retrieve a super collection in two ways. 

GET /api/super_collections/12345678.json

or

GET /api/super_collections/green-things-on-sale.json

The advantage of using the handle form of the request is that you don't need to search all the super collections first in order to determine the super collection id, as you will already know what the handle is. This will reduce the number of API calls that you need to make and greatly simplifies the amount of coding that is needed to manage your super collections.

Super Collection Properties

id 
{ "id" : 155 }

A unique numeric identifier for the super collection.

title 
{ "title": "Green Things" }

The title of the super collection.

handle 
{ "handle": "green-things" }

A unique, human-friendly string for the super collection, generated automatically from its title. In online store themes, the Liquid templating language refers to a super collection by its handle.

body 
{ "body": "This is a collection of green things." }

The text content of the super collection in Textile markup. This is automatically translated into body_html for display on a browser.

body_html 
{ "body_html": "<p>This is a collection of green things.</p>" }

The text content of the super collection, complete with HTML markup.

published 
{ "published" : true }

Indicates whether the super collection is published and visible to customers.

sort_order 
{ "sort_order" : "alpha_a" }

Indicates the default sorting order for the super collection. This field has the following options:

  • manual: Manually sorted
  • featured: Featured Products first
  • alpha_a: Alphabetically A-Z
  • alpha_d: Alphabetically Z-A
  • date_a: Oldest Created first
  • date_d: Most Recent Created first
  • update_a: Oldest Updated first
  • update_d: Most Recent Updated first
  • price_a: Most Expensive first
  • price_d: Least Expensive first
  • random: Random
products_count 
{ "products_count" : 41 }

This is the number of products in the collection.

created_at 
{ "created_at": "2008-07-15T20:00:00-04:00" }

The date and time (ISO 8601 format) when the super collection was created.

updated_at 
{ "updated_at": "2008-07-16T20:00:00-04:00" }

The date and time (ISO 8601 format) when the super collection was last updated.

images 
{ "images" : [
  { "id": 2296,
    "product_id": 123456789,
    "position": 1,
    "alt": "",
    "filename": "chrysanthemum.jpg",
    "extension": "jpg",
    "digest": "71465638e6ee742dd0194de93b8efde3",
    "src": "http://server1.spiffystores.com/sites/4/products/123456789_chrysanthemum_full.jpg",
    "product_id": 123456789,
    "variation_ids": [1345, 6789]
  }, …
] }

A list of all the super collection images is returned.

Endpoints

GET /api/super_collections.json

Retrieve a list of all super collections.

Optional Parameters

limit Number of results returned. The default is 30, with a maximum of 50 in a single request.
page The number of the page to return. The number of results per page is set by the limit parameter. If more results are required, then submit the request again, increasing the page number each time.
since_id Limit the results to only include objects which have an id greater than the given value.
product_id Limit the results to only include super collections that include a given product.
title Limit the results to only include super collections with the given title.
handle Limit the results to only include super collections with the given handle.
published_status Limit the results to only include super collections with the given published status ('published' or 'unpublished').
created_at_min Return only the super collections created after the given date and time. Use the format "2014-12-31 12:00".
created_at_max Return only the super collections created before the given date and time. Use the format "2014-12-31 12:00".
updated_at_min Return only the super collections updated after the given date and time. Use the format "2014-12-31 12:00".
updated_at_max Return only the super collections updated before the given date and time. Use the format "2014-12-31 12:00".
fields A comma-separated list of fields to return in the response. If a list of fields is provided, then the images field will always be excluded.

Example Request and Response

GET /api/super_collections.json

HTTP/1.1 200 OK

{
  "super_collections": [
    {
      "id": 155,
      "title": "Green Things",
      "handle": "green-things",
      "body": "Here is an introduction to the 'green things' collection.  Each collection should have a short introduction so that visitors can see what it's about by quickly scanning your intro text and looking at the product pictures displayed below.  Search engines also enjoy reading this text.",
      "body_html": "<p>Here is an introduction to the 'green things' collection.  Each collection should have a short introduction so that visitors can see what it's about by quickly scanning your intro text and looking at the product pictures displayed below.  Search engines also enjoy reading this text.</p>",
      "published": true,
      "sort_order": "manual",
      "products_count": 15,
      "created_at": "2008-07-16T08:18:54.000+10:00",
      "updated_at": "2016-02-26T11:24:17.276+11:00",
      "images": [
        {
          "id": 2335,
          "position": 1,
          "alt": "Test",
          "filename": "sale.jpg",
          "extension": "jpg",
          "digest": "c0580b5987ae39bcb9134074352d3b98",
          "src": "https://test.spiffystores.com/sites/1/collections/155_sale_full.jpg?v=c0580b5987ae39bcb9134074352d3b98"
        },
        {
          "id": 2332,
          "position": 2,
          "alt": "",
          "filename": "koala.jpg",
          "extension": "jpg",
          "digest": "2fd63d15d3530099d69d1c82ffbcc76c",
          "src": "https://test.spiffystores.com/sites/1/collections/155_koala_full.jpg?v=2fd63d15d3530099d69d1c82ffbcc76c"
        }
      ]
    }, ...
  ]
}

Examples using filters

GET /api/super_collections.json?fields=id,title

GET /api/super_collections/count.json

Return a count of the number of super collections.

Optional Parameters

since_id Limit the results to only include objects which have an id greater than the given value.
product_id Limit the results to only include super collections that include a given product.
title Limit the results to only include super collections with the given title.
handle Limit the results to only include super collections with the given handle.
published_status Limit the results to only include super collections with the given published status ('published' or 'unpublished').
created_at_min Return only the super collections created after the given date and time. Use the format "2014-12-31 12:00".
created_at_max Return only the super collections created before the given date and time. Use the format "2014-12-31 12:00".
updated_at_min Return only the super collections updated after the given date and time. Use the format "2014-12-31 12:00".
updated_at_max Return only the super collections updated before the given date and time. Use the format "2014-12-31 12:00".

Example Request and Response

GET /api/super_collections/count.json

HTTP/1.1 200 OK

{
  "count": 15
}

GET /api/super_collections/(SUPER_COLLECTION_ID|SUPER_COLLECTION_HANDLE).json

Retrieves a single super collection by ID or handle.

Optional Parameters

fields A comma-separated list of fields to return in the response. If a list of fields is provided, then the images field will always be excluded.

Example Request and Response

GET /api/super_collections/190.json

HTTP/1.1 200 OK

{
  "super_collection": {
    "id": 190,
    "title": "Green Things",
    "handle": "green-things",
    "body": "Here is an introduction to the 'green things' collection.  Each collection should have a short introduction so that visitors can see what it's about by quickly scanning your intro text and looking at the product pictures displayed below.  Search engines also enjoy reading this text.",
    "body_html": "<p>Here is an introduction to the 'green things' collection.  Each collection should have a short introduction so that visitors can see what it's about by quickly scanning your intro text and looking at the product pictures displayed below.  Search engines also enjoy reading this text.</p>",
    "published": true,
    "sort_order": "manual",
    "products_count": 15,
    "created_at": "2008-07-16T08:18:54.000+10:00",
    "updated_at": "2016-02-26T11:24:17.276+11:00",
    "images": [
      {
        "id": 2335,
        "position": 1,
        "alt": "Test",
        "filename": "sale.jpg",
        "extension": "jpg",
        "digest": "c0580b5987ae39bcb9134074352d3b98",
        "src": "https://test.spiffystores.com/sites/1/collections/155_sale_full.jpg?v=c0580b5987ae39bcb9134074352d3b98"
      },
      {
        "id": 2332,
        "position": 2,
        "alt": "",
        "filename": "koala.jpg",
        "extension": "jpg",
        "digest": "2fd63d15d3530099d69d1c82ffbcc76c",
        "src": "https://test.spiffystores.com/sites/1/collections/155_koala_full.jpg?v=2fd63d15d3530099d69d1c82ffbcc76c"
      }
    ]
  }
}

POST /api/super_collections.json

Create a super collection.

Example Request and Response

POST /api/super_collections.json

{
  "super_collection": {
    "title": "My Latest Standard Collection",
    "body": "Buy these products. They're great!",
    "published": true,
    "images": [
      "attachment": "...",  # Image data
      "filename": "test_image.jpg",
      "alt": "A picture of a Standard Product"
    ]
  }
}

HTTP/1.1 201 Created

{
  "super_collection": {
    "id": 123490,
    "title": "My Latest Standard Collection",
    "handle": "my-latest-super-collection",
    "body": "Buy these products. They're great!",
    "body_html": "<p>Buy these products. They're great!</p>",
    "published": true,
    "sort_order": "manual",
    "products_count": 0,
    "created_at": "2018-07-16T08:18:54.000+10:00",
    "updated_at": "2018-07-16T08:18:54.000+10:00",
    "images": [
      {
        "id": 23334534,
        "position": 1,
        "alt": "A picture of a Standard Product",
        "filename": "test_image.jpg",
        "extension": "jpg",
        "digest": "c0580b5987ae39bcb9134074352d3b98",
        "src": "https://test.spiffystores.com/sites/1/collections/155_test_image.jpg?v=c0580b5987ae39bcb9134074352d3b98"
      }
    ]
  }
}

PUT /api/super_collections/(SUPER_COLLECTION_ID|SUPER_COLLECTION_HANDLE).json

Updates a super collection.

Example Request and Response

PUT /api/super_collections/248.json

{
  "super_collection": {
    "id": 248,
    "published": false
  }
}

HTTP/1.1 200 OK

DELETE /api/super_collections/(SUPER_COLLECTION_ID|SUPER_COLLECTION_HANDLE).json

Deletes a super collection.

Example Request and Response

DELETE /api/super_collections/248.json

HTTP/1.1 200 OK

{}

Further Reference

Retrieved from "http://www.spiffystores.com.au/kb/index.php?title=API_SuperCollection&oldid=7432"