API Documentation

Appearance

Data Models ​

Complete schema documentation for all request and response objects in the Engagifii Revenue API. All monetary values are in decimal format with 2 decimal places unless otherwise specified.

Table of Contents ​

Common Models ​

PagedResponse ​

Standard pagination wrapper for list responses.

typescript
interface PagedResponse<T> {
  items: T[];                  // Array of items
  totalCount: number;           // Total number of items
  page: number;                 // Current page (1-based)
  pageSize: number;             // Items per page
  totalPages: number;           // Total pages available
  hasNextPage: boolean;         // Whether next page exists
  hasPreviousPage: boolean;     // Whether previous page exists
}

ErrorResponse ​

Standard error response format.

typescript
interface ErrorResponse {
  error: {
    code: string;              // Error code (e.g., "VALIDATION_ERROR")
    message: string;           // Human-readable error message
    details?: ErrorDetail[];   // Detailed error information
    requestId: string;         // Unique request identifier
    timestamp: string;         // ISO 8601 timestamp
  };
}

interface ErrorDetail {
  field?: string;              // Field name if field-specific
  message: string;             // Error message
  code?: string;               // Specific error code
}

Money ​

Monetary amount representation.

typescript
interface Money {
  amount: number;              // Decimal amount (2 decimal places)
  currency: string;            // ISO 4217 currency code (e.g., "USD")
}

DateRange ​

Date range for filtering.

typescript
interface DateRange {
  fromDate: string;            // ISO 8601 date (YYYY-MM-DD)
  toDate: string;              // ISO 8601 date (YYYY-MM-DD)
}

Invoice Models ​

Invoice ​

Complete invoice representation.

typescript
interface Invoice {
  // Identifiers
  invoiceId: string;           // Unique invoice ID
  invoiceNumber: string;       // Human-readable invoice number
  transactionId?: string;      // External transaction reference
  
  // Customer Information
  customerId: string;          // UUID of customer
  customerType: CustomerType;  // "Person" | "Organization"
  customerName: string;        // Customer display name
  customerDetails: Customer;   // Full customer details
  
  // Dates
  invoiceDate: string;         // ISO 8601 date
  dueDate: string;             // ISO 8601 date
  createdDate: string;         // ISO 8601 datetime
  lastModifiedDate: string;    // ISO 8601 datetime
  sentDate?: string;           // ISO 8601 datetime
  paidDate?: string;           // ISO 8601 datetime
  
  // Status
  status: InvoiceStatus;       // Current invoice status
  
  // Line Items
  items: InvoiceItem[];        // Array of line items
  
  // Financial Summary
  subtotal: number;            // Sum of line items
  discountTotal: number;       // Total discounts
  taxAmount: number;           // Total tax
  totalAmount: number;         // Final amount due
  paidAmount: number;          // Amount paid
  balanceAmount: number;       // Remaining balance
  creditAmount?: number;       // Applied credits
  
  // Payment Information
  paymentTerms?: string;       // Payment terms description
  paymentTermId?: string;      // Payment term reference
  paymentMethods?: string[];   // Accepted payment methods
  
  // Addresses
  billingAddress?: Address;    // Billing address
  shippingAddress?: Address;   // Shipping address
  
  // Notes
  notes?: string;              // Customer-visible notes
  internalNotes?: string;      // Internal notes (not shown to customer)
  
  // Metadata
  currency: string;            // ISO 4217 currency code
  exchangeRate?: number;       // Exchange rate if foreign currency
  tags?: string[];             // Tags for categorization
  customFields?: Record<string, any>; // Custom field values
  
  // Audit
  createdBy?: string;          // User who created invoice
  lastModifiedBy?: string;     // User who last modified
  approvedBy?: string;         // User who approved
}

InvoiceItem ​

Line item on an invoice.

typescript
interface InvoiceItem {
  // Identifiers
  itemId: string;              // Unique item ID
  sequence: number;            // Display order
  
