Create a Customer Record in QuickBooks from a New Plan Subscription

When a customer subscribes to a Mantle plan (billing plan for Shopify app installations), this trigger activates the workflow and captures the customer ID and subscription event details. Mantle sends a webhook to MESA when subscriptions occur.

Setup requirement: You must have Mantle configured as your billing platform for this trigger to receive subscription webhooks.

Mantle context: Mantle is a billing platform for Shopify app developers. When merchants install apps and choose billing plans, Mantle handles the subscription and sends this webhook.

This step retrieves the full Mantle customer record using the customer ID from the subscription webhook. It returns complete customer data including customer name, email address, billing address with all components, customer notes, Shopify domain, contact information (including phone), and app installations array. This comprehensive data enables creation of detailed QuickBooks records.

This loop iterates through the customer's app installations array. For each installation, the loop executes QuickBooks lookup, branching logic, and customer creation/update steps. This approach creates separate accounting treatment for each app installation, which is useful for SaaS businesses offering multiple products.

Multi-app scenario: If a merchant installs multiple apps from the same developer (all using Mantle), this loop creates or updates QuickBooks customer records for each app, enabling app-specific revenue tracking.

This step queries QuickBooks using a SQL-like query "SELECT * FROM Customer WHERE PrimaryEmailAddr = '[customer email]'". It searches for customers matching the Mantle customer's email address and returns matching records. If a customer exists, the first result contains their QuickBooks customer ID. If no match is found, the array is empty.

This conditional path executes when {{quickbooks.0.Id}} is empty, meaning no matching customer was found in the QuickBooks query. The workflow evaluates this condition and proceeds to create a brand new customer record with the merchant's complete information. If this condition is true, the workflow creates rather than updates.

This step creates a QuickBooks customer using Mantle customer data. It includes:

1. DisplayName: Customer name from Mantle
2. PrimaryEmailAddr: Customer email address
3. PrimaryPhone: Phone number from first contact
4. BillAddr: Complete billing address including Line1 (combined address1 and address2), City, Country, CountrySubDivisionCode (country code), and PostalCode
5. Notes: Comprehensive notes including custom notes from Mantle, Shopify domain, and installation timestamp

Notes field value: The notes combine multiple data points in format: "[customer notes] \nShopify Domain: [domain]\nInstalled at: [timestamp]", providing context about the subscription for accounting reference.

The created customer is added to QuickBooks and ready for invoicing and payment tracking.

This path checks if the QuickBooks customer ID is not empty. If true (customer found), the workflow follows Path 2 which updates the existing customer. If false (no customer found), this path is skipped.

This step updates an existing QuickBooks customer using the customer ID and SyncToken from the query. It updates the same fields as the create operation plus:

1. Id: QuickBooks customer ID (required for updates)
2. SyncToken: Version token (required for QuickBooks updates to prevent conflicts)
3. sparse: Set to true (partial update mode, only updates provided fields)
4. BillAddr.Id: Existing billing address ID (required to update rather than create new address)

All other fields (DisplayName, email, phone, billing address components, notes) update with current Mantle data. The sparse mode ensures only the provided fields update without affecting other customer properties in QuickBooks.

SyncToken importance: QuickBooks requires the SyncToken for updates to ensure you're updating the current version. This prevents conflicts if multiple systems update the same customer simultaneously.