Shipments API

Mine

Retrieve a list of the current user’s shipments by making this request:

GET /api/v1/shipments/mine

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

GET /api/v1/shipments/mine?page=2

Parameters

page
The page number of shipments to display.
per_page
The number of shipments to return per page.

Response

Status: 200 OK
{
  "shipments": [
    {
      "id": 1,
      "tracking": null,
      "number": "H123456789",
      "cost": "5.0",
      "shipped_at": null,
      "state": "pending",
      "selected_shipping_rate": {
        "id": 1,
        "name": "UPS Ground (USD)",
        "cost": 5,
        "selected": true,
        "shipping_method_id": 5,
        "shipping_method_code": null,
        "display_cost": "$5.00"
      },
      "inventory_units": [
        {
          "id": 1,
          "state": "on_hand",
          "variant_id": 1,
          "shipment_id": 1,
          "variant": {
            "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
          },
          "line_item": {
            "id": 1,
            "quantity": 2,
            "price": "19.99",
            "variant_id": 1,
            "single_display_amount": "$19.99",
            "display_total": "$39.99",
            "total": "39.99"
          }
        }
      ],
      "order": {
        "id": 1,
        "number": "R335381310",
        "item_total": "100.0",
        "total": "100.0",
        "ship_total": "0.0",
        "state": "payment",
        "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,
        "channel": "spree",
        "included_tax_total": "0.0",
        "additional_tax_total": "0.0",
        "display_included_tax_total": "$0.0",
        "display_additional_tax_total": "$0.0",
        "tax_total": "0.0",
        "currency": "USD",
        "considered_risky": false,
        "canceler_id": null,
        "display_item_total": "$100.00",
        "total_quantity": 1,
        "display_total": "$100.00",
        "display_ship_total": "$0.00",
        "display_tax_total": "$0.00",
        "display_adjustment_total": "$0.00",
        "token": "abcdef123456",
        "checkout_steps": [
          "address,",
          "delivery",
          "complete"
        ],
        "bill_address": {
          "id": 1,
          "firstname": "Spree",
          "lastname": "Commerce",
          "full_name": "Spree Commerce",
          "address1": "1 Someplace Lane",
          "address2": "Suite 1",
          "city": "Bethesda",
          "zipcode": "16804",
          "phone": "123.4567.890",
          "company": null,
          "alternative_phone": null,
          "country_id": 1,
          "state_id": 1,
          "state_name": null,
          "state_text": "NY",
          "country": {
            "id": 1,
            "iso_name": "UNITED STATES",
            "iso": "US",
            "iso3": "USA",
            "name": "United States",
            "numcode": 1
          },
          "state": {
            "id": 1,
            "name": "New York",
            "abbr": "NY",
            "country_id": 1
          }
        },
        "ship_address": {
          "id": 1,
          "firstname": "Spree",
          "lastname": "Commerce",
          "full_name": "Spree Commerce",
          "address1": "1 Someplace Lane",
          "address2": "Suite 1",
          "city": "Bethesda",
          "zipcode": "16804",
          "phone": "123.4567.890",
          "company": null,
          "alternative_phone": null,
          "country_id": 1,
          "state_id": 1,
          "state_name": null,
          "state_text": "NY",
          "country": {
            "id": 1,
            "iso_name": "UNITED STATES",
            "iso": "US",
            "iso3": "USA",
            "name": "United States",
            "numcode": 1
          },
          "state": {
            "id": 1,
            "name": "New York",
            "abbr": "NY",
            "country_id": 1
          }
        },
        "adjustments": [

        ],
        "payments": [
          {
            "id": 1,
            "source_type": "Spree::CreditCard",
            "source_id": 1,
            "amount": "10.00",
            "display_amount": "$10.00",
            "payment_method_id": 1,
            "state": "checkout",
            "avs_response": null,
            "created_at": "2012-10-24T23:26:23Z",
            "updated_at": "2012-10-24T23:26:23Z",
            "number": "P58PJCXG"
          }
        ]
      }
    }
  ],
  "count": 25,
  "current_page": 1,
  "pages": 5
}

Create

This action is only accessible by an admin user.

The following attributes are required when creating a shipment:

  • order_id
  • stock_location_id
  • variant_id

To create a shipment, make a request like this:

POST /api/v1/shipments?shipment[order_id]=R123456789

The order_id is the number of the order to create a shipment for and is provided as part of the URL string as shown above. The shipment will be created at the selected stock location and include the variant selected.

Assuming in this instance that you want to create a shipment with a stock_location_id of 1 and a variant_id of 10 for order R1234567, send through the parameters like this:

{
  "order_id": "R1234567",
  "stock_location_id": 1,
  "variant_id": 10
}

Response

