> 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/get-parcels-by-parcel-codes.md).

# Get Parcels By Parcel Codes

```php
POST /parcels/getParcelsByParcelCodes
```

This API is used to get parcels information based on their parcel codes.

#### 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="128.5999755859375">Field Name</th><th width="106.79998779296875">Required</th><th width="137">Type</th><th>Notes</th></tr></thead><tbody><tr><td>parcel_codes</td><td>yes</td><td>array of strings</td><td>The array is limited to a maximum of 100 entries<br>Should be filled with the parcels <mark style="color:blue;">parcel_code</mark></td></tr></tbody></table>

Request body example:

{% code lineNumbers="true" %}

```json
{
    "parcel_codes": ["asnf-000-9638079", "asnf-000-6910054", "asnf-000-0539149", "asnf-230-0539149"], 
    "Shiply_API_KEY": "your_api_key"
}
```

{% endcode %}

#### Response body

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

```json
{
    "success": true,
    "found_parcels": [
        {
            "parcel_code": "asnf-000-0539149",
            "description": "EMPIRE 1 /",
            "customer_user_id": 4,
            "driver_user_id": null,
            "paid_driver_id": null,
            "in_account": 0,
            "parcel_status_id": 1,
            "is_locked": 0,
            "parcel_position_id": 1,
            "parcel_type_id": null,
            "reference_parcel_code": null,
            "returned_reason_id": null,
            "address_id": 1471244,
            "recipient_id": 1464194,
            "qr_code": null,
            "qr_hash": "",
            "region_cost_map_id": 2038,
            "total_price": 190,
            "actual_price": 115,
            "parcel_delivery_cost": 70,
            "price_extra_fee": 0,
            "planned_date": null,
            "note": null,
            "weight": null,
            "length": 40,
            "width": 40,
            "height": 40,
            "size_fee": 0,
            "created_at": "2025-03-27 12:26:53",
            "updated_at": "2025-04-08 14:14:51",
            "customer_invoice_id": null,
            "final_parcel_status_id": null,
            "extra_delivery_cost": 0,
            "is_replacement": 0,
            "commission": 0,
            "customer_private_note": null,
            "cell": null,
            "reference_number": null,
            "is_completely_received": null,
            "companion_parcels_count": 0,
            "discount_value": 0,
            "size": 64000,
            "total_size": 64000,
            "contents": [],
            "parcel_status": {
                "id": 1,
                "name": "Draft",
                "ar_aliase": "قيد الإنشاء",
                "en_aliase": "Draft",
                "description": ""
            },
            "customer": {
                "id": 4,
                "first_name": "demo",
                "customer_contacts": []
            },
            "recipient": {
                "id": 1464194,
                "address_id": 1471244,
                "first_name": "عمر كناعنة",
                "last_name": "",
                "note": null,
                "phone": "556652316",
                "phone2": null,
                "is_blocked": 0,
                "recipient_info_id": null,
                "created_at": "2025-03-27 12:26:53",
                "updated_at": "2025-03-27 12:26:53"
            },
            "address": {
                "id": 1471244,
                "city_id": 23,
                "village_id": 455,
                "street_name": "كفر قرع",
                "location_updated_at": "2025-03-27 12:26:53",
                "additional_information": null,
                "order": 0,
                "created_at": "2025-03-27 12:26:53",
                "updated_at": "2025-03-27 12:26:53",
                "location_updated_by_user_id": 4,
                "hasLocation": false,
                "city": {
                    "id": 23,
                    "name": "ام الفحم"
                },
                "village": {
                    "id": 455,
                    "name": "كفر قرع"
                }
            },
            "driver_note": null,
            "customer_note": null,
            "companion_parcels": [],
            "parcel_type": null,
            "returned_reason": null,
            "promotion_usages": []
        },
        .................
    ],
    "not_found_parcels": [
        "asnf-230-0539149"
    ]
}
```

The response includes the following:

* <mark style="color:blue;">success</mark> flag: Indicates whether the request was processed successfully.
* <mark style="color:blue;">found\_parcels</mark> array: A list of parcels that were successfully retrieved based on the provided <mark style="color:blue;">parcel\_codes</mark>.&#x20;
* <mark style="color:blue;">not\_found\_parcels</mark> array: A list of parcel codes from the request that were not found in the system. This array will be empty if all provided codes are matched.
  {% endtab %}

{% tab title="Size limit" %}
Status code: <mark style="color:red;">422
&#x20;Unprocessable Entity</mark>

{% code lineNumbers="true" %}

```json
{
    "message": "The given data was invalid.",
    "errors": {
        "parcel_codes": [
            "The parcel codes may not have more than 100 items."
        ]
    }
}
```

{% endcode %}

This response is returned when the <mark style="color:blue;">parcel\_codes</mark> array contains more than 100 entries.
{% endtab %}

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

{% code lineNumbers="true" %}

```json
{
    "success": true,
    "found_parcels": [],
    "not_found_parcels": [
        "asnf-000-9638079",
        "asnf-000-6910054",
        "asnf-000-0539149",
        "asnf-230-0539149"
    ]
}
```

{% endcode %}

This response is returned when the user is not authorized to access the requested parcels. In this case, all provided <mark style="color:blue;">parcel\_codes</mark> are included in the <mark style="color:blue;">not\_found\_parcels</mark> array.
{% 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 %}