Wave Financial API Integration Guide (In-Depth)

Wave Financials is a comprehensive, cloud-based accounting and financial management platform designed specifically for small businesses, freelancers, and entrepreneurs. As a completely free core accounting software (with paid add-ons for payments, payroll, and coaching), Wave has gained significant traction among businesses seeking strong financial tools without the high costs associated with traditional accounting software.

Wave's API ecosystem empowers developers to automate accounting workflows, synchronize financial data, and build custom integrations that extend Wave's capabilities. 

In this guide, you will learn everything about integrating with Wave Financials API, from authentication and setup to real-world use cases and best practices for 2025.

What is Wave Financials and Why It Matters

Wave Financials is a complete suite of financial tools, including accounting, invoicing, receipt scanning, and payment processing, all accessible through a modern, intuitive interface. Unlike many accounting platforms that charge monthly fees, Wave offers its core accounting features completely free, making it particularly attractive for startups and small businesses.

What Wave Financials Does

Why Wave Financial Matters to Small Businesses

Wave has revolutionized small business accounting by removing cost barriers while maintaining enterprise-level functionality. Here's why it matters:

1. Zero-Cost Accounting: Wave provides completely free accounting software with no limitations on users, transactions, or businesses. This democratizes professional accounting tools for businesses of all sizes.

2. All-in-One Financial Hub: By combining invoicing, payments, accounting, and payroll in one platform, Wave eliminates the need for multiple disparate systems, reducing complexity and improving data accuracy.

3. Mobile-First Approach: With powerful mobile apps for iOS and Android, Wave enables business owners to manage finances on the go, scanning receipts, sending invoices, and viewing reports from anywhere.

4. Automated Bank Reconciliation: Wave's bank connection technology automatically imports and categorizes transactions, saving hours of manual data entry each month.

5. Professional Invoicing: Even free users get access to professional, customizable invoice templates with automatic payment reminders and online payment options.

Important Terminology for Wave Financials API

Before integrating with Wave Financials API, understanding these key terms is essential:

• Business: In Wave, each business is a separate entity with its own chart of accounts, transactions, and settings. API requests typically target a specific business.
  
  
• Client ID & Client Secret: Credentials obtained when registering your application in the Wave Developer Portal, used for OAuth 2.0 authentication.
  
  
• OAuth 2.0: The authentication framework used by Wave's API to securely grant applications access to user data without sharing passwords.
  
  
• Access Token: Short-lived token (typically 2 hours) included in API request headers to authenticate your application.
  
  
• Refresh Token: Long-lived token used to obtain new access tokens without requiring user re-authentication.
  
  
• Scopes: Permissions your application requests during OAuth, such as accounting:read or transactions:write.
  
  
• Webhooks: Event notifications sent by Wave to your application when specific changes occur in a user's account.
  
  
• Business Currency: The primary currency for a Wave business, affecting how amounts are displayed and processed.

Wave Financials API Integration Use Cases

The Wave Financials API enables businesses to connect their accounting data with e-commerce platforms, CRM systems, custom applications, and financial analysis tools. These integrations automate workflows, reduce manual data entry, and provide real-time financial insights.

1. E-commerce Order to Invoice Automation

Online retailers using platforms like Shopify, Etsy, or WooCommerce can automatically create Wave invoices when orders are placed. This eliminates manual invoice creation and ensures accurate revenue tracking.

How It Works:

• When a customer completes a purchase, your integration creates a customer in Wave (if new) and generates an invoice
• The invoice includes line items, taxes, and shipping costs from the order
• Payment status updates automatically when the customer pays through your e-commerce platform
• Inventory adjustments can trigger COGS (Cost of Goods Sold) journal entries

2. Expense Management Integration

Businesses using expense management tools like Expensify, Rydoo, or mobile receipt scanning apps can sync expenses directly to Wave for categorization and reporting.

How It Works:

• Employee-submitted expenses automatically create bills or expense transactions in Wave
• Receipt images are attached to transactions for audit trails
• Approval workflows in expense tools trigger payment processing in Wave
• Categorization rules ensure consistent accounting treatment

