Index

List products visible to the authenticated user. If the user is not an admin, they will only be able to see products which have an available_on date in the past. If the user is an admin, they are able to see all products.

GET /api/v1/products

Products are paginated and can be iterated through by passing along a page parameter:

GET /api/v1/products?page=2

Parameters

show_deleted
boolean - true to show deleted products, false to hide them. Default: false. Only available to users with an admin role.
ids
A comma-separated list of products ids. Specifying this parameter will display the respective products.
page
The page number of products to display.
per_page
The number of products to return per page

Response

Status: 200 OK
{
  "products": [
    {
      "id": 1,
      "name": "Example product",
      "description": "Description",
      "price": "15.99",
      "display_price": "$15.99",
      "available_on": "2012-10-17T03:43:57Z",
      "slug": "example-product",
      "meta_description": null,
      "meta_keywords": null,
      "shipping_category_id": 1,
      "taxon_ids": [
        1,
        2,
        3
      ],
      "total_on_hand": 10,
      "master": {
        "id": 1,
        "name": "Ruby on Rails Tote",
        "sku": "ROR-00011",
        "price": "15.99",
        "weight": null,
        "height": null,
        "width": null,
        "depth": null,
        "is_master": true,
        "slug": "ruby-on-rails-tote",
        "description": "A text description of the product.",
        "track_inventory": true,
        "cost_price": null,
        "option_values": [
          {
            "id": 1,
            "name": "Small",
            "presentation": "S",
            "option_type_name": "tshirt-size",
            "option_type_id": 1,
            "option_type_presentation": "S"
          }
        ],
        "images": [
          {
            "id": 1,
            "position": 1,
            "attachment_content_type": "image/jpg",
            "attachment_file_name": "ror_tote.jpeg",
            "type": "Spree::Image",
            "attachment_updated_at": null,
            "attachment_width": 360,
            "attachment_height": 360,
            "alt": null,
            "viewable_type": "Spree::Variant",
            "viewable_id": 1,
            "mini_url": "/spree/products/1/mini/file.png?1370533476",
            "small_url": "/spree/products/1/small/file.png?1370533476",
            "product_url": "/spree/products/1/product/file.png?1370533476",
            "large_url": "/spree/products/1/large/file.png?1370533476"
          }
        ],
        "display_price": "$15.99",
        "options_text": "(Size: small, Colour: red)",
        "in_stock": true,
        "is_backorderable": true,
        "is_orderable": true,
        "total_on_hand": 10,
        "is_destroyed": false
      },
      "variants": [
        {
          "id": 1,
          "name": "Ruby on Rails Tote",
          "sku": "ROR-00011",
          "price": "15.99",
          "weight": null,
          "height": null,
          "width": null,
          "depth": null,
          "is_master": false,
          "slug": "ruby-on-rails-tote",
          "description": "A text description of the product.",
          "track_inventory": true,
          "cost_price": null,
          "option_values": [
            {
              "id": 1,
              "name": "Small",
              "presentation": "S",
              "option_type_name": "tshirt-size",
              "option_type_id": 1,
              "option_type_presentation": "S"
            }
          ],
          "images": [
            {
              "id": 1,
              "position": 1,
              "attachment_content_type": "image/jpg",
              "attachment_file_name": "ror_tote.jpeg",
              "type": "Spree::Image",
              "attachment_updated_at": null,
              "attachment_width": 360,
              "attachment_height": 360,
              "alt": null,
              "viewable_type": "Spree::Variant",
              "viewable_id": 1,
              "mini_url": "/spree/products/1/mini/file.png?1370533476",
              "small_url": "/spree/products/1/small/file.png?1370533476",
              "product_url": "/spree/products/1/product/file.png?1370533476",
              "large_url": "/spree/products/1/large/file.png?1370533476"
            }
          ],
          "display_price": "$15.99",
          "options_text": "(Size: small, Colour: red)",
          "in_stock": true,
          "is_backorderable": true,
          "is_orderable": true,
          "total_on_hand": 10,
          "is_destroyed": false
        }
      ],
      "option_types": [
        {
          "id": 1,
          "name": "tshirt-size",
          "presentation": "Size",
          "position": 1
        }
      ],
      "product_properties": [
        {
          "id": 1,
          "product_id": 1,
          "property_id": 1,
          "value": "Tote",
          "property_name": "bag_type"
        }
      ],
      "classifications": [
        {
          "taxon_id": 3,
          "position": 1,
          "taxon": {
            "id": 2,
            "name": "Ruby on Rails",
            "pretty_name": "Ruby on Rails",
            "permalink": "brands/ruby-on-rails",
            "parent_id": 1,
            "taxonomy_id": 1,
            "meta_title": "Ruby on Rails",
            "meta_description": "Ruby on Rails",
            "taxons": [

            ]
          }
        }
      ],
      "has_variants": true
    }
  ],
  "count": 25,
  "pages": 5,
  "current_page": 1
}

