# Shipments

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

A shipment represents physical fulfillment of a number of items after an order is placed. Shipments contain information about items being fulfilled, and shipping details such as address and tracking number.

## The shipment model

### Fields

- `id` (objectId): Unique identifier for the shipment.
- `items` (array of object, required): List of line items describing the products shipped.
  - `id` (objectId, auto): Unique identifier for the shipment item.
  - `order_item_id` (objectId): ID of the order item shipped.
  - `product_id` (objectId, required): ID of the item product.
  - `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.
  - `product` (product): Expandable link to the item product.
  - `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.
- `order_id` (objectId, required): The id of the order this shipment was created for.
- `canceled` (boolean): Indicates the shipment was canceled.
- `carrier` (string): The id of a third-party carrier offering the service, if applicable.
- `carrier_name` (string): Name of a third-party carrier offering the service, if applicable.
- `date_created` (date, auto): Date and time the shipment was created.
- `date_estimated` (date): Date the expected shipment is meant to arrive at the destination, if applicable.
- `date_updated` (date, auto): Date and time the shipment was last updated.
- `destination` (object): The customer's shipping address.
  - `name` (string, required): Destination customer name.
  - `address1` (string, required): Destination address line 1: street address/PO box/company name.
  - `address2` (string): Destination address line 2: apartment/suite/unit/building.
  - `country` (string, required): Two-letter ISO code country code.
  - `city` (string): Destination city/district/suburb/town/village.
  - `state` (string): Destination state/county/province/region.
  - `zip` (string): Destination zip/postal code.
  - `phone` (string): Destination phone number.
- `draft` (boolean): Indicates the shipment is a draft.
- `notes` (string): Internal admin notes, not visible to the customer.
- `notifications` (Notification): Expandable list of notifications sent on behalf of the shipment.
- `number` (string, auto): Unique incremental shipment number, assigned automatically.
- `order` (Order): Expandable link to the order.
- `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): The id of a shipping service as configured in shipment settings.
- `service_name` (string): Name of the shipping service.
- `tracking_code` (string): Tracking code used to identify the shipment, if applicable.
- `label` (object): The order’s shipping label.
  - `date_created` (date, auto): Date and time the label was created.
  - `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.
    - `id` (objectId, required): Unique identifier for the image.
    - `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, required): A reference to the raw image data.
    - `private` (boolean): Indicates the image is not visible to customers.
    - `url` (string, required): 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 response

```json
{
  "id": "60f199509111e70000000089",
  "items": [
    {
      "id": "5ca537326a0ec32a521139dd",
      "order_item_id": null,
      "product_id": "5cad15bc9b14d1990724663b",
      "quantity": 2
    }
  ],
  "order_id": "60f199509111e7000000008b",
  "date_created": "2021-07-16T14:36:00.413Z",
  "date_updated": "2021-07-16T14:36:00.413Z",
  "destination": {
    "name": "Hieronymus Lex",
    "address1": "South Watch Tower, Captain's Quarters",
    "city": "Imperial City",
    "state": "NY",
    "zip": 11201,
    "country": "US",
    "phone": "(555) 555-5555"
  },
  "service": "imperial_express",
  "tracking_code": "T192000000XYZ"
}
```


## 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",
  ...
}
```


## Update a shipment

Update an existing shipment using the ID that was obtained when it was created.

### Arguments

- `id` (objectId, required): Unique identifier for the shipment.
- `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.
- `order` (Order): Expandable link to the order.
- `tracking_code` (string): Tracking code used to identify the shipment, if applicable.
- `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.
    - `id` (objectId, required): Unique identifier for the image.
    - `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

`PUT /shipments/:id`

**cURL**

```bash
$ curl https://api.swell.store/shipments/60f199509111e70000000089 \
  -u store-id:secret-key \
  -d tracking_code=T192000000XYZ \
  -X PUT
```

**Node**

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

await swell.put('/shipments/{id}', {
  id: '60f199509111e70000000089',
  tracking_code: 'T192000000XYZ'
});
```

**PHP**

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

$swell->put('/shipments/{id}', [
  'id' => '60f199509111e70000000089',
  'tracking_code' => 'T192000000XYZ'
]);
```

### Example response

```json
{
  "id": "60f199509111e70000000089",
  "items": [
    {
      "id": "5ca537326a0ec32a521139dd",
      "order_item_id": null,
      "product_id": "5cad15bc9b14d1990724663b",
      "quantity": 2
    }
  ],
  "order_id": "60f199509111e7000000008e",
  "date_created": "2021-07-16T14:36:00.413Z",
  "date_updated": "2021-07-16T14:36:00.413Z",
  "destination": {
    "name": "Jon Snow",
    "address1": "1 Main Street",
    "city": "Brooklyn",
    "state": "NY",
    "zip": 11201,
    "country": "US",
    "phone": "(555) 555-5555"
  },
  "service": "fedex_ground",
  "tracking_code": "T192000000XYZ"
}
```


## Retrieve a shipment

### Arguments

- `id` (objectId, required): The id of the shipment to retrieve.
- `expand` (string): Expanding link fields and child collections is performed using the expand argument.

  - For example, `expand=account` would return a related customer account if one exists.

  When the field represents a collection, you can specify the query limit.

  - For example, `expand=variants:10` would return up to 10 records of the variants collection.

  See [expanding ](https://developers.swell.is/backend-api/querying/expanding)for more details.
- `fields` (string): Return only the specified fields in the result. For example `fields=name,slug` would return only the fields `name` and `slug` in the response. Supports nested object and array fields using dot-notation, for example, `items.product_id`. The category `id` is always returned.
- `include` (string): Include one or more arbitrary queries in the response, possibly related to the main query.

  See [including ](https://developers.swell.is/backend-api/querying/including)for more details.

### Example request

`GET /shipments/:id`

**cURL**

```bash
$ curl https://api.swell.store/shipments/60f199509111e70000000094 \
  -u store-id:secret-key
