API Reference

Complete endpoint documentation for the Engagifii Revenue API. All endpoints require authentication and appropriate headers as described in the Authentication Guide.

Quick Links

Postman Collection - Import and start testing immediately
OpenAPI Spec - Complete API specification for code generation

Base Configuration
Invoices
Payments
Credit Notes
Refunds
Subscriptions
Subscription Addons
Membership
Account Codes
Reports
QuickBooks Integration
Settings
Webhooks

Base Configuration

Base URL

https://engagifii-prod-revenue.azurewebsites.net/api/{api-version}

Required Headers

http

Authorization: Bearer {access_token}
tenant-code: {your_tenant_code}
api-version: 1.0
Content-Type: application/json

Common Parameters

Parameter	Type	Description
`page`	integer	Page number for pagination (default: 1)
`pageSize`	integer	Items per page (default: 20, max: 100)
`sortBy`	string	Field to sort by
`sortOrder`	string	Sort direction: `asc` or `desc`
`search`	string	Search term for filtering

Invoices

The Invoice API provides comprehensive invoice management capabilities including creation, retrieval, updates, and payment tracking.

List Invoices

Retrieve a paginated list of invoices with filtering options.

Endpoint: GET /invoice

Query Parameters:

Parameter	Type	Required	Description
`status`	string	No	Filter by status: `Draft`, `Sent`, `Paid`, `Overdue`, `Cancelled`
`customerId`	guid	No	Filter by customer ID
`customerType`	string	No	`Person` or `Organization`
`fromDate`	date	No	Start date (ISO 8601)
`toDate`	date	No	End date (ISO 8601)
`minAmount`	decimal	No	Minimum invoice amount
`maxAmount`	decimal	No	Maximum invoice amount
`page`	integer	No	Page number (default: 1)
`pageSize`	integer	No	Items per page (default: 20)

Response:

json

{
  "items": [
    {
      "invoiceId": "INV-2024-001",
      "invoiceNumber": "INV-2024-001",
      "customerId": "123e4567-e89b-12d3-a456-426614174000",
      "customerType": "Person",
      "customerName": "John Doe",
      "invoiceDate": "2024-01-15",
      "dueDate": "2024-02-15",
      "status": "Sent",
      "subtotal": 1500.00,
      "taxAmount": 150.00,
      "totalAmount": 1650.00,
      "paidAmount": 0.00,
      "balanceAmount": 1650.00,
      "currency": "USD",
      "createdDate": "2024-01-15T10:30:00Z"
    }
  ],
  "totalCount": 150,
  "page": 1,
  "pageSize": 20,
  "hasMore": true
}

Example:

bash

curl -X GET "https://engagifii-prod-revenue.azurewebsites.net/api/1.0/invoice?status=Sent&page=1&pageSize=10" \
  -H "Authorization: Bearer {token}" \
  -H "tenant-code: {tenant}" \
  -H "api-version: 1.0"

Get Invoice Details

Retrieve complete details for a specific invoice.

Endpoint: GET /invoice/{invoiceId}

Path Parameters:

Parameter	Type	Required	Description
`invoiceId`	string	Yes	Unique invoice identifier

Response:

json

{
  "invoiceId": "INV-2024-001",
  "invoiceNumber": "INV-2024-001",
  "customerId": "123e4567-e89b-12d3-a456-426614174000",
  "customerType": "Person",
  "customerDetails": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "phone": "+1-555-123-4567",
    "address": {
      "street": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "USA"
    }
  },
  "invoiceDate": "2024-01-15",
  "dueDate": "2024-02-15",
  "status": "Sent",
  "items": [
    {
      "itemId": "item-001",
      "itemType": "Service",
      "itemName": "Professional Services",
      "description": "Consulting services for January 2024",
      "quantity": 10,
      "unitPrice": 150.00,
      "discountType": "Percentage",
      "discountValue": 0,
      "taxRate": 10,
      "amount": 1500.00
    }
  ],
  "subtotal": 1500.00,
  "discountTotal": 0.00,
  "taxAmount": 150.00,
  "totalAmount": 1650.00,
  "paidAmount": 0.00,
  "balanceAmount": 1650.00,
  "paymentTerms": "Net 30",
  "notes": "Payment due within 30 days",
  "internalNotes": "Priority customer",
  "currency": "USD",
  "createdBy": "user123",
  "createdDate": "2024-01-15T10:30:00Z",
  "lastModifiedDate": "2024-01-15T10:30:00Z"
}

