Index

This action is only accessible by an admin user.

Retrieve a list of orders by making this request:

GET /api/orders

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

GET /api/orders?page=2

Parameters

page
The page number of order to display.
per_page
The number of orders to return per page

Response

Status: 200 OK
{
  "orders": [
    {
      "id": 1,
      "number": "R335381310",
      "item_total": "100.0",
      "display_item_total": "$100.00",
      "total": "100.0",
      "display_total": "$100.00",
      "state": "cart",
      "adjustment_total": "-12.0",
      "user_id": null,
      "created_at": "2012-10-24T01:02:25Z",
      "updated_at": "2012-10-24T01:02:25Z",
      "completed_at": null,
      "payment_total": "0.0",
      "shipment_state": null,
      "payment_state": null,
      "email": null,
      "special_instructions": null,
      "total_quantity": 1,
      "token": "abcdef123456",
      "line_items": [

      ],
      "adjustments": [

      ],
      "payments": [

      ],
      "shipments": [

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

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

GET /api/orders?q[email_cont]=bob

The searching API is provided through the Ransack gem which Spree depends on. The email_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
{
  "orders": [
    {
      "id": 1,
      "number": "R335381310",
      "item_total": "100.0",
      "display_item_total": "$100.00",
      "total": "100.0",
      "display_total": "$100.00",
      "state": "cart",
      "adjustment_total": "-12.0",
      "user_id": null,
      "created_at": "2012-10-24T01:02:25Z",
      "updated_at": "2012-10-24T01:02:25Z",
      "completed_at": null,
      "payment_total": "0.0",
      "shipment_state": null,
      "payment_state": null,
      "email": null,
      "special_instructions": null,
      "total_quantity": 1,
      "token": "abcdef123456",
      "line_items": [

      ],
      "adjustments": [

      ],
      "payments": [

      ],
      "shipments": [

      ]
    }
  ],
  "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/orders?q[s]=number%20desc

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

GET /api/orders?q[s]=user_name%20asc

Show

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

GET /api/orders/R123456789

Orders through the API will only be visible to admins and the users who own them. If a user attempts to access an order that does not belong to them, they will be met with an authorization error.

Users may pass in the order’s token in order to be authorized to view an order:

GET /api/orders/R123456789?order_token=abcdef123456

The order_token parameter will work for authorizing any action for an order within Spree’s API.

Successful Response

Status: 200 OK
{
  "id": 1,
  "number": "R335381310",
  "item_total": "100.0",
  "display_item_total": "$100.00",
  "total": "100.0",
  "display_total": "$100.00",
  "state": "cart",
  "adjustment_total": "-12.0",
  "user_id": null,
  "created_at": "2012-10-24T01:02:25Z",
  "updated_at": "2012-10-24T01:02:25Z",
  "completed_at": null,
  "payment_total": "0.0",
  "shipment_state": null,
  "payment_state": null,
  "email": null,
  "special_instructions": null,
  "total_quantity": 1,
  "token": "abcdef123456",
  "line_items": [
    {
      "id": 1,
      "quantity": 2,
      "price": "19.99",
      "single_display_amount": "$19.99",
      "total": "39.99",
      "display_total": "$39.99",
      "variant_id": 1,
      "variant": {
        "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"
          }
        ]
      }
    }
  ],
  "adjustments": [

  ],
  "payments": [

  ],
  "shipments": [

  ]
}

Not Found Response

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

Authorization Failure

Status: 401 Unauthorized
{
  "error": "You are not authorized to perform that action."
}

Show (delivery)

When an order is in the “delivery” state, additional shipments information will be returned in the API:

{
  "shipments": [
    {
      "id": 1,
      "tracking": null,
      "number": "H123456789",
      "cost": "5.0",
      "shipped_at": null,
      "state": "pending",
      "order_id": "R1234567",
      "stock_location_name": "NY Warehouse",
      "shipping_rates": [
        {
          "id": 1,
          "name": "UPS Ground (USD)",
          "cost": 5,
          "selected": true,
          "shipment_id": 1,
          "shipping_method_id": 5
        }
      ],
      "shipping_method": {
        "name": "UPS Ground",
        "zone_id": 1,
        "shipping_category_id": 1
      },
      "manifest": [
        {
          "quantity": 1,
          "states": {
            "on_hand": 1
          },
          "variant": {
            "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"
              }
            ]
          }
        }
      ]
    }
  ]
}

Create

To create a new order through the API, make this request:

POST /api/orders

If you wish to create an order with a line item matching to a variant whose ID is "1" and quantity is 5, make this request:

POST /api/orders?order[line_items][0][variant_id]=1&order[line_items][0][quantity]=5

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"
    ]
  }
}

Update Address

To add address information to an order, please see the checkout transitions section of the Checkouts guide.

Empty

To empty an order's cart, make this request:

PUT /api/orders/R1234567/empty

All line items will be removed from the cart and the order's information will be cleared. Inventory that was previously depleted by this order will be repleted.