To search for a particular product, make a request like this:

GET /api/v1/products?q[name_cont]=Spree

The searching API is provided through the Ransack gem which Spree depends on. The name_cont here is called a predicate, and you can learn more about them by reading about Predicates on the Ransack wiki.

The search results are paginated.

Response

Status: 200 OK
{
  "products": [
    {
      "id": 1,
      "name": "Example product",
      "description": "Description",
      "price": "15.99",
      "display_price": "$15.99",
      "available_on": "2012-10-17T03:43:57Z",
      "slug": "example-product",
      "meta_description": null,
      "meta_keywords": null,
      "shipping_category_id": 1,
      "taxon_ids": [
        1,
        2,
        3
      ],
      "total_on_hand": 10,
      "master": {
        "id": 1,
        "name": "Ruby on Rails Tote",
        "sku": "ROR-00011",
        "price": "15.99",
        "weight": null,
        "height": null,
        "width": null,
        "depth": null,
        "is_master": true,
        "slug": "ruby-on-rails-tote",
        "description": "A text description of the product.",
        "track_inventory": true,
        "cost_price": null,
        "option_values": [
          {
            "id": 1,
            "name": "Small",
            "presentation": "S",
            "option_type_name": "tshirt-size",
            "option_type_id": 1,
            "option_type_presentation": "S"
          }
        ],
        "images": [
          {
            "id": 1,
            "position": 1,
            "attachment_content_type": "image/jpg",
            "attachment_file_name": "ror_tote.jpeg",
            "type": "Spree::Image",
            "attachment_updated_at": null,
            "attachment_width": 360,
            "attachment_height": 360,
            "alt": null,
            "viewable_type": "Spree::Variant",
            "viewable_id": 1,
            "mini_url": "/spree/products/1/mini/file.png?1370533476",
            "small_url": "/spree/products/1/small/file.png?1370533476",
            "product_url": "/spree/products/1/product/file.png?1370533476",
            "large_url": "/spree/products/1/large/file.png?1370533476"
          }
        ],
        "display_price": "$15.99",
        "options_text": "(Size: small, Colour: red)",
        "in_stock": true,
        "is_backorderable": true,
        "is_orderable": true,
        "total_on_hand": 10,
        "is_destroyed": false
      },
      "variants": [
        {
          "id": 1,
          "name": "Ruby on Rails Tote",
          "sku": "ROR-00011",
          "price": "15.99",
          "weight": null,
          "height": null,
          "width": null,
          "depth": null,
          "is_master": false,
          "slug": "ruby-on-rails-tote",
          "description": "A text description of the product.",
          "track_inventory": true,
          "cost_price": null,
          "option_values": [
            {
              "id": 1,
              "name": "Small",
              "presentation": "S",
              "option_type_name": "tshirt-size",
              "option_type_id": 1,
              "option_type_presentation": "S"
            }
          ],
          "images": [
            {
              "id": 1,
              "position": 1,
              "attachment_content_type": "image/jpg",
              "attachment_file_name": "ror_tote.jpeg",
              "type": "Spree::Image",
              "attachment_updated_at": null,
              "attachment_width": 360,
              "attachment_height": 360,
              "alt": null,
              "viewable_type": "Spree::Variant",
              "viewable_id": 1,
              "mini_url": "/spree/products/1/mini/file.png?1370533476",
              "small_url": "/spree/products/1/small/file.png?1370533476",
              "product_url": "/spree/products/1/product/file.png?1370533476",
              "large_url": "/spree/products/1/large/file.png?1370533476"
            }
          ],
          "display_price": "$15.99",
          "options_text": "(Size: small, Colour: red)",
          "in_stock": true,
          "is_backorderable": true,
          "is_orderable": true,
          "total_on_hand": 10,
          "is_destroyed": false
        }
      ],
      "option_types": [
        {
          "id": 1,
          "name": "tshirt-size",
          "presentation": "Size",
          "position": 1
        }
      ],
      "product_properties": [
        {
          "id": 1,
          "product_id": 1,
          "property_id": 1,
          "value": "Tote",
          "property_name": "bag_type"
        }
      ],
      "classifications": [
        {
          "taxon_id": 3,
          "position": 1,
          "taxon": {
            "id": 2,
            "name": "Ruby on Rails",
            "pretty_name": "Ruby on Rails",
            "permalink": "brands/ruby-on-rails",
            "parent_id": 1,
            "taxonomy_id": 1,
            "meta_title": "Ruby on Rails",
            "meta_description": "Ruby on Rails",
            "taxons": [

            ]
          }
        }
      ],
      "has_variants": true
    }
  ],
  "count": 25,
  "pages": 5,
  "current_page": 1
}