Create Invoice

Create a new invoice with line items.

Endpoint: POST /invoice/manual

Request Body:

json

{
  "customerType": "Person",
  "customerId": "123e4567-e89b-12d3-a456-426614174000",
  "invoiceDate": "2024-01-15",
  "dueDate": "2024-02-15",
  "paymentTermId": "term-net30",
  "billingAddress": {
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "postalCode": "10001",
    "country": "USA"
  },
  "items": [
    {
      "itemType": "Service",
      "itemName": "Professional Services",
      "description": "Consulting services for January 2024",
      "quantity": 10,
      "unitPrice": 150.00,
      "discountType": "Percentage",
      "discountValue": 10,
      "taxRate": 10
    }
  ],
  "notes": "Payment due within 30 days",
  "internalNotes": "Priority customer",
  "sendEmail": true,
  "emailTo": ["john.doe@example.com"]
}

Response:

json

{
  "success": true,
  "invoiceId": "INV-2024-001",
  "invoiceNumber": "INV-2024-001",
  "status": "Draft",
  "totalAmount": 1485.00,
  "message": "Invoice created successfully"
}

Update Invoice

Update an existing invoice (only for Draft status).

Endpoint: PUT /invoice/{invoiceId}

Request Body:

json

{
  "dueDate": "2024-02-20",
  "items": [
    {
      "itemId": "item-001",
      "quantity": 12,
      "unitPrice": 150.00
    }
  ],
  "notes": "Updated payment terms"
}

Send Invoice

Send invoice to customer via email.

Endpoint: POST /invoice/send/{invoiceId}

Request Body:

json

{
  "emailTo": ["john.doe@example.com", "accounts@example.com"],
  "emailCc": ["manager@example.com"],
  "emailSubject": "Invoice INV-2024-001 from Engagifii",
  "emailMessage": "Please find attached invoice for your recent purchase.",
  "attachPdf": true
}

Mark Invoice as Paid

Mark an invoice as paid manually.

Endpoint: POST /invoice/{invoiceId}/mark-paid

Request Body:

json

{
  "paymentDate": "2024-01-20",
  "paymentMethod": "BankTransfer",
  "referenceNumber": "TXN-123456",
  "amount": 1650.00,
  "notes": "Payment received via wire transfer"
}

Void Invoice

Void/cancel an invoice.

Endpoint: POST /invoice/{invoiceId}/void

Request Body:

json

{
  "reason": "Duplicate invoice created",
  "notifyCustomer": true
}

Download Invoice PDF

Generate and download invoice as PDF.

Endpoint: GET /invoice/{invoiceId}/pdf

Response: Binary PDF file

Example:

bash

curl -X GET "https://engagifii-prod-revenue.azurewebsites.net/api/1.0/invoice/INV-2024-001/pdf" \
  -H "Authorization: Bearer {token}" \
  -H "tenant-code: {tenant}" \
  -H "api-version: 1.0" \
  -o invoice.pdf

Payments

Process and manage payments for invoices.

Process Payment

Process a payment for one or more invoices.

Endpoint: POST /payment

Request Body:

json

{
  "paymentMethod": "CreditCard",
  "amount": 1650.00,
  "currency": "USD",
  "paymentDate": "2024-01-20",
  "invoices": [
    {
      "invoiceId": "INV-2024-001",
      "amount": 1650.00
    }
  ],
  "creditCard": {
    "cardNumber": "4111111111111111",
    "cardholderName": "John Doe",
    "expiryMonth": "12",
    "expiryYear": "2025",
    "cvv": "123",
    "saveCard": true
  },
  "billingAddress": {
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "postalCode": "10001",
    "country": "USA"
  }
}

