Shipments API

Mine

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

GET /api/shipments/mine

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

GET /api/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
{
  "count": 25,
  "current_page": 1,
  "pages": 5,
  "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

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/shipments?shipment[order_id]=R1234567

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": 123456,
  "stock_location_id": 1,
  "variant_id": 10
}

Response

Status: 200 OK
{
  "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"
          }
        ]
      }
    }
  ]
}

Update

This action is only accessible by an admin user.

To update shipment information, make a request like this:

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

Parameters

unlock
When set to yes, the shipment’s adjustment will be recalculated.

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

PUT /api/shipments/H123456789?shipment[selected_shipping_rate_id]=162&shipment[unlock]=yes

Response

Status: 200 OK
{
  "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"
          }
        ]
      }
    }
  ]
}

Ready

This action is only accessible by an admin user.

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

PUT /api/shipments/H123456789/ready

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

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

Response

Status: 200 OK
{
  "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"
          }
        ]
      }
    }
  ]
}

Ship

This action is only accessible by an admin user.

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

PUT /api/shipments/H123456789/ship

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

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

Response

Status: 200 OK
{
  "id": 1,
  "tracking": "1234567",
  "number": "H123456789",
  "cost": "5.0",
  "shipped_at": "2012-10-24T01:02:25Z",
  "state": "shipped",
  "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"
          }
        ]
      }
    }
  ]
}

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/shipments/H123456789/add?variant_id=1&quantity=1

Response

Status: 200 OK
{
  "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"
          }
        ]
      }
    }
  ]
}

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/shipments/H123456789/remove?variant_id=1&quantity=1

Response

Status: 200 OK
{
  "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"
          }
        ]
      }
    }
  ]
}