Connect QuickBooks: push records on a transition

Audience: power users (Pro+) · Recipe: Push a record into QuickBooks automatically when it reaches a state.

What you'll build

By the end of this recipe, moving an order from one state to another in FastYoke will create a matching invoice in QuickBooks Online — no export, no CSV, no copy-paste. When an operator drags an order to Invoiced on the board (or clicks the transition button), FastYoke reaches into your connected QuickBooks company, finds or creates the customer, and posts an invoice for the order total. Move that same order to Paid and FastYoke records a payment against the invoice it already created.

The whole thing is driven by your workflow. There is no separate "sync now" button and no scheduler polling for changes. The push is a side-effect of the state transition itself: the record reaches the state you nominated, and the push fires. It is one-directional — FastYoke writes to QuickBooks, never the reverse — because QuickBooks stays the system of record for your books. FastYoke only holds the connection tokens, an id-mapping ledger, and the status of each push.

Before you start

You'll need a few things in place:

• The QuickBooks connector enabled for your tenant. It's a Marketplace add-on gated behind a Pro-or-above plan. If you don't see the QuickBooks card in Settings, it isn't enabled yet — an admin can add it from the Marketplace, or ask your account owner.
• A QuickBooks Online company you can authorize. The connector uses the standard Intuit OAuth consent screen, so you sign in as yourself and grant FastYoke access to one company (Intuit calls this the realm).
• An app with a workflow and a money field. This recipe assumes an order-shaped entity — something with a numeric total and either a linked customer or an inline customer name and email. A CRM sales app or any app whose records carry a total field works out of the box.

Everything below happens inside your own tenant. The connection, the tokens, the field mapping, and every pushed invoice are scoped to your tenant and no other — the same isolation guarantee that applies to the rest of your data.

Steps

1. Connect your QuickBooks company

Open Settings and find the QuickBooks connector card, then start the connect flow. FastYoke hands you off to Intuit's OAuth consent screen. Sign in, pick the company you want FastYoke to write to, and approve access. Intuit redirects you back to FastYoke, which exchanges the authorization code for an access token and a refresh token, encrypts both, and stores them against your tenant along with your company's realm id.

You'll land back on Settings with the connector showing connected. FastYoke records whether the connection is against a QuickBooks sandbox or production environment based on how your deployment is configured, so a test connection is clearly labeled as such. The refresh token rotates on its own — the connector refreshes the access token when it's near expiry and writes the rotated pair back — so a healthy connection stays connected without you touching it again.

2. Map your workflow to QuickBooks

With the company connected, tell FastYoke which transition should push and what to push. In the connector's configuration you choose three things:

• The workflow (schema) whose transitions should drive pushes. Only records governed by this workflow are considered — every other app in your tenant is untouched.
• The invoice state. When a record lands in this state, FastYoke posts an invoice. Pick the state that means "this order is billable" — often something like Invoiced or Confirmed.
• The payment state. When a record lands here, FastYoke records a payment against the invoice it previously created for that record. Pick the state that means "money received" — often Paid or Closed.

You also nominate the amount field — the field on the record that holds the total to bill. It defaults to total, so if your entity already has a total field you can leave it. FastYoke validates your two state names against the workflow when you save: pick a state the workflow doesn't define and the save is rejected, so you can't wire a push to a state that can never happen.

Under the hood the amount is read straight off the record's payload, and the customer comes from a linked crm_customer_id if the record has one, or from inline customer_name / customer_email fields if it doesn't. Either way FastYoke keys its customer map so the same customer is reused rather than duplicated on the next push.

3. Fire it from a transition

Now do the thing. Take an order through your workflow until it reaches the invoice state — via the board, the detail view, or a bulk transition, it doesn't matter which. The moment the transition commits, FastYoke:

1. Finds or creates the customer in QuickBooks. If the record's email matches an existing QuickBooks customer, FastYoke adopts it; otherwise it creates one. It also ensures a generic "FastYoke Sales" service item exists to hang the line on.
2. Posts an invoice for the record's amount, tagged with the FastYoke job id in the memo so you can trace it back.
3. Records the QuickBooks invoice id against the record so it never double-posts.

Move the same order to the payment state and FastYoke records a payment against that invoice. Both operations are idempotent: if a record is already invoiced, re-entering the state is a no-op, and a payment only posts once. The push runs after the transition commits and is deliberately best-effort — if QuickBooks is slow or rejects the write, your transition still succeeds and the failure is recorded rather than rolling back your workflow. You can review the push history and retry any failed push from the connector, so a transient QuickBooks hiccup never leaves an order silently unbilled.

Take it further

The single-connection setup is the whole story for most teams, but the pattern scales:

• Validate before you go live. If your operator has configured a QuickBooks sandbox environment, use it to tune your state mapping and confirm the invoices look right before pointing the connector at production — so nothing about your testing touches your real books.
• Combine with an approval gate. Put an approval step in front of your invoice state so a manager signs off before anything hits QuickBooks. The push only fires on the state that actually commits, so an order parked awaiting approval never bills — it bills the instant approval lands it in the invoice state.
• Fan out with webhooks. QuickBooks is one destination. If you also need to notify a Slack channel or a downstream system on the same transition, fire an outbound webhook on state change alongside the QuickBooks push — same trigger, many consumers.

Related

• Fire a webhook when a record changes state — the same on-transition side-effect pattern, pointed at any HTTP endpoint.
• Add an approval gate to a workflow — hold a record before it reaches the state that bills.
• Bulk-transition records — move many orders into the invoice state at once.
• Marketplace → the QuickBooks connector listing, to enable it for your tenant.