> 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/general-definitions.md).

# General Definitions

This section provides definitions and classifications of key terms related to Shiply. This section is designed to help you better understand the concepts involved when working with the integration APIs.

## Parcel Statuses

When you encounter the terms <mark style="color:blue;">parcel\_status\_id</mark> or <mark style="color:blue;">final\_parcel\_status\_id</mark> in parcel information, they refer to the status of a parcel:

* <mark style="color:blue;">parcel\_status\_id</mark>: Represents the current status of the parcel.
* <mark style="color:blue;">final\_parcel\_status\_id</mark>: Indicates the final status of the parcel, which can be one of the following: **Replaced**, **Delivered**, or **Returned**.

Below are the parcel statuses in Shiply:

<table><thead><tr><th width="121">id</th><th width="222">name</th><th width="208">ar_aliase</th><th width="192">en_aliase</th></tr></thead><tbody><tr><td>1</td><td>Draft</td><td>قيد الإنشاء</td><td>Draft</td></tr><tr><td>2</td><td>Submitted</td><td>جاهز للإرسال</td><td>Submitted</td></tr><tr><td>3</td><td>OnTheWay</td><td>مشحون</td><td>On The Way</td></tr><tr><td>4</td><td>AttemptToDeliver</td><td>محاولة تسليم</td><td>Attempt To Deliver</td></tr><tr><td>5</td><td>Pending</td><td>عالق</td><td>Pending</td></tr><tr><td>6</td><td>Delivered</td><td>واصل</td><td>Delivered</td></tr><tr><td>7</td><td>Returned</td><td>راجع</td><td>Returned</td></tr><tr><td>8</td><td>Finished</td><td>منتهي</td><td>Finished</td></tr><tr><td>9</td><td>Replaced</td><td>تم التبديل</td><td>Replaced</td></tr><tr><td>10</td><td>Resolved</td><td>تمت المعالجة</td><td>Resolved</td></tr></tbody></table>

## Parcel Positions

The term <mark style="color:blue;">parcel\_position\_id</mark> in parcel information indicates the current location or position of the parcel.

Below is a list of parcel positions available in Shiply:

{% tabs %}
{% tab title="Palestine" %}

<table><thead><tr><th width="121">id</th><th>name</th><th>ar_aliase</th><th>en_aliase</th></tr></thead><tbody><tr><td>1</td><td>Customer</td><td>مع المرسل</td><td>Customer</td></tr><tr><td>2</td><td>Nablus</td><td>في نابلس</td><td>Nablus</td></tr><tr><td>3</td><td>Ramallah</td><td>في رام الله</td><td>Ramallah</td></tr><tr><td>4</td><td>Hebron</td><td>في الخليل</td><td>Hebron</td></tr><tr><td>5</td><td>Driver</td><td>مع السائق</td><td>Driver</td></tr><tr><td>6</td><td>Recipient</td><td>مع المستلم</td><td>Recipient</td></tr><tr><td>7</td><td>NablusStore</td><td>*في نابلس</td><td>In Nablus*</td></tr><tr><td>8</td><td>OccupiedAreaStore</td><td>*في الداخل</td><td>In Occupied Area*</td></tr><tr><td>9</td><td>HebronStore</td><td>*في الخليل</td><td>In Hebron*</td></tr></tbody></table>
{% endtab %}

{% tab title="Jordan" %}

<table><thead><tr><th width="121">id</th><th>name</th><th>ar_aliase</th><th>en_aliase</th></tr></thead><tbody><tr><td>1</td><td>Customer</td><td>مع المرسل</td><td>Customer</td></tr><tr><td>2</td><td>Amman</td><td>عمان</td><td>Amman</td></tr><tr><td>3</td><td>Mqableen</td><td>المقابلين</td><td>Mqableen</td></tr><tr><td>5</td><td>Driver</td><td>مع السائق</td><td>Driver</td></tr><tr><td>6</td><td>Recipient</td><td>مع المستلم</td><td>Recipient</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

## Parcel Types

The term <mark style="color:blue;">parcel\_type\_id</mark> represents the type of parcel. Shiply categorizes parcels into the following types:

<table><thead><tr><th width="66">id</th><th width="149">alias</th><th width="100">ar_name</th><th width="152">en_name</th><th>description</th></tr></thead><tbody><tr><td>1</td><td>SendParcel</td><td>طرد إرسال</td><td>Send Parcel</td><td>Normal traditional Parcel to send one package to your recipient</td></tr><tr><td>2</td><td>ReplaceParcel</td><td>طرد بدل</td><td>Replace Parcel</td><td>Send one package and bring another one package from your recipient</td></tr><tr><td>3</td><td>BringParcel</td><td>طرد ترجيع</td><td>Bring Parcel</td><td>Get one package from your recipient</td></tr><tr><td>4</td><td>PaymentParcel</td><td>طرد دفع</td><td>Payment Parcel</td><td>Pay Money To recipient</td></tr><tr><td>5</td><td>PurchaseParcel</td><td>طرد شراء</td><td>Purchase Parcel</td><td>Purchase items and bring them to the customer</td></tr></tbody></table>