3. Custom Financial Reporting Dashboards

Companies needing specialized financial reporting beyond Wave's built-in reports can extract data to build custom dashboards in tools like Google Data Studio, Tableau, or Power BI.

How It Works:

• Daily API calls fetch transaction data, account balances, and invoice metrics
• Data transforms into business-specific KPIs and visualizations
• Real-time dashboards show cash flow forecasts, customer payment trends, and expense analysis
• Automated reports are generated and distributed to stakeholders

4. Time Tracking to Invoice Automation

Service businesses using time tracking tools like Toggl, Harvest, or Clockify can automatically convert billable hours into Wave invoices.

How It Works:

• Time entries sync to Wave as invoice line items
• Project-based tracking links time to specific clients and projects
• Invoice generation triggers automatically at the end of billing periods
• Payment status updates reflect in both systems

5. Multi-Platform Sales Reconciliation

Businesses selling across multiple channels (in-person, online, marketplace) can consolidate all sales data into Wave for unified financial reporting.

How It Works:

• Square, PayPal, Stripe, and other payment processor transactions sync to Wave.
• Sales from different channels are categorized appropriately in the chart of accounts.
• Daily reconciliation ensures all revenue is captured accurately.
• Discrepancy alerts flag potential issues automatically.

6. Automated Accounts Payable Processing

Businesses receiving invoices from vendors via email or procurement systems can automate the accounts payable workflow in Wave.

How It Works:

• Vendor invoices captured via email parsing or API create bills in Wave.
• Approval routing happens within existing business systems.
• Upon approval, bills are scheduled for payment in Wave.
• Payment execution through connected bank accounts or Wave Payments.

Wave Financials API Architecture and Design Principles

RESTful API Design: Wave's API follows REST principles with resource-oriented endpoints using standard HTTP methods (GET, POST, PUT, DELETE).

GraphQL Alternative: Wave offers a GraphQL API alongside REST, allowing clients to request exactly the data they need in a single query.

JSON-Based Communication: All request and response bodies use JSON format, making integration straightforward across different programming languages.

Pagination Support: Lists of resources support cursor-based pagination to handle large datasets efficiently.

Rate Limiting: To ensure service stability, Wave implements rate limits on API calls, which vary based on your application's tier and user load.

Idempotency Key Support: For POST and PUT operations, you can include an idempotency key to prevent duplicate operations from network retries.

Error Handling: Comprehensive error responses include machine-readable codes and human-readable messages for debugging.

Versioning: API versioning ensures backward compatibility, with the current version indicated in endpoint URLs.

Explore the complete API architecture in the Wave API Documentation.

Secure Authentication with OAuth 2.0

Wave uses industry-standard OAuth 2.0 for secure API authentication. Here's how it works:

Application Registration: Start by creating an application in the Wave Developer Portal to obtain your Client ID and Client Secret.

Authorization Flow:

1. Redirect users to Wave's authorization endpoint
2. Users authenticate and grant permissions to your application
3. Wave redirects back with an authorization code
4. Exchange the code for access and refresh tokens

Token Management:

• Access tokens expire after 2 hours
• Refresh tokens (with offline_access scope) allow obtaining new access tokens without user interaction
• Always store tokens securely and never expose them client-side

Scope Definitions:

• accounting:read - Read accounting data
• accounting:write - Write accounting data
• transactions:read - Read transactions
• transactions:write - Write transactions
• user:read - Read user profile
• offline_access - Get refresh tokens for long-term access

For implementation details, see the Wave OAuth 2.0 Guide.

Wave Financials API Documentation Overview

The Wave Financials API provides programmatic access to all core accounting functions. Whether you're building an integration for invoicing, expense tracking, or financial reporting, Wave's API offers the endpoints you need.

API Categories and Core Functions

Endpoint Structure

Wave's REST API follows a consistent structure:

Base URL:

https://api.waveapps.com/{version}/