Response:

json

{
  "success": true,
  "paymentId": "PAY-2024-001",
  "transactionId": "TXN-ABC123",
  "status": "Approved",
  "processedAmount": 1650.00,
  "processingFee": 0.00,
  "message": "Payment processed successfully"
}

List Payments

Retrieve payment history.

Endpoint: GET /payment

Query Parameters:

Parameter	Type	Required	Description
`invoiceId`	string	No	Filter by invoice
`customerId`	guid	No	Filter by customer
`status`	string	No	`Pending`, `Approved`, `Declined`, `Refunded`
`fromDate`	date	No	Start date
`toDate`	date	No	End date
`paymentMethod`	string	No	Payment method filter

Get Payment Details

Endpoint: GET /payment/{paymentId}

Refund Payment

Process a refund for a payment.

Endpoint: POST /payment/{paymentId}/refund

Request Body:

json

{
  "amount": 500.00,
  "reason": "Partial refund for services not rendered",
  "notifyCustomer": true
}

Credit Notes

Manage credit notes for refunds and adjustments.

Create Credit Note

Endpoint: POST /creditNote

Request Body:

json

{
  "customerId": "123e4567-e89b-12d3-a456-426614174000",
  "customerType": "Person",
  "creditNoteDate": "2024-01-20",
  "creditNoteType": "Refund",
  "relatedInvoiceId": "INV-2024-001",
  "items": [
    {
      "description": "Service refund",
      "amount": 500.00,
      "taxRate": 10
    }
  ],
  "reason": "Service cancellation",
  "notes": "Refund for cancelled services"
}

List Credit Notes

Endpoint: GET /creditNote

Query Parameters:

Parameter	Type	Required	Description
`customerId`	guid	No	Filter by customer
`status`	string	No	`Draft`, `Issued`, `Applied`, `Expired`
`fromDate`	date	No	Start date
`toDate`	date	No	End date

Apply Credit Note

Apply credit note to invoices.

Endpoint: POST /creditNote/{creditNoteId}/apply

Request Body:

json

{
  "invoices": [
    {
      "invoiceId": "INV-2024-002",
      "amountToApply": 500.00
    }
  ]
}

Refunds

Process refunds for payments and credit notes.

Create Refund

Endpoint: POST /refund

Request Body:

json

{
  "refundType": "Payment",
  "paymentId": "PAY-2024-001",
  "amount": 500.00,
  "refundMethod": "CreditCard",
  "reason": "Service cancellation",
  "processImmediately": true
}

List Refunds

Endpoint: GET /refund

Get Refund Status

Endpoint: GET /refund/{refundId}

Subscriptions

Manage recurring billing subscriptions.

Create Subscription

Endpoint: POST /subscription

Request Body:

json

{
  "customerId": "123e4567-e89b-12d3-a456-426614174000",
  "customerType": "Person",
  "subscriptionPlanId": "plan-professional",
  "startDate": "2024-02-01",
  "billingCycle": "Monthly",
  "price": 99.99,
  "setupFee": 0.00,
  "trialDays": 14,
  "autoRenew": true,
  "paymentMethodId": "pm-123",
  "notes": "Professional plan subscription"
}

List Subscriptions

Endpoint: GET /subscription

Query Parameters:

Parameter	Type	Required	Description
`customerId`	guid	No	Filter by customer
`status`	string	No	`Active`, `Paused`, `Cancelled`, `Expired`
`planId`	string	No	Filter by plan

Get Subscription

Endpoint: GET /subscription/{subscriptionId}

Update Subscription

Endpoint: PUT /subscription/{subscriptionId}

Request Body:

json

{
  "billingCycle": "Annual",
  "price": 999.99,
  "nextBillingDate": "2024-03-01"
}

Pause Subscription

