/
Documentation

Introduction to SyncBooks Add-ons

Build powerful extensions that integrate directly into the SyncBooks accounting platform. Your add-on can read data, create records, react to events, and provide custom UI — all within a secure, sandboxed environment.

New to add-on development?

If you're building your first add-on, start with the Quick Start guide to have a working add-on in 5 minutes.

What is a SyncBooks Add-on?

A SyncBooks add-on is a web application that runs inside a sandboxed iframe within the SyncBooks UI. It uses the @syncbooks/addon-sdk package to communicate with SyncBooks and access organization data through a scoped REST API.

Think of it like a Chrome extension, but for SyncBooks. Organizations install add-ons from the marketplace, grant permissions, and their team members can use them.

What Can Add-ons Do?

  • Read data — customers, invoices, products, payments, expenses, and 20+ more resource types
  • Create & update records — generate invoices, add customers, log expenses, update inventory
  • React to events — get notified via webhooks when invoices are paid, orders created, etc.
  • Show custom UI — dashboards, analytics, forms, reports in a native-looking interface
  • Send notifications — toast messages and push notifications to SyncBooks users
  • Navigate — redirect users to specific SyncBooks pages
  • Store configuration — save per-organization settings for your add-on

Full Freedom: Your Code, Your Stack, Your Database

You're not limited to our SDK

SyncBooks add-ons are your own web applications. You have complete freedom over your technology choices.

Your add-on is a regular web app that happens to run inside a SyncBooks iframe. This means:

Use any UI framework or components

  • React with Material UI, Chakra UI, Ant Design, shadcn/ui, or your own components
  • Vue with Vuetify, Quasar, or Element Plus
  • Svelte with SvelteUI or Skeleton
  • Angular with Angular Material
  • Plain HTML/CSS — no framework required at all
  • Any CSS — Tailwind, Bootstrap, custom SCSS, CSS modules, styled-components

The SDK's UI components are optional — they just help your add-on look native to SyncBooks. You don't have to use them.

Use your own backend and database

  • Your own server — Express, Django, Rails, FastAPI, Go, anything
  • Your own database — PostgreSQL, MySQL, MongoDB, Supabase, Firebase, PlanetScale
  • Your own authentication — for features outside SyncBooks (your own user accounts)
  • External APIs — WhatsApp, Twilio, Stripe, Paystack, Google, anything

The SyncBooks API is for reading/writing SyncBooks data (invoices, customers, etc.). Your add-on can have its own separate data storage for anything else — analytics, user preferences, external integrations, AI models, whatever you need.

What's required vs. optional

ComponentRequired?Purpose
SyncBooksProvider / initBridge()RequiredConnects to SyncBooks, receives auth token
SDK API clientOptionalConvenience wrapper — you can use raw fetch() with the token instead
SDK React hooksOptionalPre-built data fetching — you can use React Query, SWR, or useState+useEffect
SDK UI componentsOptionalNative-looking UI — you can use any component library or custom CSS
HTTPS hostingRequiredYour add-on must be served over HTTPS
Your own backendOptionalOnly needed if you have webhooks, external APIs, or your own database

Example: Add-on with its own backend + database

text
┌─────────────────────────────────┐
│  Your Add-on Frontend            │  (React + Chakra UI)
│  Hosted on Vercel                │
│  Uses SyncBooksProvider for auth │
└──────────────┬──────────────────┘
               │
       ┌───────┴────────┐
       │                 │
       ▼                 ▼
┌─────────────┐   ┌──────────────┐
│ SyncBooks   │   │ Your Backend │  (Express + PostgreSQL)
│ API         │   │ API          │
│ /api/addon/ │   │ /api/...     │
│             │   │              │
│ Read/write  │   │ Your own     │
│ invoices,   │   │ data, logic, │
│ customers   │   │ ML models,   │
│             │   │ analytics    │
└─────────────┘   └──────────────┘

Where Add-ons Appear

Add-ons can appear in multiple places within SyncBooks:

navigation.itemItem in the sidebar navigation
dashboard.widgetCard on the main dashboard
invoice.sidebarPanel next to invoice detail
invoice.actionsButton in invoice action menu
customer.sidebarPanel next to customer detail
customer.actionsButton in customer actions
product.sidebarPanel next to product detail
payment.actionsButton in payment actions
settings.pageFull page under settings
command.paletteCommand in command palette

Security Model

SyncBooks add-ons operate under a strict security model:

  • Sandboxed iframe — your code cannot access the SyncBooks DOM
  • Scoped API access — you only see data you were granted permission for
  • Short-lived tokens — session tokens expire after 1 hour
  • HMAC-signed webhooks — verify that events come from SyncBooks
  • Rate limiting — 1,000 requests per hour per add-on per organization

Technology Stack

You can build add-ons with any web technology:

  • React, Vue, Svelte, Angular, or plain HTML/JavaScript
  • The SDK provides React hooks, but the core bridge works with any framework
  • Deploy anywhere that serves HTTPS (Vercel, Netlify, Railway, etc.)

Revenue Opportunity

Developers can monetize their add-ons through the marketplace:

  • Free add-ons — great for building user base and brand awareness
  • Paid add-ons — set a monthly price (minimum GHS 10/month)
  • You keep 75% — SyncBooks takes a 25% platform commission
  • Monthly payouts — via Mobile Money or bank transfer

Ready to build?

Continue to the Quick Start to create your first add-on, or read How It Works to understand the architecture in detail.

Next

Quick Start