App guides
The Zoho app connects your Swell store to Zoho Books, Zoho Inventory, or both. Products and variants become Zoho items, customers become Zoho contacts, and orders reach Zoho as sales orders, then as invoices and payments once they are paid. Cancellations and refunds are reversed in Zoho.
With Zoho Inventory, Zoho becomes the place where you manage stock. Stock changes and shipments made in Zoho come back to Swell within seconds.
The app works in every Zoho data center: zoho.com, zoho.eu, zoho.in, zoho.com.au, zoho.jp, zohocloud.ca, zoho.sa and zoho.uk.
| When | What the app does |
| A product or variant is created or changed | Links it to a Zoho item, or creates the item if Zoho doesn't have one. Name, SKU and price changes are sent to Zoho. |
| An order is placed | Creates a Zoho sales order, which reserves the stock. The customer becomes a Zoho contact with their first order. |
| An order is paid | Creates an invoice from the sales order and records the payment. |
| An order is canceled or refunded | Reverses it in Zoho, depending on whether the order was paid and shipped. |
| Stock changes in Zoho | Sets the Swell stock of the items involved to Zoho's available-for-sale quantity. |
| An order is shipped in Zoho | Adds a shipment with the carrier and tracking number to the Swell order. |
Zoho sends stock changes and shipments to the app through workflow rules in your Zoho organization. The app can set these rules up for you.
Organizations with Zoho Books only get contacts, items, invoices and payments. Sales orders, stock updates and shipments need Zoho Inventory.
- A Zoho Books or Zoho Inventory organization, or both, and a Zoho user who can create API clients and approve access.
- The same currency in your Swell store and your Zoho organization. Amounts are sent without currency conversion.
- A Zoho tax for each tax rate your orders use. Each order line's tax is matched to the Zoho tax with the same rate.
- A separate Zoho organization for the test environment. Test orders create real documents in the organization they are connected to, and two environments connected to the same organization can't both receive updates from Zoho.
Install Zoho from the Swell App Store, then open Zoho in the dashboard sidebar. Set up the test environment before the live one.
Create a Zoho API client
On the Zoho page, copy the Authorized Redirect URI. Open the Zoho API Console for your data center, which the page links to, choose Add Client > Server-based Applications, give it any name and paste the redirect URI. Zoho shows a Client ID and a Client Secret.
Enter the client details
Go to Apps > Zoho > Settings, choose your Zoho data center, enter the Client ID and Client secret, and click Save settings.
Connect to Zoho
On the Zoho page, click Connect to Zoho, sign in and approve access. If your Zoho user has several organizations, pick one and click Use this organization.
The page shows whether the organization has Zoho Books, Zoho Inventory or both, and warns you if its currency differs from your store's.
Sync your catalog
Click Sync products in the Products card. The sync runs in the background, and the card shows its progress and any products Zoho rejected.
Turn on updates from Zoho
With Zoho Inventory, click Set up in Zoho in the Updates from Zoho card. Every rule should show Set up.
Place a test order
Place an order and pay for it. The order's Zoho tab shows its sales order and invoice, with links to them in Zoho. Ship the order in Zoho, and check that the shipment appears on the Swell order.
Go live
In the live environment, repeat steps 1 to 5. Its Zoho page shows its own redirect URI, and its settings and connection are separate from the test environment's.
- Products and variants are linked to Zoho items by SKU, or by exact name when they have no SKU. A product with a SKU that no Zoho item has gets a new item.
- Items that already exist in Zoho are linked without changes, and the product's Swell stock is set to Zoho's available quantity.
- Missing items are created for active products, each variant as its own item named after the product and the variant. With Zoho Inventory, stock-tracked products become stock items, with Swell's stock as their opening stock, valued at the product's regular price.
- Name, SKU and price changes are sent to Zoho. Deleting a product in Swell leaves its Zoho item in place.
- Manage stock in Zoho: receive goods, make adjustments, transfer stock and process returns there, and Swell follows. Units in Swell orders that haven't reached Zoho yet are subtracted from Zoho's number, so Swell doesn't oversell.
- Stock changed directly in Swell outside orders, such as a return put back in stock or a manual adjustment, is set back to Zoho's number.
- Line prices, discounts and shipping are sent with each order, and each line's tax is matched to the Zoho tax with the same rate.
- Customers become Zoho contacts with their first order. An existing Zoho contact with the same email is linked instead. Later changes to a customer's name, email, phone or addresses in Swell are sent to the linked contact.
- An order that can't be sent shows the reason on its Zoho tab and in the Orders card of the Zoho page, and is retried automatically: after 10 minutes, then at doubling intervals up to once a day. To retry right away after fixing the cause in Zoho, click Retry now in the Orders card.
| When | What happens in Zoho |
| Canceled before payment | The sales order is voided, which releases the stock. |
| Canceled after payment, before anything is packed or shipped | The payment is removed from the invoice, and the invoice and sales order are voided, as if the order never happened. |
| Refunded in full after items were packed or shipped | A credit note for the invoice and its refund are recorded. No stock moves. Returned goods count again when they are received in Zoho. |
With Zoho Inventory, shipping an order in Zoho adds a shipment to the Swell order, with the carrier, tracking number and service. Partial shipments are added as they happen, and a tracking number added later in Zoho updates the Swell shipment.
| Location | What it shows |
| Zoho (sidebar) | The Zoho page: the connection, the Products card with the catalog sync, the Orders card with orders waiting to retry, and the Updates from Zoho card with the status of each Zoho rule. |
| Orders list | A Zoho column with each order's sync status: Synced, In progress or Error. |
| Order > Zoho tab | The sales order, invoice and credit note with links to Zoho, whether documents were voided, the refund, the last error and when the order last synced. |
| Apps > Zoho > Settings | The Zoho API client details and what to sync. |
Settings are in Apps > Zoho > Settings and are saved separately for each environment.
| Setting | Description | Default |
| Zoho data center | The Zoho region you sign in to: US, EU, India, Australia, Japan, Canada, Saudi Arabia or UK. Decides which Zoho sign-in page and API Console the app uses. | US |
| Client ID | Client ID of your Zoho API client. | None |
| Client secret | Client secret of the same client. Changing it requires connecting again. | None |
| Products, variants and stock | Links products and variants to Zoho items and sends their changes. When off, product changes are not sent and Sync products can't be started. Stock updates from Zoho continue. | On |
| Orders, customers and payments | Sends orders, customers, invoices and payments to Zoho. When off, new orders are not sent. | On |
Turning a sync off stops it from then on. Nothing already in Zoho is changed or removed.
- Partial refunds are not sent to Zoho.
- A full refund on an order that isn't canceled records a credit note and refund, and leaves the sales order open in Zoho.
- When a partly shipped order is canceled or refunded, the credit note covers the whole invoice, and the unshipped items stay reserved on the sales order.
- Orders placed while the app is disconnected, or while order sync is off, are not sent when they are placed. Such an order is sent later if it is paid or refunded after the app is connected again.
- Bundles and gift cards are sent as text lines on orders.
- Swell stock locations aren't supported. All stock is in Zoho's default location.
- Order lines with more than one tax can't be sent.
- If an order's lines are edited in Zoho, its shipments are not added to the Swell order.
- Deleting a stock document in Zoho, such as an adjustment or a receive, doesn't update Swell until the item's stock changes again.
- The app keeps its links to items and contacts when you connect a different Zoho organization, so orders sent afterwards can fail. Keep each environment on one organization.
- Zoho's API allows 100 calls a minute per organization, and a daily number of calls that depends on your Zoho plan. The catalog sync pauses at a limit and continues by itself, and orders are retried.
- Zoho limits workflow webhook calls per day, by plan. Calls over the limit are not sent, and the Swell stock of the items involved catches up with their next stock change in Zoho.
- The client secret is visible to store admins in the app settings.
The Orders card on the Zoho page lists the most recent orders waiting to retry, with the reason. The most common cause is a missing Zoho tax for the order's tax rate. Fix the cause in Zoho, then click Retry now or wait for the automatic retry.
The Not synced list in the Products card shows the most recent products Zoho rejected, with the reason. Fix them, then click Sync again.
Check the Updates from Zoho card on the Zoho page. Click Set up in Zoho to create missing rules and update outdated ones. A rule marked Turned off in Zoho must be turned back on in Zoho. Stock and shipments need Zoho Inventory.
If the test and live environments are connected to the same Zoho organization, only the environment connected last receives updates from Zoho.
Reinstalling the app gives the Zoho page a new address. Replace the redirect URI in the Zoho API Console with the one the page shows, then click Reconnect. The app updates the Zoho rules for the new install by itself within a few minutes.
Amounts are sent without conversion, so your Swell store and your Zoho organization must use the same currency.
Uninstalling the app stops syncing in both directions. It applies to the environment you are in, so remove the app from the test and live environments separately.
Before you uninstall, click Disconnect on the Zoho page. This revokes the app's access at Zoho.
Everything the app created in Zoho stays there: items, contacts, sales orders, invoices, payments and credit notes. The app's workflow rules also stay, and keep calling Swell, which counts against Zoho's daily webhook limit. Turn them off or delete them in Zoho.
The app stores its sync state under $app.zoho on orders and shipments, and in four collections of its own.
| Field | Description |
| orders: zoho_status | Sync state of the order: synced, pending or error. |
| orders: zoho_contact_id | Zoho contact the order was sent for. |
| orders: zoho_salesorder_id, zoho_salesorder_number, zoho_salesorder_url | The Zoho sales order. |
| orders: zoho_invoice_id, zoho_invoice_number, zoho_invoice_url | The Zoho invoice. |
| orders: zoho_payment_id | The payment recorded in Zoho. |
| orders: zoho_creditnote_id, zoho_creditnote_number, zoho_creditnote_url | The credit note recorded for a refund or cancellation. |
| orders: zoho_refund_id | The refund recorded in Zoho. |
| orders: zoho_error, zoho_attempts, zoho_retry_at | The last error, the number of attempts, and when the order is retried next. |
| orders: zoho_synced_at | When the order last synced. |
| shipments: zoho_shipment_id | The Zoho shipment or package the Swell shipment was created from. |
| Collection | Description |
| apps/zoho/connections | The Zoho connection of the environment: tokens, data center and organization. |
| apps/zoho/item-links | Which Zoho item each product and variant is linked to. |
| apps/zoho/contact-links | Which Zoho contact each customer is linked to. |
| apps/zoho/webhook-events | Calls received from Zoho, processed in the background. |
Orders are sent on order.submitted, order.paid, order.canceled and order.refunded, and a job every 10 minutes retries failed orders. Product and variant events send catalog changes, and a job every minute runs the catalog sync and updates the Zoho rules after a reinstall.
Zoho's workflow rules post to https://<store-id>.swell.store/functions/zoho/zoho-webhook with three headers: Authorization, the app's public key for the environment; X-Swell-Topic, shipments or stock; and X-Swell-Token, a secret per environment. Calls with another token are rejected. The Set up by hand instead section of the Updates from Zoho card shows the values to use.
The app asks Zoho for read and write access to contacts, items, sales orders, invoices, customer payments and credit notes; read access to settings, packages and shipments; permission to create webhooks and workflow rules and update the webhooks; and permission to remove a payment from an invoice, used only to undo a paid order that is canceled before shipping.
Swell builds and maintains the Zoho app. For help with the app, email support@swell.is. For questions about your Zoho organization, plan or limits, contact Zoho.