Wave

Manage Wave businesses, customers, products, accounts, sales taxes, and invoices

Connect Wave when a project needs customer, catalogue, invoice, or accounting data from a Wave business. A Swarmz administrator configures the shared OAuth application once. Each workspace then authorises its own Wave account, so the administrator's client credentials identify Swarmz but don't grant access to every user's business data.

Wave remains hidden from normal Swarmz users until the OAuth application is verified and an administrator turns on its visibility. Connections belong to the workspace and can be linked to projects. This release supports shared project connections; it doesn't ask every user of a published app to connect a separate Wave account.

Before you configure Wave

Wave's public API allows an OAuth user to grant businesses with an active Wave Pro or Wave Advisor subscription. Confirm the test business is eligible before you configure the app. See Wave's OAuth guide and API reference for the current provider setup and schema.

Configure the OAuth application

Open Admin > Settings > Managed connector apps.
Select Wave.
Copy the Callback URL from Swarmz into the Wave OAuth application.
Enter the application's client ID and client secret.
Select Test & save, authorise an eligible Wave business, then enable the OAuth app.
Turn on Wave visibility for Swarmz users.

The client secret is write-only. Swarmz stores it server-side and uses it for OAuth code and refresh-token exchanges. Removing or disabling the OAuth app blocks new connections; each workspace's Wave grant remains a separate encrypted record.

Available operations

Area	Read operations	Write operations	Limit per minute
User and businesses	`get_user`, `list_businesses`, `get_business`	None	30
Customers	`list_customers`, `get_customer`	`create_customer`, `update_customer`	30 read, 10 write
Products	`list_products`	`create_product`, `update_product`, `archive_product`	30 read, 10 write
Accounting reference	`list_accounts`, `list_sales_taxes`	None	30
Invoices	`list_invoices`, `get_invoice`	`create_invoice`, `update_invoice`, `approve_invoice`, `mark_invoice_sent`, `send_invoice`	30 read, 10 write

Swarmz owns every GraphQL document. Project code supplies only validated variables; it can't submit a custom query, endpoint, URL, or header. Requests use https://gql.waveapps.com/graphql/public, are limited to 128 KB, and time out after 10 seconds. Responses are limited to 2 MB.

Read permission requests user:read, business:read, customer:read, product:read, account:read, invoice:read, and sales_tax:read. Write permission adds customer:write, product:write, invoice:write, and invoice:send. Wave write scopes don't replace the corresponding read scopes.

Connect a Wave account

In Settings > Integrations, select Wave, then select Connect new.
Enter a name that identifies the business or test environment.
Choose read permission for dashboards and lookup tools. Add write permission for customers, products, or invoices.
Complete Wave's consent screen and choose an eligible business.
Link the connection to the project when the AI requests it.

Swarmz stores the resulting access and refresh tokens server-side. Reauthorise the connection if the grant is revoked or Wave rejects its refresh token.

Build with Wave

Describe the business workflow and the exact point where a write is allowed. For example:

“Use Wave to build a customer directory that searches customers and lets an approved user create or update one.”
“Build a product catalogue from Wave and allow an administrator to create, update, or archive a product.”
“Create an accounting reference screen that lists the business's accounts and sales taxes.”
“Build an invoice workspace that creates a draft, approves it after review, and sends it only after a separate confirmation.”
“Show invoice status and totals, then let a user mark an externally delivered invoice as sent.”

The AI requests the Wave connection when it reaches the first accounting operation. Reads run immediately during a build. Writes pause for approval and still depend on the scopes granted during OAuth consent.

Test Wave

Use a test business and disposable records for write checks.

Run get_user, list businesses, and open the selected business. Confirm the returned IDs and names.
List customers, open one customer, create a disposable customer, then update it.
List products, create a disposable product, update it, then archive it.
List accounts and sales taxes. Confirm several IDs and names against Wave before using them in an invoice payload.
Create a draft invoice for the disposable customer and product, then read it back.
Update and approve the draft. Test mark_invoice_sent only for an invoice delivered outside Wave.
Test send_invoice with an address you control and confirm the status in Wave.

If reads work and writes fail, reconnect with write permission and confirm the OAuth application includes the matching write scopes. If the client secret may have leaked, rotate it in Wave, then enter the replacement in Managed connector apps and run Test & save again.