> 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-returned-parcels.md).

# Get Returned Parcels

```php
GET /parcels/returned
```

This API is used to retrieve a list of returned parcels for a customer.

#### 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="155">Field Name</th><th width="105">Required</th><th width="93">Type</th><th>Notes</th></tr></thead><tbody><tr><td>from</td><td>no</td><td>integer</td><td><strong>Used for pagination:</strong> Specifies the starting number.<br>Default value = 0</td></tr><tr><td>to</td><td>no</td><td>integer</td><td><strong>Used for pagination:</strong> Specifies the ending number.<br>Default value = 20</td></tr><tr><td>getAll</td><td>no</td><td>boolean</td><td>If true then get all returned parcels at once (without pagination).<br>Default value = false</td></tr><tr><td>fromDate</td><td>no</td><td>date</td><td>Format: "YYYY-MM-DD", the starting date.</td></tr><tr><td>toDate</td><td>no</td><td>date</td><td>Format: "YYYY-MM-DD", the ending date.</td></tr></tbody></table>

{% hint style="info" %} <mark style="color:blue;">from</mark> and <mark style="color:blue;">to</mark> in the request body are optional parameters used for partial data retrieval, which is useful for pagination. The specified range should not exceed 100.
{% endhint %}

Request body example:

{% code lineNumbers="true" %}

```json
{
    "fromDate": "2024-10-01",
    "toDate": "2024-11-01",
    "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,
    "total_count": 1,
    "parcels": [
        {
            "parcel_code": "asnf-000-4749245",
            "description": "Jjjjjj",
            "customer_user_id": 4,
            "driver_user_id": null,
            "paid_driver_id": null,
            "in_account": 0,
            "parcel_status_id": 8,
            "is_locked": 0,
            "parcel_position_id": 1,
            "parcel_type_id": null,
            "returned_reason_id": null,
            "address_id": 1469018,
            "recipient_id": 1462047,
            "qr_code": null,
            "qr_hash": "",
            "region_cost_map_id": null,
            "total_price": 66,
            "actual_price": 46,
            "parcel_delivery_cost": 0,
            "price_extra_fee": 0,
            "planned_date": "2024-10-22",
            "note": "Noooo",
            "weight": null,
            "length": 40,
            "width": 40,
            "height": 40,
            "size_fee": 0,
            "created_at": "2024-10-14 09:40:18",
            "updated_at": "2024-11-23 15:52:13",
            "customer_invoice_id": 125848,
            "final_parcel_status_id": 7,
            "extra_delivery_cost": 0,
            "is_replacement": 0,
            "commission": 0,
            "customer_private_note": "",
            "cell": null,
            "reference_number": "Jjjjjj",
            "companion_parcels_count": 0,
            "discount_value": 0,
            "size": 64000,
            "total_size": 64000,
            "contents": [],
            "address": {
                "id": 1469018,
                "city_id": 3,
                "village_id": 1,
                "street_name": "sfs dsf ds d",
                "location_updated_at": null,
                "additional_information": null,
                "order": 0,
                "created_at": "2024-10-10 09:14:30",
                "updated_at": "2024-10-10 09:14:30",
                "location_updated_by_user_id": null,
                "hasLocation": false,
                "city": {
                    "id": 3,
                    "name": "نابلس",
                    "deleted_at": null
                },
                "village": {
                    "id": 1,
                    "city_id": 3,
                    "name": "نابلس",
                    "driver_region_id": null,
                    "region_id": 1,
                    "region_type": 1,
                    "note": null,
                    "is_closed": 0,
                    "deleted_at": null
                }
            },
            "recipient": {
                "id": 1462047,
                "address_id": 1469018,
                "first_name": "feras",
                "last_name": null,
                "note": null,
                "phone": "0599235342",
                "phone2": "0598123455",
                "is_blocked": 0,
                "recipient_info_id": null,
                "created_at": "2024-10-10 09:14:30",
                "updated_at": "2024-10-10 09:14:30"
            },
            "customer": {
                "id": 4,
                "first_name": "demo",
                "customer_contacts": []
            },
            "return_parcel_delivery_history": {
                "id": 15361764,
                "parcel_status_id": 7,
                "parcel_position_id": 1,
                "actor_user_id": 11,
                "driver_id": null,
                "history_type": 2,
                "note": null,
                "created_at": "2024-10-14 09:42:46",
                "updated_at": "2024-10-14 09:42:46",
                "actor_user": {
                    "id": 11,
                    "first_name": "حساب الأدمن",
                    "user_type_id": 1,
                    "customer_contacts": []
                }
            },
            "parcel_type": null,
            "companion_parcels": [],
            "promotion_usages": []
        }
    ]
}
```

{% endcode %}

The response contains 2 main values which are:

* <mark style="color:blue;">total\_count</mark>: The total number of returned parcels.
* <mark style="color:blue;">parcels</mark>: An array contains the information for all returned parcels.&#x20;
  {% endtab %}

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

{% code lineNumbers="true" %}

```json
{
    "success": false,
    "error": "range is too big"
}
```

{% endcode %}

This response is returned when the <mark style="color:blue;">from</mark> - <mark style="color:blue;">to</mark> range exceeds 100.
{% 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 %}