Sorting results

Results can be returned in a specific order by specifying which field to sort by when making a request.

GET /api/v1/products?q[s]=sku%20asc

It is also possible to sort results using an associated object’s field.

GET /api/v1/products?q[s]=shipping_category_name%20asc

Show

To view the details for a single product, make a request using that product's permalink:

GET /api/v1/products/a-product

You may also query by the product's id attribute:

GET /api/v1/products/1

Note that the API will attempt a permalink lookup before an ID lookup.

Successful Response

Status: 200 OK
{
  "id": 1,
  "name": "Example product",
  "description": "Description",
  "price": "15.99",
  "display_price": "$15.99",
  "available_on": "2012-10-17T03:43:57Z",
  "slug": "example-product",
  "meta_description": null,
  "meta_keywords": null,
  "shipping_category_id": 1,
  "taxon_ids": [
    1,
    2,
    3
  ],
  "total_on_hand": 10,
  "master": {
    "id": 1,
    "name": "Ruby on Rails Tote",
    "sku": "ROR-00011",
    "price": "15.99",
    "weight": null,
    "height": null,
    "width": null,
    "depth": null,
    "is_master": true,
    "slug": "ruby-on-rails-tote",
    "description": "A text description of the product.",
    "track_inventory": true,
    "cost_price": null,
    "option_values": [
      {
        "id": 1,
        "name": "Small",
        "presentation": "S",
        "option_type_name": "tshirt-size",
        "option_type_id": 1,
        "option_type_presentation": "S"
      }
    ],
    "images": [
      {
        "id": 1,
        "position": 1,
        "attachment_content_type": "image/jpg",
        "attachment_file_name": "ror_tote.jpeg",
        "type": "Spree::Image",
        "attachment_updated_at": null,
        "attachment_width": 360,
        "attachment_height": 360,
        "alt": null,
        "viewable_type": "Spree::Variant",
        "viewable_id": 1,
        "mini_url": "/spree/products/1/mini/file.png?1370533476",
        "small_url": "/spree/products/1/small/file.png?1370533476",
        "product_url": "/spree/products/1/product/file.png?1370533476",
        "large_url": "/spree/products/1/large/file.png?1370533476"
      }
    ],
    "display_price": "$15.99",
    "options_text": "(Size: small, Colour: red)",
    "in_stock": true,
    "is_backorderable": true,
    "is_orderable": true,
    "total_on_hand": 10,
    "is_destroyed": false
  },
  "variants": [
    {
      "id": 1,
      "name": "Ruby on Rails Tote",
      "sku": "ROR-00011",
      "price": "15.99",
      "weight": null,
      "height": null,
      "width": null,
      "depth": null,
      "is_master": false,
      "slug": "ruby-on-rails-tote",
      "description": "A text description of the product.",
      "track_inventory": true,
      "cost_price": null,
      "option_values": [
        {
          "id": 1,
          "name": "Small",
          "presentation": "S",
          "option_type_name": "tshirt-size",
          "option_type_id": 1,
          "option_type_presentation": "S"
        }
      ],
      "images": [
        {
          "id": 1,
          "position": 1,
          "attachment_content_type": "image/jpg",
          "attachment_file_name": "ror_tote.jpeg",
          "type": "Spree::Image",
          "attachment_updated_at": null,
          "attachment_width": 360,
          "attachment_height": 360,
          "alt": null,
          "viewable_type": "Spree::Variant",
          "viewable_id": 1,
          "mini_url": "/spree/products/1/mini/file.png?1370533476",
          "small_url": "/spree/products/1/small/file.png?1370533476",
          "product_url": "/spree/products/1/product/file.png?1370533476",
          "large_url": "/spree/products/1/large/file.png?1370533476"
        }
      ],
      "display_price": "$15.99",
      "options_text": "(Size: small, Colour: red)",
      "in_stock": true,
      "is_backorderable": true,
      "is_orderable": true,
      "total_on_hand": 10,
      "is_destroyed": false
    }
  ],
  "option_types": [
    {
      "id": 1,
      "name": "tshirt-size",
      "presentation": "Size",
      "position": 1
    }
  ],
  "product_properties": [
    {
      "id": 1,
      "product_id": 1,
      "property_id": 1,
      "value": "Tote",
      "property_name": "bag_type"
    }
  ],
  "classifications": [
    {
      "taxon_id": 3,
      "position": 1,
      "taxon": {
        "id": 2,
        "name": "Ruby on Rails",
        "pretty_name": "Ruby on Rails",
        "permalink": "brands/ruby-on-rails",
        "parent_id": 1,
        "taxonomy_id": 1,
        "meta_title": "Ruby on Rails",
        "meta_description": "Ruby on Rails",
        "taxons": [

        ]
      }
    }
  ],
  "has_variants": true
}

