@commenda-integrations/api

Official TypeScript SDK for the Commenda Integrations V4 API. Read and write unified accounting, payments, e-commerce, and CRM data across every supported platform through a single API.

Installation

npm install @commenda-integrations/api

Quick start

import { CommendaIntegrations } from "@commenda-integrations/api";

const commenda = new CommendaIntegrations({ apiKey: process.env.COMMENDA_API_KEY! });

// Read a data model (company-scoped): list, filter, expand relations
const {
  data: invoices,
  total_count,
  next,
} = await commenda.dataModels.invoices.list(companyId, {
  "status[eq]": "PAID",
  "posted_date[gte]": "2024-01-01",
  limit: 50,
  expand: "line_items",
});

// Get one record
const { data: invoice } = await commenda.dataModels.invoices.get(companyId, invoiceId);

// Create / update (proxied to the connected platform)
await commenda.dataModels.invoices.create(companyId, {
  data: {
    /* fields */
  },
});

// Trigger a sync
await commenda.core.syncs.initSync(companyId, { fullSync: true });

Authentication

Requests are authenticated with your API key, sent in the api_key header. Pass it once when constructing the client:

const commenda = new CommendaIntegrations({ apiKey: "your-api-key" });

Environments

The client targets production (https://api.integrations.commenda.io) by default; just pass your apiKey. Pass baseUrl to override the host if you need to.

Filtering, sorting & pagination

List endpoints accept per-field filters using operator keys, plus limit and cursor pagination:

await commenda.dataModels.invoices.list(companyId, {
  "status[eq]": "PAID", // exact match
  "currency_id[in]": "USD,EUR", // one of
  "total_amount[gte]": "100", // range (numeric / date fields)
  "sort[posted_date]": "desc",
  limit: 100,
});

Iterate every page with the pagination helpers:

import { paginate } from "@commenda-integrations/api";

for await (const invoice of paginate(next => commenda.dataModels.invoices.list(companyId, { limit: 100, next }))) {
  // ...
}

Responses & errors

Methods return the response payload directly — the { data, request_id } envelope is unwrapped for you (list methods return { data, total_count, next, prev }). Non-2xx responses throw a CommendaApiError:

import { CommendaApiError } from "@commenda-integrations/api";

try {
  await commenda.dataModels.invoices.get(companyId, invoiceId);
} catch (err) {
  if (err instanceof CommendaApiError) {
    console.error(err.statusCode, err.message, err.errorCode, err.requestId);
  }
}

Resources

Data models live under commenda.dataModels.*; platform & management resources under commenda.core.*. TypeScript autocomplete surfaces every resource and method.

Data models — commenda.dataModels.<model>, each supporting list(companyId, query?), get(companyId, id, query?), and (where writable) create / update. TypeScript autocomplete lists every model; the full set:

accounts, balances, balanceSheets, bankAccounts, bankTransactions,
billCreditNotes, billPayments, bills, cashFlowStatements, cashRefunds,
cashSales, companies, companyInfo, contacts, currencies, disputes, documents,
estimates, expenses, goodsReceiptNotes, incomeStatements, inventory,
invoiceCreditNotes, invoicePayments, invoices, items, journalEntries, leads,
lineItem, notes, opportunities, orders, owners, payouts, pipelines, projects,
purchaseOrders, salesOrders, subscriptions, tasks, taxRates, trackingCategories,
transactions

Core (platform & management) — commenda.core.<resource>:

• companies — connection management, distinct from dataModels.companies (CRM records): list, get, update, updateSyncConfig, resetSyncConfig, resetSingleModelConfig, disconnect, archive
• inviteLinks — create, list, getByInviteLinkUuid, updateByInviteLinkUuid, delete
• syncs — initSync, list · syncActions, jobs
• integrations, passthrough, webhookConfigs, webhookCredentials, webhookLogs, members, organization, disconnectRequests, stats, apiLogs

Versioning & breaking changes

Semantic versioning. The major version tracks the Commenda Integrations API major (4.x → V4): breaking API-surface changes ship in a new major; additive changes are minor/patch.