Products
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/productsProducts are paginated and can be iterated through by passing along a page parameter:
GET /api/v1/products?page=2Parameters
- show_deleted:
boolean -
trueto show deleted products,falseto hide them. Default:false. Only available to users with an admin role.- show_discontinued:
boolean -
trueto show discontinued products,falseto 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 product properties to display.
- per_page:
The number of product properties 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,"option_values": [{"id": 1,"name": "Small","presentation": "S","option_type_name": "tshirt-size","option_type_id": 1,"option_type_presentation": "S"}]}],"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}
Search
To search for a particular product, make a request like this:
GET /api/v1/products?q[name_cont]=SpreeThe searching API is provided through the Ransack gem which Boxid 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,"option_values": [{"id": 1,"name": "Small","presentation": "S","option_type_name": "tshirt-size","option_type_id": 1,"option_type_presentation": "S"}]}],"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%20ascIt is also possible to sort results using an associated object’s field.
GET /api/v1/products?q[s]=shipping_category_name%20ascShow
To view the details for a single product, make a request using that product’s permalink:
GET /api/v1/products/a-productYou may also query by the product’s id attribute:
GET /api/v1/products/1Note 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,"option_values": [{"id": 1,"name": "Small","presentation": "S","option_type_name": "tshirt-size","option_type_id": 1,"option_type_presentation": "S"}]}],"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/newResponse
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/productsFor 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]=1Successful 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-productFor instance, to update a product’s name, send it through like this:
PUT /api/v1/products/a-product?product[name]=HeadphonesSuccessful 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-productThis 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