  // Item Details
  itemType: ItemType;          // Type of item
  itemCode?: string;           // SKU or item code
  itemName: string;            // Item display name
  description?: string;        // Detailed description
  
  // Quantity & Pricing
  quantity: number;            // Quantity (decimal)
  unitPrice: number;           // Price per unit
  unit?: string;               // Unit of measure
  
  // Discounts
  discountType?: DiscountType; // "Percentage" | "Amount"
  discountValue?: number;      // Discount value
  discountAmount: number;      // Calculated discount
  
  // Tax
  taxable: boolean;            // Whether item is taxable
  taxRate?: number;            // Tax percentage
  taxAmount: number;           // Calculated tax
  
  // Totals
  subtotal: number;            // quantity * unitPrice
  amount: number;              // Final amount after discount & tax
  
  // References
  relatedItemId?: string;      // Related product/service ID
  accountCode?: string;        // GL account code
  department?: string;         // Department code
  
  // Metadata
  notes?: string;              // Item-specific notes
  customFields?: Record<string, any>;
}

CreateInvoiceRequest ​

Request to create a new invoice.

typescript
interface CreateInvoiceRequest {
  // Customer
  customerType: CustomerType;  // Required
  customerId: string;          // Required - UUID
  
  // Dates
  invoiceDate: string;         // Required - ISO 8601
  dueDate: string;             // Required - ISO 8601
  
  // Items
  items: CreateInvoiceItem[];  // Required - At least 1 item
  
  // Optional Fields
  invoiceNumber?: string;      // Custom invoice number
  paymentTermId?: string;      // Payment term reference
  billingAddress?: Address;    // Billing address
  shippingAddress?: Address;   // Shipping address
  notes?: string;              // Customer notes
  internalNotes?: string;      // Internal notes
  
  // Email Options
  sendEmail?: boolean;         // Send immediately
  emailTo?: string[];          // Email recipients
  emailCc?: string[];          // CC recipients
  emailSubject?: string;       // Custom subject
  emailMessage?: string;       // Custom message
  
  // Settings
  currency?: string;           // Default: Account currency
  exchangeRate?: number;       // For foreign currency
  tags?: string[];            // Tags
  customFields?: Record<string, any>;
}

UpdateInvoiceRequest ​

Request to update an existing invoice.

typescript
interface UpdateInvoiceRequest {
  // Only Draft invoices can be updated
  dueDate?: string;            // Update due date
  items?: UpdateInvoiceItem[]; // Update line items
  notes?: string;              // Update notes
  internalNotes?: string;      // Update internal notes
  billingAddress?: Address;    // Update billing address
  shippingAddress?: Address;   // Update shipping address
  tags?: string[];            // Update tags
}

Payment Models ​

Payment ​

Payment record.

typescript
interface Payment {
  // Identifiers
  paymentId: string;           // Unique payment ID
  paymentNumber: string;       // Human-readable number
  transactionId: string;       // Gateway transaction ID
  
  // Payment Details
  paymentMethod: PaymentMethod; // Payment method used
  paymentDate: string;         // ISO 8601 date
  amount: number;              // Payment amount
  currency: string;            // ISO 4217 code
  
  // Status
  status: PaymentStatus;       // Payment status
  statusMessage?: string;      // Status details
  
  // Applied To
  invoices: PaymentAllocation[]; // Invoice allocations
  
  // Payment Method Details
  creditCard?: CreditCardDetails;
  bankAccount?: BankAccountDetails;
  check?: CheckDetails;
  
  // Gateway Information
  gateway?: string;            // Payment gateway used
  gatewayResponse?: any;       // Gateway response data
  
  // Fees
  processingFee?: number;      // Processing fee
  netAmount?: number;          // Amount after fees
  
  // Reference
  referenceNumber?: string;    // External reference
  notes?: string;              // Payment notes
  
