Shipments
Mine
Retrieve a list of the current user’s shipments by making this request:
GET /api/v1/shipments/mineShipments are paginated and can be iterated through by passing along a page parameter:
GET /api/v1/shipments/mine?page=2Parameters
- page:
The page number of shipments to display.
- per_page:
The number of shipments to return per page.
Response
Status:
200 OK
[{"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,"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,"product_id": 1},"adjustments": [],"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"}]}}]
Create
This action is only accessible by an admin user.
The following attributes are required when creating a shipment:
- order_id
- stocklocationid
- variant_id
To create a shipment, make a request like this:
POST /api/v1/shipments?shipment[order_id]=R123456789The 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 stocklocationid 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": "Default 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]=TRK9000To update order ship method inspect order/shipments/shippingrates for available shippingrate_id values and use following api call:
PUT /api/v1/shipments/H123456789?shipment[selected_shipping_rate_id]=1Response
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": "Default 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/readyYou may choose to update shipment attributes with this request as well:
PUT /api/v1/shipments/H123456789/ready?shipment[number]=1234567Response
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": "Default 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/shipYou may choose to update shipment attributes with this request as well:
PUT /api/v1/shipments/H123456789/ship?shipment[tracking]=1234567Response
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": "Default 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": "Default 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=1Response
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": "Default 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"}