> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trypopcorn.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Shipping and payment

> Set the shipping options, delivery coverage and payment methods the AI agent uses when it creates an order for a customer in chat.

When the agent's **Take orders in chat** switch is on, it can collect an address and create an order inside the conversation. **Settings → Shipping** tells it where you deliver and what delivery costs; **Settings → Payment** tells it which payment methods it may offer and where customers send a bank transfer. Without these, the agent has no delivery fee to add and no payment method to ask for.

## Before you start

* Both pages are listed for every predefined role (orders view access). Changing them needs orders edit access (Owner, Admin, Manager), and deleting a shipping option needs orders delete access. See [Team and roles](https://docs.trypopcorn.ai/settings/team-and-roles.md).
* Turn on **Take orders in chat** on the agent's **Actions** tab; see [Capabilities](https://docs.trypopcorn.ai/agents/capabilities.md).
* The Shipping page depends on which store is connected. With Shopify the list is titled **Delivery coverage** and fees are left to Shopify's checkout. With Zid, Salla or no store it is titled **Shipping options** and you set fees and delivery times in Popcorn.

> [!NOTE]
>
> During setup, the agent step can open **Add delivery fee and time** (or **Add delivery time**, when your store already gave each delivery option its fee), **How customers pay** and **Add your IBAN**. They save the same delivery, payment and bank information as the pages below.

## Shipping options

This is the page you get with a Zid or Salla store, or with no store connected. Each option is a delivery method with a fee, a delivery window and the countries and cities it covers.

**1. Add an option**

Go to **Settings → Shipping** and click **Add shipping option**.

**2. Describe it**

Fill in **Name**, **Fee**, **Fastest delivery (days)** and, if you like, **Slowest delivery (days)**, **Free shipping over** and **Store shipping ID**. Leave **Active** on. The money labels show your default currency, for example **Fee (SAR)**.

**3. Choose where it applies**

Under **Countries**, search and tick each country. Each starts as **All cities**; click **Choose cities**, tick the cities, and click **Save cities**.

**4. Save**

Click **Save**. The page confirms **Shipping option saved**.

| Field | Meaning |
| - | - |
| **Name** | What the customer sees as the delivery method |
| **Store shipping ID** | Optional. The method's identifier in your store; filled in for you when you use **Sync from store**. Zid needs it to create the order |
| **Fee** | Amount added to the order, in the workspace [default currency](https://docs.trypopcorn.ai/settings/workspace.md#products). Enter 0 for free delivery |
| **Free shipping over** | When the order's product subtotal (before delivery and cash-on-delivery fees) reaches this amount, the fee is 0. Leave it empty, or 0, for no threshold. For free delivery on every order, set the fee to 0 |
| **Fastest delivery (days)** / **Slowest delivery (days)** | Expected delivery in days. The list shows "3 days" or "2 to 5 days". The slowest can't be shorter than the fastest |
| **Active** | Inactive options are ignored at checkout |
| **Countries** and **Cities covered** | Which countries, and which cities in each, the option delivers to. Choose at least one country, and at least one city in each unless it is **All cities** |

The table lists **Name**, **Fee** ("Free" for 0, with "Free over" and the amount underneath, and, for an option synced from a Zid zone, its cash on delivery terms), **Delivery time**, **Status** (**Active** or **Inactive**) and **Ships to**, a summary such as "Saudi Arabia, all cities" or "Saudi Arabia and 3 more". Click the **Ships to** summary (on a phone, **View places** in the row menu) to see every country in a **Ships to** dialog. Click a row, or use **Edit** in its menu, to change it. **Delete** asks for confirmation ("Your agent will stop offering this option to customers. This can't be undone.") and then shows **Shipping option deleted**.

### Sync from store

**Sync from store** pulls the delivery methods defined in your Zid or Salla store so you do not retype them. The button shows only with one of those stores connected.

1. Click **Sync from store**. In **Sync shipping from your store**, Popcorn lists each method with its store ID, its store status, and a badge: **New** or **Already synced**. Zid prices a method by zone, so a Zid method appears once per zone, with the zone's cities and its cash on delivery terms: **Cash on delivery fee** and the amount, **Cash on delivery, no fee**, or **No cash on delivery**.
2. Tick the methods to import. For each one enter **Fee** and **Fastest delivery (days)** (both required), and optionally **Slowest delivery (days)** and **Free shipping over**. A Zid zone's fee starts at the fee Zid sets for it; other fields start from what Popcorn already has, or what the store sends.
3. If an option that is active in Popcorn is turned off or missing in the store, it is listed under a warning ("Deactivate them so your agent stops offering them."); tick **Deactivate** to switch it off in Popcorn too.
4. Click **Sync methods**. The page confirms **Shipping methods synced**, or says how many didn't ("2 of 3 shipping methods didn't sync") and which; open **Sync from store** again to retry them.

If the store has no methods the dialog reads "Your store has no shipping methods yet."

> [!WARNING]
>
> When you connect Zid and it is the store your checkout runs on, Popcorn adds your active Zid delivery options, one per zone, if you have none yet. They carry Zid's fee for each zone when Zid shares it (a zone priced by weight has none), and never a delivery time. When Popcorn can't read Zid's zones, the options arrive with no fee. An option with no fee, or with no **Store shipping ID**, can't be ordered: the agent tells the customer your team will confirm delivery and hands the conversation over. Check that every option has a fee, and add delivery times so the agent can quote them. See [Zid](https://docs.trypopcorn.ai/integrations/zid.md#shipping-methods).

## Delivery coverage (Shopify)

With a Shopify store, shipping rates and delivery windows are handled in Shopify's checkout, so Popcorn only needs to know where you deliver: "Countries and cities your agent can accept before sending a Shopify checkout." Click **Add delivery coverage**, give it a **Name**, choose **Countries** and cities, and click **Save**. The table shows only **Name**, **Status** and **Ships to**, and **Sync from store** is not offered.

## How the agent uses shipping at checkout

1. The agent checks the customer's country against your active options. If you have active options and none covers that country, it is told delivery isn't available there and asks the customer for a supported country or city. If you have no active options at all, it carries on with the customer's city.
2. It picks the active option that covers the customer's city, under any common spelling such as "Makkah" and "Mecca". When several options cover the city, it uses the one that costs this order least: an option the order gets free delivery on counts as free, and for cash on delivery the cash on delivery fee counts too. An option with no fee is used only when no option with a fee covers the city; with Zid it then stops the order, as the warning above says: the agent tells the customer your team will confirm the delivery cost and hands the conversation over. If the customer asks for another option that covers their city, the agent uses that one.
3. It adds that option's fee to the order, or 0 when the order reaches **Free shipping over**. With Zid, the fee is quoted with any VAT Zid adds on top at checkout once Popcorn knows it: for a fee you entered or changed yourself, that is after the first Zid order that uses it; see [Zid](https://docs.trypopcorn.ai/integrations/zid.md#checkout-and-payment).
4. If no option covers the city:
   * With Shopify or Zid, and active coverage in place, the order is not created and the agent asks for a supported city or country.
   * With Salla or no store, the order is created with a delivery fee of 0.
5. For cash on delivery, an option synced from a Zid zone uses the zone's own terms: its cash on delivery fee replaces the one under **Settings → Payment**, and a zone that shows **No cash on delivery** doesn't take it. The agent then names the options to that city that take cash on delivery, or asks for another payment method.
6. The order summary names the option and its fee. If that option is switched off or replaced by a sync before the customer taps **Confirm order**, the customer gets a fresh summary with the option that delivers to their city now.

## Payment methods

Open **Settings → Payment**. **Payment methods** ("Choose how customers can pay.") has three switches, and the agent only offers the ones that are on. A new workspace starts with cash on delivery on.

| Method | Setting | What happens at checkout |
| - | - | - |
| **Cash on delivery** | The switch | "Customers pay in cash when the order arrives." |
| | **Charge a cash on delivery fee** | "Added to orders paid in cash on delivery." Enter **Fee amount** (0 or more); a "CoD Fee" line is added to every cash-on-delivery order, except where a Zid zone sets its own fee. With Zid, the fee is quoted with any VAT Zid adds on top once Popcorn has learned it from a Zid order that uses the fee. The switch shows only while cash on delivery is on |
| **Bank transfer** | The switch, with **Bank name**, **Account holder** and **IBAN** | "Customers pay by bank transfer to your account." The agent gives the customer these details after the order. **Account holder** and **IBAN** are required while it is on; **Bank name** is optional |
| **Payment link** | The switch | "Customers pay online through a link." The agent creates the order and sends a payment link from your store. It needs a connected store that can issue payment links |

The **IBAN** is checked before saving: it starts with your country code, such as SA, then digits, and Popcorn refuses one with the wrong length or a wrong digit. A bank transfer saved earlier as free text keeps working and is shown under the fields ("Your agent now sends this to customers who choose bank transfer. Fill in the fields above to replace it.") until you fill them in.

A bar appears with "Unsaved changes". Click **Save changes** (or **Discard**); the page confirms **Payment methods saved**. If one method can't be saved you see, for example, "Couldn't save bank transfer", and the others still save. If the page can't load it reads **Couldn't load payment methods**.

If no method is on, or bank transfer is on with no details saved, the agent doesn't take the order for that method: it offers another, or tells the customer your team will confirm how to pay and hands the conversation over. With a Zid store, Popcorn first offers only the methods Zid accepts and never uses one your Zid store has off; once you change payment methods here, your choice wins. See [Zid](https://docs.trypopcorn.ai/integrations/zid.md#checkout-and-payment).

## What the customer sees

1. The agent asks for the delivery address (on WhatsApp through an address form; in Saudi Arabia it can use the national address). See [Orders](https://docs.trypopcorn.ai/orders/overview.md).
2. It checks the city against your coverage and quotes the delivery window and fee.
3. It asks for a payment method from those you enabled and creates the order, adding the delivery fee and, for cash on delivery, the CoD fee.
4. For bank transfer it sends your bank details; for payment link it sends the link; the order appears under **Orders** and in your store.

## Troubleshooting

| Symptom | Cause and fix |
| - | - |
| The agent says delivery is not available for a country or city | No active option covers that country (any store), or, with Shopify or Zid, no option lists that city. Edit the option's coverage or add one. |
| Delivery fee is 0 on every order | The order subtotal reached **Free shipping over**, the option's fee is 0, or (with Salla or no store) no option matched the city. Check the fee, the threshold and the coverage. |
| The agent hands over a Zid order to your team before confirming | The Zid option has no fee or no **Store shipping ID**, or no delivery option exists. Open **Settings → Shipping** and complete it. |
| Cash on delivery is refused for some cities (Zid) | The Zid zone for that city shows **No cash on delivery**. Change it in Zid and sync it again with **Sync from store**. |
| Customers choose a payment method you do not offer | Turn it off on **Settings → Payment** and save. |
| A bank transfer is refused | No bank details are saved. Add **Account holder** and **IBAN** on **Settings → Payment**. |
| Payment link orders fail with no link | Your connected store cannot issue payment links, or no store is connected. Use cash on delivery or bank transfer, or connect a store. |
| "Getting shipping methods from your store" never finishes, or **Couldn't get shipping methods from your store** | The store connection is not ready. Check **Integrations** and reconnect if needed. See [Integrations troubleshooting](https://docs.trypopcorn.ai/integrations/troubleshooting.md). |

## Related

* [Orders](https://docs.trypopcorn.ai/orders/overview.md) for the order list, statuses and where orders appear in your store
* [Workspace settings](https://docs.trypopcorn.ai/settings/workspace.md) for **Default currency**, quantities and custom options
* [Capabilities](https://docs.trypopcorn.ai/agents/capabilities.md) for the agent's **Take orders in chat** and **Track orders** switches


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.