```

**Node**

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

await swell.get('/shipments/{id}', {
  id: '60f199509111e70000000094'
});
```

**PHP**

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

$swell->get('/shipments/{id}', [
  'id' => '60f199509111e70000000094'
]);
```

### Example response

```json
{
  "id": "60f199509111e70000000094",
  "items": [
    {
      "id": "5ca537326a0ec32a521139dd",
      "order_item_id": null,
      "product_id": "5cad15bc9b14d1990724663b",
      "quantity": 2
    }
  ],
  "order_id": "60f199509111e70000000095",
  "date_created": "2021-07-16T14:36:00.413Z",
  "date_updated": "2021-07-16T14:36:00.413Z",
  "destination": {
    "name": "Jon Snow",
    "address1": "1 Main Street",
    "city": "Brooklyn",
    "state": "NY",
    "zip": 11201,
    "country": "US",
    "phone": "(555) 555-5555"
  },
  "service": "fedex_ground",
  "tracking_code": "T192000000XYZ"
}
```


## List all shipments

Return a list of shipments.

### Arguments

- `expand` (string): Expand link fields and child collections by using the expand argument.

  - For example, `expand=account` would return a related customer account if one exists.

  When the field represents a collection, you can specify the query limit.

  - For example, `expand=variants:10` would return up to 10 records of the variants collection.

  See [expanding](https://developers.swell.is/backend-api/querying/expanding) for more details.
- `fields` (string): Returns only the specified fields in the result.

  - For example `fields=name,slug` would return only the fields `name` and `slug` in the response.

  Supports nested object and array fields using dot-notation.

  - For example, `items.product_id`. The product `id` is always returned.
- `include` (object): Include one or more arbitrary queries in the response which are potentially related to the main query.

  See [including](https://developers.swell.is/backend-api/querying/including) for more details.
- `limit` (int): Limit the number of records returned, ranging between `1` and `1000`. Defaults to `15`. Default: `15`.
- `page` (int): The page number of results to return given the specified or default `limit`.
- `search` (string): A text search is performed using the search argument. Searchable fields are defined by the model.

  - For example, `search=red` would return records containing the word "red" anywhere in the defined text fields.

  See [searching](https://developers.swell.is/backend-api/querying/searching) for more details.
- `sort` (string): Expression to sort results by using a format similar to a SQL sort statement.

  - For example, `sort=name asc` would return records sorted by name ascending.

  See [sorting](https://developers.swell.is/backend-api/querying/sorting) for more details.
- `where` (object): An object with criteria to filter the result.

  - For example, `active=true` would return records containing a field `active` with the value `true`.

  It's also possible to use query operators, for example, `$eq`, `$ne`, `$gt`, and more.

  See [querying](https://developers.swell.is/backend-api/querying) for more details.

### Example request

`GET /shipments`

**cURL**

```bash
$ curl https://api.swell.store/shipments?limit=25&page=1 \
  -u store-id:secret-key \
  -G
```

**Node**

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

await swell.get('/shipments', {
  limit: 25,
  page: 1
});
```

**PHP**

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

$swell->get('/shipments', [
  'limit' => 25,
  'page' => 1
]);
```

### Example response

```json
{
  "count": 51,
  "results": [
    {
      "id": "60f199509111e70000000089",
      "items": [
        {
          "id": "5ca537326a0ec32a521139dd",
          "order_item_id": null,
          "product_id": "5cad15bc9b14d1990724663b",
          "quantity": 2
        }
      ],
      "order_id": "60f199509111e70000000099",
      "date_created": "2021-07-16T14:36:00.413Z",
      "date_updated": "2021-07-16T14:36:00.413Z",
      "destination": {
        "name": "Jon Snow",
        "address1": "1 Main Street",
        "city": "Brooklyn",
        "state": "NY",
        "zip": 11201,
        "country": "US",
        "phone": "(555) 555-5555"
      },
      "service": "fedex_ground",
      "tracking_code": "T192000000XYZ"
    },
    {...},
    {...}
  ],
  "page": 1,
  "page_count": 3,
  "limit": 25,
  "pages": {
    "1": {
      "start": 1,
      "end": 25
    },
    "2": {
      "start": 26,
      "end": 50
    },
    "3": {
      "start": 51,
      "end": 51
    }
  }
}
```