  // Audit
  createdDate: string;         // ISO 8601 datetime
  createdBy?: string;          // User who created
  modifiedDate?: string;       // ISO 8601 datetime
  modifiedBy?: string;         // User who modified
}

ProcessPaymentRequest ​

Request to process a payment.

typescript
interface ProcessPaymentRequest {
  // Payment Info
  paymentMethod: PaymentMethod; // Required
  amount: number;               // Required
  currency?: string;            // Default: Account currency
  paymentDate?: string;         // Default: Today
  
  // Apply To Invoices
  invoices: Array<{
    invoiceId: string;          // Invoice to pay
    amount: number;             // Amount to apply
  }>;
  
  // Payment Method Details
  creditCard?: {
    cardNumber?: string;        // New card number
    cardholderName: string;     // Cardholder name
    expiryMonth: string;        // MM
    expiryYear: string;         // YYYY
    cvv: string;                // Security code
    saveCard?: boolean;         // Save for future use
    savedCardId?: string;       // Use saved card
  };
  
  bankAccount?: {
    accountNumber?: string;     // Account number
    routingNumber?: string;     // Routing number
    accountType: string;        // "Checking" | "Savings"
    accountName: string;        // Account holder name
    saveAccount?: boolean;      // Save for future use
    savedAccountId?: string;    // Use saved account
  };
  
  // Billing Address
  billingAddress?: Address;    // Required for new cards
  
  // Options
  sendReceipt?: boolean;       // Email receipt
  receiptEmail?: string;       // Receipt email address
  notes?: string;              // Payment notes
}

PaymentAllocation ​

How payment is allocated to invoices.

typescript
interface PaymentAllocation {
  invoiceId: string;           // Invoice ID
  invoiceNumber: string;       // Invoice number
  amountApplied: number;       // Amount applied
  previousBalance: number;     // Balance before payment
  newBalance: number;          // Balance after payment
}

RefundRequest ​

Request to process a refund.

typescript
interface RefundRequest {
  // Refund Details
  refundType: RefundType;      // "Full" | "Partial"
  amount: number;               // Amount to refund
  reason: string;               // Required - Refund reason
  
  // Source
  paymentId?: string;          // Refund specific payment
  invoiceId?: string;          // Refund invoice
  
  // Method
  refundMethod?: RefundMethod; // How to refund
  
  // Options
  processImmediately?: boolean; // Process now vs queue
  notifyCustomer?: boolean;     // Send notification
  notes?: string;               // Internal notes
}

Credit Note Models ​

CreditNote ​

Credit note for refunds and adjustments.

typescript
interface CreditNote {
  // Identifiers
  creditNoteId: string;        // Unique ID
  creditNoteNumber: string;    // Human-readable number
  
  // Customer
  customerId: string;          // Customer UUID
  customerType: CustomerType;  // Customer type
  customerName: string;        // Customer name
  
  // Details
  creditNoteDate: string;      // ISO 8601 date
  creditNoteType: CreditNoteType; // Type of credit
  status: CreditNoteStatus;    // Current status
  
  // Related Documents
  relatedInvoiceId?: string;   // Related invoice
  relatedPaymentId?: string;   // Related payment
  
  // Items
  items: CreditNoteItem[];     // Line items
  
  // Amounts
  subtotal: number;            // Sum of items
  taxAmount: number;           // Tax amount
  totalAmount: number;         // Total credit
  appliedAmount: number;       // Amount used
  remainingAmount: number;     // Available credit
  
  // Application
  appliedTo: CreditApplication[]; // Where credit applied
  
  // Metadata
  reason: string;              // Reason for credit
  notes?: string;              // Additional notes
  tags?: string[];            // Tags
  
  // Dates
  issuedDate?: string;        // When issued
  expiryDate?: string;        // Expiration date
  voidedDate?: string;        // If voided
  
  // Audit
  createdDate: string;        // Created date
  createdBy: string;          // Created by user
  approvedBy?: string;        // Approved by user
  approvedDate?: string;      // Approval date
}

