Shopify QuickBooks integration

What moves between Shopify and QuickBooks

Shopify takes the order and the money. QuickBooks Online keeps the books, and on the Plus and Advanced plans it can count stock. Most of the flow goes one way: from Shopify into QuickBooks.

A sales receipt records sale and payment together. It fits a card or wallet payment at checkout. An invoice fits a B2B order on 30-day terms: it stays open until the payment arrives and is applied to it.

Which system owns what

What Shopify and QuickBooks store differently

Variants and items

QuickBooks has no variants. A Shopify product with 3 colors and 4 sizes is 12 items in QuickBooks. Item Name is required, at most 100 characters, and unique across all items; Sku is optional, also 100 characters. Two products both called Classic Tee with a variant Black / M would produce the same name, so the integration builds names from a rule that cannot collide and keeps a map of Shopify variant ID to QuickBooks item ID. A product renamed in Shopify does not create a new item.

Customers and names

DisplayName must be unique across all customers, vendors and employees. A web buyer called Jane Miller cannot be created when Jane Miller is already a vendor; QuickBooks answers with error 6240, Duplicate Name Exists. The integration matches on email first, then creates the customer with a suffix when the name is taken. Company buyers become customers, their locations sub-customers, up to four levels under a parent. More in duplicate customers and orders.

Sales tax

US companies created after November 10, 2017 use automated sales tax. QuickBooks then calculates tax from the company's legal address and the transaction's ship-to address, and replaces tax codes an app assigns. Shopify calculated tax at checkout with its own rules. A local pickup order without a shipping address is taxed by QuickBooks at the company address; Shopify may have charged something else. So the integration supplies TxnTaxDetail.TotalTax and TxnTaxCodeRef at creation, which QuickBooks honors and spreads over the rates of that tax code. US transaction lines are always tax-exclusive; sending GlobalTaxCalculation on a US company is an error. Outside the US the same field is required, with TaxExcluded or TaxInclusive.

Rounding is the second difference. QuickBooks keeps UnitPrice to 7 decimals and rounds the line to 2. Intuit's own example at 12 percent: a unit price of 37.37499999 gives a line of 37.38 and tax of 4.49; the line entered as 37.37 gives tax of 4.48. The integration sends line amounts exactly as Shopify charged them. Background in money, tax and rounding.

Numbers, addresses, locations

DocNumber holds 21 characters; a prefix such as SHOP- leaves room for Shopify's order numbers and keeps them apart from invoices typed by hand. A number that is already used returns 6140, Duplicate Doc Num. Countries go in as ISO alpha-3 or a full name, so Shopify's US becomes USA. A QuickBooks location is a Department: a tag for reporting by store or region, not a place where stock is kept.

The technical reality of this pair

Payout, worked through. A payout covers three orders of 120.00, 85.00 and 45.00. Fees on the three charges are 3.62, 2.77 and 1.61, together 8.00. The bank receives 250.00 minus 8.00, which is 242.00. In QuickBooks the three sales receipts sit in Undeposited Funds at 250.00. The deposit links all three and adds a line of minus 8.00 on the merchant fees account, so it totals 242.00, the bank line to the cent:

{
  "DepositToAccountRef": { "value": "35", "name": "Checking" },
  "Line": [
    { "Amount": 120.00, "LinkedTxn": [{ "TxnId": "1501", "TxnType": "SalesReceipt", "TxnLineId": "0" }] },
    { "Amount": 85.00, "LinkedTxn": [{ "TxnId": "1502", "TxnType": "SalesReceipt", "TxnLineId": "0" }] },
    { "Amount": 45.00, "LinkedTxn": [{ "TxnId": "1503", "TxnType": "SalesReceipt", "TxnLineId": "0" }] },
    { "Amount": -8.00, "DetailType": "DepositLineDetail",
      "DepositLineDetail": { "AccountRef": { "value": "92", "name": "Merchant fees" } } }
  ]
}

The figures come from the payout's balance transactions, which carry amount, fee and net for each charge and refund. Refunds and adjustments in a payout are handled the same way, as further lines. Reading them needs the view_payouts permission.

Volume. 2,000 orders on a sale day, each with a customer lookup and a sales receipt, are 4,000 requests. At 10 per second that is under 7 minutes of API time. The QuickBooks limit is not the problem. A token is: the refresh token changes value every 24 hours and expires after 100 days without use, after which someone has to authorize the app again. The integration stores every new value and refreshes on schedule.

Webhooks and polling. QuickBooks expects an answer within 3 seconds and may deliver events out of order. Intuit's own advice is a cdc call back to the last processed event, plus a daily one. We do both. The Shopify side is in Shopify API rate limits.

Where standard connectors stop

Standard connectors and iPaaS templates post orders into QuickBooks with fixed settings. The data model above shows where those settings run out:

• Tax recalculated. Without TotalTax in the request, automated sales tax recalculates every order, and pickup orders and tax-exempt customers come out different from Shopify.
• Payouts. Gross receipts without a deposit built from the payout leave a bank line that matches nothing.
• Names. Variant names that collide, and buyers whose name is already a vendor, stop on 6240 one by one.
• Desktop. For QuickBooks Desktop the Web Connector decides when data moves: on its schedule, and only while the machine runs. See integrating a system without an API.

A built integration follows your chart of accounts and your accountant's choices: per order or per day, which account takes fees, which class takes which channel.

When it goes wrong

Writes carry a request ID, so a retry after a timeout is recognized as the same request instead of a second sales receipt. A record that still fails is kept with its payload and sent again once the cause is fixed. Before go-live the integration runs as a dry run against a QuickBooks sandbox company and shows the receipts, invoices and deposits it would create; after that every run leaves a diff per record. This is part of every e-commerce ERP integration we build. QuickBooks itself is covered on the QuickBooks page and Shopify on the Shopify page; for a full ERP behind Shopify see Shopify ERP integration and Shopify Acumatica integration. Tell us how your accountant wants Shopify booked.