## Parcel Return Reasons

The term <mark style="color:blue;">returned\_reason\_id</mark> represents the reason of returning a specific parcel if its status is returned and can be one of the following:

<table><thead><tr><th width="83">id</th><th>en_reason</th><th>ar_reason</th></tr></thead><tbody><tr><td>1</td><td>Returned by the seller before completion of the delivery process</td><td>تم الإرجاع من قبل البائع قبل إكمال عملية التوصيل</td></tr><tr><td>2</td><td>Returned by the seller after completion of the delivery process</td><td>تم الإرجاع من قبل البائع بعد إكمال عملية التوصيل</td></tr><tr><td>3</td><td>Returned by the recipient before completion of the delivery process</td><td>تم الإرجاع من قبل المستلم قبل إكمال عملية التوصيل</td></tr><tr><td>4</td><td>Returned by the recipient after completion of the delivery process</td><td>تم الإرجاع من قبل المستلم بعد إكمال عملية التوصيل</td></tr><tr><td>5</td><td>Returned by the Shiply team before the completion of the delivery process</td><td>تم الإرجاع من قبل فريق شبلي قبل إكمال عملية التوصيل</td></tr><tr><td>6</td><td>Returned by the Shiply team after completion of the delivery process</td><td>تم الإرجاع من قبل فريق شبلي بعد إكمال عملية التوصيل</td></tr></tbody></table>

## Parcel Identification

The <mark style="color:blue;">parcel\_code</mark> serves as the unique identifier for each parcel in Shiply. It is highly recommended to store this value in your system to ensure precise tracking and efficient parcel management.

## Companion Parcels

This section explains the integration APIs within the Shiply system that are related to companion parcels. Companion parcels are additional parcels that can be linked as "children" to an already created parcel. The system treats the parent parcel and its companion parcels as a single package for processing and management.

## Premium Customers

This section outlines the features related to employees of premium customers within the Shiply system. Premium customers are businesses that manage their parcels through Shiply by assigning individual accounts to their employees. These employees play a crucial role in managing parcels, with their access and responsibilities governed by permissions granted by their managers. This structure enables efficient parcel handling and better operational control.

Additionally, the premium customers feature in Shiply is designed to support businesses that work with multiple vendors. It allows premium customers to manage all their vendors. This functionality enhances parcel tracking, shipping management, and overall coordination between vendors, ensuring a more streamlined and integrated logistics process.

### Premium Cutomers Employees Premissions

Below is the list of permissions that can be assigned to premium customer employees:

<table><thead><tr><th width="83">id</th><th width="304">name</th><th width="259">display_name</th><th>used_by</th></tr></thead><tbody><tr><td>1</td><td>LIST_USERS</td><td>List users</td><td>[9]</td></tr><tr><td>2</td><td>ADD_EDIT_USER</td><td>Add/Edit user</td><td>[9]</td></tr><tr><td>3</td><td>SHOW_TOTAL_MONEY</td><td>Show total money</td><td>[9]</td></tr><tr><td>4</td><td>SHOW_DELIVERED_COUNTER</td><td>Show delivered counter</td><td>[9,10]</td></tr><tr><td>5</td><td>SHOW_DELIVERY_COST</td><td>Show delivery cost</td><td>[9,10]</td></tr><tr><td>6</td><td>SHOW_PARCEL_PRICE</td><td>Show parcel price</td><td>[9,10]</td></tr><tr><td>7</td><td>SHOW_PARCEL_HISTORY</td><td>Show parcel history</td><td>[9,10]</td></tr><tr><td>8</td><td>ADD_EDIT_PARCELS</td><td>Add/Edit parcels</td><td>[9,10]</td></tr><tr><td>9</td><td>RETURN_RESEND_PERMISSION</td><td>Return/Resend permission</td><td>[9,10]</td></tr><tr><td>10</td><td>ADD_REPLACE_QR</td><td>Add/replace QR</td><td>[9,10]</td></tr><tr><td>11</td><td>SEARCH_FOR_FINISHED_PARCELS</td><td>Search for finished parcels</td><td>[9,10]</td></tr><tr><td>12</td><td>DOWNLOAD_EXCEL</td><td>Download excel</td><td>[9,10]</td></tr><tr><td>13</td><td>LIST_INVOICES</td><td>List invoices</td><td>[9]</td></tr><tr><td>14</td><td>CREATE_INVOICE</td><td>Create invoice</td><td>[9]</td></tr><tr><td>15</td><td>CHANGE_PASSWORD</td><td>Change password</td><td>[9, 10]</td></tr><tr><td>16</td><td>EDIT_PRICE_AFTER_CREATION</td><td>Edit price after creation</td><td>[9, 10]</td></tr><tr><td>18</td><td>CAN_MANAGE_PRODUCTS</td><td>Manage products</td><td>[9, 10]</td></tr></tbody></table>