Current Version: Most endpoints use /v1/ as the current stable version.

Example Endpoints:

Get all businesses for a user:

GET https://api.waveapps.com/v1/businesses/

Create a new invoice:

POST https://api.waveapps.com/v1/businesses/{business_id}/invoices/

Retrieve customer list:

GET https://api.waveapps.com/v1/businesses/{business_id}/customers/

GraphQL API Alternative

For more complex data requirements, Wave offers a GraphQL endpoint:

POST https://gql.waveapps.com/graphql

This allows you to request multiple resources in a single query and receive exactly the fields you need.

Key API Endpoints and Data Models

Wave exposes comprehensive endpoints for all accounting functions. Here are the most commonly used ones:

Here is the information formatted into a clean table:

Important Data Models

Invoice Model Example:

{
  "id": "abc123",
  "created_at": "2024-01-15T10:30:00Z",
  "modified_at": "2024-01-15T10:30:00Z",
  "invoice_number": "INV-001",
  "customer": {
    "id": "cust_123",
    "name": "Acme Corp"
  },
  "due_date": "2024-02-14",
  "amount_due": {
    "raw": 1000.00,
    "value": "1000.00",
    "currency": "USD"
  },
  "status": "SAVED",
  "items": [
    {
      "product": {
        "id": "prod_456",
        "name": "Consulting Services"
      },
      "quantity": 10,
      "price": 100.00
    }
  ]
}

Transaction Model Example:

{
  "id": "txn_789",
  "date": "2024-01-15",
  "description": "Office supplies purchase",
  "amount": -250.00,
  "balance": 12500.00,
  "account": {
    "id": "acc_101",
    "name": "Office Expenses"
  }
}

Authenticating to Wave Financials API

Follow these steps to authenticate your application with Wave's API:

Step 1: Register Your Application

1. Visit the Wave Developer Portal
   
   
2. Sign in with your Wave account (or create one)
   
   
3. Click "Create New App"
   
   
4. Fill in:
   
   • App Name: Your integration's name
   • Description: What your app does
   • Website URL: Your application's website
   • Redirect URI: Where Wave should redirect users after authorization
     
     
5. Click "Create App" and note your Client ID and Client Secret

Step 2: Implement OAuth 2.0 Flow

Here's a Python example of the authorization code flow:

import requests
from flask import Flask, redirect, request

app = Flask(__name__)

# Configuration
CLIENT_ID = 'your_client_id'
CLIENT_SECRET = 'your_client_secret'
REDIRECT_URI = 'https://yourapp.com/callback'
WAVE_AUTH_URL = 'https://api.waveapps.com/oauth2/authorize/'
WAVE_TOKEN_URL = 'https://api.waveapps.com/oauth2/token/'

@app.route('/login')
def login():
    # Redirect user to Wave for authorization
    auth_url = (
        f"{WAVE_AUTH_URL}?"
        f"client_id={CLIENT_ID}&"
f"redirect_uri={REDIRECT_URI}&"
        f"response_type=code&"
        f"scope=accounting:read accounting:write"
    )
    return redirect(auth_url)

@app.route('/callback')
def callback():
    # Exchange authorization code for tokens
    code = request.args.get('code')
    
    token_data = {
        'client_id': CLIENT_ID,
        'client_secret': CLIENT_SECRET,
        'code': code,
        'grant_type': 'authorization_code',
        'redirect_uri': REDIRECT_URI
    }
    
    response = requests.post(WAVE_TOKEN_URL, data=token_data)
    tokens = response.json()
    
    # Store these securely
    access_token = tokens['access_token']
    refresh_token = tokens.get('refresh_token')
    
    return "Authentication successful!"

Step 3: Make Authenticated API Requests

Once you have an access token, include it in your API requests:

def get_businesses(access_token):
    headers = {
        'Authorization': f'Bearer {access_token}',
        'Content-Type': 'application/json'
    }
    
    response = requests.get(
        'https://api.waveapps.com/v1/businesses/',
        headers=headers
    )
    
    if response.status_code == 200:
	return response.json()
    else:
        raise Exception(f"API Error: {response.status_code}")