CreateCreditNoteRequest ​

Request to create a credit note.

typescript
interface CreateCreditNoteRequest {
  // Customer
  customerId: string;          // Required
  customerType: CustomerType;  // Required
  
  // Details
  creditNoteDate: string;      // Required - ISO 8601
  creditNoteType: CreditNoteType; // Required
  
  // Items
  items: Array<{
    description: string;       // Required
    amount: number;           // Required
    taxRate?: number;         // Tax rate if applicable
    accountCode?: string;     // GL account
  }>;
  
  // References
  relatedInvoiceId?: string;  // Related invoice
  relatedPaymentId?: string;  // Related payment
  
  // Metadata
  reason: string;             // Required - Reason
  notes?: string;             // Additional notes
  
  // Options
  autoApply?: boolean;        // Auto-apply to open invoices
  sendEmail?: boolean;        // Email to customer
  expiryDate?: string;        // Expiration date
}

ApplyCreditNoteRequest ​

Request to apply credit note to invoices.

typescript
interface ApplyCreditNoteRequest {
  invoices: Array<{
    invoiceId: string;        // Invoice to apply to
    amountToApply: number;    // Amount to apply
  }>;
  
  notes?: string;             // Application notes
  sendNotification?: boolean; // Notify customer
}

Subscription Models ​

Subscription ​

Recurring subscription.

typescript
interface Subscription {
  // Identifiers
  subscriptionId: string;      // Unique ID
  subscriptionNumber: string;  // Human-readable number
  
  // Customer
  customerId: string;          // Customer UUID
  customerType: CustomerType;  // Customer type
  customerName: string;        // Customer name
  
  // Plan
  planId: string;              // Subscription plan ID
  planName: string;            // Plan name
  
  // Schedule
  startDate: string;           // ISO 8601 date
  endDate?: string;            // ISO 8601 date (if fixed term)
  nextBillingDate: string;     // Next billing date
  billingCycle: BillingCycle;  // Billing frequency
  
  // Status
  status: SubscriptionStatus;  // Current status
  pausedUntil?: string;        // If paused
  cancelledDate?: string;      // If cancelled
  
  // Pricing
  price: number;               // Recurring price
  setupFee?: number;           // One-time setup fee
  currency: string;            // ISO 4217 code
  
  // Trial
  trialDays?: number;          // Trial period days
  trialEndDate?: string;       // Trial end date
  
  // Billing
  paymentMethodId?: string;    // Default payment method
  autoRenew: boolean;          // Auto-renewal enabled
  invoicesSent: number;        // Number of invoices
  
  // Addons
  addons?: SubscriptionAddon[]; // Active addons
  
  // Metadata
  notes?: string;              // Subscription notes
  tags?: string[];            // Tags
  customFields?: Record<string, any>;
  
  // Stats
  totalRevenue: number;        // Lifetime revenue
  averageOrderValue: number;   // Average invoice amount
  
  // Audit
  createdDate: string;         // Creation date
  createdBy: string;          // Created by user
  modifiedDate?: string;       // Last modified
  modifiedBy?: string;         // Modified by user
}

CreateSubscriptionRequest ​

Request to create a subscription.

typescript
interface CreateSubscriptionRequest {
  // Customer
  customerId: string;          // Required
  customerType: CustomerType;  // Required
  
  // Plan
  planId: string;              // Required - Plan to subscribe
  
  // Schedule
  startDate: string;           // Required - Start date
  billingCycle?: BillingCycle; // Override plan default
  
  // Pricing
  price?: number;              // Override plan price
  setupFee?: number;           // Setup fee
  
  // Trial
  trialDays?: number;          // Trial period
  
  // Payment
  paymentMethodId?: string;    // Payment method
  autoRenew?: boolean;         // Default: true
  
  // Addons
  addonIds?: string[];         // Initial addons
  
