# Restocking Shipments

## The RestockingShipment resource

<table><thead><tr><th width="258">Property</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>barcode</td><td>String (read-only)</td><td>The barcode of the shipment</td></tr><tr><td>delivery_option<mark style="color:red;">*</mark></td><td>String</td><td>One of the following: <strong>postal</strong>, <strong>courier</strong>, <strong>dropoff</strong>, <strong>hive_freight</strong></td></tr><tr><td>estimated_arrival_date<mark style="color:red;">*</mark></td><td>ISO8601 date</td><td>Estimated arrival date</td></tr><tr><td>id</td><td>Integer (read-only)</td><td>Hive's unique identifier</td></tr><tr><td>po_number</td><td>String</td><td>Purchase order number</td></tr><tr><td>restocking_shipment_items</td><td>An array of <a href="#the-restockingshipmentitem-resource">RestockingShipmentItem</a> objects</td><td>A list of items in the shipment</td></tr><tr><td>status</td><td>String (read-only)</td><td><p>Possible values:</p><p><strong>shipped</strong> - initial status meaning that restocking shipment is on the way</p><p><strong>delivered</strong> - the restocking shipment is delivered to the fulfillment center, but its content is not verified yet</p><p><strong>arrived</strong> - Hive completed the arrival documentation, checked packing slip, picture of shipment and documents are uploaded</p><p><strong>processing</strong> - the restocking shipment is getting unpacked and its items are getting restocked into storage boxes and pallets</p><p><strong>restocked</strong> - the restocking shipment is fully processed in the fulfillment center and its items are completely restocked</p><p><strong>cancelled</strong> - the restocking shipment is cancelled by merchant</p></td></tr><tr><td>supplier_name</td><td>String</td><td>Supplier name</td></tr><tr><td>tracking_code</td><td>String</td><td>Shipment tracking code</td></tr><tr><td>warehouse_id<mark style="color:red;">*</mark></td><td>Integer</td><td>The ID of the Hive destination warehouse</td></tr></tbody></table>

## The RestockingShipmentItem resource

<table><thead><tr><th width="209">Property</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>announced_quantity</td><td>Integer</td><td>Quantity of this item in the shipment</td></tr><tr><td>arrived_quantity</td><td>Integer  (read-only)</td><td>Arrived quantity of this item (after shipment is received)</td></tr><tr><td>damaged_quantity</td><td>Integer  (read-only)</td><td>Damaged quantity of this item (after shipment is received)</td></tr><tr><td>id</td><td>Integer  (read-only)</td><td>Hive's unique identifier</td></tr><tr><td>inventory_batches</td><td>A RestockingShipmentInventoryBatch object</td><td>Batches of this item included in the shipment</td></tr><tr><td>merchant_sku_id</td><td>String</td><td>The merchant's SKU identifier - required if <code>sku_id</code> is not provided</td></tr><tr><td>missing_quantity</td><td>Integer  (read-only)</td><td>Missing quantity of this item (after shipment is received)</td></tr><tr><td>remarks</td><td>String</td><td>Free text for remarks</td></tr><tr><td>sku_id</td><td>Integer</td><td>Hive SKU identifier - required if <code>merchant_sku_id</code> is not provided</td></tr><tr><td>total_cost_in_cents</td><td>Integer</td><td>Cost in cents</td></tr></tbody></table>

## The RestockingShipmentInventoryBatch resource

<table><thead><tr><th width="193">Property</th><th width="218">Type</th><th>Description</th></tr></thead><tbody><tr><td>arrived_quantity</td><td>Integer (read-only)</td><td>Arrived quantity of this batch (after shipment is received)</td></tr><tr><td>expiry_date</td><td>ISO8601 date (read-only)</td><td>Expiration date of the batch</td></tr><tr><td>id</td><td>Integer (read-only)</td><td>Hive's unique identifier</td></tr><tr><td>name</td><td>String (read-only)</td><td>Batch name</td></tr><tr><td>tracking_code</td><td>String (read-only)</td><td>Batch tracking code</td></tr></tbody></table>

{% hint style="info" %} <mark style="color:red;">\*</mark>Required properties when creating a new record.
{% endhint %}

## List all restocking shipments

## List all Restocking Shipments

<mark style="color:blue;">`GET`</mark> `https://app.hive.app/merchant_api/v1/restocking_shipments`

Returns restocking shipments ordered by descending creation time.

{% tabs %}
{% tab title="200: OK " %}
note: `arrived_quantity`, `damaged_quantity` and `missing_quantity` are visible only if the status is `restocked`