Step 4: Handle Token Refresh

Access tokens expire after 2 hours. Use refresh tokens to get new ones:

def refresh_access_token(refresh_token):
    token_data = {
        'client_id': CLIENT_ID,
        'client_secret': CLIENT_SECRET,
        'refresh_token': refresh_token,
        'grant_type': 'refresh_token'
    }
    
    response = requests.post(WAVE_TOKEN_URL, data=token_data)
    new_tokens = response.json()
    
    return new_tokens['access_token'], new_tokens.get('refresh_token')

Step-by-Step: Building a Wave API Integration

Integrating with the Wave API involves working with its GraphQL-based architecture, which provides flexible data querying. This comprehensive, beginner-friendly guide (updated December 18, 2025) walks you through from setup to production, based on the official Wave Developer Portal at https://developer.waveapps.com/hc/en-us.

Important Note: As of May 26, 2025, third-party applications require connected businesses to have an active Wave Pro subscription (or Wave Advisors package) for OAuth access. Personal/development use with full access tokens does not require Pro.

Step 1: Creating a Wave Account and Test Businesses

Start with a Wave account for development and testing.

Steps:

1. Sign up for a free Wave account at waveapps.com if needed (see guide: Create a Wave Account and Test Businesses).
2. In your Wave dashboard, create one or more test businesses with sample data.
3. No separate sandbox exists, use test businesses in your account for safe experimentation.

✅ You now have a Wave account ready for API work.

Step 2: Registering Your Application (Managing Applications)

Register to get credentials.