  // Metadata
  notes?: string;              // Notes
  tags?: string[];            // Tags
  customFields?: Record<string, any>;
}

SubscriptionAddon ​

Addon attached to subscription.

typescript
interface SubscriptionAddon {
  addonId: string;             // Addon ID
  name: string;                // Addon name
  description?: string;        // Description
  quantity: number;            // Quantity
  price: number;               // Price per unit
  billingCycle: BillingCycle;  // Billing frequency
  startDate: string;           // Start date
  endDate?: string;            // End date
  status: string;              // Active/Cancelled
}

Customer Models ​

Customer ​

Customer (Person or Organization).

typescript
interface Customer {
  customerId: string;          // UUID
  customerType: CustomerType;  // Type
  
  // Common Fields
  name: string;                // Display name
  email: string;               // Primary email
  phone?: string;              // Primary phone
  status: CustomerStatus;      // Active/Inactive
  
  // Person-specific
  firstName?: string;          // First name
  lastName?: string;           // Last name
  title?: string;              // Job title
  
  // Organization-specific
  organizationName?: string;   // Legal name
  taxId?: string;              // Tax ID/EIN
  website?: string;            // Website URL
  
  // Addresses
  billingAddress?: Address;    // Default billing
  shippingAddress?: Address;   // Default shipping
  addresses?: Address[];       // All addresses
  
  // Payment
  defaultPaymentMethodId?: string; // Default payment
  paymentMethods?: PaymentMethod[]; // Saved methods
  creditLimit?: number;        // Credit limit
  
  // Metadata
  tags?: string[];            // Tags
  customFields?: Record<string, any>;
  notes?: string;             // Customer notes
  
  // Stats
  totalRevenue?: number;      // Lifetime revenue
  totalInvoices?: number;     // Invoice count
  outstandingBalance?: number; // Current balance
  
  // Dates
  createdDate: string;        // Created date
  lastActivityDate?: string;  // Last activity
}

Address Models ​

Address ​

Physical or mailing address.

typescript
interface Address {
  addressId?: string;          // Address ID
  addressType?: AddressType;  // "Billing" | "Shipping" | "Both"
  
  // Address Lines
  street1: string;             // Required - Street line 1
  street2?: string;            // Street line 2
  street3?: string;            // Street line 3
  
  // Location
  city: string;                // Required - City
  state?: string;              // State/Province
  postalCode?: string;         // ZIP/Postal code
  country: string;             // Required - ISO country code
  
  // Contact
  attention?: string;          // Attention to
  phone?: string;              // Phone number
  email?: string;              // Email address
  
  // Validation
  isValid?: boolean;           // Address validated
  validatedDate?: string;      // Validation date
  
  // Default
  isDefault?: boolean;         // Default address
}

Enumerations ​

CustomerType ​

typescript
type CustomerType = "Person" | "Organization";

InvoiceStatus ​

typescript
type InvoiceStatus = 
  | "Draft"      // Not finalized
  | "Sent"       // Sent to customer
  | "Viewed"     // Customer viewed
  | "Paid"       // Fully paid
  | "Partial"    // Partially paid
  | "Overdue"    // Past due date
  | "Cancelled"  // Cancelled/Voided
  | "Refunded";  // Refunded

PaymentStatus ​

typescript
type PaymentStatus = 
  | "Pending"    // Processing
  | "Approved"   // Successful
  | "Declined"   // Failed
  | "Refunded"   // Refunded
  | "Cancelled"; // Cancelled

PaymentMethod ​

typescript
type PaymentMethod = 
  | "CreditCard"
  | "DebitCard"
  | "BankTransfer"
  | "ACH"
  | "Check"
  | "Cash"
  | "PayPal"
  | "Stripe"
  | "Other";

CreditNoteType ​

typescript
type CreditNoteType = 
  | "Refund"     // Payment refund
  | "Discount"   // Discount credit
  | "Return"     // Product return
  | "Adjustment" // General adjustment
  | "WriteOff";  // Bad debt write-off

