APIDeveloperUserRelease NotesDemoContact Us
  • Api

    • Summary
    • Address
    • Checkouts
    • Countries
    • Customer Returns
    • Line Items
    • Option Types
    • Option Values
    • Orders
    • Payments
    • Product Images
    • Product Properties
    • Products
    • Return Authorizations
    • Shipments
    • States
    • Stock Items
    • Stock Locations
    • Stock Movements
    • Taxonomies
    • Users
    • Variants
    • Zones

Table Of Contents

MineParametersResponseCreateResponseUpdateResponseReadyResponseShipResponseAdd VariantResponseRemove VariantResponse

Shipments

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
[
{
"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]=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 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]=TRK9000

To 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]=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": "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/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": "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/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": "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=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": "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"
}
Propose changes to this page
Designed and developed bySpree Commerce & Ruby on Rails developers© Spree Commerce. 2021 All Rights Reserved.