Not Found Response

Status: 404 Not Found
{
  "error": "The resource you were looking for could not be found."
}

New

You can learn about the potential attributes (required and non-required) for a product by making this request:

GET /api/v1/products/new

Response

Status: 200 OK
{
  "attributes": [
    "id",
    "name",
    "description",
    "price",
    "display_price",
    "available_on",
    "slug",
    "meta_description",
    "meta_keywords",
    "shipping_category_id",
    "taxon_ids",
    "total_on_hand"
  ],
  "required_attributes": [
    "name",
    "shipping_category",
    "price"
  ]
}

Create

This action is only accessible by an admin user.

To create a new product through the API, make this request with the necessary parameters:

POST /api/v1/products

For instance, a request to create a new product called "Headphones" with a price of $100 would look like this:

POST /api/v1/products?product[name]=Headphones&product[price]=100&product[shipping_category_id]=1

Successful response

Status: 201 Created

Failed response

Status: 422 Unprocessable Entity
{
  "error": "Invalid resource. Please fix errors and try again.",
  "errors": {
    "name": [
      "can't be blank"
    ],
    "price": [
      "can't be blank"
    ],
    "shipping_category_id": [
      "can't be blank"
    ]
  }
}

Update

This action is only accessible by an admin user.

To update a product's details, make this request with the necessary parameters:

PUT /api/v1/products/a-product

For instance, to update a product's name, send it through like this:

PUT /api/v1/products/a-product?product[name]=Headphones

Successful response

Status: 201 Created

Failed response

Status: 422 Unprocessable Entity
{
  "error": "Invalid resource. Please fix errors and try again.",
  "errors": {
    "name": [
      "can't be blank"
    ],
    "price": [
      "can't be blank"
    ],
    "shipping_category_id": [
      "can't be blank"
    ]
  }
}

Delete

This action is only accessible by an admin user.

To delete a product, make this request:

DELETE /api/v1/products/a-product

This request, much like a typical product "deletion" through the admin interface, will not actually remove the record from the database. It simply sets the deleted_at field to the current time on the product, as well as all of that product's variants.

Status: 204 No Content