CreditNoteStatus ​

typescript
type CreditNoteStatus = 
  | "Draft"      // Not finalized
  | "Issued"     // Available for use
  | "Partial"    // Partially used
  | "Applied"    // Fully used
  | "Expired"    // Past expiry date
  | "Voided";    // Cancelled

SubscriptionStatus ​

typescript
type SubscriptionStatus = 
  | "Pending"    // Not yet started
  | "Trial"      // In trial period
  | "Active"     // Currently active
  | "PastDue"    // Payment failed
  | "Paused"     // Temporarily paused
  | "Cancelled"  // Cancelled by user
  | "Expired";   // Term ended

BillingCycle ​

typescript
type BillingCycle = 
  | "Daily"
  | "Weekly"
  | "Biweekly"
  | "Monthly"
  | "Quarterly"
  | "SemiAnnual"
  | "Annual"
  | "Custom";

DiscountType ​

typescript
type DiscountType = "Percentage" | "Amount";

ItemType ​

typescript
type ItemType = 
  | "Product"
  | "Service"
  | "Subscription"
  | "Fee"
  | "Discount"
  | "Tax"
  | "Other";

RefundType ​

typescript
type RefundType = "Full" | "Partial";

RefundMethod ​

typescript
type RefundMethod = 
  | "OriginalPaymentMethod"
  | "Credit"
  | "Check"
  | "BankTransfer"
  | "Other";

Validation Rules ​

Common Validation Rules ​

Monetary Values ​

  • Must be positive numbers
  • Maximum 2 decimal places
  • Maximum value: 999,999,999.99
  • Minimum value: 0.00 (0.01 for required amounts)

Dates ​

  • Format: ISO 8601 (YYYY-MM-DD for dates, YYYY-MM-DDTHH:mm:ssZ for datetimes)
  • Dates cannot be more than 100 years in the past
  • Due dates must be today or future
  • Date ranges: fromDate must be before or equal to toDate

Strings ​

  • Maximum length varies by field (typically 255 characters)
  • Required fields cannot be empty strings
  • Email addresses must be valid format
  • Phone numbers should include country code

UUIDs ​

  • Must be valid UUID v4 format
  • Case-insensitive matching

Field-Specific Validation ​

Invoice ​

  • invoiceNumber: Unique per tenant, max 50 characters
  • items: Must have at least 1 item
  • dueDate: Must be >= invoiceDate
  • totalAmount: Must equal sum of items + tax - discount

Payment ​

  • amount: Must be > 0
  • creditCard.cardNumber: Must pass Luhn check
  • creditCard.expiryMonth: 01-12
  • creditCard.expiryYear: Current year or future
  • creditCard.cvv: 3-4 digits

Credit Note ​

  • totalAmount: Must be > 0
  • remainingAmount: Cannot exceed totalAmount
  • expiryDate: Must be future date if specified

Subscription ​

  • startDate: Can be today or future
  • price: Must be >= 0
  • trialDays: 0-365
  • billingCycle: Must be valid enum value

Address ​

  • country: Must be valid ISO 3166-1 alpha-2 code
  • postalCode: Format varies by country
  • state: Required for US, Canada, Australia

Custom Field Validation ​

Custom fields support the following types:

  • string: Max 1000 characters
  • number: Decimal up to 10 digits
  • boolean: true/false
  • date: ISO 8601 format
  • array: Max 100 items
  • object: Max 50 properties

Response Headers ​

All API responses include standard headers:

http
X-Request-Id: uuid-v4
X-Response-Time: 123
X-Rate-Limit-Limit: 60
X-Rate-Limit-Remaining: 45
X-Rate-Limit-Reset: 1609459200
Content-Type: application/json

JSON Schema ​

Complete JSON schemas are available:

For implementation examples using these models, see the Integration Examples directory.

Copyright © 2025 Engagifii