API Product

The Spiffy Stores API Product object represents an individual item for sale in a store. Anything that can be sold is regarded as a product in your store, even if it's not a physical item. For example, any sort of service or customization that you perform counts as a product.

You can view your products, update them, create new ones, and delete them.

A product will have a least one Variation and may also have one or more Images. A Product may also belong to a StandardCollection or a SuperCollection.

The advantage of using the handle form of the request is that you don't need to search all the products first in order to determine the product 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 products.

Product Properties

id	{ "id" : 123456789 } A unique numeric identifier for the product.
title	{ "title" : "Cute Dog" } The title of the product.
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.
metafields_global_title_tag	{ "metafields_global_title_tag" : "Spiffy T-Shirt - Orange, Medium" } The title of the product which is used specifically for Search Engine Optimization purposes. This value will be used in the <meta name='title'> tag.
metafields_global_description_tag	{ "metafields_global_description_tag" : "A Spiffy T-Shirt fits everyone." } The description of the product which is used specifically for Search Engine Optimization purposes. This value will be used in the <meta name='description'> tag.
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, "position": 1 }, { "value": "Red", "price": 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", "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 product images is returned.
variations	{ "variations": [ { "id": 2299, "product_id": 123456789, "title": "Default", "position": 1, "sku": "", "barcode": "", "price": 15, "wholesale_price": 0, "compare_at_price": 0, "discount": 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": "spiffy", "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", "image_id": 13456 } ] } 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 Variation for more detailed information about the Variation object.

Endpoints

`GET /api/products.json GET /api/standard_collections/(STANDARD_COLLECTION_ID|STANDARD_COLLECTION_HANDLE)/products.json GET /api/super_collections/(SUPER_COLLECTION_ID|SUPER_COLLECTION_HANDLE)/products.json`

Return a list of products. A standard collection or a super collection may be specified to return only the products belonging to that collection.

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.
ids	A comma-separated list of products ids.
since_id	Limit the results to only include objects which have an id greater than the given value.
vendor	Limit the results to only include products supplied by the given vendor.
product_type	Limit the results to only include products that belong to the given product_type.
handle	Return the product with the given handle.
collection_id	Return only the products that belong to the given collection. Either a unique collection id or handle may be specified.
created_at_min	Return only the products created after the given date and time. Use the format "2014-12-31 12:00".
created_at_max	Return only the products created before the given date and time. Use the format "2014-12-31 12:00".
updated_at_min	Return only the products updated after the given date and time. Use the format "2014-12-31 12:00".
updated_at_max	Return only the products updated before the given date and time. Use the format "2014-12-31 12:00".
published_status	Return only products with the given published status. published - Include only published products unpublished - Include only unpublished products any - Include all products (default)
featured_status	Return only products with the given featured status. featured - Include only featured products any - Include all products (default)
archived_status	Return only products with the given archived status. archived - Include only archived products any - Include all products (default)
fields	A comma-separated list of fields to return in the response.

Example Request and Response

GET /api/products.json

HTTP/1.1 200 OK

{
  "products": [
    { 
      "id": 123456789,
      "title": "Cute Puppy",
      "handle": "cute-puppy",
      "body": "A very cute puppy.",
      "body_html": "<p>A very cute puppy.</p>",
      "shipping_code": "",
      "created_at": "2012-03-28T17:53:26Z",
      "updated_at": "2014-01-16T05:50:56Z",
      "tags": ["cute", "puppy", "dog", "brown dog"],
      "published": true,
      "featured": true,
      "archived": false,
      "product_type": "Dog",
      "vendor": "Spiffy Stores",
      "options": [
        {
          "name": "Title",
          "position": 1
        }
      ],
      "custom_options": [],
      "images": [
        {
          "id": 1603342682,
          "position": 1,
          "alt": "This is a test product",
          "filename": "cute_puppy.jpg",
          "extension": "jpg",
          "digest": "f19b394b02b9d266508d3da2034ead16",
          "src": "http://server1.spiffystores.com/sites/4/products/123456789_cute_puppy_full.jpg",
          "product_id": 123456789,
          "variation_ids": [1771]
        }
      ],
      "variations": [
        {
          "id": 28234540068,
          "product_id": 123456789,
          "title": "Default",
          "position": 1,
          "sku": "B3300",
          "barcode": "",
          "price": "139.8",
          "wholesale_price": "0.0",
          "compare_at_price": "0.0",
          "discount": "0.0",
          "taxable": true,
          "instalments": 1,
          "grams": 2000.0,
          "length": 0.0,
          "width": 0.0,
          "height": 0.0,
          "inventory_quantity": 5,
          "old_inventory_quantity": 5,
          "inventory_policy": "deny",
          "inventory_management": "spiffy",
          "fulfilment_service": "manual",
          "shipping_code": "",
          "free_shipping": false,
          "requires_shipping": true,
          "ship_separately": false,
          "created_at": "2012-03-28T17:53:26Z",
          "updated_at": "2014-01-16T05:50:56Z",
          "image_id": 23456
        }
      ]
    }, ...
  ]   
}

Examples using filters

GET /api/products.json?fields=id,title,images

GET /api/products.json?collection_id=23238768

`GET /api/products/count.json GET /api/standard_collections/(STANDARD_COLLECTION_ID|STANDARD_COLLECTION_HANDLE)/products/count.json GET /api/super_collections/(SUPER_COLLECTION_ID|SUPER_COLLECTION_HANDLE)/products/count.json`

Return a count of products.

Optional Parameters

since_id	Limit the results to only include objects which have an id greater than the given value.
vendor	Limit the results to only include products supplied by the given vendor.
product_type	Limit the results to only include products that belong to the given product_type.
handle	Return the product with the given handle.
collection_id	Return only the products that belong to the given collection. Either a unique collection id or handle may be specified.
created_at_min	Return only the products created after the given date and time. Use the format "2014-12-31 12:00".
created_at_max	Return only the products created before the given date and time. Use the format "2014-12-31 12:00".
updated_at_min	Return only the products updated after the given date and time. Use the format "2014-12-31 12:00".
updated_at_max	Return only the products updated before the given date and time. Use the format "2014-12-31 12:00".
published_status	Return only products with the given published status. published - Include only published products unpublished - Include only unpublished products any - Include all products (default)
featured_status	Return only products with the given featured status. featured - Include only featured products any - Include all products (default)
archived_status	Return only products with the given archived status. archived - Include only archived products any - Include all products (default)

Example Request and Response

GET /api/products/count.json

HTTP/1.1 200 OK

{
  "count": 578
}

Examples using filters

GET /api/products/count.json?collection_id=234293847

`GET /api/products/(PRODUCT_ID|PRODUCT_HANDLE).json`

Return a single product.

Optional Parameters

fields	A comma-separated list of fields to return in the response.

Example Request and Response

GET /api/products/123456789.json

HTTP/1.1 200 OK

{
  "product": 
    { 
      "id": 123456789,
      "title": "Cute Puppy",
      "handle": "cute-puppy",
      "body": "A very cute puppy.",
      ...
    }
}

Alternative form

GET /api/products/cute-puppy.json

`POST /api/products.json`

Create a new product.

You can include images for the new product, either by including the image as Base64 data using the attachment tag, or by including a URL to the image which can be used to download the image using the src tag.

Example Request and Response

POST /api/products.json

{
  "product": {
    "title": "Brand New Product",
    "body": "A must for every home.",
    "vendor": "Big Brand",
    "product_type": "Gadget",
    "tags": "yellow, gadget, blue, home",
    "variations": [
      {
        "option1": "Large",
        "option2": "Yellow",
        "price": "10.00",
        "sku": "123",
        "inventory_quantity": 100
      },
      {
        "option1": "Small",
        "option2": "Blue",
        "price": "20.00",
        "sku": "456",
        "inventory_quantity": 50
      }
    ],
    "options": [
      { 
        "name": "Size",
        "position": 1
      },
      { 
        "name": "Colour",
        "position": 2
      }

    ],
    "images": [
      {
        "attachment": "R0lGODlhAQABAIAAAAAAAAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==\n",
        "filename": "cute_puppy.jpg"
      },
      {
        "src": "http://www.puppies-r-us.com/images/cute_puppy2.jpg",
        "filename": "cute_puppy2.jpg"
      }
    ]
  }
}

HTTP/1.1 201 Created

Create a Product with a Metafield

POST /api/products.json

{
  "product": {
    "title": "Brand New Product",
    "body": "A must for every home.",
    "vendor": "Big Brand",
    "product_type": "Gadget",
    "variations": [
      {
        "option1": "Large",
        "option2": "Yellow",
        "price": "10.00",
        "sku": "123",
        "inventory_quantity": 100
      },
      {
        "option1": "Small",
        "option2": "Blue",
        "price": "20.00",
        "sku": "456",
        "inventory_quantity": 50
      }
    ],
    "metafields": [
      {
        "namespace": "inventory",
        "key": "stock_location",
        "value": "Sydney",
        "value_type": "string"
      }
    ]
  }
}

HTTP/1.1 201 Created

`PUT /api/products/(PRODUCT_ID|PRODUCT_HANDLE).json`

Update a product and associated images and variations.

You can include images for the updated product, either by including the image as Base64 data using the attachment tag, or by including a URL to the image which can be used to download the image using the src tag.

When you update a product, you must include the id parameter, which must match the product_id specified in the POST URL.

You can update any of the product properties by including the parameter in the PUT data. All other product properties remain unchanged.

You cannot change the number of options. Only the name of the option can be updated.

Product variations, custom_options and images cannot be individually updated using this API. If you specify any new variations, custom_options or images, then all existing variations, custom_options or images are deleted and replaced by the new variations, custom_options or images provided by this API.

Individual variations and images can be updated using the specific API calls for Variations and Images.

Example Request and Response

PUT /api/products/123456789.json

{
  "product": {
    "id": 123456789,
    "title": "This is a new title"
  }
}

HTTP/1.1 200 OK

Add a Metafield to an existing Product

PUT /api/products/123456789.json

{
  "product": {
    "id": 123456789,
    "metafields": [
      {
        "namespace": "inventory",
        "key": "stock_location",
        "value": "Sydney",
        "value_type": "string"
      }
    ]
  }
}

HTTP/1.1 200 OK

`DELETE /api/products/(PRODUCT_ID|PRODUCT_HANDLE).json`

Delete a product and all associated images and variations.

Example Request and Response

DELETE /api/products/123456789.json

HTTP/1.1 200 OK

{}

Alternative form

DELETE /api/products/cute-puppy.json

Contact us

Resources

API Product

From Spiffy Stores Knowledge Base

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

Contents

Accessing a Product

Product Properties

Endpoints

`GET /api/products.json GET /api/standard_collections/(STANDARD_COLLECTION_ID|STANDARD_COLLECTION_HANDLE)/products.json GET /api/super_collections/(SUPER_COLLECTION_ID|SUPER_COLLECTION_HANDLE)/products.json`

Optional Parameters

Example Request and Response

`GET /api/products/count.json GET /api/standard_collections/(STANDARD_COLLECTION_ID|STANDARD_COLLECTION_HANDLE)/products/count.json GET /api/super_collections/(SUPER_COLLECTION_ID|SUPER_COLLECTION_HANDLE)/products/count.json`

Optional Parameters

Example Request and Response

`GET /api/products/(PRODUCT_ID|PRODUCT_HANDLE).json`

Optional Parameters

Example Request and Response

`POST /api/products.json`

Example Request and Response

`PUT /api/products/(PRODUCT_ID|PRODUCT_HANDLE).json`

Example Request and Response

`DELETE /api/products/(PRODUCT_ID|PRODUCT_HANDLE).json`

Example Request and Response

Further Reference

SPIFFY STORES

DESIGN & FEATURES

Social

HELP

Contact us

Resources

API Product

From Spiffy Stores Knowledge Base

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

Contents

Accessing a Product

Product Properties

Endpoints

GET /api/products.jsonGET /api/standard_collections/(STANDARD_COLLECTION_ID|STANDARD_COLLECTION_HANDLE)/products.jsonGET /api/super_collections/(SUPER_COLLECTION_ID|SUPER_COLLECTION_HANDLE)/products.json

Optional Parameters

Example Request and Response

GET /api/products/count.jsonGET /api/standard_collections/(STANDARD_COLLECTION_ID|STANDARD_COLLECTION_HANDLE)/products/count.jsonGET /api/super_collections/(SUPER_COLLECTION_ID|SUPER_COLLECTION_HANDLE)/products/count.json

Optional Parameters

Example Request and Response

GET /api/products/(PRODUCT_ID|PRODUCT_HANDLE).json

Optional Parameters

Example Request and Response

POST /api/products.json

Example Request and Response

PUT /api/products/(PRODUCT_ID|PRODUCT_HANDLE).json

Example Request and Response

DELETE /api/products/(PRODUCT_ID|PRODUCT_HANDLE).json

Example Request and Response

Further Reference

SPIFFY STORES

DESIGN & FEATURES

Social

HELP

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

`GET /api/products.json GET /api/standard_collections/(STANDARD_COLLECTION_ID|STANDARD_COLLECTION_HANDLE)/products.json GET /api/super_collections/(SUPER_COLLECTION_ID|SUPER_COLLECTION_HANDLE)/products.json`

`GET /api/products/count.json GET /api/standard_collections/(STANDARD_COLLECTION_ID|STANDARD_COLLECTION_HANDLE)/products/count.json GET /api/super_collections/(SUPER_COLLECTION_ID|SUPER_COLLECTION_HANDLE)/products/count.json`

`GET /api/products/(PRODUCT_ID|PRODUCT_HANDLE).json`

`POST /api/products.json`

`PUT /api/products/(PRODUCT_ID|PRODUCT_HANDLE).json`

`DELETE /api/products/(PRODUCT_ID|PRODUCT_HANDLE).json`