> 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-plugins-and-apps/shopify-app.md).

# Shopify App

This section provides a detailed overview of the Shiply Logistics Shopify App, designed to seamlessly integrate Shiply’s logistics services into any Shopify store.

## Installation Guide

Follow this link to install the Shiply Logistics App: <https://apps.shopify.com/shiply-logistics>, then follow these steps:

* Grant the app access to store data to ensure optimal integration for orders with parcel actions in the Shiply system, by clicking on install button:

<figure><img src="/files/2hddEdq1ufaGoAWcAF04" alt="" width="478"><figcaption></figcaption></figure>

* Once the app is installed, it will appear in the store installed apps (under "Apps" in the left list), and this page will be displayed:&#x20;

<figure><img src="/files/3Nf1lWNC99YDFOQkfMQd" alt=""><figcaption></figcaption></figure>

## Usage Guide

### Welcome page

<figure><img src="/files/NFf2jEUewcxNW3uMN0MD" alt=""><figcaption></figcaption></figure>

This page provides an overview of the app current status, including:

* **Environment**: Indicates whether the app is running in "Testing" or "Production" mode.
* **Country**: Specifies the selected country "Palestine" or "Jordan".
* **API Keys Status**: Shows whether the required API keys are configured.

Additionally, the page includes two navigation buttons:

* **Manage settings**: Redirects to the settings page, where can configure the environment, country, API keys, and other options.
* **Go to parcels**: Redirects to the orders and parcels page.

When installing the app for the first time, the following will be displayed on the welcome page:

<figure><img src="/files/R9KrZOYvScg8Xa5TPGwK" alt=""><figcaption></figcaption></figure>

From there, can navigate to the settings page to configure the app.

### Settings page

<figure><img src="/files/A3SDUNcLK54jJzXnRJ1j" alt=""><figcaption></figcaption></figure>

This page allows managing all app-related settings, including:

* **Editing Shiply API keys**
* **Changing the app environment and country**
  * ***Note:** Changing the app environment from "Testing" to "Production" means all parcel actions will affect the live Shiply account. Parcels will be created and updated in the live environment, and the app will prompt to confirm before switching.*
* **Configuring preferences**, such as whether to include the calculated delivery cost—based on the shipping address—when creating parcels for orders

### Parcels page

<figure><img src="/files/ldC0ruGcZppaIWk7u9X7" alt=""><figcaption></figcaption></figure>

This page displays a list of store orders along with their associated parcels (if any). It also provides filtering options and actions to help manage orders efficiently.

**Filters**

* Filter orders by a specific date range
* Filter orders that do not yet have associated parcels

**Actions**

* **Bulk Create:** Allows you to create parcels in bulk for selected orders that do not already have parcels

#### Bulk Create Parcels

When there are Shopify orders that are not yet associated with parcels and you want to create parcels for them in bulk, click on the **BULK CREATE** button. This will open the following modal:

<figure><img src="/files/yRw0X6WgmKJGche08ADd" alt=""><figcaption></figcaption></figure>

All orders without associated parcels are automatically selected by default. You can review and adjust the selection based on the orders you want to create parcels for.

**Page components:**

* **Table:** Displays basic order information, including:
  * **Order:** Shopify order number
  * **Recipient Name**
  * **Shopify Address:** Address provided in the Shopify order
  * **Shiply Address:** Shiply parcel delivery address
  * **Shipping:** Parcel delivery cost
  * **Add Shipping Cost:** Indicates whether the calculated shipping cost should be added to the order total
  * **Error:** Displays any issues that may block parcel creation
* **PREDICT ALL** button: This button attempts to automatically predict and map the Shiply delivery address based on the recipient’s address entered during checkout.

  * Some addresses may not be successfully predicted or may be incomplete.
  * In such cases, you will need to manually map the address by selecting the **City** and **Village** from the dropdown menus.

  After clicking this button, the predicted results will appear as follows:<br>

  <figure><img src="/files/H3OgtJ8m2qaUuCWdqU6c" alt=""><figcaption></figcaption></figure>
* **Add Shipping Cost to Total Price for orders (toggle per row in label):** This checkbox reflects the previously configured setting that determines whether the calculated shipping cost should be added to the order total. This setting can be overridden individually for each order.
* **I confirm that I have reviewed all shipping addresses:** This checkbox must be selected after verifying all shipping addresses. Once checked, the **CREATE (X) PARCELS** button will be enabled, allowing you to proceed with parcel creation.<br>

  <figure><img src="/files/vKGWPAX2B7LwBO3WjFNB" alt=""><figcaption></figcaption></figure>
