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

# Create Parcel

```php
POST /parcels/create
```

This API is used to create a new parcel in the system.

#### 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>yes</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>If not set, it takes a default value (40).</td></tr><tr><td>width</td><td>no</td><td>integer</td><td>If not set, it takes a default value (40).</td></tr><tr><td>height</td><td>no</td><td>integer</td><td>If not set, it takes a default value (40).</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>is_favorite_recipient</td><td>no</td><td>boolean</td><td>If want to set the recipient as favorite recipient. </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>forceDuplicate</td><td>no</td><td>boolean</td><td>True if want to create a parcel for a recipient that has already an existing parcel before.</td></tr></tbody></table>

Request body example:

{% code lineNumbers="true" %}

```json
{
    "recipient": {
        "first_name" : "مستلم",
        "phone" : "0599999999"
    },
    "address": {
        "city_id" : 1,
        "village_id" : 105,
        "street_name" : "شارع"
    },
    "total_price": 150,
    "description":"طرد تجريبي",
    "note":"ملاحظة",
    "length": 40,
    "width": 40,
    "height": 40,
    "planned_date": "2024-11-20",
    "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, 
    "parcel_code": "xyzn-234214" 
}
```

{% endcode %}

The response includes a success flag and the <mark style="color:blue;">parcel\_code</mark> for the newly created parcel.
{% endtab %}

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

{% code lineNumbers="true" %}

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

{% endcode %}

{% code lineNumbers="true" %}

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

{% endcode %}

This response is returned when the selected village is either hidden (not selectable by the customer) or closed (Shiply does not deliver to it at this time).
{% endtab %}

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

{% code lineNumbers="true" %}

```json
{
    "success": false,
    "recipient_blocked": true,
    "errors": [
        "Recipient is blocked"
    ]  
}
```

{% endcode %}

This response is returned when the selected recipient's information is associated with a blocked recipient in Shiply.
{% endtab %}

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

{% code lineNumbers="true" %}

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

{% endcode %}

This response is returned when the user does not have permission to create a parcel.
{% 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="Duplicate parcel" %}
Status code: <mark style="color:green;">200 OK</mark>

{% code lineNumbers="true" %}

```json
{
    "success": false,
    "duplicate": "0599999999",
    "errors": [
        "phone number is duplicated from same customer parcels phone"
    ]
}
```

{% endcode %}

This response is returned when the recipient information for the newly created parcel belongs to a recipient who already has an existing parcel.
{% endtab %}

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

{% code lineNumbers="true" %}

```json
{
    "success": false,
    "errors": [
        "can't create parcel with total price more than xxxx"
    ]
}
```

{% endcode %}

This response is returned when the <mark style="color:blue;">total\_price</mark> of the parcel exceeds the allowed limit for the customer.
{% endtab %}

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

{% code lineNumbers="true" %}

```json
{
    "success": false,
    "errors": [
        "failed to add"
    ]
}
```

{% endcode %}

This response is returned when a database error occurs while attempting to crate a 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 %}

{% hint style="success" %}
**Recommendation:** Store the returned <mark style="color:blue;">parcel\_code</mark>, as it may be required for future actions related to the parcel.
{% endhint %}