> 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/parcels/update-parcel.md).

# Update Parcel

```php
PUT /parcels/update/{parcel_id}
```

This API is used to update specific information about an existing parcel.

{% hint style="info" %}
**Note:** Replace <mark style="color:blue;">{parcel\_id}</mark> with the <mark style="color:blue;">parcel\_code</mark> of the parcel whose information you wish to update.
{% endhint %}

#### 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="218">Field Name</th><th width="99">Required</th><th width="93">Type</th><th width="311">Notes</th></tr></thead><tbody><tr><td>recipient.first_name</td><td>yes</td><td>string</td><td></td></tr><tr><td>recipient.phone</td><td>yes</td><td>string</td><td>Allowed formats: "xxxxxxxxx", "0xxxxxxxxx", "+970xxxxxxxxx", "+972xxxxxxxxx"</td></tr><tr><td>recipient.phone2</td><td>no</td><td>string</td><td>An additional phone number provided for the recipient.<br>Allowed formats: "xxxxxxxxx", "0xxxxxxxxx", "+970xxxxxxxxx", "+972xxxxxxxxx"</td></tr><tr><td>address.village_id</td><td>yes</td><td>integer</td><td>It must be a valid <strong>village</strong> id selected from the list retrieved by this API: <a data-mention href="/pages/j6HVoKWzCtpDxR104oGo">/pages/j6HVoKWzCtpDxR104oGo</a></td></tr><tr><td>address.street_name</td><td>yes</td><td>string</td><td></td></tr><tr><td>total_price</td><td>no</td><td>numeric</td><td>Includes: parcel price + delivery cost.<br><strong>Palestine:</strong> The number should be integer (without any decimal points).<br><strong>Jordan:</strong> The number can have up to 2 decimal points.</td></tr><tr><td>actual_price</td><td>no</td><td>numeric</td><td>Parcel price only. <br><strong>Palestine:</strong> The number should be integer (without any decimal points).<br><strong>Jordan:</strong> The number can have up to 2 decimal points.</td></tr><tr><td>description</td><td>yes</td><td>string</td><td>A minimum of 3 characters and a maximum of 255 characters.</td></tr><tr><td>note</td><td>no</td><td>string</td><td>Maximum of 1023 characters. </td></tr><tr><td>customer_private_note</td><td>no</td><td>string</td><td>Private note appears only for the customer.<br>Maximum of 2047 characters.</td></tr><tr><td>weight</td><td>no</td><td>numeric</td><td></td></tr><tr><td>length</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>height</td><td>no</td><td>integer</td><td></td></tr><tr><td>is_replacement</td><td>no</td><td>boolean</td><td>Used for return, replace and buy parcels. </td></tr><tr><td>planned_date</td><td>no</td><td>date</td><td><p>If want to set a specific delivery date for the parcel, set in format:</p><p>"YYYY-MM-DD".</p></td></tr><tr><td>reference_number</td><td>no</td><td>string</td><td>To link the parcel with order id (as example) in your system. </td></tr><tr><td>parcel_type</td><td>no</td><td>integer</td><td>Can be one of parcel types listed here <a data-mention href="/pages/ytyFxVNwUjYSuxIJIePJ">/pages/ytyFxVNwUjYSuxIJIePJ</a></td></tr><tr><td>extra_delivery_cost</td><td>no</td><td>numeric</td><td></td></tr><tr><td>is_completely_received</td><td>no</td><td>boolean</td><td>To indicate if the parcel content partially or completely received from the recipient.<br>If <strong>0 (false)</strong>: The recipient has partially received the items, meaning some were returned to the customer.<br>If <strong>1 (true)</strong>: The recipient has received all items in the parcel.<br><strong>Note:</strong> Its default value is true (if it is not set - null) </td></tr></tbody></table>

Request body example:

{% code lineNumbers="true" %}

```json
{
    "total_price": 150,
    "description":"طرد تجريبي",
    "note":"ملاحظة ",
    "recipient": {
        "first_name" : "First Name",
        "phone" : "0132654789"
    },
    "address": {
        "city_id" : 1,
        "village_id" : 105,
        "street_name" : "0132654789"
    },
    "length": 40,
    "width": 40,
    "height": 40,
    "planned_date": "2024-11-20",
    "is_replacement": "false",
    "Shiply_API_KEY": "your_api_key"
}
```

{% endcode %}

#### Response body

{% hint style="danger" %}
It may return the same errors as those returned when creating a parcel, along with the following additional errors.
{% endhint %}

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

{% code lineNumbers="true" %}

```json
{
    "success": true, 
    "parcel_code": "xyzn-234214" 
}
```

{% endcode %}

It returns success flag and the <mark style="color:blue;">parcel\_code</mark> for the updated 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 <mark style="color:blue;">{parcel\_id}</mark> provided in the route does not correspond to an existing parcel.
{% endtab %}

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

{% code lineNumbers="true" %}

```json
{
    "success": false,
    "errors": [
        "can not edit parcel in this state."
    ]
}
```

{% endcode %}

This response is returned when the <mark style="color:blue;">{parcel\_id}</mark> provided in the route corresponds to a parcel that is in an not editable status.
{% endtab %}

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

{% code lineNumbers="true" %}

```json
{
    "success": false,
    "errors": [
        "you are not allowed to edit price after creation"
    ]
}
```

{% endcode %}

{% code lineNumbers="true" %}

```json
{
    "success": false,
    "errors": [
        "لا يمكنك تعديل السعر لأن الزبون منع أحد موظفيه من التعديل على السعر بعد إنشاء الطرد"
    ]
}
```

{% endcode %}

{% code lineNumbers="true" %}

```json
{
    "success": false,
    "errors": [
        "can't update total price  to value more than xxxx"
    ]
}
```

{% endcode %}

{% code lineNumbers="true" %}

```json
{
    "success": false,
    "errors": [
        "cannot change price"
    ]
}
```

{% endcode %}

{% code lineNumbers="true" %}

```json
{
    "success": false,
    "errors": [
        "can't update actual price to value more than xxxx"
    ]
}
```

{% endcode %}
{% endtab %}

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

{% code lineNumbers="true" %}

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

{% endcode %}

This response is returned when the <mark style="color:blue;">{parcel\_id}</mark> provided in the route correspond to a locked parcel.
{% endtab %}

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

{% code lineNumbers="true" %}

```json
{
    "success": false,
    "errors": [
        "you change size only when parcel status is draft or submitted"
    ]
}
```

{% endcode %}
{% endtab %}
{% endtabs %}