API Metafield

From Spiffy Stores Knowledge Base

The Spiffy Stores API Metafield object allows you to attach metadata to a number of your Store's objects.

In this context, metadata represents any sort of data that can be represented by a key/value structure and can be associated with one of the following types of store objects.

  • Store
  • Product
  • Variation
  • Page
  • Blog
  • Standard Collection
  • Super Collection
  • Customer
  • Order

A Metafield has the following properties:

  • Namespace
  • Key
  • Value
  • Value Type (integer or string)
  • Description (Optional)

The Namespace allows you to group a number of related keys together.

Within a Namespace, there will be one or more unique Keys.

Each Key within the Namespace will have a Value which may be either an integer or string value.

Finally, for documentation purposes, an optional Description may also be added when the Metafield is created.

Metafields have many uses. For example, they allow you to store additional information about a product, that is specific to a certain type of product. You could use Metafields to associate products to a specific set of accessories for that product. Metafields provide a generic customization capabilities that allow you to organize your store's products, customers, orders and other content in any way that suits your particular needs.

Accessing a Metafield

Metafields can be created and associated with your Store. These sort of Metafields are global as only one instance of a store exists.

You can manage these sort of Metafields using the following types of API calls -

GET /api/metafields.json
GET /api/metafields/12345.json

and so on…

Metafields may also be associated with individual instances of store objects. In these cases, the Metafields are created when the object is created or added at a later time.

In order to manage these sort of Metafields, the object to which they belong must be referenced in the API call. For example -

GET /api/products/56789/metafields.json
GET /api/products/56789/metafields/24234.json

or

GET /api/variations/36789/metafields.json
GET /api/variations/36789/metafields/34523.json

or

GET /api/pages/234234/metafields.json
GET /api/pages/234234/metafields/456656.json

or

GET /api/blogs/86868/metafields.json
GET /api/blogs/86868/metafields/23423.json

or

GET /api/standard_collections/886789/metafields.json
GET /api/standard_collections/886789/metafields/67435.json

or

GET /api/super_collections/996789/metafields.json
GET /api/super_collections/996789/metafields/126575.json

or

GET /api/customers/56222/metafields.json
GET /api/customers/56222/metafields/12775.json

or

GET /api/orders/56111/metafields.json
GET /api/orders/56111/metafields/133325.json


Metafield Properties

id { "id" : 123456789 }

A unique numeric identifier for the metafield.

namespace { "namespace" : "accessories" }

This is the name assigned to a set of unique metadata keys. Namespaces allow you to group and manage the metadata associated with the objects. A Namespace name has a maximum of 20 characters.

handle { "handle" : "cute-dog" }

A unique, human-friendly string for the product. Usually, the handle is automatically generated from its title. The handle is used in the product URL to refer to the product, and can also be used access the product from the API and in the store's templates.

body { "body" : "This puppy is very cute." }

The description of the product, without HTML formatting.

body_html { "body_html" : "<p>This puppy is very cute.</p>" }

The description of the product, complete with HTML formatting.

shipping_code { "shipping_code" : "BULK" }

If the product requires special shipping, the shipping code is used to determine the specific shipping rate applicable to this product.

created_at { "created_at" : "2007-10-24T18:26:31Z" }

The date and time when the product was created. The timestamp is in ISO 8601 format.

updated_at { "updated_at" : "2014-01-16T05:50:56Z" }

The date and time when the product was last updated. The timestamp is in ISO 8601 format.

tags { "tags" : ["cute", "dog", "puppy", "brown dog"] }

This is a list of tags that are associated with this product. Tags can be used for filtering, searching and building collections of related products.

published { "published" : true }

Indicates whether the product has been published and is visible in the store front.

featured { "featured" : true }

Indicates whether the product is featured which allows it to be promoted to the top of a collection if required.

archived { "archived" : false }

Indicates whether the product is archived. An archived product is automatically hidden when it has sold out.

product_type { "product_type" : "Dogs" }

All products belong to a product type to help categorize and group the store's inventory.

vendor { "vendor" : "Spiffy Stores" }

All products have a vendor or maker which also can be used to help categorize and group the store's inventory.

options { "options" : [{ "name" : "Title", "position" : 1 }] }

A product may have up to 3 options each of which can be assigned a property name, such as "Size", "Colour", "Material" or whatever suits your product. Each product variation will have a different combination of values for each of these options.

custom_options { "custom_options" :

[{"id":250, "name":"Gift Wrap Colour", "position":1, "option_values":[{"value":"Blue", "price":"5.0", "position":1}, {"value":"Red", "price":"0.0", "position":2}]}] }
Custom options can be added to a product as additional services or customization choices. Each custom option allows for a number of choices to be added to the base product, with an optional extra charge.

images { "images" : [{"id":2296, "product_id":123456789, "position":1, "alt":"", "filename":"chrysanthemum.jpg", "src":"123456789_chrysanthemum_full.jpg"},{"id":2295, "position":2, "alt":"", "filename":"penguins.jpg", "src":"123456789_penguins_full.jpg"}] }

A list of all the product images is returned.

variations { "variations":[{"id":2299, "product_id":123456789, "title":"Default", "position":1, "sku":"", "barcode":"", "price":"15.0", "wholesale_price":"0.0", "compare_at_price":"0.0", "discount":"0.0", "taxable":true, "instalments":1, "grams":500.0, "length":0.0, "width":0.0, "height":0.0, "inventory_quantity":0, "old_inventory_quantity":0, "inventory_policy":"deny", "inventory_management":"", "fulfilment_service":"manual", "shipping_code":"", "free_shipping":false, "requires_shipping":true, "ship_separately":false, "created_at":"2013-11-27T09:59:10Z", "updated_at":"2014-08-21T10:26:48Z"}] }

A list of all the product variations is returned. Each variation represents a different physical version of the product which can be tracked and managed using an inventory count.
See API Variation for more detailed information about the Variation object.