```json
{
  "data": [
    {
      "id": 13,
      "merchant_id": 1,
      "warehouse_id": 71,
      "estimated_arrival_date": "2022-12-01",
      "delivery_option": "postal",
      "tracking_code": "1234567",
      "po_number": null,
      "supplier_name": null,
      "status": "restocked",
      "barcode": "RS.13",
      "restocking_shipment_items": [
        {
          "id": 15,
          "sku_id": 558,
          "announced_quantity": 10,
          "arrived_quantity": 2,
          "damaged_quantity": 1,
          "missing_quantity": 7,
          "remarks": null,
          "total_cost_in_cents": null,
          "inventory_batches": [
            {
              "id": 827,
              "name": "Morph II - 827",
              "tracking_code": "A01234",
              "expiry_date": "2023-12-30",
              "arrived_quantity": 3
            },
            {
              "id": 828,
              "name": "Morph II - 828",
              "tracking_code": "B56789",
              "expiry_date": "2024-02-15",
              "arrived_quantity": 1
            }
          ]
        }
      ]
    }
  ],
  "pagination": {
    "current_page": 1,
    "item_count": 1,
    "page_count": 1,
    "items_per_page": 20
  }
}
```

{% endtab %}
{% endtabs %}

## Get one restocking shipment

## Get one restocking shipment

<mark style="color:blue;">`GET`</mark> `https://app.hive.app/merchant_api/v1/restocking_shipments/{id}`

#### Path Parameters

| Name                                 | Type   | Description                              |
| ------------------------------------ | ------ | ---------------------------------------- |
| id<mark style="color:red;">\*</mark> | String | The (Hive) ID of the restocking shipment |

{% tabs %}
{% tab title="200: OK " %}

```json
{
  "id": 13,
  "merchant_id": 1,
  "warehouse_id": 71,
  "estimated_arrival_date": "2022-12-01",
  "delivery_option": "postal",
  "tracking_code": "1234567",
  "po_number": null,
  "supplier_name": null,
  "status": "shipped",
  "barcode": "RS.13",
  "restocking_shipment_items": [
    {
      "id": 15,
      "sku_id": 558,
      "announced_quantity": 10,
      "arrived_quantity": 2,
      "damaged_quantity": 1,
      "missing_quantity": 7,
      "remarks": null,
      "total_cost_in_cents": null,
      "inventory_batches": [
        {
          "id": 827,
          "name": "Morph II - 827",
          "tracking_code": "A01234",
          "expiry_date": "2023-12-30",
          "arrived_quantity": 3
        },
        {
          "id": 828,
          "name": "Morph II - 828",
          "tracking_code": "B56789",
          "expiry_date": "2024-02-15",
          "arrived_quantity": 1
        }
      ]
    }
  ]
}
```

{% endtab %}

{% tab title="404: Not Found There was no restocking shipment matching the given ID" %}

```json
{
  "success": false,
  "errors": [
    "record not found"
  ]
}
```

{% endtab %}
{% endtabs %}

## Create a new restocking shipment

## Creates a new restocking shipment

<mark style="color:green;">`POST`</mark> `https://app.hive.app/merchant_api/v1/restocking_shipments/`

#### Request Body

| Name                                                                              | Type             | Description                                                                         |
| --------------------------------------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------------- |
| warehouse\_id<mark style="color:red;">\*</mark>                                   | Integer          | An ID that uniquely identifies the warehouse                                        |
| estimated\_arrival\_date<mark style="color:red;">\*</mark>                        | ISO8601 datetime | The estimated arrival date                                                          |
| delivery\_option<mark style="color:red;">\*</mark>                                | String           | The delivery option, must be one of: `postal`, `courier`, `dropoff`, `hive_freight` |
| tracking\_code                                                                    | String           | The shipment tracking code                                                          |
| po\_number                                                                        | String           | The po number                                                                       |
| supplier\_name                                                                    | String           | The supplier name                                                                   |
| restocking\_shipment\_items.sku\_id<mark style="color:red;">\*</mark>             | Integer          | The (Hive) ID of the sku                                                            |
| restocking\_shipment\_items.announced\_quantity<mark style="color:red;">\*</mark> | Integer          | The sku quantity                                                                    |
| restocking\_shipment\_items.remarks                                               | String           | The remarks                                                                         |
| restocking\_shipment\_items.total\_cost\_in\_cents                                | Integer          | The total cost in cents of the                                                      |

