API Metafield
From Spiffy Stores Knowledge Base
The Spiffy Stores API Metafield reference 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, string or json_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, string or json_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.
Contents
- 1 Accessing a Metafield
- 2 Metafield Properties
- 3 Endpoints
- 3.1 GET /api/metafields.jsonGET /api/products/PRODUCT_ID/metafields.jsonGET /api/variations/VARIATION_ID/metafields.jsonGET /api/pages/PAGE_ID/metafields.jsonGET /api/blogs/BLOG_ID/metafields.jsonGET /api/standard_collections/STANDARD_COLLECTION_ID/metafields.jsonGET /api/super_collections/SUPER_COLLECTION_ID/metafields.jsonGET /api/customers/CUSTOMER_ID/metafields.jsonGET /api/orders/ORDER_ID/metafields.json
- 3.2 GET /api/metafields/count.jsonGET /api/products/PRODUCT_ID/metafields/count.jsonGET /api/variations/VARIATION_ID/metafields/count.jsonGET /api/pages/PAGE_ID/metafields/count.jsonGET /api/blogs/BLOG_ID/metafields/count.jsonGET /api/standard_collections/STANDARD_COLLECTION_ID/metafields/count.jsonGET /api/super_collections/SUPER_COLLECTION_ID/metafields/count.jsonGET /api/customers/CUSTOMER_ID/metafields/count.jsonGET /api/orders/ORDER_ID/metafields/count.json
- 3.3 GET /api/metafields/METAFIELD_ID.jsonGET /api/products/PRODUCT_ID/metafields/METAFIELD_ID.jsonGET /api/variations/VARIATION_ID/metafields/METAFIELD_ID.jsonGET /api/pages/PAGE_ID/metafields/METAFIELD_ID.jsonGET /api/blogs/BLOG_ID/metafields/METAFIELD_ID.jsonGET /api/standard_collections/STANDARD_COLLECTION_ID/metafields/METAFIELD_ID.jsonGET /api/super_collections/SUPER_COLLECTION_ID/metafields/METAFIELD_ID.jsonGET /api/customers/CUSTOMER_ID/metafields/METAFIELD_ID.jsonGET /api/orders/ORDER_ID/metafields/METAFIELD_ID.json
- 3.4 POST /api/metafields.jsonPOST /api/products/PRODUCT_ID/metafields.jsonPOST /api/variations/VARIATION_ID/metafields.jsonPOST /api/pages/PAGE_ID/metafields.jsonPOST /api/blogs/BLOG_ID/metafields.jsonPOST /api/standard_collections/STANDARD_COLLECTION_ID/metafields.jsonPOST /api/super_collections/SUPER_COLLECTION_ID/metafields.jsonPOST /api/customers/CUSTOMER_ID/metafields.jsonPOST /api/orders/ORDER_ID/metafields.json
- 3.5 PUT /api/metafields/METAFIELD_ID.jsonPUT /api/products/PRODUCT_ID/metafields/METAFIELD_ID.jsonPUT /api/variations/VARIATION_ID/metafields/METAFIELD_ID.jsonPUT /api/pages/PAGE_ID/metafields/METAFIELD_ID.jsonPUT /api/blogs/BLOG_ID/metafields/METAFIELD_ID.jsonPUT /api/standard_collections/STANDARD_COLLECTION_ID/metafields/METAFIELD_ID.jsonPUT /api/super_collections/SUPER_COLLECTION_ID/metafields/METAFIELD_ID.jsonPUT /api/customers/CUSTOMER_ID/metafields/METAFIELD_ID.jsonPUT /api/orders/ORDER_ID/metafields/METAFIELD_ID.json
- 3.6 DELETE /api/metafields/METAFIELD_ID.jsonDELETE /api/products/PRODUCT_ID/metafields/METAFIELD_ID.jsonDELETE /api/variations/VARIATION_ID/metafields/METAFIELD_ID.jsonDELETE /api/pages/PAGE_ID/metafields/METAFIELD_ID.jsonDELETE /api/blogs/BLOG_ID/metafields/METAFIELD_ID.jsonDELETE /api/standard_collections/STANDARD_COLLECTION_ID/metafields/METAFIELD_ID.jsonDELETE /api/super_collections/SUPER_COLLECTION_ID/metafields/METAFIELD_ID.jsonDELETE /api/customers/CUSTOMER_ID/metafields/METAFIELD_ID.jsonDELETE /api/orders/ORDER_ID/metafields/METAFIELD_ID.json
- 4 Further Reference
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
Metafields can be added to an object when it is created or updated. Examples of this process are provided in the API documentation for each of the objects that supports Metafields.
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 lower-case alphabetic characters, numbers and '_'. |
key | { "key" : "stock_location" } The key identifies the associated metadata within the given namespace. It has a maximum of 30 characters. |
value | { "value" : "Sydney" } This is the actual value of the metadata. |
value_type | { "value_type" : "string" } The metadata value can be treated as either a string, integer or json_string. |
description | { "description" : "This is where the product is physically located." } This is an optional property that can be used to document the use of the metadata. |
owner_id | { "owner_id" : "345354354" } A unique numeric identifier for the owner of the metafield. |
owner_resource | { "owner_resource" : "Product" } This is the type of resource that owns the metafield. |
created_at | { "created_at" : "2015-02-16T05:33:20Z" } The date and time when the metafield was created. The timestamp is in ISO 8601 format. |
updated_at | { "updated_at" : "2015-02-16T05:33:20Z" } The date and time when the metafield was updated. The timestamp is in ISO 8601 format. |
Endpoints
GET /api/metafields.json
GET /api/products/PRODUCT_ID/metafields.json
GET /api/variations/VARIATION_ID/metafields.json
GET /api/pages/PAGE_ID/metafields.json
GET /api/blogs/BLOG_ID/metafields.json
GET /api/standard_collections/STANDARD_COLLECTION_ID/metafields.json
GET /api/super_collections/SUPER_COLLECTION_ID/metafields.json
GET /api/customers/CUSTOMER_ID/metafields.json
GET /api/orders/ORDER_ID/metafields.json
GET /api/products/PRODUCT_ID/metafields.json
GET /api/variations/VARIATION_ID/metafields.json
GET /api/pages/PAGE_ID/metafields.json
GET /api/blogs/BLOG_ID/metafields.json
GET /api/standard_collections/STANDARD_COLLECTION_ID/metafields.json
GET /api/super_collections/SUPER_COLLECTION_ID/metafields.json
GET /api/customers/CUSTOMER_ID/metafields.json
GET /api/orders/ORDER_ID/metafields.json
Return a list of metafields that belong to the store, product, variation, page, blog, standard collection, super collection, customer or order.
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. |
namespace | Limit the results to only include metafields with the given namespace. |
key | Limit the results to only include metafields with the given key. |
value_type | Limit the results to only include metafields with the given value_type. |
created_at_min | Return only the metafields created after the given date and time. Use the format "2014-12-31 12:00". |
created_at_max | Return only the metafields created before the given date and time. Use the format "2014-12-31 12:00". |
updated_at_min | Return only the metafields updated after the given date and time. Use the format "2014-12-31 12:00". |
updated_at_max | Return only the metafields 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. |
Example Request and Response
GET /api/metafields.json HTTP/1.1 200 OK { "metafields": [ { "id": 123456789, "namespace": "inventory", "key": "stock_location", "value": "Sydney", "value_type": "string", "description": "Physical location of stock items", "owner_id": 36903842, "owner_resource": "Store", "created_at": "2015-02-19T06:02:51Z", "updated_at": "2015-02-19T06:02:51Z" }, ... ] } Examples using filters GET /api/metafields.json?fields=id,namespace,key,value GET /api/metafields.json?namespace=inventory
GET /api/metafields/count.json
GET /api/products/PRODUCT_ID/metafields/count.json
GET /api/variations/VARIATION_ID/metafields/count.json
GET /api/pages/PAGE_ID/metafields/count.json
GET /api/blogs/BLOG_ID/metafields/count.json
GET /api/standard_collections/STANDARD_COLLECTION_ID/metafields/count.json
GET /api/super_collections/SUPER_COLLECTION_ID/metafields/count.json
GET /api/customers/CUSTOMER_ID/metafields/count.json
GET /api/orders/ORDER_ID/metafields/count.json
GET /api/products/PRODUCT_ID/metafields/count.json
GET /api/variations/VARIATION_ID/metafields/count.json
GET /api/pages/PAGE_ID/metafields/count.json
GET /api/blogs/BLOG_ID/metafields/count.json
GET /api/standard_collections/STANDARD_COLLECTION_ID/metafields/count.json
GET /api/super_collections/SUPER_COLLECTION_ID/metafields/count.json
GET /api/customers/CUSTOMER_ID/metafields/count.json
GET /api/orders/ORDER_ID/metafields/count.json
Return a count of metafields that belong to the store, product, variation, page, blog, standard collection, super collection, customer or order.
Optional Parameters
since_id | Limit the results to only include objects which have an id greater than the given value. |
---|---|
namespace | Limit the results to only include metafields with the given namespace. |
key | Limit the results to only include metafields with the given key. |
value_type | Limit the results to only include metafields with the given value_type. |
created_at_min | Return only the metafields created after the given date and time. Use the format "2014-12-31 12:00". |
created_at_max | Return only the metafields created before the given date and time. Use the format "2014-12-31 12:00". |
updated_at_min | Return only the metafields updated after the given date and time. Use the format "2014-12-31 12:00". |
updated_at_max | Return only the metafields updated before the given date and time. Use the format "2014-12-31 12:00". |
Example Request and Response
GET /api/metafields/count.json HTTP/1.1 200 OK { "count": 578 } Examples using filters GET /api/metafields/count.json?namespace=inventory
GET /api/metafields/METAFIELD_ID.json
GET /api/products/PRODUCT_ID/metafields/METAFIELD_ID.json
GET /api/variations/VARIATION_ID/metafields/METAFIELD_ID.json
GET /api/pages/PAGE_ID/metafields/METAFIELD_ID.json
GET /api/blogs/BLOG_ID/metafields/METAFIELD_ID.json
GET /api/standard_collections/STANDARD_COLLECTION_ID/metafields/METAFIELD_ID.json
GET /api/super_collections/SUPER_COLLECTION_ID/metafields/METAFIELD_ID.json
GET /api/customers/CUSTOMER_ID/metafields/METAFIELD_ID.json
GET /api/orders/ORDER_ID/metafields/METAFIELD_ID.json
GET /api/products/PRODUCT_ID/metafields/METAFIELD_ID.json
GET /api/variations/VARIATION_ID/metafields/METAFIELD_ID.json
GET /api/pages/PAGE_ID/metafields/METAFIELD_ID.json
GET /api/blogs/BLOG_ID/metafields/METAFIELD_ID.json
GET /api/standard_collections/STANDARD_COLLECTION_ID/metafields/METAFIELD_ID.json
GET /api/super_collections/SUPER_COLLECTION_ID/metafields/METAFIELD_ID.json
GET /api/customers/CUSTOMER_ID/metafields/METAFIELD_ID.json
GET /api/orders/ORDER_ID/metafields/METAFIELD_ID.json
Return a single metafield that belongs to the store, product, variation, page, blog, standard collection, super collection, customer or order.
Optional Parameters
fields | A comma-separated list of fields to return in the response. |
---|
Example Request and Response
GET /api/metafields/123456789.json HTTP/1.1 200 OK { "metafield": { "id": 123456789, "namespace": "inventory", "key": "stock_location", "value": "Sydney", "value_type": "string", "description": "Physical location of stock items", "owner_id": 36903842, "owner_resource": "Store", "created_at": "2015-02-19T06:02:51Z", "updated_at": "2015-02-19T06:02:51Z" } }
POST /api/metafields.json
POST /api/products/PRODUCT_ID/metafields.json
POST /api/variations/VARIATION_ID/metafields.json
POST /api/pages/PAGE_ID/metafields.json
POST /api/blogs/BLOG_ID/metafields.json
POST /api/standard_collections/STANDARD_COLLECTION_ID/metafields.json
POST /api/super_collections/SUPER_COLLECTION_ID/metafields.json
POST /api/customers/CUSTOMER_ID/metafields.json
POST /api/orders/ORDER_ID/metafields.json
POST /api/products/PRODUCT_ID/metafields.json
POST /api/variations/VARIATION_ID/metafields.json
POST /api/pages/PAGE_ID/metafields.json
POST /api/blogs/BLOG_ID/metafields.json
POST /api/standard_collections/STANDARD_COLLECTION_ID/metafields.json
POST /api/super_collections/SUPER_COLLECTION_ID/metafields.json
POST /api/customers/CUSTOMER_ID/metafields.json
POST /api/orders/ORDER_ID/metafields.json
Create a new metafield that belongs to the store, product, variation, page, blog, standard collection, super collection, customer or order.
Example Request and Response
POST /api/metafields.json { "metafield": { "namespace": "inventory", "key": "stock_location", "value": "Sydney", "value_type": "string", "description": "Physical location of stock items" } } HTTP/1.1 201 Created
PUT /api/metafields/METAFIELD_ID.json
PUT /api/products/PRODUCT_ID/metafields/METAFIELD_ID.json
PUT /api/variations/VARIATION_ID/metafields/METAFIELD_ID.json
PUT /api/pages/PAGE_ID/metafields/METAFIELD_ID.json
PUT /api/blogs/BLOG_ID/metafields/METAFIELD_ID.json
PUT /api/standard_collections/STANDARD_COLLECTION_ID/metafields/METAFIELD_ID.json
PUT /api/super_collections/SUPER_COLLECTION_ID/metafields/METAFIELD_ID.json
PUT /api/customers/CUSTOMER_ID/metafields/METAFIELD_ID.json
PUT /api/orders/ORDER_ID/metafields/METAFIELD_ID.json
PUT /api/products/PRODUCT_ID/metafields/METAFIELD_ID.json
PUT /api/variations/VARIATION_ID/metafields/METAFIELD_ID.json
PUT /api/pages/PAGE_ID/metafields/METAFIELD_ID.json
PUT /api/blogs/BLOG_ID/metafields/METAFIELD_ID.json
PUT /api/standard_collections/STANDARD_COLLECTION_ID/metafields/METAFIELD_ID.json
PUT /api/super_collections/SUPER_COLLECTION_ID/metafields/METAFIELD_ID.json
PUT /api/customers/CUSTOMER_ID/metafields/METAFIELD_ID.json
PUT /api/orders/ORDER_ID/metafields/METAFIELD_ID.json
Update an existing metafield that belongs to the store, product, variation, page, blog, standard collection, super collection, customer or order.
The Namespace and Key of an existing metafield cannot be changed.
Example Request and Response
PUT /api/metafields/123456789.json { "metafield": { "id": 123456789, "value": "Melbourne", "value_type": "string" } } HTTP/1.1 200 OK
DELETE /api/metafields/METAFIELD_ID.json
DELETE /api/products/PRODUCT_ID/metafields/METAFIELD_ID.json
DELETE /api/variations/VARIATION_ID/metafields/METAFIELD_ID.json
DELETE /api/pages/PAGE_ID/metafields/METAFIELD_ID.json
DELETE /api/blogs/BLOG_ID/metafields/METAFIELD_ID.json
DELETE /api/standard_collections/STANDARD_COLLECTION_ID/metafields/METAFIELD_ID.json
DELETE /api/super_collections/SUPER_COLLECTION_ID/metafields/METAFIELD_ID.json
DELETE /api/customers/CUSTOMER_ID/metafields/METAFIELD_ID.json
DELETE /api/orders/ORDER_ID/metafields/METAFIELD_ID.json
DELETE /api/products/PRODUCT_ID/metafields/METAFIELD_ID.json
DELETE /api/variations/VARIATION_ID/metafields/METAFIELD_ID.json
DELETE /api/pages/PAGE_ID/metafields/METAFIELD_ID.json
DELETE /api/blogs/BLOG_ID/metafields/METAFIELD_ID.json
DELETE /api/standard_collections/STANDARD_COLLECTION_ID/metafields/METAFIELD_ID.json
DELETE /api/super_collections/SUPER_COLLECTION_ID/metafields/METAFIELD_ID.json
DELETE /api/customers/CUSTOMER_ID/metafields/METAFIELD_ID.json
DELETE /api/orders/ORDER_ID/metafields/METAFIELD_ID.json
Delete an existing metafield that belongs to the store, product, variation, page, blog, standard collection, super collection, customer or order.
Example Request and Response
DELETE /api/metafields/123456789.json HTTP/1.1 200 OK {}