Zoho Invoice Add API (TypeScript)

English | 日本語 (Japanese)

TypeScript project with ESLint and integration for the Zoho Invoice API v3 — create (add) invoice via POST /invoices.

Requirements

• Node.js 18+ (for native fetch)
• A Zoho Invoice account and OAuth 2.0 access token

Setup

npm install

Copy environment template and set your credentials:

cp .env.example .env

Edit .env and set at least:

• ZOHO_ACCESS_TOKEN – OAuth 2.0 access token from Zoho API Console (Invoice scope).
• ZOHO_CUSTOMER_ID – A contact/customer ID from Zoho Invoice (required for the create-invoice example). List contacts via API or from the Invoice UI.

Optional:

• ZOHO_ORGANIZATION_ID – Required if your account has multiple organizations.
• ZOHO_DATA_CENTER – com (default), eu, in, com.au, or jp to match your Zoho region.

Build & run

npm run build
npm start

Or run after build:

node dist/index.js

The default index.ts creates a sample invoice for the customer set in ZOHO_CUSTOMER_ID.

Scripts

Command	Description
npm run build	Compile TypeScript to dist
npm start	Run compiled dist/index.js
npm run dev	Watch and recompile
npm run lint	Run ESLint on src
npm run lint:fix	ESLint with auto-fix

Zoho Invoice Add API

• Endpoint: POST https://invoice.zoho.{dc}/api/v3/invoices
• Auth: Header Authorization: Zoho-oauthtoken {access_token}
• Docs: Create an invoice

Usage in code

import { ZohoInvoiceClient } from "./client.js";
import type { ZohoCreateInvoicePayload } from "./types.js";

const client = new ZohoInvoiceClient({
  accessToken: process.env.ZOHO_ACCESS_TOKEN!,
  organizationId: process.env.ZOHO_ORGANIZATION_ID,
  dataCenter: "com",
});

const payload: ZohoCreateInvoicePayload = {
  customer_id: "CONTACT_ID",
  date: "2025-03-12",
  line_items: [
    { name: "Item name", quantity: 2, rate: 50 },
  ],
};

const result = await client.createInvoice(payload);
console.log(result.invoice?.invoice_id);

Getting an OAuth access token

1. Register a server-based app in Zoho API Console.
2. Add the Zoho Invoice scope (e.g. ZohoInvoice.invoices.CREATE).
3. Use the OAuth 2.0 authorization code or self-client flow to obtain an access token.
4. Do not commit .env or any file containing the token.

Project layout

├── src/
│   ├── index.ts   # Example: create one invoice
│   ├── client.ts  # ZohoInvoiceClient (createInvoice)
│   └── types.ts   # Request/response types
├── eslint.config.js
├── tsconfig.json
├── package.json
├── .env.example
├── README.md      # English
└── README.ja.md   # 日本語

License

MIT