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/products
Products are paginated and can be iterated through by passing along a page parameter:
GET /api/products?page=2
Parameters
- show_deleted
- boolean -
trueto show deleted products,falseto hide them. Default:false. Only available to users with an admin role. - 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",
"permalink": "ruby-on-rails-tote",
"meta_description": null,
"meta_keywords": null,
"taxon_ids": [
1,
2,
3
],
"shipping_category_id": 1,
"has_variants": true,
"master": {
"id": 1,
"name": "Ruby on Rails Tote",
"sku": "ROR-00011",
"price": "15.99",
"display_price": "$15.99",
"weight": null,
"height": null,
"width": null,
"depth": null,
"is_master": true,
"cost_price": "13.0",
"permalink": "ruby-on-rails-tote",
"description": "A text description of the product.",
"options_text": "(Size: small, Colour: red)",
"in_stock": true,
"option_values": [
{
"id": 1,
"name": "Small",
"presentation": "S",
"option_type_name": "tshirt-size",
"option_type_id": 1
}
],
"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"
}
]
},
"variants": [
{
"id": 1,
"name": "Ruby on Rails Tote",
"sku": "ROR-00011",
"price": "15.99",
"display_price": "$15.99",
"weight": null,
"height": null,
"width": null,
"depth": null,
"is_master": false,
"cost_price": "13.0",
"permalink": "ruby-on-rails-tote",
"description": "A text description of the product.",
"options_text": "(Size: small, Colour: red)",
"in_stock": true,
"option_values": [
{
"id": 1,
"name": "Small",
"presentation": "S",
"option_type_name": "tshirt-size",
"option_type_id": 1
}
],
"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"
}
]
}
],
"product_properties": [
{
"id": 1,
"product_id": 1,
"property_id": 1,
"value": "Tote",
"property_name": "bag_type"
}
],
"option_types": [
{
"id": 1,
"name": "tshirt-size",
"presentation": "Size",
"position": 1
}
]
}
],
"count": 25,
"pages": 5,
"current_page": 1
}Search
To search for a particular product, make a request like this:
GET /api/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",
"permalink": "ruby-on-rails-tote",
"meta_description": null,
"meta_keywords": null,
"taxon_ids": [
1,
2,
3
],
"shipping_category_id": 1,
"has_variants": true,
"master": {
"id": 1,
"name": "Ruby on Rails Tote",
"sku": "ROR-00011",
"price": "15.99",
"display_price": "$15.99",
"weight": null,
"height": null,
"width": null,
"depth": null,
"is_master": true,
"cost_price": "13.0",
"permalink": "ruby-on-rails-tote",
"description": "A text description of the product.",
"options_text": "(Size: small, Colour: red)",
"in_stock": true,
"option_values": [
{
"id": 1,
"name": "Small",
"presentation": "S",
"option_type_name": "tshirt-size",
"option_type_id": 1
}
],
"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"
}
]
},
"variants": [
{
"id": 1,
"name": "Ruby on Rails Tote",
"sku": "ROR-00011",
"price": "15.99",
"display_price": "$15.99",
"weight": null,
"height": null,
"width": null,
"depth": null,
"is_master": false,
"cost_price": "13.0",
"permalink": "ruby-on-rails-tote",
"description": "A text description of the product.",
"options_text": "(Size: small, Colour: red)",
"in_stock": true,
"option_values": [
{
"id": 1,
"name": "Small",
"presentation": "S",
"option_type_name": "tshirt-size",
"option_type_id": 1
}
],
"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"
}
]
}
],
"product_properties": [
{
"id": 1,
"product_id": 1,
"property_id": 1,
"value": "Tote",
"property_name": "bag_type"
}
],
"option_types": [
{
"id": 1,
"name": "tshirt-size",
"presentation": "Size",
"position": 1
}
]
}
],
"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/products?q[s]=sku%20asc
It is also possible to sort results using an associated object’s field.
GET /api/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/products/a-product
You may also query by the product's id attribute:
GET /api/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",
"permalink": "ruby-on-rails-tote",
"meta_description": null,
"meta_keywords": null,
"taxon_ids": [
1,
2,
3
],
"shipping_category_id": 1,
"has_variants": true,
"master": {
"id": 1,
"name": "Ruby on Rails Tote",
"sku": "ROR-00011",
"price": "15.99",
"display_price": "$15.99",
"weight": null,
"height": null,
"width": null,
"depth": null,
"is_master": true,
"cost_price": "13.0",
"permalink": "ruby-on-rails-tote",
"description": "A text description of the product.",
"options_text": "(Size: small, Colour: red)",
"in_stock": true,
"option_values": [
{
"id": 1,
"name": "Small",
"presentation": "S",
"option_type_name": "tshirt-size",
"option_type_id": 1
}
],
"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"
}
]
},
"variants": [
{
"id": 1,
"name": "Ruby on Rails Tote",
"sku": "ROR-00011",
"price": "15.99",
"display_price": "$15.99",
"weight": null,
"height": null,
"width": null,
"depth": null,
"is_master": false,
"cost_price": "13.0",
"permalink": "ruby-on-rails-tote",
"description": "A text description of the product.",
"options_text": "(Size: small, Colour: red)",
"in_stock": true,
"option_values": [
{
"id": 1,
"name": "Small",
"presentation": "S",
"option_type_name": "tshirt-size",
"option_type_id": 1
}
],
"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"
}
]
}
],
"product_properties": [
{
"id": 1,
"product_id": 1,
"property_id": 1,
"value": "Tote",
"property_name": "bag_type"
}
],
"option_types": [
{
"id": 1,
"name": "tshirt-size",
"presentation": "Size",
"position": 1
}
]
}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/products/new
Response
Status: 200 OK{
"attributes": [
"id",
"name",
"description",
"price",
"available_on",
"permalink",
"count_on_hand",
"meta_description",
"meta_keywords",
"shipping_category_id",
"taxon_ids"
],
"required_attributes": [
"name",
"price",
"shipping_category_id"
]
}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/products
For instance, a request to create a new product called "Headphones" with a price of $100 would look like this:
POST /api/products?product[name]=Headphones&product[price]=100&product[shipping_category_id]=1
Successful response
Status: 201 CreatedFailed 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/products/a-product
For instance, to update a product's name, send it through like this:
PUT /api/products/a-product?product[name]=Headphones
Successful response
Status: 201 CreatedFailed 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/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