While \[9] is premium customer employee and \[10] is premium customer sales representative.&#x20;

## Parcel Content

This section focuses on the contents of a parcel, detailing what is included inside it. Customers can have a predefined catalog of products related to their business. When creating a parcel, customers can add its content either by selecting items from the predefined product catalog or by manually entering the item names and descriptions.

## Webhooks

Webhooks are notifications sent by us to an HTTP endpoint on one of your services. They are useful for when you want to be notified whenever something important happens on our side that you should know (eg: a parcel status change).

## Shiply Shipping Address

In Shiply, the parcel's shipping address is defined using three components: <mark style="color:blue;">city\_id</mark>, <mark style="color:blue;">village\_id</mark> and <mark style="color:blue;">street\_name</mark>. To assign a <mark style="color:blue;">city\_id</mark> and <mark style="color:blue;">village\_id</mark> to a parcel's shipping address, Shiply provides a predefined collection of cities and their corresponding villages.

Here is an example of how these are represented:

{% tabs %}
{% tab title="Palestine" %}
Cities example:

<table><thead><tr><th width="116">id</th><th>name</th></tr></thead><tbody><tr><td>1</td><td>القدس</td></tr><tr><td>2</td><td>رام الله والبيرة</td></tr><tr><td>3</td><td>نابلس</td></tr><tr><td>4</td><td>بيت لحم</td></tr></tbody></table>

Villages example:

<table><thead><tr><th width="68">id</th><th width="84">city_id</th><th width="105">name</th><th>region_id</th><th width="123">region_type</th><th width="86">note</th><th width="111">is_closed</th><th>deleted_at</th></tr></thead><tbody><tr><td>1</td><td>3</td><td>نابلس</td><td>1</td><td>1</td><td></td><td>0</td><td></td></tr><tr><td>5</td><td>3</td><td>بيتا</td><td>1</td><td>1</td><td></td><td>0</td><td></td></tr><tr><td>6</td><td>3</td><td>عقربا</td><td>1</td><td>1</td><td></td><td>0</td><td></td></tr><tr><td>7</td><td>3</td><td>بيت فوريك</td><td>1</td><td>1</td><td></td><td>0</td><td></td></tr></tbody></table>
{% endtab %}

{% tab title="Jordan" %}
Cities example:

<table><thead><tr><th width="116">id</th><th>name</th></tr></thead><tbody><tr><td>1</td><td>عمان الشمالية</td></tr><tr><td>2</td><td>عمان الجنوبية</td></tr><tr><td>3</td><td>عمان الشرقية</td></tr><tr><td>4</td><td>عمان الغربية</td></tr><tr><td>5</td><td>شمال الأردن</td></tr></tbody></table>

Villages example:

<table><thead><tr><th width="68">id</th><th width="84">city_id</th><th width="134">name</th><th>region_id</th><th width="123">region_type</th><th width="86">note</th><th width="111">is_closed</th><th>deleted_at</th></tr></thead><tbody><tr><td>2</td><td>4</td><td>ضاحية الرشيد</td><td></td><td>1</td><td></td><td>0</td><td></td></tr><tr><td>3</td><td>4</td><td>المدينة الرياضية</td><td></td><td>1</td><td></td><td>0</td><td></td></tr><tr><td>4</td><td>4</td><td>تلاع العلي</td><td></td><td>1</td><td></td><td>0</td><td></td></tr><tr><td>5</td><td>4</td><td>الرابية</td><td></td><td>1</td><td></td><td>0</td><td></td></tr></tbody></table>
{% endtab %}
{% endtabs %}

<mark style="color:blue;">is\_closed</mark>: This field indicates whether a village is closed for deliveries.

* **True (1)**: Shiply does not deliver to this village.
* **False (0)**: Shiply can deliver parcels to this village

You can get all cities and their villages using this API: [Get Cities And Villages](/shiply-integration-documentation/integration-apis/shipping-address/get-cities-and-villages.md)