{% tabs %}
{% tab title="201: Created The restocking shipment was created successfully" %}

```json
{
    "id": 16,
    "merchant_id": 1,
    "warehouse_id": 71,
    "estimated_arrival_date": "2022-12-01",
    "delivery_option": "postal",
    "tracking_code": null,
    "po_number": null,
    "supplier_name": null,
    "status": "shipped",
    "barcode": "RS.16",
    "restocking_shipment_items": [
        {
            "id": 18,
            "sku_id": 558,
            "announced_quantity": 12,
            "remarks": null,
            "total_cost_in_cents": null
        }
    ]
}
```

{% endtab %}

{% tab title="400: Bad Request The request was malformed" %}

```json
{
  "success": false,
  "errors": [
    "bad request"
  ]
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity The data was invalid" %}

```json
{
    "success": false,
    "errors": [
        "Warehouse can't be blank"
    ]
}
```

{% endtab %}
{% endtabs %}

## Update a restocking shipment

## Update a restocking shipment

<mark style="color:orange;">`PUT`</mark> `https://app.hive.app/merchant_api/v1/restocking_shipments/{id}/`

Replaces the whole resource. \
The restocking shipment can be updated only if the status is `shipped` or `created`

#### Path Parameters

| Name                                 | Type    | Description                              |
| ------------------------------------ | ------- | ---------------------------------------- |
| id<mark style="color:red;">\*</mark> | Integer | The (Hive) ID of the restocking shipment |

#### Request Body

| Name                                                                              | Type             | Description                                                                         |
| --------------------------------------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------------- |
| warehouse\_id<mark style="color:red;">\*</mark>                                   | Integer          | An ID that uniquely identifies the wharehouse                                       |
| estimated\_arrival\_date<mark style="color:red;">\*</mark>                        | ISO8601 datetime | The estimated arrival date                                                          |
| delivery\_option<mark style="color:red;">\*</mark>                                | String           | The delivery option, must be one of: `postal`, `courier`, `dropoff`, `hive_freight` |
| tracking\_code                                                                    | String           | The shipment tracking code                                                          |
| po\_number                                                                        | String           | The po number                                                                       |
| supplier\_name                                                                    | String           | The supplier name                                                                   |
| restocking\_shipment\_items.sku\_id<mark style="color:red;">\*</mark>             | Integer          | The (Hive) ID of the sku                                                            |
| restocking\_shipment\_items.announced\_quantity<mark style="color:red;">\*</mark> | Integer          | The sku quantity                                                                    |
| restocking\_shipment\_items.remarks                                               | String           | The remarks                                                                         |
| restocking\_shipment\_items.total\_cost\_in\_cents                                | Integer          | The total cost in cents of the                                                      |

{% tabs %}
{% tab title="200: OK The restocking shipment was updated successfully" %}

```json
{
    "id": 16,
    "merchant_id": 1,
    "warehouse_id": 71,
    "estimated_arrival_date": "2022-12-01",
    "delivery_option": "postal",
    "tracking_code": null,
    "po_number": null,
    "supplier_name": null,
    "status": "shipped",
    "barcode": "RS.16",
    "restocking_shipment_items": [
        {
            "id": 18,
            "sku_id": 558,
            "announced_quantity": 12,
            "remarks": null,
            "total_cost_in_cents": null
        }
    ]
}
```

{% endtab %}

{% tab title="400: Bad Request The request was malformed" %}

```json
{
  "success": false,
  "errors": [
    "bad request"
  ]
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity The data was invalid" %}

```json
{
    "success": false,
    "errors": [
        "Warehouse can't be blank"
    ]
}
```

{% endtab %}
{% endtabs %}

## Cancel a restocking shipment

## Cancel a restocking shipment

<mark style="color:orange;">`PUT`</mark> `https://app.hive.app/merchant_api/v1/restocking_shipments/{id}/cancel`

The restocking shipment can be canceled only if the status is `shipped` or `created`

#### Query Parameters

| Name                                 | Type    | Description                              |
| ------------------------------------ | ------- | ---------------------------------------- |
| id<mark style="color:red;">\*</mark> | Integer | The (Hive) ID of the restocking shipment |

{% tabs %}
{% tab title="200: OK The restocking shipment was canceled successfully" %}

{% endtab %}

{% tab title="422: Unprocessable Entity The data was invalid" %}

```json
{
    "success": false,
    "errors": [
        "Cannot cancel a restocking shipment with status arrived"
    ]
}
```

{% endtab %}
{% endtabs %}