# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.hive.app/reference/api-reference/restocking-shipments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.