# Create a shipment

Source: https://developers.swell.is/backend-api/shipments/create-a-shipment

Create a new shipment.

When fulfilling bundle items within a shipment, each item within the bundle will need to have shipment information added individually.

**Bundle item shipment example**

```json
POST /orders /60f199509111e7000000008b/shipments
{
  "id": null,
  "items": [
      {
        "id": null,
        "order_item_id": "5ca537326a0ec32a521139dd",
        "product_id": "628ba3c7499bba0019b1a961",
        "quantity": 1,
        "bundle_item_id": "90d80ebcec09e980012ef3c14"
      },
      {
        "id": null,
        "order_item_id": "5ca537326a0ec32a521139dd",
        "product_id": "628ba3c7499bba0019b1a962",
        "quantity": 1,
        "bundle_item_id": "90d80ebcec09e980012ef3c15"
      },
      {
       "id": null,
       "order_item_id": "5ca537326a0ec32a521139dd",
       "product_id": "628ba3c7499bba0019b1a94",
       "quantity": 10,
       "bundle_item_id": "90d80ebcec09e980012ef3c16"
      }
    ],
  "order_id": "60f199509111e7000000008b",
}
```

## Arguments

- `items` (array of object, required): List of line items describing the products shipped.
  - `order_item_id` (objectId): ID of the order item shipped.
  - `product_id` (objectId, required): ID of the item product.
  - `product` (product): Expandable link to the product item.
  - `bundle_item_id` (objectId): ID of the order bundle item shipped, if applicable.
  - `options` (array of object): Options from the order item shipped, if applicable.
    - `id` (string): Unique identifier for the object.
    - `name` (string): Name of the product option.
    - `value` (string): Name value of the product option.
  - `quantity` (int): Quantity of the item shipped. Defaults to 1. Default: `1`.
  - `variant_id` (objectId): ID of the item variant, if applicable.
  - `variant` (variant): Expandable link to the item variant, if applicable.
  - `id` (objectId, auto): Unique identifier for the shipment item.
- `order_id` (objectId, required): ID of the order this shipment was created for.
- `tracking_code` (string): Tracking code used to identify the shipment, if applicable.
- `order` (Order): Expandable link to the order.
- `canceled` (boolean): Indicates the shipment was canceled.
- `carrier` (string): ID of a 3rd party carrier offering the service, if applicable.
- `carrier_name` (string): Name of a 3rd party carrier offering the service, if applicable.
- `date_estimated` (date): Date the expected shipment is meant to arrive at the destination, if applicable.
- `destination` (object): The customer's shipping address.
  - `name` (string): Destination customer name.
  - `address1` (string): Destination address line 1: street address/PO box/company name.
  - `address2` (string): Destination address line 2: apartment/suite/unit/building.
  - `city` (string): Destination city/district/suburb/town/village.
  - `country` (string): Two-letter ISO code country code.
  - `phone` (string): Destination phone number.
  - `state` (string): Destination state/county/province/region.
  - `zip` (string): Destination zip/postal code.
- `notes` (string): Internal admin notes, not visible to the customer.
- `origin` (object): The shipment origin location.
  - `location` (string): ID of the origin location, if applicable. Default: `"default"`.
- `packages` (array of object): List of packages included in this shipment.
  - `height` (float): Height of the package in centimeters or inches.
  - `length` (float): Length of the package in centimeters or inches.
  - `type` (string): Type of package. This value can be enumerated, representing the types of packages used by the fulfillment provider.
  - `weight` (float): Weight of the package in the unit of the store's default (lb, oz, lb).
  - `width` (float): Width of the package in centimeters or inches.
- `service` (string): ID of a shipping service as configured in shipment settings.
- `service_name` (string): Name of the shipping service.
- `notifications` (Notification): Expandable list of notifications sent on behalf of the shipment.
- `number` (string, auto): Unique incremental shipment number, assigned automatically.
- `label` (object): The order’s shipping label.
  - `purchase` (boolean): When set to true, a shipment label will be purchased on-demand from the carrier. The carrier is set in label purchase settings.
  - `image` (object): An image of the shipment label, if present.
    - `date_uploaded` (date): Date the image was uploaded.
    - `length` (int): Size of the image in bytes.
    - `md5` (string): An MD5 hash of the image contents. This can be used to identify the image for caching purposes.
    - `filename` (string): Optional image name.
    - `content_type` (string): MIME content type of the image.
    - `metadata` (object): Arbitrary image data, typically used to store custom values. See Frontend API for more details.
    - `data` (filedata): A reference to the raw image data.
    - `private` (boolean): Indicates the image is not visible to customers.
    - `url` (string): A public URL to reference the image. Updated automatically if image content changes.
    - `width` (int): Image width in pixels, if applicable.
    - `height` (int): Image height in pixels, if applicable.
  - `date_purchased` (date)

## Example request

`POST /shipments`

**cURL**

```bash
$ curl https://api.swell.store/shipments \
  -u store-id:secret-key \
  -d order_id=5a9ea7ba3f95740a914267f1 \
  -d items[0][order_item_id]=5a9ea7ba3f95740a914267f2 \
  -d items[0][product_id]=5cad15bc9b14d1990724663a \
  -d items[0][quantity]=2 \
  -d tracking_code=T192000000XYZ
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.post('/shipments', {
  order_id: '5a9ea7ba3f95740a914267f1',
  items: [
    {
      order_item_id: '5a9ea7ba3f95740a914267f2',
      product_id: '5cad15bc9b14d1990724663a',
      quantity: 2,
    }
  ],
  tracking_code: 'T192000000XYZ',
});
```

**PHP**

```php
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->post('/shipments', [
  'order_id' => '5a9ea7ba3f95740a914267f1',
  'items' => [
    [
      'order_item_id' => '5a9ea7ba3f95740a914267f2',
      'product_id' => '5cad15bc9b14d1990724663a',
      'quantity' => 2,
    ]
  ],
  'tracking_code' => 'T192000000XYZ'
]);
```

## Example response

```json
{
  "id": "5cad15bc9b14d1990724663a",
  "number": "S10001",
  "order_id": "5a9ea7ba3f95740a914267f1",
  "items": [
    {
      "id": "5a9ea7ba3f95740a914267f2",
      "order_item_id": "5a9ea7ba3f95740a914267f2",
      "product_id": "5cad15bc9b14d1990724663b",
      "quantity": 2,
      ...
    }
  ],
  "tracking_code": "T192000000XYZ",
  ...
}
```