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