Endpoint: POST /subscription/{subscriptionId}/pause

Request Body:

json

{
  "pauseUntil": "2024-03-01",
  "reason": "Customer request"
}

Resume Subscription

Endpoint: POST /subscription/{subscriptionId}/resume

Cancel Subscription

Endpoint: POST /subscription/{subscriptionId}/cancel

Request Body:

json

{
  "cancellationType": "Immediate",
  "reason": "Customer request",
  "refundUnusedPeriod": true
}

Subscription Addons

Manage additional features and services for subscriptions.

Create Addon

Endpoint: POST /subscription/addon

Request Body:

json

{
  "name": "Extra Storage",
  "description": "Additional 100GB storage",
  "price": 9.99,
  "billingCycle": "Monthly",
  "isRecurring": true,
  "taxable": true
}

List Addons

Endpoint: GET /subscription/addon

Add Addon to Subscription

Endpoint: POST /subscription/{subscriptionId}/addon

Request Body:

json

{
  "addonId": "addon-storage",
  "quantity": 2,
  "startDate": "2024-02-01"
}

Membership

Manage membership billing and tracking.

Create Membership

Endpoint: POST /membership

Request Body:

json

{
  "memberId": "123e4567-e89b-12d3-a456-426614174000",
  "memberType": "Individual",
  "membershipPlanId": "gold-annual",
  "startDate": "2024-01-01",
  "endDate": "2024-12-31",
  "fee": 500.00,
  "autoRenew": true
}

List Memberships

Endpoint: GET /membership

Get Membership Details

Endpoint: GET /membership/{membershipId}

Renew Membership

Endpoint: POST /membership/{membershipId}/renew

Account Codes

Manage chart of accounts and accounting codes.

List Account Codes

Endpoint: GET /accountCode

Query Parameters:

Parameter	Type	Required	Description
`type`	string	No	Account type filter
`search`	string	No	Search in code or description

Create Account Code

Endpoint: POST /accountCode

Request Body:

json

{
  "code": "4000",
  "name": "Sales Revenue",
  "type": "Revenue",
  "description": "Product sales revenue",
  "isActive": true
}

Update Account Code

Endpoint: PUT /accountCode/{accountCodeId}

Map Account Code

Map account codes to specific entities.

Endpoint: POST /accountCode/mapping

Request Body:

json

{
  "accountCodeId": "acc-4000",
  "entityType": "Product",
  "entityId": "prod-123"
}

Reports

Generate and retrieve financial reports.

Available Reports

Endpoint: GET /report/available

Response:

json

[
  {
    "reportId": "revenue-summary",
    "name": "Revenue Summary",
    "category": "Financial",
    "parameters": ["fromDate", "toDate", "groupBy"]
  },
  {
    "reportId": "invoice-aging",
    "name": "Invoice Aging Report",
    "category": "Receivables",
    "parameters": ["asOfDate", "customerType"]
  }
]

Generate Report

Endpoint: POST /report/generate

Request Body:

json

{
  "reportId": "revenue-summary",
  "parameters": {
    "fromDate": "2024-01-01",
    "toDate": "2024-01-31",
    "groupBy": "day"
  },
  "format": "json",
  "emailResults": false
}

Response:

json

{
  "reportId": "rpt-123456",
  "status": "Processing",
  "estimatedCompletionTime": "2024-01-20T10:35:00Z",
  "downloadUrl": null
}

Get Report Status

Endpoint: GET /report/{reportId}/status

Download Report

Endpoint: GET /report/{reportId}/download

Query Parameters:

Parameter	Type	Required	Description
`format`	string	No	`json`, `csv`, `pdf`, `xlsx`

QuickBooks Integration

Synchronize data with QuickBooks accounting software.

Connect QuickBooks

Endpoint: POST /qb/integration/connect

Request Body:

json

{
  "companyId": "1234567890",
  "authCode": "AUTH_CODE_FROM_QB",
  "realmId": "REALM_ID"
}

Sync Status

Endpoint: GET /qb/integration/status