Status: 200 OK
{
  "id": 1,
  "tracking": null,
  "number": "H71047039332",
  "cost": "5.0",
  "shipped_at": null,
  "state": "pending",
  "shipping_rates": [
    {
      "id": 1,
      "name": "UPS Ground (USD)",
      "cost": 5,
      "selected": true,
      "shipping_method_id": 5,
      "shipping_method_code": null,
      "display_cost": "$5.00"
    }
  ],
  "selected_shipping_rate": [
    {
      "id": 1,
      "name": "UPS Ground (USD)",
      "cost": 5,
      "selected": true,
      "shipping_method_id": 5,
      "shipping_method_code": null,
      "display_cost": "$5.00"
    }
  ],
  "shipping_methods": [
    {
      "id": 1,
      "code": null,
      "name": "UPS Ground",
      "zones": [
        {
          "id": 1,
          "name": "America",
          "description": "The US",
          "zone_members": [
            {
              "id": 1,
              "zoneable_type": "Spree::Country",
              "zoneable_id": 1
            }
          ]
        }
      ],
      "shipping_categories": [
        {
          "id": 1,
          "name": "Defaukt category"
        }
      ]
    }
  ],
  "manifest": [
    {
      "variant": {
        "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
      },
      "quantity": 1,
      "states": {
        "on_hand": 1
      }
    }
  ],
  "order_id": 1,
  "stock_location_name": "default"
}

Update

This action is only accessible by an admin user.

To update shipment information, make a request like this:

PUT /api/v1/shipments/H123456789?shipment[tracking]=TRK9000

To update order ship method inspect order/shipments/shipping_rates for available shipping_rate_id values and use following api call:

PUT /api/v1/shipments/H123456789?shipment[selected_shipping_rate_id]=1

Response

Status: 200 OK
{
  "id": 1,
  "tracking": null,
  "number": "H71047039332",
  "cost": "5.0",
  "shipped_at": null,
  "state": "pending",
  "shipping_rates": [
    {
      "id": 1,
      "name": "UPS Ground (USD)",
      "cost": 5,
      "selected": true,
      "shipping_method_id": 5,
      "shipping_method_code": null,
      "display_cost": "$5.00"
    }
  ],
  "selected_shipping_rate": [
    {
      "id": 1,
      "name": "UPS Ground (USD)",
      "cost": 5,
      "selected": true,
      "shipping_method_id": 5,
      "shipping_method_code": null,
      "display_cost": "$5.00"
    }
  ],
  "shipping_methods": [
    {
      "id": 1,
      "code": null,
      "name": "UPS Ground",
      "zones": [
        {
          "id": 1,
          "name": "America",
          "description": "The US",
          "zone_members": [
            {
              "id": 1,
              "zoneable_type": "Spree::Country",
              "zoneable_id": 1
            }
          ]
        }
      ],
      "shipping_categories": [
        {
          "id": 1,
          "name": "Defaukt category"
        }
      ]
    }
  ],
  "manifest": [
    {
      "variant": {
        "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
      },
      "quantity": 1,
      "states": {
        "on_hand": 1
      }
    }
  ],
  "order_id": 1,
  "stock_location_name": "default"
}

Ready

This action is only accessible by an admin user.

To mark a shipment as ready, make a request like this:

PUT /api/v1/shipments/H123456789/ready

You may choose to update shipment attributes with this request as well:

PUT /api/v1/shipments/H123456789/ready?shipment[number]=1234567

Response

Status: 200 OK
{
  "id": 1,
  "tracking": null,
  "number": "H71047039332",
  "cost": "5.0",
  "shipped_at": null,
  "state": "ready",
  "shipping_rates": [
    {
      "id": 1,
      "name": "UPS Ground (USD)",
      "cost": 5,
      "selected": true,
      "shipping_method_id": 5,
      "shipping_method_code": null,
      "display_cost": "$5.00"
    }
  ],
  "selected_shipping_rate": [
    {
      "id": 1,
      "name": "UPS Ground (USD)",
      "cost": 5,
      "selected": true,
      "shipping_method_id": 5,
      "shipping_method_code": null,
      "display_cost": "$5.00"
    }
  ],
  "shipping_methods": [
    {
      "id": 1,
      "code": null,
      "name": "UPS Ground",
      "zones": [
        {
          "id": 1,
          "name": "America",
          "description": "The US",
          "zone_members": [
            {
              "id": 1,
              "zoneable_type": "Spree::Country",
              "zoneable_id": 1
            }
          ]
        }
      ],
      "shipping_categories": [
        {
          "id": 1,
          "name": "Defaukt category"
        }
      ]
    }
  ],
  "manifest": [
    {
      "variant": {
        "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
      },
      "quantity": 1,
      "states": {
        "on_hand": 1
      }
    }
  ],
  "order_id": 1,
  "stock_location_name": "default"
}

Ship

This action is only accessible by an admin user.

To mark a shipment as shipped, make a request like this:

PUT /api/v1/shipments/H123456789/ship

You may choose to update shipment attributes with this request as well:

PUT /api/v1/shipments/H123456789/ship?shipment[tracking]=1234567

Response

Status: 200 OK
{
  "id": 1,
  "tracking": null,
  "number": "H71047039332",
  "cost": "5.0",
  "shipped_at": null,
  "state": "shipped",
  "shipping_rates": [
    {
      "id": 1,
      "name": "UPS Ground (USD)",
      "cost": 5,
      "selected": true,
      "shipping_method_id": 5,
      "shipping_method_code": null,
      "display_cost": "$5.00"
    }
  ],
  "selected_shipping_rate": [
    {
      "id": 1,
      "name": "UPS Ground (USD)",
      "cost": 5,
      "selected": true,
      "shipping_method_id": 5,
      "shipping_method_code": null,
      "display_cost": "$5.00"
    }
  ],
  "shipping_methods": [
    {
      "id": 1,
      "code": null,
      "name": "UPS Ground",
      "zones": [
        {
          "id": 1,
          "name": "America",
          "description": "The US",
          "zone_members": [
            {
              "id": 1,
              "zoneable_type": "Spree::Country",
              "zoneable_id": 1
            }
          ]
        }
      ],
      "shipping_categories": [
        {
          "id": 1,
          "name": "Defaukt category"
        }
      ]
    }
  ],
  "manifest": [
    {
      "variant": {
        "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
      },
      "quantity": 1,
      "states": {
        "on_hand": 1
      }
    }
  ],
  "order_id": 1,
  "stock_location_name": "default"
}

Add Variant

This action is only accessible by an admin user.

To add a variant to a shipment, make a request like this:

PUT /api/v1/shipments/H123456789/add
{
  "order_id": 123456,
  "stock_location_id": 1,
  "variant_id": 10
}

Response

Status: 200 OK
{
  "id": 1,
  "tracking": null,
  "number": "H71047039332",
  "cost": "5.0",
  "shipped_at": null,
  "state": "pending",
  "shipping_rates": [
    {
      "id": 1,
      "name": "UPS Ground (USD)",
      "cost": 5,
      "selected": true,
      "shipping_method_id": 5,
      "shipping_method_code": null,
      "display_cost": "$5.00"
    }
  ],
  "selected_shipping_rate": [
    {
      "id": 1,
      "name": "UPS Ground (USD)",
      "cost": 5,
      "selected": true,
      "shipping_method_id": 5,
      "shipping_method_code": null,
      "display_cost": "$5.00"
    }
  ],
  "shipping_methods": [
    {
      "id": 1,
      "code": null,
      "name": "UPS Ground",
      "zones": [
        {
          "id": 1,
          "name": "America",
          "description": "The US",
          "zone_members": [
            {
              "id": 1,
              "zoneable_type": "Spree::Country",
              "zoneable_id": 1
            }
          ]
        }
      ],
      "shipping_categories": [
        {
          "id": 1,
          "name": "Defaukt category"
        }
      ]
    }
  ],
  "manifest": [
    {
      "variant": {
        "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
      },
      "quantity": 1,
      "states": {
        "on_hand": 1
      }
    }
  ],
  "order_id": 1,
  "stock_location_name": "default"
}

Remove Variant

This action is only accessible by an admin user.

To remove a variant from a shipment, make a request like this:

PUT /api/v1/shipments/H123456789/remove?variant_id=1&quantity=1

Response

Status: 200 OK
{
  "id": 1,
  "tracking": null,
  "number": "H71047039332",
  "cost": "5.0",
  "shipped_at": null,
  "state": "pending",
  "shipping_rates": [
    {
      "id": 1,
      "name": "UPS Ground (USD)",
      "cost": 5,
      "selected": true,
      "shipping_method_id": 5,
      "shipping_method_code": null,
      "display_cost": "$5.00"
    }
  ],
  "selected_shipping_rate": [
    {
      "id": 1,
      "name": "UPS Ground (USD)",
      "cost": 5,
      "selected": true,
      "shipping_method_id": 5,
      "shipping_method_code": null,
      "display_cost": "$5.00"
    }
  ],
  "shipping_methods": [
    {
      "id": 1,
      "code": null,
      "name": "UPS Ground",
      "zones": [
        {
          "id": 1,
          "name": "America",
          "description": "The US",
          "zone_members": [
            {
              "id": 1,
              "zoneable_type": "Spree::Country",
              "zoneable_id": 1
            }
          ]
        }
      ],
      "shipping_categories": [
        {
          "id": 1,
          "name": "Defaukt category"
        }
      ]
    }
  ],
  "manifest": [
    {
      "variant": {
        "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
      },
      "quantity": 1,
      "states": {
        "on_hand": 1
      }
    }
  ],
  "order_id": 1,
  "stock_location_name": "default"
}