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

# Integrations & Orders Inbox

> Connect Bodha Route Planner to your accounting systems, spreadsheets, storefronts, and custom tools.

> [!NOTE]
>
> Integrations and the Orders Inbox are available on the **Pro** plan.

## Overview

Bodha Route Planner connects to your existing business tools so orders flow directly into your **Orders Inbox** — geocoded, matched to customers, and ready to plan into routes. No manual re-entry, no copy-pasting, no spreadsheet juggling.

Every integration follows the same pattern:

1. **Connect** a data source (CRM, spreadsheet, e-commerce store, or API)
2. **Map your fields** — tell Bodha Route Planner which fields correspond to address, customer name, order reference, etc.
3. Orders **sync automatically** on a schedule (or on demand)
4. Orders land in your **Orders Inbox** with status: ready or needs review
5. **Select orders** and plan them into routes
6. Delivery status **writes back** to the source system (where supported)

To manage integrations, go to **Settings → Integrations** or visit the **Integrations** page from the main navigation.

***

## Live integrations

These integrations are available today.

***

### Method CRM

> **[Full Method CRM setup guide →](https://help.bodharouteplanner.com/help/integration-method-crm.md)**
>
> Detailed walkthrough: API key, field mapping, write-back verification, troubleshooting, and limits.

> [!NOTE]
>
> **Category:** Accounting & CRM · **Setup time:** \~5 minutes · **Sync:** Every 15 minutes

Turn QuickBooks invoices into planned delivery routes. Every invoice you raise in Method CRM becomes an order in your Bodha Route Planner inbox — geocoded, matched to a customer, and ready to plan. When the driver delivers, the invoice updates itself, so nobody reconciles deliveries against paperwork by hand.

#### How to connect

1. In **Method CRM**, go to **Integrations → API** and generate an API key. The key does not expire.
2. In Bodha Route Planner, go to **Integrations → Method CRM** and click **Connect**.
3. Paste your Method API key. It's encrypted on our side and never shown again — not even to you.
4. **Map your fields** — Bodha Route Planner reads one real invoice and shows you its actual fields with live values beside them. Map each field to the corresponding Bodha Route Planner field. Nothing is typed from memory — you see real data.
5. Set a **start date** and a **filter** for what counts as deliverable, so only relevant invoices arrive.
6. Click **Save**. Orders start syncing within 15 minutes.

#### Data mapping

| Method CRM field | Bodha Route Planner field | Notes |
| - | - | - |
| ShipAddress fields | Delivery address | Falls back to the bill-to address when ship-to is blank |
| ShipDate / DueDate | Deliver-by date | Read as a deadline, not a fixed day |
| Customer | Customer | Matched on the Method record ID, then phone or email |
| RefNumber | Order number | |
| RecordID | Reference ID | How the integration finds the invoice again to update it |
| TotalAmount | Order value | |
| Memo | Notes | |

#### Write-back

When a stop is completed or failed, the following data is written back to Method CRM:

* Delivery status (completed / failed)
* Date and time of delivery
* Tracking link
* Failure reason (if applicable)

Write-back goes into **Method-only custom fields** that you choose during setup. Your QuickBooks data is never modified — the integration refuses to write to any QuickBooks-owned field (balances, totals, dates, addresses), even if one is mapped by mistake.

> [!WARNING]
>
> Write-back stays off until you map the target fields and the integration verifies the write lands correctly. This prevents accidental changes to your accounting data.

#### Limits and notes

* Syncs every 15 minutes (Method CRM has no webhooks, so real-time sync isn't possible). Press **Sync now** at any time for an immediate pull.
* **One connection per organization.** Multi-account support is not yet available.
* Works best if you raise the invoice before you deliver, not after.
* Old invoices are not imported — only records from your chosen start date forward.

> **Where do I find my Method API key?**
>
> In Method CRM, open **Integrations → API** and generate a key. It does not expire. Paste it once in Bodha Route Planner.

> **Will this change my QuickBooks data?**
>
> No. The integration only writes to Method-only custom fields that you nominate. It will not write to any QuickBooks-owned field.

> **What if an address is wrong or missing?**
>
> The order still arrives in your inbox — flagged for review with the reason. Nothing is silently dropped. Fix the address in the inbox and the fix survives the next sync.

> **Will it import years of old invoices?**
>
> No. You set a start date when you connect, so only work from that point forward arrives.

***

### Google Sheets

> **[Full Google Sheets setup guide →](https://help.bodharouteplanner.com/help/integration-google-sheets.md)**
>
> Detailed walkthrough: sharing, column mapping, deduplication, date formats, troubleshooting, and limits.

> [!NOTE]
>
> **Category:** Spreadsheets · **Setup time:** \~3 minutes · **Sync:** Periodic re-read

Rows in a shared Google Sheet become orders in your Bodha Route Planner inbox. This is the catch-all for work that arrives by phone, WhatsApp, or email and gets typed into a spreadsheet — it replaces the daily export-and-upload grind entirely.

#### How to connect

1. In Bodha Route Planner, go to **Integrations → Google Sheets** and click **Connect**.
2. You'll see a **service address** (an email address). Copy it.
3. In Google Sheets, **share your sheet** with that service address. Viewer access is enough.
4. Back in Bodha Route Planner, paste the sheet URL and select the tab to sync.
5. **Map your columns** — tell the integration which column is the address, the date, the name, the phone number, etc.
6. Click **Save**. Click **Sync now** to pull in orders immediately.

#### Data mapping

| Google Sheets column | Bodha Route Planner field | Notes |
| - | - | - |
| Address column | Delivery address | Geocoded automatically |
| Date column | Deliver-by date | Read as a deadline |
| Name / phone / email | Recipient and customer match | |
| Order ID column | Reference ID | Strongly recommended — see FAQ |
| Parcels / weight columns | Load (for capacity planning) | |

#### Limits and notes

* **Read-only** — Bodha Route Planner never modifies your sheet.
* The entire sheet is re-read each sync. Very large sheets (thousands of rows) may take longer.
* Your team keeps editing the sheet as usual — Bodha Route Planner picks up new and changed rows on each sync.

> **Why does it want an order ID column?**
>
> The order ID is how the integration tells whether a row is new or one you edited. With an ID column, editing an address updates the existing order. Without one, the integration fingerprints the row, so editing an address may look like a brand-new order.

> **Do I have to keep the sheet open?**
>
> No. Bodha Route Planner reads it on a schedule from the server side. The sheet can be closed.

> **What if I delete a row?**
>
> Orders already created stay in the inbox — they may already be planned onto a route. Cancel them in the inbox if they're not going out.

***

### REST API & Webhooks

> [!NOTE]
>
> **Category:** Developer · **Setup time:** \~2 minutes · **Requires:** Pro plan

For developers and technical teams: generate a scoped API key, call the REST API to read routes, create orders, and update stops — and register webhook endpoints to receive real-time callbacks when delivery events happen.

#### How to connect

1. Go to **Integrations → API & Webhooks**.
2. Click **Create API Key**.
3. Choose which **scopes** the key may access (e.g. `routes:read`, `orders:write`).
4. Copy the key — it's shown **only once**.
5. Use the key as an `X-API-Key` header or `Bearer` token in your API calls.
6. Optionally, add a **webhook endpoint** — tell Bodha Route Planner where to POST when events happen.

#### What you can do

| Action | How |
| - | - |
| Read routes and stops | `GET /api/v1/routes`, `GET /api/v1/stops/:id` |
| Create orders | `POST /api/v1/orders` with address, contact, promise, parcels |
| Update stops | `PATCH /api/v1/stops/:id` |
| Manage customers | `GET`, `POST`, `PATCH`, `DELETE /api/v1/customers` |
| Receive events | Webhook POSTs for route dispatched, stop delivered, stop failed |

#### Webhook events

| Event | When it fires |
| - | - |
| `route.dispatched` | A route is sent to drivers |
| `stop.delivered` | A stop is marked as delivered (with proof of delivery if collected) |
| `stop.failed` | A stop is marked as failed (with failure reason) |

#### Webhook security

Each webhook endpoint has a **signing secret**. Bodha Route Planner sends an HMAC-SHA256 signature in the `X-Bodha-Signature` header. Verify it against the raw request body before processing — this ensures the webhook came from Bodha Route Planner, not a third party.

#### Limits and notes

* API keys are **scoped** — a key with `routes:read` cannot write orders. Create separate keys for separate systems.
* **Rate-limited** per key. Audit logs track every call.
* Multiple API keys supported — use different keys for different environments (dev, staging, production).

See the [API Reference](https://help.bodharouteplanner.com/api-reference/introduction.md) for full endpoint documentation, request/response examples, and error codes.

***

## Coming soon

These integrations are planned but not yet built. **Request one to move it up the build list** — every request is counted against the account that made it, and that count is what decides the build order.

You can request any of these from the **Integrations** page in your dashboard. In the meantime, export a spreadsheet from any of these systems and import it into your Orders inbox — the column mapping is remembered, so repeat imports take seconds.

| Integration | Category | What it will do |
| - | - | - |
| **QuickBooks** | Accounting | Invoices and sales receipts as delivery orders, with delivery status written back |
| **Xero** | Accounting | Xero invoices as delivery orders. *Note: Xero's API does not expose a per-invoice delivery address — only the customer's default address. If you use Method CRM with Xero behind it, connect Method instead.* |
| **Shopify** | E-commerce | Storefront orders auto-arrive; marking a stop delivered fulfils the Shopify order with a tracking link |
| **WooCommerce** | E-commerce | WordPress store orders synced to inbox; order status and tracking written back |
| **Airtable** | Spreadsheets | Base/view rows synced as orders with record ID deduplication |

> [!NOTE]
>
> Need an integration we don't have yet? Request it from the Integrations page or contact [support@bodharouteplanner.com](mailto:support@bodharouteplanner.com).

***

## The Orders Inbox

The Orders Inbox is your central queue for incoming work from **all sources** — integrations, API, manual entry, and spreadsheet imports.

### Order statuses

| Status | Meaning |
| - | - |
| **Ready** | Address geocoded, all required fields present — ready to add to a route |
| **Needs review** | Address couldn't be geocoded or required fields are missing — fix before planning |
| **Assigned** | Added to a route |
| **Completed** | Delivery is done |
| **Cancelled** | Order was cancelled |

### Working with orders

1. **View all orders** — Filter by status, date, source, or search by reference / customer name.
2. **Fix issues** — Click orders in "Needs review" to correct the address or fill in missing fields. Bodha Route Planner re-geocodes automatically when you save.
3. **Add to route** — Select one or more orders and click **Add to Route**. Choose an existing route or create a new one.
4. **Manual orders** — Click **Create Order** to add one manually, or paste addresses to bulk-add.

### Deduplication

Bodha Route Planner automatically detects duplicate orders based on the external reference ID. If the same order comes in from your integration twice, it updates the existing order instead of creating a duplicate. This is why setting an Order ID / Reference ID column is strongly recommended for all integrations.

***

## Integration settings

For each connected integration, you can configure:

| Setting | Description |
| - | - |
| **Field mapping** | Map source fields to Bodha Route Planner order fields |
| **Sync frequency** | How often to pull new orders (varies by integration) |
| **Auto-geocode** | Automatically geocode addresses on import (on by default) |
| **Write-back** | Send delivery status back to the source system (where supported) |

***

## Troubleshooting

> **Orders are stuck in 'Needs review'**
>
> The address couldn't be geocoded. Open the order, check the address for typos or missing details (city, postal code), fix it, and save. Bodha Route Planner re-geocodes the address automatically.

> **Sync isn't picking up new orders**
>
> Check that:
>
> 1. The integration is still **connected** (not in error state)
> 2. New rows/records exist in the source since the last sync
> 3. The field mapping is correct — especially the address field
>
> Click **Sync now** to trigger an immediate sync and check the results.

> **Duplicate orders appearing**
>
> Make sure your source data has a unique reference ID field mapped to Bodha Route Planner's **Reference ID** field. Without a reference ID, each sync may create new orders instead of updating existing ones.

> **Write-back isn't working (Method CRM)**
>
> Write-back must be explicitly enabled after field mapping. Check that:
>
> 1. You've mapped the write-back target fields in Method CRM
> 2. The integration verified the write landed correctly during setup
> 3. The Method API key is still active and has write permission


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