Introduction
Welcome to the Solidus JSON API! You can use our API to grab data from our database and make updates.
We currently only have a language binding in Shell. You can view code examples in the dark area to the right.
This example API documentation page was created with Slate. Feel free to edit it and use it as a base for documenting APIs of your own.
This JSON API is formatted after the JSON API spec. Please follow its guidelines to learn about:
- Pagination
- Including Relationships
- Sorting
- Error Objects
- The Document Structure
Errors
The Solidus JSON API uses the following error codes:
| Error Code | Meaning |
|---|---|
| 400 | Bad Request – Your request sucks |
| 401 | Unauthorized – Your API key is wrong |
| 403 | Forbidden – The kitten requested is hidden for administrators only |
| 404 | Not Found – The specified kitten could not be found |
| 405 | Method Not Allowed – You tried to access a kitten with an invalid method |
| 406 | Not Acceptable – You requested a format that isn’t json |
| 410 | Gone – The kitten requested has been removed from our servers |
| 418 | I’m a teapot |
| 429 | Too Many Requests – You’re requesting too many kittens! Slow down! |
| 500 | Internal Server Error – We had a problem with our server. Try again later. |
| 503 | Service Unavailable – We’re temporarially offline for maintanance. Please try again later. |
Pagination
curl "https://example.com/api/v2/kitten?page[number]2&page[size]=20"
This projects supports the JSON API’s page keyword.
To specify the page number, set a page[number] value.
To specify the page size (the amount of records returned), set a page[size] value; the default is 24.
If you would like the links to the self, next, prev, first, and last it is not yet supported.
Filtering
curl "https://example.com/api/v2/kittens?filter[id]=1"
curl "https://example.com/api/v2/kittens?filter[id]=2,3,4"
curl "https://example.com/api/v2/kittens?filter[breed]=Persian,British%20Shorthair,Bengal"
This project supports the JSON API’s filter keyword with only the root object, not any of its relationships yet.
You can filter any of the attributes that is inside of the data object.
Please see the example requests to the side on how you my filter a kitten object.
Countries
List Countries
curl "https://example.com/api/v2/countries"
{
"data": [
{
"id": "1",
"type": "spree_countries",
"attributes": {
"iso_name": "ANDORRA",
"iso": "AD",
"iso3": "AND",
"name": "Andorra",
"numcode": 20,
"states_required": true
},
"relationships": {
"states": {
"data": [
{
"type": "spree_states",
"id": "1"
}
]
}
}
}
]
}
List all of the ~200 countries in the DB.
Show Country
curl "https://example.com/api/v2/countries/1"
{
"data": {
"id": "1",
"type": "spree_countries",
"attributes": {
"iso_name": "ANDORRA",
"iso": "AD",
"iso3": "AND",
"name": "Andorra",
"numcode": 20,
"states_required": true
},
"relationships": {
"states": {
"data": [
{
"type": "spree_states",
"id": "1"
}
]
}
}
}
}
Select a country via its id.
List States of a Country
curl "https://example.com/api/v2/countries/1/states"
{
"data": [
{
"id": "1",
"type": "spree_states",
"attributes": {
"name": "Canillo",
"abbr": "02"
},
"relationships": {
"country": {
"data": {
"type": "spree_countries",
"id": "1"
}
}
}
}
]
}
See all of the states that a country owns via the country’s id.
Show State of a Country
curl "https://example.com/api/v2/countries/1/states/1"
{
"data": {
"id": "1",
"type": "spree_states",
"attributes": {
"name": "Canillo",
"abbr": "02"
},
"relationships": {
"country": {
"data": {
"type": "spree_countries",
"id": "1"
}
}
}
}
}
View one of the states that a country owns via the country’s id and the state’s id.
Images
List Images
curl "https://example.com/api/v2/images"
{
"data": [
{
"id": "1",
"type": "spree_images",
"attributes": {
"position": 1,
"alt": null,
"links": {
"original": "/spree/products/1/original/ror_baseball_jersey_red.png?1442035822",
"mini": "/spree/products/1/mini/ror_baseball_jersey_red.png?1442035822",
"small": "/spree/products/1/small/ror_baseball_jersey_red.png?1442035822",
"product": "/spree/products/1/product/ror_baseball_jersey_red.png?1442035822",
"large": "/spree/products/1/large/ror_baseball_jersey_red.png?1442035822"
}
},
"relationships": {
"viewable": {
"data": {
"type": "spree_variants",
"id": "1"
}
}
}
}
]
}
List all of the images stored in the database.
Show Image
curl "https://example.com/api/v2/images/1"
{
"data": {
"id": "1",
"type": "spree_images",
"attributes": {
"position": 1,
"alt": null,
"links": {
"original": "/spree/products/1/original/ror_baseball_jersey_red.png?1442035822",
"mini": "/spree/products/1/mini/ror_baseball_jersey_red.png?1442035822",
"small": "/spree/products/1/small/ror_baseball_jersey_red.png?1442035822",
"product": "/spree/products/1/product/ror_baseball_jersey_red.png?1442035822",
"large": "/spree/products/1/large/ror_baseball_jersey_red.png?1442035822"
}
},
"relationships": {
"viewable": {
"data": {
"type": "spree_variants",
"id": "1"
}
}
}
}
}
Fetch an image and its links via the image’s id.
Show Variant of an Image
curl "https://example.com/api/v2/images/1/variant"
{
"data": {
"id": "17",
"type": "spree_variants",
"attributes": {
"sku": "ROR-00001",
"weight": "0.0",
"height": null,
"width": null,
"depth": null,
"is_master": false,
"position": 2,
"name": "Ruby on Rails Baseball Jersey",
"price": null,
"display_price": "$0.00 CAD"
},
"relationships": {
"prices": {
"data": [
{
"type": "spree_prices",
"id": "33"
}
]
},
"option_values": {
"data": [
{
"type": "spree_option_values",
"id": "1"
}
]
},
"images": {
"data": [
{
"type": "spree_images",
"id": "1"
}
]
},
"product": {
"data": {
"type": "spree_products",
"id": "3"
}
}
}
}
}
Fetch the variant that an image belongs to via the variant’s id.
Show Product of an Image
curl "https://example.com/api/v2/images/1/product"
{
"data": {
"id": "3",
"type": "spree_products",
"attributes": {
"name": "Ruby on Rails Baseball Jersey",
"description": "Dolorem molestias sint maxime id at rem qui exercitationem. Neque voluptas corrupti magni suscipit iusto voluptatum. Ea quibusdam dolorem inventore praesentium sed dicta eveniet et. Rerum inventore laudantium quisquam earum consequatur dignissimos.",
"slug": "ruby-on-rails-baseball-jersey",
"meta_description": null,
"meta_keywords": null,
"store_name": "Whole New Home"
},
"relationships": {
"master": {
"data": {
"type": "spree_variants",
"id": "3"
}
},
"variants": {
"data": [
{
"type": "spree_variants",
"id": "1"
}
]
},
"taxons": {
"data": [
{
"type": "spree_taxons",
"id": "53"
}
]
},
"option_types": {
"data": [
{
"type": "spree_option_types",
"id": "1"
}
]
},
"images": {
"data": [
{
"type": "spree_images",
"id": "24"
}
]
}
}
}
}
Find the product that image belongs to via the image’s id.
Line Items
Create Line Item
curl "https://example.com/api/v2/line_items"
-X POST
-d token=abc123
-d data[attributes][order_id]=1
-d data[attributes][variant_id]=1
-d data[attributes][quantity]=1
{
"data": {
"attributes": {
"additional_tax_total": "0",
"adjustment_total": "0.0",
"amount": "10.0",
"cost_price": "17.0",
"currency": "CAD",
"display_amount": "$10.00 CAD",
"display_price": "$10.00 CAD",
"display_total": "$10.00 CAD",
"order_id": 1,
"price": "10.0",
"quantity": 1,
"total": "10.0",
"variant_id": 1
},
"relationships": {
"order": {
"data": {
"type": "spree_orders"
}
},
"variant": {
"data": {
"type": "spree_variants"
}
}
},
"type": "spree_line_items"
}
}
This endpoint allows you add a variant to a users order by creating a line item.
When Out of Range
Quantity is out of range.
curl "https://example.com/api/v2/line_items"
-X POST
-d token=abc123
-d data[attributes][order_id]=1
-d data[attributes][variant_id]=1
-d data[attributes][quantity]=100000000000
{
"errors": [
{
"code": "400",
"detail": "Quantity is too High",
"meta": {},
"status": "Bad Request",
"title": "The quantity that you have submitted is astronomically high, please tone it down a bit."
}
]
}
When requesting an insanely large amount of variants to be added to your order, this will result in an error.
When a Variant or an Order Could Not be Found
Order could not be found.
curl "https://example.com/api/v2/line_items"
-X POST
-d token=abc123
-d data[attributes][order_id]=0
-d data[attributes][variant_id]=1
-d data[attributes][quantity]=1
{
"errors": [
{
"code": "400",
"detail": "Record Not Found",
"meta": {},
"status": "Bad Request",
"title": "One of the records that you were looking for could not be found. Please check to see if the record exists or if you're permitted to read it"
}
]
}
Sometimes, you’ll submit a bad variant id or order id. When this happens, you’ll receive an error because of it.
When the Product is Out of Stock
Product is out of stock.
curl "https://example.com/api/v2/line_items"
-X POST
-d token=abc123
-d data[attributes][order_id]=1
-d data[attributes][variant_id]=1
-d data[attributes][quantity]=1
{
"errors": [
{
"code": "400",
"detail": "Product is out of Stock",
"meta": {},
"status": "Bad Request",
"title": "This product is out of stock for the selected quantity."
}
]
}
Sometimes, there’s just not going to be any left in stock. This can happen for both two reasons:
- The variant is tracking inventory and its stock items
count_on_hands have all reached 0. - The variant is not backorderable.
If both of these conditions are met, then you will reveice an out of stock error.
Option Types
List Option Types
curl "https://example.com/api/v2/option_types"
{
"data": [
{
"id": "1",
"type": "spree_option_types",
"attributes": {
"name": "tshirt-size",
"presentation": "Size",
"position": 1
},
"relationships": {
"option_values": {
"data": [
{
"type": "spree_option_values",
"id": "1"
}
]
},
"products": {
"data": [
{
"type": "spree_products",
"id": "1"
}
]
}
}
}
]
}
List all of the option types in the database.
Show Option Type
curl "https://example.com/api/v2/option_types/1"
{
"data": {
"id": "1",
"type": "spree_option_types",
"attributes": {
"name": "tshirt-size",
"presentation": "Size",
"position": 1
},
"relationships": {
"option_values": {
"data": [
{
"type": "spree_option_values",
"id": "1"
}
]
},
"products": {
"data": [
{
"type": "spree_products",
"id": "1"
}
]
}
}
}
}
Fetch an option type in the database.
List Option Values of a Option Type
curl "https://example.com/api/v2/option_types/1/option_values"
{
"data": [
{
"id": "1",
"type": "spree_option_values",
"attributes": {
"name": "Small",
"presentation": "S",
"position": 1
},
"relationships": {
"option_type": {
"data": {
"type": "spree_option_types",
"id": "1"
}
}
}
}
]
}
See all of the option values that an option type owns.
Show Option Values of a Option Type
curl "https://example.com/api/v2/option_types/1/option_values/1"
{
"data": {
"id": "1",
"type": "spree_option_values",
"attributes": {
"name": "Small",
"presentation": "S",
"position": 1
},
"relationships": {
"option_type": {
"data": {
"type": "spree_option_types",
"id": "1"
}
}
}
}
}
Fetch an option value that an option type owns.
List Products of a Option Type
curl "https://example.com/api/v2/option_types/1/products"
{
"data": [
{
"id": "1",
"type": "spree_products",
"attributes": {
"name": "Ruby on Rails Tote",
"description": "Velit nemo odio ducimus nobis non doloremque beatae sunt. Totam quia voluptatum perferendis tempore sed voluptate consequuntur. Sit id corporis autem veritatis reprehenderit.",
"slug": "ruby-on-rails-tote",
"meta_description": null,
"meta_keywords": null,
"store_name": "Whole New Home"
},
"relationships": {
"master": {
"data": {
"type": "spree_variants",
"id": "1"
}
},
"variants": {
"data": []
},
"taxons": {
"data": [
{
"type": "spree_taxons",
"id": "1"
}
]
},
"option_types": {
"data": [
{
"type": "spree_option_types",
"id": "1"
}
]
},
"images": {
"data": [
{
"type": "spree_images",
"id": "1"
}
]
}
}
}
]
}
See all of the products that an option type owns.
Show Product of a Option Type
curl "https://example.com/api/v2/option_types/1/products/1"
{
"data": {
"id": "1",
"type": "spree_products",
"attributes": {
"name": "Ruby on Rails Tote",
"description": "Velit nemo odio ducimus nobis non doloremque beatae sunt. Totam quia voluptatum perferendis tempore sed voluptate consequuntur. Sit id corporis autem veritatis reprehenderit.",
"slug": "ruby-on-rails-tote",
"meta_description": null,
"meta_keywords": null,
"store_name": "Whole New Home"
},
"relationships": {
"master": {
"data": {
"type": "spree_variants",
"id": "1"
}
},
"variants": {
"data": []
},
"taxons": {
"data": [
{
"type": "spree_taxons",
"id": "1"
}
]
},
"option_types": {
"data": [
{
"type": "spree_option_types",
"id": "1"
}
]
},
"images": {
"data": [
{
"type": "spree_images",
"id": "1"
}
]
}
}
}
}
Find a product that an option type owns.
Option Values
List Option Values
curl "https://example.com/api/v2/option_values"
{
"data": [
{
"id": "1",
"type": "spree_option_values",
"attributes": {
"name": "Small",
"presentation": "S",
"position": 1
},
"relationships": {
"option_type": {
"data": {
"type": "spree_option_types",
"id": "1"
}
}
}
}
]
}
List all of the option values.
Show Option Value
curl "https://example.com/api/v2/option_values/1"
{
"data": {
"id": "1",
"type": "spree_option_values",
"attributes": {
"name": "Small",
"presentation": "S",
"position": 1
},
"relationships": {
"option_type": {
"data": {
"type": "spree_option_types",
"id": "1"
}
}
}
}
}
Find an option value by its id.
Show Option Type of an Option Value
curl "https://example.com/api/v2/option_values/1/option_type"
{
"data": {
"id": "1",
"type": "spree_option_types",
"attributes": {
"name": "tshirt-size",
"presentation": "Size",
"position": 1
},
"relationships": {
"option_values": {
"data": [
{
"type": "spree_option_values",
"id": "1"
}
]
},
"products": {
"data": [
{
"type": "spree_products",
"id": "1"
}
]
}
}
}
}
Find the option type of an option value by the option value’s id.
List Variants of an Option Value
curl "https://example.com/api/v2/option_values/1/variants"
{
"data": [
{
"id": "1",
"type": "spree_variants",
"attributes": {
"sku": "ROR-00001",
"weight": "0.0",
"height": null,
"width": null,
"depth": null,
"is_master": false,
"position": 2,
"name": "Ruby on Rails Baseball Jersey",
"price": "15.99",
"display_price": "$15.99 CAD"
},
"relationships": {
"prices": {
"data": [
{
"type": "spree_prices",
"id": "33"
}
]
},
"option_values": {
"data": [
{
"type": "spree_option_values",
"id": "1"
}
]
},
"images": {
"data": [
{
"type": "spree_images",
"id": "1"
}
]
},
"product": {
"data": {
"type": "spree_products",
"id": "3"
}
}
}
}
]
}
List all of the variants that belong to an option value via the option value’s id.
Show Variant of an Option Value
curl "https://example.com/api/v2/option_values/1/variants/1"
{
"data": {
"id": "1",
"type": "spree_variants",
"attributes": {
"sku": "ROR-00001",
"weight": "0.0",
"height": null,
"width": null,
"depth": null,
"is_master": false,
"position": 2,
"name": "Ruby on Rails Baseball Jersey",
"price": "15.99",
"display_price": "$15.99 CAD"
},
"relationships": {
"prices": {
"data": [
{
"type": "spree_prices",
"id": "33"
}
]
},
"option_values": {
"data": [
{
"type": "spree_option_values",
"id": "1"
}
]
},
"images": {
"data": [
{
"type": "spree_images",
"id": "1"
}
]
},
"product": {
"data": {
"type": "spree_products",
"id": "3"
}
}
}
}
}
Show a variant that belongs to an option value via the option value’s id.
Orders
List Orders
curl "https://example.com/api/v2/orders"
-d token=abc123
{
"data" : [
{
"attributes" : {
"additional_tax_total" : "0.0",
"adjustment_total" : "0.0",
"approved_at" : null,
"canceled_at" : null,
"channel" : "spree",
"completed_at" : "2015-09-08T04:04:01.162Z",
"confirmation_delivered" : false,
"currency" : "CAD",
"display_additional_tax_total" : "$0.00 CAD",
"display_adjustment_total" : "$0.00 CAD",
"display_included_tax_total" : "$0.00 CAD",
"display_item_total" : "$10.00 CAD",
"display_promo_total" : "$0.00 CAD",
"display_shipment_total" : "$100.00 CAD",
"display_total" : "$110.00 CAD",
"email" : "spree@example.com",
"included_tax_total" : "0.0",
"item_count" : 0,
"item_total" : "10.0",
"number" : "#R123456789",
"payment_state" : null,
"payment_total" : "0.0",
"promo_total" : "0.0",
"shipment_state" : null,
"shipment_total" : "100.0",
"special_instructions" : null,
"state" : "complete",
"store_name" : "Example Store",
"total" : "110.0"
},
"relationships" : {
"bill_address" : {
"data" : {
"type" : "spree_addresses"
}
},
"line_items" : {
"data" : [
{
"type" : "spree_line_items"
}
]
},
"ship_address" : {
"data" : {
"type" : "spree_addresses"
}
},
"user" : {
"data" : {
"type" : "spree_users"
}
}
},
"type" : "spree_orders"
}
]
}
List all of the orders in the DB if you’re an admin. If you’re a standard user, then only the orders that you own are listed.
Show Order
curl "https://example.com/api/v2/orders/:id"
-d token=abc123
{
"data" : {
"attributes" : {
"additional_tax_total" : "0.0",
"adjustment_total" : "0.0",
"approved_at" : null,
"canceled_at" : null,
"channel" : "spree",
"completed_at" : "2015-09-08T04:04:01.162Z",
"confirmation_delivered" : false,
"currency" : "CAD",
"display_additional_tax_total" : "$0.00 CAD",
"display_adjustment_total" : "$0.00 CAD",
"display_included_tax_total" : "$0.00 CAD",
"display_item_total" : "$10.00 CAD",
"display_promo_total" : "$0.00 CAD",
"display_shipment_total" : "$100.00 CAD",
"display_total" : "$110.00 CAD",
"email" : "spree@example.com",
"included_tax_total" : "0.0",
"item_count" : 0,
"item_total" : "10.0",
"number" : "#R123456789",
"payment_state" : null,
"payment_total" : "0.0",
"promo_total" : "0.0",
"shipment_state" : null,
"shipment_total" : "100.0",
"special_instructions" : null,
"state" : "complete",
"store_name" : "Example Store",
"total" : "110.0"
},
"relationships" : {
"bill_address" : {
"data" : {
"type" : "spree_addresses"
}
},
"line_items" : {
"data" : [
{
"type" : "spree_line_items"
}
]
},
"ship_address" : {
"data" : {
"type" : "spree_addresses"
}
},
"user" : {
"data" : {
"type" : "spree_users"
}
}
},
"type" : "spree_orders"
}
}
This will get an order via the id supplied. Please note that you can ony access the orders that you own. If you are an admin, you can view any order.
Prices
List Prices
curl "https://example.com/api/v2/prices"
{
"data": [
{
"id": "1",
"type": "spree_prices",
"attributes": {
"amount": "15.99",
"price": "15.99",
"display_amount": "$15.99 CAD",
"display_price": "$15.99 CAD",
"currency": "CAD"
},
"relationships": {
"variant": {
"data": {
"type": "spree_variants",
"id": "1"
}
}
}
}
]
}
List all of the prices in the database.
Show Price
curl "https://example.com/api/v2/prices/1"
{
"data": {
"id": "1",
"type": "spree_prices",
"attributes": {
"amount": "15.99",
"price": "15.99",
"display_amount": "$15.99 CAD",
"display_price": "$15.99 CAD",
"currency": "CAD"
},
"relationships": {
"variant": {
"data": {
"type": "spree_variants",
"id": "1"
}
}
}
}
}
Fetch a price via its id.
Show Variant of a Price
curl "https://example.com/api/v2/prices/1/variant"
{
"data": {
"id": "1",
"type": "spree_variants",
"attributes": {
"sku": "ROR-00011",
"weight": "0.0",
"height": "1.0",
"width": "3.0",
"depth": "2.0",
"is_master": true,
"position": 1,
"name": "Ruby on Rails Tote",
"price": "15.99",
"display_price" : "$15.99 CAD"
},
"relationships": {
"prices": {
"data": [
{
"type": "spree_prices",
"id": "1"
}
]
},
"option_values": {
"data": [
{
"type": "spree_option_values",
"id": "1"
}
]
},
"images": {
"data": [
{
"type": "spree_images",
"id": "1"
}
]
},
"product": {
"data": {
"type": "spree_products",
"id": "1"
}
}
}
}
}
Fetch the variant a price belongs to via the price’s id.
Show Product of a Price
curl "https://example.com/api/v2/prices/1/product"
{
"data": {
"id": "1",
"type": "spree_products",
"attributes": {
"name": "Ruby on Rails Tote",
"description": "Dolorem molestias sint maxime id at rem qui exercitationem. Neque voluptas corrupti magni suscipit iusto voluptatum. Ea quibusdam dolorem inventore praesentium sed dicta eveniet et. Rerum inventore laudantium quisquam earum consequatur dignissimos.",
"slug": "ruby-on-rails-tote",
"meta_description": null,
"meta_keywords": null,
"store_name": "Whole New Home"
},
"relationships": {
"master": {
"data": {
"type": "spree_variants",
"id": "1"
}
},
"variants": {
"data": []
},
"taxons": {
"data": [
{
"type": "spree_taxons",
"id": "18"
}
]
},
"option_types": {
"data": [
{
"type": "spree_option_types",
"id": "1"
}
]
},
"images": {
"data": [
{
"type": "spree_images",
"id": "1"
}
]
}
}
}
}
Fetch the product a price belongs to via the price’s id.
Products
List Products
curl "https://example.com/api/v2/products"
{
"data": [
{
"id": "1",
"type": "spree_products",
"attributes": {
"name": "Ruby on Rails Tote",
"description": "Velit nemo odio ducimus nobis non doloremque beatae sunt. Totam quia voluptatum perferendis tempore sed voluptate consequuntur. Sit id corporis autem veritatis reprehenderit.",
"slug": "ruby-on-rails-tote",
"meta_description": null,
"meta_keywords": null,
"store_name": "Whole New Home"
},
"relationships": {
"master": {
"data": {
"type": "spree_variants",
"id": "1"
}
},
"variants": {
"data": []
},
"option_types": {
"data": [
{
"type": "spree_option_types",
"id": "1"
}
]
},
"taxons": {
"data": [
{
"type": "spree_taxons",
"id": "1"
}
]
}
},
"images": {
"data": [
{
"type": "spree_images",
"id": "1"
}
]
}
}
]
}
List all of the products in the database.
Show Product
curl "https://example.com/api/v2/products/1"
# or by slug
curl "https://example.com/api/v2/products/ruby-on-rails-tote"
{
"data": {
"id": "1",
"type": "spree_products",
"attributes": {
"name": "Ruby on Rails Tote",
"description": "Velit nemo odio ducimus nobis non doloremque beatae sunt. Totam quia voluptatum perferendis tempore sed voluptate consequuntur. Sit id corporis autem veritatis reprehenderit.",
"slug": "ruby-on-rails-tote",
"meta_description": null,
"meta_keywords": null,
"store_name": "Whole New Home"
},
"relationships": {
"master": {
"data": {
"type": "spree_variants",
"id": "1"
}
},
"variants": {
"data": []
},
"taxons": {
"data": [
{
"type": "spree_taxons",
"id": "1"
}
]
},
"option_types": {
"data": [
{
"type": "spree_option_types",
"id": "1"
}
]
},
"images": {
"data": [
{
"type": "spree_images",
"id": "1"
}
]
}
}
}
}
Select a product via it’s id.
List Option Types of a Product
curl "https://example.com/api/v2/products/1/option_types"
{
"data": [
{
"id": "1",
"type": "spree_option_types",
"attributes": {
"name": "tshirt-size",
"presentation": "Size",
"position": 1
},
"relationships": {
"option_values": {
"data": [
{
"type": "spree_option_values",
"id": "1"
}
]
},
"products": {
"data": [
{
"type": "spree_products",
"id": "1"
}
]
}
}
}
]
}
List all of the option types that a product owns via the product’s id.
Show Option Type of a Product
curl "https://example.com/api/v2/products/1/option_types/1"
{
"data": {
"id": "1",
"type": "spree_option_types",
"attributes": {
"name": "tshirt-size",
"presentation": "Size",
"position": 1
},
"relationships": {
"option_values": {
"data": [
{
"type": "spree_option_values",
"id": "1"
}
]
},
"products": {
"data": [
{
"type": "spree_products",
"id": "1"
}
]
}
}
}
}
Fetch an option type of a product by both of their ids.
List Variants of a Product
curl "https://example.com/api/v2/products/1/variants"
{
"data": [
{
"id": "1",
"type": "spree_variants",
"attributes": {
"sku": "ROR-00011",
"weight": "0.0",
"height": "1.0",
"width": "3.0",
"depth": "2.0",
"is_master": true,
"position": 1,
"name": "Ruby on Rails Tote",
"price": "15.99",
"display_price" : "$15.99 CAD"
},
"relationships": {
"prices": {
"data": [
{
"type": "spree_prices",
"id": "1"
}
]
},
"option_values": {
"data": [
{
"type": "spree_option_values",
"id": "1"
}
]
},
"images": {
"data": [
{
"type": "spree_images",
"id": "1"
}
]
},
"product": {
"data": {
"type": "spree_products",
"id": "1"
}
}
}
}
]
}
List all variants including the master of a product by the products id.
Show Variant of a Product
curl "https://example.com/api/v2/products/1/variants/1"
{
"data": {
"id": "1",
"type": "spree_variants",
"attributes": {
"sku": "ROR-00011",
"weight": "0.0",
"height": "1.0",
"width": "3.0",
"depth": "2.0",
"is_master": true,
"position": 1,
"name": "Ruby on Rails Tote",
"price": "15.99",
"display_price" : "$15.99 CAD"
},
"relationships": {
"prices": {
"data": [
{
"type": "spree_prices",
"id": "1"
}
]
},
"option_values": {
"data": [
{
"type": "spree_option_values",
"id": "1"
}
]
},
"images": {
"data": [
{
"type": "spree_images",
"id": "1"
}
]
},
"product": {
"data": {
"type": "spree_products",
"id": "1"
}
}
}
}
}
Fetch a variant or a product’s master variant that a product owns by the products id.
List Images of a Product
curl "https://example.com/api/v2/products/1/images"
{
"data": [
{
"id": "21",
"type": "spree_images",
"attributes": {
"position": 1,
"alt": null,
"links": {
"original": "/spree/products/21/original/ror_tote.jpeg?1442035828",
"mini": "/spree/products/21/mini/ror_tote.jpeg?1442035828",
"small": "/spree/products/21/small/ror_tote.jpeg?1442035828",
"product": "/spree/products/21/product/ror_tote.jpeg?1442035828",
"large": "/spree/products/21/large/ror_tote.jpeg?1442035828"
}
},
"relationships": {
"viewable": {
"data": {
"type": "spree_variants",
"id": "1"
}
}
}
}
]
}
List all of the images that belong to a product via the product’s id.
Show Image of a Product
curl "https://example.com/api/v2/products/1/images/21"
{
"data": {
"id": "21",
"type": "spree_images",
"attributes": {
"position": 1,
"alt": null,
"links": {
"original": "/spree/products/21/original/ror_tote.jpeg?1442035828",
"mini": "/spree/products/21/mini/ror_tote.jpeg?1442035828",
"small": "/spree/products/21/small/ror_tote.jpeg?1442035828",
"product": "/spree/products/21/product/ror_tote.jpeg?1442035828",
"large": "/spree/products/21/large/ror_tote.jpeg?1442035828"
}
},
"relationships": {
"viewable": {
"data": {
"type": "spree_variants",
"id": "1"
}
}
}
}
}
Fetch an image of a product via the product and the images’ id.
States
List States
curl "https://example.com/api/v2/states"
{
"data": [
{
"id": "1",
"type": "spree_states",
"attributes": {
"name": "Canillo",
"abbr": "02"
},
"relationships": {
"country": {
"data": {
"type": "spree_countries",
"id": "1"
}
}
}
}
]
}
This will list all of the states.
Show State
curl "https://example.com/api/v2/states/1"
{
"data": {
"id": "1",
"type": "spree_states",
"attributes": {
"name": "Canillo",
"abbr": "02"
},
"relationships": {
"country": {
"data": {
"type": "spree_countries",
"id": "1"
}
}
}
}
}
Select a state via its id.
Show Country of a States
curl "https://example.com/api/v2/states/1/countries"
{
"data": {
"id": "1",
"type": "spree_countries",
"attributes": {
"iso_name": "ANDORRA",
"iso": "AD",
"iso3": "AND",
"name": "Andorra",
"numcode": 20,
"states_required": true
},
"relationships": {
"states": {
"data": [
{
"type": "spree_states",
"id": "1"
}
]
}
}
}
}
View the country that a state belongs to via the state’s id.
Taxonomies
List Taxonomies
curl "https://example.com/api/v2/taxonomies"
{
"data": [
{
"id": "1",
"type": "spree_taxonomies",
"attributes": {
"name": "Category",
"position": 1
},
"relationships": {
"taxons": {
"data": [
{
"type": "spree_taxons",
"id": "2"
},
{
"type": "spree_taxons",
"id": "1"
}
]
},
"children": {
"data": [
{
"type": "spree_taxons",
"id": "2"
}
]
}
}
}
]
}
List of the taxonomies in the database.
Show Taxonomy
curl "https://example.com/api/v2/taxonomies/1"
{
"data": {
"id": "1",
"type": "spree_taxonomies",
"attributes": {
"name": "Category",
"position": 1
},
"relationships": {
"taxons": {
"data": [
{
"type": "spree_taxons",
"id": "2"
},
{
"type": "spree_taxons",
"id": "1"
}
]
},
"children": {
"data": [
{
"type": "spree_taxons",
"id": "2"
}
]
}
}
}
}
Select a taxonomy via the id.
List Taxons of a Taxonomy
curl "https://example.com/api/v2/taxonomies/1/taxons"
{
"data": [
{
"id": "2",
"type": "spree_taxons",
"attributes": {
"name": "SLEEP",
"permalink": "category/sleep",
"position": 0,
"description": null,
"meta_title": null,
"meta_description": null,
"meta_keywords": null,
"depth": 1,
"classifications_count": null
},
"relationships": {
"taxonomy": {
"data": {
"type": "spree_taxonomies",
"id": "1"
}
},
"parent": {
"data": {
"type": "spree_taxons",
"id": "1"
}
},
"children": {
"data": [
{
"type": "spree_taxons",
"id": "3"
}
]
}
}
},
{
"id": "1",
"type": "spree_taxons",
"attributes": {
"name": "Category",
"permalink": "category",
"position": 0,
"description": null,
"meta_title": null,
"meta_description": null,
"meta_keywords": null,
"depth": 0,
"classifications_count": 1
},
"relationships": {
"taxonomy": {
"data": {
"type": "spree_taxonomies",
"id": "1"
}
},
"parent": {
"data": null
},
"children": {
"data": [
{
"type": "spree_taxons",
"id": "2"
}
]
}
}
}
]
}
List all of the taxons that a taxonomy has a reference to.
Show Taxon of a Taxonomy
curl "https://example.com/api/v2/taxonomies/1/taxons/1"
{
"data": {
"id": "1",
"type": "spree_taxons",
"attributes": {
"name": "Category",
"permalink": "category",
"position": 0,
"description": null,
"meta_title": null,
"meta_description": null,
"meta_keywords": null,
"depth": 0,
"classifications_count": 1
},
"relationships": {
"taxonomy": {
"data": {
"type": "spree_taxonomies",
"id": "1"
}
},
"parent": {
"data": null
},
"children": {
"data": [
{
"type": "spree_taxons",
"id": "2"
}
]
}
}
}
}
Find a taxon that the taxonomy owns via the taxonomy’s id and the taxon’s id.
List Children of a Taxonomy
curl "https://example.com/api/v2/taxonomies/1/children"
{
"data": [
{
"id": "2",
"type": "spree_taxons",
"attributes": {
"name": "SLEEP",
"permalink": "category/sleep",
"position": 0,
"description": null,
"meta_title": null,
"meta_description": null,
"meta_keywords": null,
"depth": 1,
"classifications_count": null
},
"relationships": {
"taxonomy": {
"data": {
"type": "spree_taxonomies",
"id": "1"
}
},
"parent": {
"data": {
"type": "spree_taxons",
"id": "1"
}
},
"children": {
"data": [
{
"type": "spree_taxons",
"id": "3"
}
]
}
}
}
]
}
List all of the children of a taxonomy. This does not include the root taxon that would be included when listing all of the taxons of this taxonomy.
Show Child of a Taxonomy
curl "https://example.com/api/v2/taxonomies/1/children/2"
{
"data": {
"id": "2",
"type": "spree_taxons",
"attributes": {
"name": "SLEEP",
"permalink": "category/sleep",
"position": 0,
"description": null,
"meta_title": null,
"meta_description": null,
"meta_keywords": null,
"depth": 1,
"classifications_count": null
},
"relationships": {
"taxonomy": {
"data": {
"type": "spree_taxonomies",
"id": "1"
}
},
"parent": {
"data": {
"type": "spree_taxons",
"id": "1"
}
},
"children": {
"data": [
{
"type": "spree_taxons",
"id": "3"
}
]
}
}
}
}
Fetch a child of the taxnomy via the taxonomy’s id and the child’s id.
Taxons
List Taxons
curl "https://example.com/api/v2/taxons"
{
"data": [
{
"id": "2",
"type": "spree_taxons",
"attributes": {
"name": "SLEEP",
"permalink": "category/sleep",
"position": 0,
"description": null,
"meta_title": null,
"meta_description": null,
"meta_keywords": null,
"depth": 1,
"classifications_count": null
},
"relationships": {
"taxonomy": {
"data": {
"type": "spree_taxonomies",
"id": "1"
}
},
"parent": {
"data": {
"type": "spree_taxons",
"id": "1"
}
},
"children": {
"data": [
{
"type": "spree_taxons",
"id": "3"
}
]
}
}
}
]
}
List all the taxons in the database.
Show Taxon
curl "https://example.com/api/v2/taxons/1"
{
"data": {
"id": "1",
"type": "spree_taxons",
"attributes": {
"name": "Category",
"permalink": "category",
"position": 0,
"description": null,
"meta_title": null,
"meta_description": null,
"meta_keywords": null,
"depth": 0,
"classifications_count": 1
},
"relationships": {
"taxonomy": {
"data": {
"type": "spree_taxonomies",
"id": "1"
}
},
"parent": {
"data": null
},
"children": {
"data": [
{
"type": "spree_taxons",
"id": "2"
}
]
}
}
}
}
Locate the taxon that you’re looking for via its id.
Show Taxonomy of a Taxon
curl "https://example.com/api/v2/taxons/1/taxonomy"
{
"data": {
"id": "1",
"type": "spree_taxonomies",
"attributes": {
"name": "Category",
"position": 1
},
"relationships": {
"taxons": {
"data": [
{
"type": "spree_taxons",
"id": "2"
},
{
"type": "spree_taxons",
"id": "1"
}
]
},
"children": {
"data": [
{
"type": "spree_taxons",
"id": "2"
}
]
}
}
}
}
Display the taxonomy that a taxon belongs.
Show Parent of a Taxon
curl "https://example.com/api/v2/taxons/2/parent"
{
"data": {
"id": "1",
"type": "spree_taxons",
"attributes": {
"name": "Category",
"permalink": "category",
"position": 0,
"description": null,
"meta_title": null,
"meta_description": null,
"meta_keywords": null,
"depth": 0,
"classifications_count": 1
},
"relationships": {
"taxonomy": {
"data": {
"type": "spree_taxonomies",
"id": "1"
}
},
"parent": {
"data": null
},
"children": {
"data": [
{
"type": "spree_taxons",
"id": "2"
}
]
}
}
}
}
Display the parent taxon that a taxon may belong to.
List Children of a Taxon
curl "https://example.com/api/v2/taxons/1/children"
{
"data": [
{
"id": "2",
"type": "spree_taxons",
"attributes": {
"name": "SLEEP",
"permalink": "category/sleep",
"position": 0,
"description": null,
"meta_title": null,
"meta_description": null,
"meta_keywords": null,
"depth": 1,
"classifications_count": null
},
"relationships": {
"taxonomy": {
"data": {
"type": "spree_taxonomies",
"id": "1"
}
},
"parent": {
"data": {
"type": "spree_taxons",
"id": "1"
}
},
"children": {
"data": [
{
"type": "spree_taxons",
"id": "3"
}
]
}
}
}
]
}
List all the children that a taxon has.
Show Child of a Taxon
curl "https://example.com/api/v2/taxons/1/children/2"
{
"data": {
"id": "2",
"type": "spree_taxons",
"attributes": {
"name": "SLEEP",
"permalink": "category/sleep",
"position": 0,
"description": null,
"meta_title": null,
"meta_description": null,
"meta_keywords": null,
"depth": 1,
"classifications_count": null
},
"relationships": {
"taxonomy": {
"data": {
"type": "spree_taxonomies",
"id": "1"
}
},
"parent": {
"data": {
"type": "spree_taxons",
"id": "1"
}
},
"children": {
"data": [
{
"type": "spree_taxons",
"id": "3"
}
]
}
}
}
}
Find a child via its id and its owners (taxon) id.
List Products of a Taxon
curl "https://example.com/api/v2/taxons/1/products"
{
"data": [
{
"id": "10",
"type": "spree_products",
"attributes": {
"name": "Spree Ringer T-Shirt",
"description": "Velit nemo odio ducimus nobis non doloremque beatae sunt. Totam quia voluptatum perferendis tempore sed voluptate consequuntur. Sit id corporis autem veritatis reprehenderit.",
"slug": "spree-ringer-t-shirt",
"meta_description": null,
"meta_keywords": null,
"store_name": "Whole New Home"
},
"relationships": {
"master": {
"data": {
"type": "spree_variants",
"id": "10"
}
},
"variants": {
"data": []
},
"taxons": {
"data": [
{
"type": "spree_taxons",
"id": "1"
}
]
},
"option_types": {
"data": [
{
"type": "spree_option_types",
"id": "1"
}
]
},
"images": {
"data": [
{
"type": "spree_images",
"id": "1"
}
]
}
}
}
]
}
List all of the products that taxon owns via the taxons id.
Show Product of a Taxon
curl "https://example.com/api/v2/taxons/1/products/10"
{
"data": {
"id": "10",
"type": "spree_products",
"attributes": {
"name": "Spree Ringer T-Shirt",
"description": "Velit nemo odio ducimus nobis non doloremque beatae sunt. Totam quia voluptatum perferendis tempore sed voluptate consequuntur. Sit id corporis autem veritatis reprehenderit.",
"slug": "spree-ringer-t-shirt",
"meta_description": null,
"meta_keywords": null,
"store_name": "Whole New Home"
},
"relationships": {
"master": {
"data": {
"type": "spree_variants",
"id": "10"
}
},
"variants": {
"data": []
},
"taxons": {
"data": [
{
"type": "spree_taxons",
"id": "1"
}
]
},
"option_types": {
"data": [
{
"type": "spree_option_types",
"id": "1"
}
]
},
"images": {
"data": [
{
"type": "spree_images",
"id": "1"
}
]
}
}
}
}
Fetch a product of taxon via the taxon’s id and the products id.
Variants
List Variants
curl "https://example.com/api/v2/variants"
{
"data": [
{
"id": "1",
"type": "spree_variants",
"attributes": {
"sku": "ROR-00011",
"weight": "0.0",
"height": "1.0",
"width": "3.0",
"depth": "2.0",
"is_master": true,
"position": 1,
"name": "Ruby on Rails Tote",
"price": "15.99",
"display_price" : "$15.99 CAD"
},
"relationships": {
"prices": {
"data": [
{
"type": "spree_prices",
"id": "1"
},
{
"type": "spree_prices",
"id": "2"
}
]
},
"option_values": {
"data": [
{
"type": "spree_option_values",
"id": "1"
}
]
},
"images": {
"data": [
{
"type": "spree_images",
"id": "1"
}
]
},
"product": {
"data": {
"type": "spree_products",
"id": "1"
}
}
}
}
]
}
List all variants in the DB including master variants.
Show Variant
curl "https://example.com/api/v2/variants/1"
{
"data": {
"id": "1",
"type": "spree_variants",
"attributes": {
"sku": "ROR-00011",
"weight": "0.0",
"height": "1.0",
"width": "3.0",
"depth": "2.0",
"is_master": true,
"position": 1,
"name": "Ruby on Rails Tote",
"price": "15.99",
"display_price" : "$15.99 CAD"
},
"relationships": {
"prices": {
"data": [
{
"type": "spree_prices",
"id": "1"
},
{
"type": "spree_prices",
"id": "2"
}
]
},
"option_values": {
"data": [
{
"type": "spree_option_values",
"id": "1"
}
]
},
"images": {
"data": [
{
"type": "spree_images",
"id": "1"
}
]
},
"product": {
"data": {
"type": "spree_products",
"id": "1"
}
}
}
}
}
Fetch a variant by its id.
List Prices of a Variant
curl "https://example.com/api/v2/variants/1/prices"
{
"data": [
{
"id": "1",
"type": "spree_prices",
"attributes": {
"amount": "15.99",
"price": "15.99",
"display_amount": "$15.99 CAD",
"display_price": "$15.99 CAD",
"currency": "CAD"
},
"relationships": {
"variant": {
"data": {
"type": "spree_variants",
"id": "1"
}
}
}
},
{
"id": "2",
"type": "spree_prices",
"attributes": {
"amount": "14.0",
"price": "14.0",
"display_amount": "€14,00 EUR",
"display_price": "€14,00 EUR",
"currency": "EUR"
},
"relationships": {
"variant": {
"data": {
"type": "spree_variants",
"id": "1"
}
}
}
}
]
}
List all of the prices for a variant.
Show Price of a Variant
curl "https://example.com/api/v2/variants/1/prices/1"
{
"data": {
"id": "1",
"type": "spree_prices",
"attributes": {
"amount": "15.99",
"price": "15.99",
"display_amount": "$15.99 CAD",
"display_price": "$15.99 CAD",
"currency": "CAD"
},
"relationships": {
"variant": {
"data": {
"type": "spree_variants",
"id": "1"
}
}
}
}
}
Fetch a price for a variant by the price and variants id.
Show Product of a Variant
curl "https://example.com/api/v2/variants/1/product"
{
"data": {
"id": "1",
"type": "spree_products",
"attributes": {
"name": "Ruby on Rails Tote",
"description": "Dolorem molestias sint maxime id at rem qui exercitationem. Neque voluptas corrupti magni suscipit iusto voluptatum. Ea quibusdam dolorem inventore praesentium sed dicta eveniet et. Rerum inventore laudantium quisquam earum consequatur dignissimos.",
"slug": "ruby-on-rails-tote",
"meta_description": null,
"meta_keywords": null,
"store_name": "Whole New Home"
},
"relationships": {
"master": {
"data": {
"type": "spree_variants",
"id": "1"
}
},
"variants": {
"data": []
},
"taxons": {
"data": [
{
"type": "spree_taxons",
"id": "18"
},
]
},
"option_types": {
"data": [
{
"type": "spree_option_types",
"id": "1"
}
]
},
"images": {
"data": [
{
"type": "spree_images",
"id": "1"
}
]
}
}
}
}
Fetch the product the a variant belongs to by the variant’s id.
List Option Values of a Variant
curl "https://example.com/api/v2/variants/1/option_values"
{
"data": [
{
"id": "1",
"type": "spree_option_values",
"attributes": {
"name": "Small",
"presentation": "S",
"position": 1
},
"relationships": {
"option_type": {
"data": {
"type": "spree_option_types",
"id": "1"
}
},
"variants": {
"data": [
{
"type": "spree_variants",
"id": "1"
}
]
}
}
}
]
}
List all of the option values that belong to a variant via the variant’s id.
Show Option Value of a Variant
curl "https://example.com/api/v2/variants/1/option_values/1"
{
"data": {
"id": "1",
"type": "spree_option_values",
"attributes": {
"name": "Small",
"presentation": "S",
"position": 1
},
"relationships": {
"option_type": {
"data": {
"type": "spree_option_types",
"id": "1"
}
},
"variants": {
"data": [
{
"type": "spree_variants",
"id": "1"
}
]
}
}
}
}
Fetch an option value via the option value’s id and the variant’s id.
List Images of a Variant
curl "https://example.com/api/v2/variants/1/images"
{
"data": [
{
"id": "21",
"type": "spree_images",
"attributes": {
"position": 1,
"alt": null,
"links": {
"original": "/spree/products/21/original/ror_tote.jpeg?1442035828",
"mini": "/spree/products/21/mini/tot_tote.jpeg?1442035828",
"small": "/spree/products/21/small/ror_tote.jpeg?1442035828",
"product": "/spree/products/21/product/ror_tote.jpeg?1442035828",
"large": "/spree/products/21/large/ror_tote.jpeg?1442035828"
}
},
"relationships": {
"viewable": {
"data": {
"type": "spree_variants",
"id": "1"
}
}
}
}
]
}
List all of the images of a variant via the variant’s id.
Show Image of a Variant
curl "https://example.com/api/v2/variants/1/images/21"
{
"data": {
"id": "21",
"type": "spree_images",
"attributes": {
"position": 1,
"alt": null,
"links": {
"original": "/spree/products/21/original/ror_tote.jpeg?1442035828",
"mini": "/spree/products/21/mini/tot_tote.jpeg?1442035828",
"small": "/spree/products/21/small/ror_tote.jpeg?1442035828",
"product": "/spree/products/21/product/ror_tote.jpeg?1442035828",
"large": "/spree/products/21/large/ror_tote.jpeg?1442035828"
}
},
"relationships": {
"viewable": {
"data": {
"type": "spree_variants",
"id": "1"
}
}
}
}
}
Fetch an image of a variant via the image and the variant’s ids.