* **CREATE (X) PAPRCELS** button: This button displays the number of parcels that will be created during the bulk process.
  * When clicked, a confirmation modal will be displayed:<br>

    <figure><img src="/files/Meain2pQeH0SmdtDQyZb" alt=""><figcaption></figcaption></figure>
  * You can choose between creating parcels only or creating parcels and submitting them.
  * After selecting the desired option, the system will execute the process and display a summary of the results.\
    &#x20;

    <figure><img src="/files/C4XfeZ3pVnWoGSD0hnhq" alt=""><figcaption></figcaption></figure>

#### **Row details**

<figure><img src="/files/2mdLGFJ23qSQXY2zsSNA" alt=""><figcaption></figcaption></figure>

Each row represents a Shopify order along with its associated parcel (if created). The table displays the following key information:

* **Order Name:** Shopify order number
* **Parcel Code:** Shiply parcel code
* **Parcel Status:** Shiply parcel status
* **Recipient Name**
* **Order Total:** Shopify order total
* **Delivery Cost:** Parcel delivery cost
* **Shopify Address:** Address provided in the Shopify order
* **Delivery Address:** Shiply parcel delivery address
* **Actions:** Available parcel actions based on the parcel status

**Available Actions:**

* If the parcel has not been created yet: **CREATE**
* If the parcel is in *"Draft"* status: **SUBMIT**
* If the parcel is in *"Submitted"* status: **CANCEL**

&#x20;

#### **Parcel Actions**

**Create parcel**

When a parcel has not yet been created for an order, the **Actions** column will display a **"CREATE"** option. Clicking this option will open the following modal:

<figure><img src="/files/okdiMn2S2fDoyVKsrB3l" alt=""><figcaption></figcaption></figure>

* The parcel creation form is automatically populated using the order and recipient details provided at the time of purchase. These include: **Recipient Name, Phone Number, Recipient Address, Recipient Note, and Order Total**.
* The **Description** field is pre-filled with default text, but it can be customized as needed.
* If a shipping address was provided by the recipient during checkout, the system will attempt to automatically map this address to Shiply’s shipping address fields (**City, Village, Street**).

  * If the mapping is successful, the fields will be filled automatically.
  * If any information is missing or the address cannot be mapped, you will need to manually select and map the correct Shiply shipping address based on the recipient’s input.

  **Note:** Start by selecting a **City**. This will populate the corresponding **Villages** in the village dropdown menu.
* The **Shipping Cost** is automatically calculated once a village is selected.
* The checkbox **"Add Shipping Cost to Total Price"** reflects the previously configured setting that determines whether the calculated shipping cost should be added to the order total. This setting can be overridden per parcel regardless of the default configuration.
* To proceed, you must check the **"I confirm that the shipping address is correct"** checkbox. This will enable the **CREATE PARCEL** button.
* Once you click **CREATE PARCEL** and the parcel is successfully created, the modal will close automatically, and the parcel details will appear in the table.

<figure><img src="/files/2b6HOibDsm4MzYErOz9R" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}

* If the recipient did not provide a phone number when placing the order, the "Recipient Phone Number" field will be empty. Since a phone number is required to create a parcel, you have two options:
  1. Enter the recipient’s phone number directly in the create parcel modal (this will not update the recipient information in Shopify).
  2. Update the recipient's phone number in the Shopify order details, then return to the create parcel modal -- the updated phone number will be reflected there.
* If there is no name for the recipient it will appear as "N/A" in "Recipient Name". If you want to provide a name for the parcel recipient, then update the recipient's name in the Shopify order details, then return to the create parcel modal -- the updated recipient name will be reflected there.
  {% endhint %}

**Submit parcel**

When a parcel’s status is set to *"Draft"*, the **Actions** column will include a **"SUBMIT"** option. Upon clicking it, a confirmation modal will be displayed.

<figure><img src="/files/nmB2zHjGW4dN8oHO0EGf" alt=""><figcaption></figcaption></figure>

When click on **"CONFIRM"**, the parcel will be *"Submitted"*, and its status will be updated accordingly in the table:

<figure><img src="/files/AmbGl4Oboz9hEPuRJ0iU" alt=""><figcaption></figcaption></figure>

**Cancel parcel**

When a parcel’s status is set to *"Submitted"*, the **Actions** column will include a **"CANCEL"** option. Upon clicking it, a confirmation modal will be displayed.

<figure><img src="/files/mzVmlvUbouRx7jvMMdVt" alt=""><figcaption></figcaption></figure>

When click on **"CONFIRM"**, the parcel will be *"Draft"*, and its status will be updated accordingly in the table:

<figure><img src="/files/3lBzuDlPvimo2paHoFUk" alt=""><figcaption></figcaption></figure>

**Note:** Once a parcel is created for an order and its status is no longer *"Draft"* or *"Submitted"*, no further actions will be available within the app. To perform any additional actions, please use the Shiply system directly.

<figure><img src="/files/vufd80HW5Arl5k1lZvE4" alt=""><figcaption></figcaption></figure>