> For the complete documentation index, see [llms.txt](https://shiply-integration-apis.gitbook.io/shiply-integration-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://shiply-integration-apis.gitbook.io/shiply-integration-documentation/integration-apis/companion-parcels/create-companion-parcel.md).

# Create Companion Parcel

```php
POST /parcels/companion 
```

This API is used to create a companion parcel for an existing parcel.

#### Headers

<table><thead><tr><th width="374">Key</th><th>Value</th></tr></thead><tbody><tr><td>Accept</td><td>application/json</td></tr><tr><td>Content-Type</td><td>application/json</td></tr></tbody></table>

#### Request body

Request parameters:

<table><thead><tr><th width="183">Field Name</th><th width="104">Required</th><th width="93">Type</th><th>Notes</th></tr></thead><tbody><tr><td>parcel_id</td><td>yes</td><td>integer</td><td>This refers to the <mark style="color:blue;">parcel_code</mark> of the parent parcel.</td></tr><tr><td>qr_code</td><td>no</td><td>string</td><td>This is the QR code to be assigned to the companion parcel.</td></tr><tr><td>qr_hash</td><td>no</td><td>string</td><td></td></tr><tr><td>description</td><td>no</td><td>string</td><td>Maximum of 500 characters.</td></tr><tr><td>length</td><td>no</td><td>integer</td><td></td></tr><tr><td>height</td><td>no</td><td>integer</td><td></td></tr><tr><td>width</td><td>no</td><td>integer</td><td></td></tr><tr><td>weight</td><td>no</td><td>numeric</td><td></td></tr></tbody></table>

Request body example:

{% code lineNumbers="true" %}

```json
{
    "parcel_id": "asnf-000-4280034",
    "description": "test",
    "height":40,
    "width": 40,
    "length": 40,
    "Shiply_API_KEY": "your_api_key"
}
```

{% endcode %}

#### Response body

{% tabs %}
{% tab title="Success" %}
Status code: <mark style="color:green;">200 OK</mark>

{% code lineNumbers="true" %}

```json
{
    "success": true,
    "companion_parcel": {
        "qr_code": "",
        "qr_hash": "",
        "description": "test",
        "height": 40,
        "width": 40,
        "length": 40,
        "parcel_position_id": 1,
        "weight": null,
        "updated_at": "2024-11-16 16:38:14",
        "created_at": "2024-11-16 16:38:14",
        "id": 1905,
        "size": 64000
    }
}
```

{% endcode %}

The response includes a <mark style="color:blue;">companion\_parcel</mark> field, which contains the details of the newly created companion parcel.
{% endtab %}

{% tab title="Parcel not found" %}
Status code: <mark style="color:green;">200 OK</mark>

{% code lineNumbers="true" %}

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

{% endcode %}

This response is returned when:

* The user cannot access the parent parcel.
* The <mark style="color:blue;">parcel\_id</mark> provided in the request body not belongs to a created parcel.
  {% endtab %}

{% tab title="Cannot add companion parcel" %}
Status code: <mark style="color:green;">200 OK</mark>

{% code lineNumbers="true" %}

```json
{
    "success": false,
    "error": "cant add companion parcel for not draft or submitted parcel"
}
```

{% endcode %}

{% code lineNumbers="true" %}

```json
{
    "success": false,
    "error": "cant add companion parcel for [delivered, returned, finished] parcel"
}
```

{% endcode %}

This response is returned when:

* The <mark style="color:blue;">parcel\_id</mark> provided in the request body corresponds to a parcel that can no longer be edited (finished parcel, delivered parcel, returned parcel, not draft or submitted parcel).
  {% endtab %}

{% tab title="Companion parcels limit" %}
Status code: <mark style="color:green;">200 OK</mark>

{% code lineNumbers="true" %}

```json
{
    "success": false,
    "error": "exceed the limit for number of allowed companion parcels"
}
```

{% endcode %}

This response is returned when:

* The <mark style="color:blue;">parcel\_id</mark> provided in the request body corresponds to a parcel that has already reached the maximum allowed number of companion parcels.
  {% endtab %}

{% tab title="Size limit" %}
Status code: <mark style="color:green;">200 OK</mark>

{% code lineNumbers="true" %}

```json
{
    "success": false,
    "error": "أبعاد الطرد غير متناسبة"
}
```

{% endcode %}

This response is returned when:

* The dimensions (<mark style="color:blue;">height</mark>, <mark style="color:blue;">length</mark>, <mark style="color:blue;">width</mark>) provided in the request body are not valid or accepted.
  {% endtab %}

{% tab title="Fail" %}
Status code: <mark style="color:green;">200 OK</mark>

{% code lineNumbers="true" %}

```json
{
    "success": false,
    "error": "error while adding companion parcel"
}
```

{% endcode %}

This response is returned when a database error occurs while attempting to add a companion parcel.
{% endtab %}

{% tab title="Unauthorized" %}
Status code: <mark style="color:green;">200 OK</mark>

{% code lineNumbers="true" %}

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

{% endcode %}

This response is returned when the <mark style="color:blue;">Shiply\_API\_KEY</mark> is not included in the request body.
{% endtab %}
{% endtabs %}