Sync Invoices

Endpoint: POST /qb/integration/sync/invoices

Request Body:

json

{
  "fromDate": "2024-01-01",
  "toDate": "2024-01-31",
  "syncDirection": "ToQuickBooks"
}

Sync Customers

Endpoint: POST /qb/integration/sync/customers

Map Accounts

Endpoint: POST /qb/integration/mapping

Request Body:

json

{
  "engagifiiAccountCode": "4000",
  "quickbooksAccountId": "QB-4000",
  "mappingType": "Revenue"
}

Disconnect QuickBooks

Endpoint: POST /qb/integration/disconnect

Settings

Configure system settings and preferences.

Get Invoice Settings

Endpoint: GET /settings/invoice

Response:

json

{
  "defaultPaymentTerms": "Net 30",
  "invoiceNumberPrefix": "INV-",
  "nextInvoiceNumber": "2024-002",
  "defaultTaxRate": 10,
  "currency": "USD",
  "logoUrl": "https://example.com/logo.png",
  "companyDetails": {
    "name": "Your Company",
    "address": "123 Business St",
    "phone": "+1-555-000-0000",
    "email": "billing@company.com"
  }
}

Update Invoice Settings

Endpoint: PUT /settings/invoice

Get Payment Settings

Endpoint: GET /settings/payment

Update Payment Settings

Endpoint: PUT /settings/payment

Get Notification Settings

Endpoint: GET /settings/notification

Update Notification Settings

Endpoint: PUT /settings/notification

Webhooks

Configure webhooks to receive real-time notifications.

Webhook Events

Event	Description
`invoice.created`	New invoice created
`invoice.sent`	Invoice sent to customer
`invoice.paid`	Invoice fully paid
`invoice.overdue`	Invoice past due date
`payment.received`	Payment received
`payment.failed`	Payment failed
`subscription.created`	New subscription created
`subscription.renewed`	Subscription renewed
`subscription.cancelled`	Subscription cancelled
`creditnote.issued`	Credit note issued

Register Webhook

Endpoint: POST /webhook

Request Body:

json

{
  "url": "https://yourapp.com/webhooks/revenue",
  "events": [
    "invoice.created",
    "invoice.paid",
    "payment.received"
  ],
  "secret": "your_webhook_secret",
  "isActive": true
}

Response:

json

{
  "webhookId": "wh-123456",
  "url": "https://yourapp.com/webhooks/revenue",
  "events": ["invoice.created", "invoice.paid", "payment.received"],
  "createdDate": "2024-01-20T10:30:00Z"
}

List Webhooks

Endpoint: GET /webhook

Update Webhook

Endpoint: PUT /webhook/{webhookId}

Delete Webhook

Endpoint: DELETE /webhook/{webhookId}

Test Webhook

Endpoint: POST /webhook/{webhookId}/test

Webhook Payload Format

All webhook events follow this structure:

json

{
  "id": "evt-123456",
  "type": "invoice.paid",
  "timestamp": "2024-01-20T10:30:00Z",
  "data": {
    "invoiceId": "INV-2024-001",
    "customerId": "123e4567-e89b-12d3-a456-426614174000",
    "amount": 1650.00,
    "paymentId": "PAY-2024-001"
  },
  "signature": "sha256=..."
}

Webhook Security

Verify webhook signatures:

javascript

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return `sha256=${expectedSignature}` === signature;
}

// In your webhook handler
app.post('/webhooks/revenue', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);
  
  if (!verifyWebhookSignature(payload, signature, webhookSecret)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process webhook event
  const event = req.body;
  console.log(`Received ${event.type} event`);
  
  res.status(200).send('OK');
});

Error Responses

All endpoints return consistent error responses:

json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "amount",
        "message": "Amount must be greater than 0"
      }
    ],
    "requestId": "req-123456",
    "timestamp": "2024-01-20T10:30:00Z"
  }
}

For detailed error handling, see the Error Handling Guide.

Pagination

All list endpoints support pagination:

json

{
  "items": [...],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalPages": 10,
    "totalCount": 195,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Filtering

Most list endpoints support filtering via query parameters:

GET /api/1.0/invoice?status=Paid&fromDate=2024-01-01&toDate=2024-01-31&customerId=123

Sorting

Sort results using sortBy and sortOrder:

GET /api/1.0/invoice?sortBy=invoiceDate&sortOrder=desc

Field Selection

Some endpoints support field selection to reduce payload size:

GET /api/1.0/invoice?fields=invoiceId,invoiceNumber,totalAmount,status

For additional endpoints and detailed schemas, refer to the Data Models documentation or download the complete OpenAPI specification.

API Reference ​

Quick Links ​

Table of Contents ​

Base Configuration ​

Base URL ​

Required Headers ​

Common Parameters ​

Invoices ​

List Invoices ​

Get Invoice Details ​

Create Invoice ​

Update Invoice ​

Send Invoice ​

Mark Invoice as Paid ​

Void Invoice ​

Download Invoice PDF ​

Payments ​

Process Payment ​

List Payments ​

Get Payment Details ​

Refund Payment ​

Credit Notes ​

Create Credit Note ​

List Credit Notes ​

Apply Credit Note ​

Refunds ​

Create Refund ​

List Refunds ​

Get Refund Status ​

Subscriptions ​

Create Subscription ​

List Subscriptions ​

Get Subscription ​

Update Subscription ​

Pause Subscription ​

Resume Subscription ​

Cancel Subscription ​

Subscription Addons ​

Create Addon ​

List Addons ​

Add Addon to Subscription ​

Membership ​

Create Membership ​

List Memberships ​

Get Membership Details ​

Renew Membership ​

Account Codes ​

List Account Codes ​

Create Account Code ​

Update Account Code ​

Map Account Code ​

Reports ​

Available Reports ​

Generate Report ​

Get Report Status ​

Download Report ​

QuickBooks Integration ​

Connect QuickBooks ​

Sync Status ​

Sync Invoices ​

Sync Customers ​

Map Accounts ​

Disconnect QuickBooks ​

Settings ​

Get Invoice Settings ​

Update Invoice Settings ​

Get Payment Settings ​

Update Payment Settings ​

Get Notification Settings ​

Update Notification Settings ​

Webhooks ​

Webhook Events ​

Register Webhook ​

List Webhooks ​

Update Webhook ​

Delete Webhook ​

Test Webhook ​

Webhook Payload Format ​

Webhook Security ​

Error Responses ​

API Reference

Quick Links

Table of Contents

Base Configuration

Base URL

Required Headers

Common Parameters

Invoices

List Invoices

Get Invoice Details

Create Invoice

Update Invoice

Send Invoice

Mark Invoice as Paid

Void Invoice

Download Invoice PDF

Payments

Process Payment

List Payments

Get Payment Details

Refund Payment

Credit Notes

Create Credit Note

List Credit Notes

Apply Credit Note

Refunds

Create Refund

List Refunds

Get Refund Status

Subscriptions

Create Subscription

List Subscriptions

Get Subscription

Update Subscription

Pause Subscription

Resume Subscription

Cancel Subscription

Subscription Addons

Create Addon

List Addons

Add Addon to Subscription

Membership

Create Membership

List Memberships

Get Membership Details

Renew Membership

Account Codes

List Account Codes

Create Account Code

Update Account Code

Map Account Code

Reports

Available Reports

Generate Report

Get Report Status

Download Report

QuickBooks Integration

Connect QuickBooks

Sync Status

Sync Invoices

Sync Customers

Map Accounts

Disconnect QuickBooks

Settings

Get Invoice Settings

Update Invoice Settings

Get Payment Settings

Update Payment Settings

Get Notification Settings

Update Notification Settings

Webhooks

Webhook Events

Register Webhook

List Webhooks

Update Webhook

Delete Webhook

Test Webhook

Webhook Payload Format

Webhook Security

Error Responses