1. Visit the Wave Developer Portal: https://developer.waveapps.com/hc/en-us.
2. Sign in with your Wave account.
3. Navigate to "Manage Applications" and create a new app.
4. Provide details: App Name, Description, Website URL, and Redirect URI (HTTPS required; localhost for testing, e.g., https://localhost:3000/callback).
5. Save to generate Client ID and Client Secret—store securely.

For Quick Personal Testing: Generate a Full Access Token in the portal (full permissions to your account; development/personal use only, see Authentication).

✅ You have credentials for authentication.

Step 3: Setting Up OAuth 2.0 Authentication

Use OAuth 2.0 Authorization Code Flow for multi-user apps (required for public/published integrations).

Steps (detailed in OAuth Guide):

1. Redirect to Authorization:

GET https://api.waveapps.com/oauth2/authorize?
client_id={YOUR_CLIENT_ID}&
redirect_uri={YOUR_REDIRECT_URI}&
response_type=code&
scope={SCOPES}  // e.g., business:read invoice:write (see [OAuth Scopes](https://developer.waveapps.com/hc/en-us/articles/360032818132-OAuth-Scopes))
&approval_prompt=auto  // or 'force' to reprompt

2. User logs in, consents (only Pro businesses).

3. Redirect includes code: {YOUR_REDIRECT_URI}?code={AUTH_CODE}.

4. Exchange for Tokens:

POST https://api.waveapps.com/oauth2/token/
Content-Type: application/x-www-form-urlencoded
client_id={YOUR_CLIENT_ID}
&client_secret={YOUR_CLIENT_SECRET}
&code={AUTH_CODE}
&grant_type=authorization_code
&redirect_uri={YOUR_REDIRECT_URI}

• Response: access_token (~2 hours), refresh_token (if offline_access scoped).

5. Refresh Token: Similar POST with grant_type=refresh_token.

Tips: Use PKCE for public clients. See Permitted Use for public app requirements.

✅ Authenticated requests ready with Authorization: Bearer {ACCESS_TOKEN}.

Step 4: Understanding the API (GraphQL-Based)

Wave uses a single GraphQL endpoint: https://gql.waveapps.com/graphql/public (see Clients and Building on GraphQL).

Key Features:

• Flexible queries/mutations.
• Pagination via connections/cursors.
• Full schema in API Reference.

Tools:

• Interactive API Playground (GraphiQL): https://developer.waveapps.com/hc/en-us/articles/360018937431-API-Playground, sign in for live testing.

Step 5: Building Your Integration (with Examples)

Requests:

POST https://gql.waveapps.com/graphql/public
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

Use Case 1: List Businesses

{
  "query": "query { user { businesses(first: 10) { edges { node { id name currency { code } } } } } }"
}

Use Case 2: Create Invoice (Mutation)

See examples in portal (e.g., Mutation: Create Invoice).

Use Case 3: List Customers

Nest under business:

query {
  business(id: "Biz123") {
    customers(first: 20) { edges { node { id name email } } }
  }
}

Tips: Use variables, handle pagination/errors.

Step 6: Testing Your Integration

1. Use test businesses and Full Access Tokens for quick tests.
2. Explore in the API Playground (affects your data, use tests).
3. Test full OAuth flow.
4. Scenarios: CRUD operations, token refresh, errors.

Step 7: Moving to Production

1. For public apps: Ensure OAuth use and potential approval (contact support).
2. Require Pro for user businesses.
3. Implement logging, monitoring, rate limit handling (exponential backoff).
4. Secure tokens/URIs.

Support: Submit tickets via portal or Support Resources.

How Knit Simplifies Wave Financials Integration

Building and maintaining direct API integrations with Wave Financials requires significant development effort and ongoing maintenance. Knit provides a unified integration platform that simplifies connecting to Wave and dozens of other accounting systems through a single, standardized API.

Unified Accounting API

Instead of writing separate integration code for each accounting platform (Wave, QuickBooks, Xero, FreshBooks), Knit offers one Unified Accounting API. Your application connects once to Knit and instantly works with multiple accounting systems without additional development.

Before Knit:

// Different code for each platform
if (platform === 'wave') {
  await waveAPI.createInvoice(invoiceData);
} else if (platform === 'quickbooks') {
  await quickbooksAPI.createInvoice(invoiceData);
} else if (platform === 'xero') {
  await xeroAPI.createInvoice(invoiceData);
}

With Knit:

javascript
// Same code works for all platforms
await knitAPI.createInvoice(invoiceData);

Automated Authentication Management

Wave's OAuth 2.0 implementation requires handling authorization codes, token exchanges, refresh tokens, and secure storage. Knit manages all authentication complexity:

1. Pre-built OAuth Flow: Knit provides embeddable UI components for Wave authentication
2. Automatic Token Refresh: Knit handles token expiration and renewal automatically
3. Secure Credential Storage: Tokens encrypted with enterprise-grade security
4. Multi-tenant Support: Scale to thousands of Wave connections seamlessly

Consistent Data Model Across Platforms

Every accounting system has different data structures. Wave's invoice format differs from QuickBooks', which differs from Xero's. Knit normalizes all data into a consistent schema:

// Knit's Unified Invoice Model
{
  "id": "inv_123",
  "customer": {
    "id": "cust_456",
    "name": "Acme Corp",
    "email": "billing@acmecorp.com"
  },
  "amount": 1000.00,
  "currency": "USD",
  "status": "PAID",
  "items": [
    {
      "description": "Consulting Services",
      "quantity": 10,
      "unit_price": 100.00
    }
  ]
  // Works with Wave, QuickBooks, Xero, etc.
}

Real-Time Sync with Webhooks

Polling Wave’s API is slow, inefficient, and can cause rate-limit issues, while Knit solves this by providing real-time webhooks that instantly notify your application whenever data changes in a connected Wave account. 

This enables an event-driven architecture where new invoices, payments, or customer updates are received immediately, reducing the need for constant API calls and keeping your application data continuously up to date. You can also subscribe only to the specific events you need, making the integration more efficient and customizable.

Accelerated Development Timeline

Building a stable, production-ready Wave integration normally takes 2–3 months, but with Knit you can build, test, and deploy in just a few weeks. Knit offers pre-built, production-tested Wave connectors along with SDKs for JavaScript, Python, Ruby, PHP, and Java, plus a developer sandbox that lets you test using sample Wave data. 

Its detailed documentation, complete with API references, tutorials, and best practices, combined with dedicated technical support, significantly speeds up development and reduces engineering effort.

Scalability and Maintenance

As your platform grows and you manage hundreds or even thousands of Wave connections, maintaining performance and reliability becomes difficult. Knit handles this automatically by providing centralized connection management, built-in monitoring tools, and streamlined troubleshooting via a single dashboard.

It also ensures long-term stability by updating connectors whenever Wave changes its API and offering centralized error handling, alerting, and performance monitoring to track latency and success rates across all connections.

Cost-Effective Integration

Consider the total cost of building and maintaining a direct Wave integration:

By using Knit, you reduce development costs, accelerate time-to-market, and ensure a reliable integration that scales with your business.

Wave Financials API Integration FAQs

Q. Is Wave's API free to use?

A. Yes, Wave's API is completely free to use. There are no API call fees or subscription costs for accessing the API. You only need a Wave account (which is free for core accounting features) and to register your application in the Wave Developer Portal.

Q. What are Wave's API rate limits?

A. Wave implements the following rate limits:

• 60 requests per minute per access token
• 5,000 requests per day per application
• Additional limits may apply during peak usage periods

These limits help ensure service stability for all users. Implement exponential backoff and caching to stay within limits.

Q. Does Wave support webhooks?

A. Yes, Wave Financial supports webhooks. They use webhooks to notify your application when specific events, such as a completed checkout or a received payment, occur in your Wave account. You can subscribe to events, including:

• invoice.created, invoice.updated, invoice.paid
• customer.created, customer.updated
• transaction.created
• product.created, product.updated

Webhooks require HTTPS endpoints and support signature verification for security.

Q. Can I test the Wave API without affecting live data?

A. Yes, Wave provides a sandbox environment for testing:

1. Create a free Wave account specifically for testing.
   
   
2. Use test businesses and data.
   
   
3. Wave Payments has a sandbox mode for payment testing.
   
   
4. No real financial transactions occur in test mode.

Q. What programming languages work with Wave's API?

A. You can use any language with HTTP/JSON support. Popular choices include:

• Python (using requests library)
• JavaScript/Node.js (using fetch or axios)
• Ruby (using httparty or faraday)
• PHP (using curl or Guzzle)
• Java (using HttpClient)
• C# (using HttpClient)

Q. Where can I get help with Wave API development?

A. Several resources are available:

• Official Documentation: Wave Developer Portal
• API Reference: Complete endpoint documentation
• Community Forum: Wave Community
• GitHub Repository: Wave API Examples

Q. Does Wave have a GraphQL API?

A. Yes, Wave offers both REST and GraphQL APIs. The GraphQL endpoint is at https://gql.waveapps.com/graphql and allows you to:

• Request multiple resources in one query.
  
  
• Specify exactly which fields you need.
  
  
• Reduce over-fetching of data.
  
  
• Get real-time updates via subscriptions (where supported).

Q. How do I handle errors and debug issues?

A. Wave provides detailed error responses:

{
  "errors": [
    {
      "message": "Validation failed",
      "locations": [{"line": 2, "column": 3}],
      "path": ["createInvoice"],
      "extensions": {
        "code": "VALIDATION_ERROR",
        "field": "customer_id",
        "details": "Customer not found"
      }
    }
  ]
}

Enable logging in your application and monitor HTTP status codes, error messages, and request/response bodies for debugging.

Q. Is there a mobile SDK for Wave?

A. While Wave doesn't provide a dedicated mobile SDK, its REST API works perfectly with mobile applications. For mobile development:

• Use OAuth 2.0 with PKCE for enhanced mobile security.
  
  
• Implement token storage using platform-specific secure storage (Keychain for iOS, Keystore for Android).
  
  
• Consider using GraphQL for efficient data fetching in mobile apps.
  
  
• Test with Wave's mobile-optimized endpoints.

Wave's API continues to evolve, so always check the official documentation for the latest features and best practices.

‍