Skip to main content

​
Getting Started with V4

The Commenda Integrations API V4 provides a unified interface for managing customers, invoices, subscriptions, and all payment-related transactions across multiple payment platforms. This version introduces significant improvements including:
  • Unified Transaction Model: Payments, refunds, and credit notes are consolidated into a single Transaction model
  • Embedded Relationships: Invoices include complete transaction history and payment links
  • Enhanced Tracking: Subscriptions track invoice history, transaction IDs, and billing dates
  • Consistent Enums: All status and type fields use standardized, lowercase enum values

​
Environments

Default API endpoint is https://api.rootfi.dev/v4 KSA (Kingdom of Saudi Arabia) region API endpoint is https://api.sa.rootfi.dev/v4

​
Authentication

All API requests require authentication using an API key. Include your API key in the api_key header: 
curl -X GET "https://api.rootfi.dev/v4/payments/contacts" \
  -H "api_key: YOUR_API_KEY"

​
Rate Limits

  • Standard rate limit: 100 requests per minute per API key
  • Burst limit: 200 requests per minute
  • Rate limit headers included in all responses:
    • X-RateLimit-Limit
    • X-RateLimit-Remaining
    • X-RateLimit-Reset

​
Callback URLs

The default callback URL for OAuth2 integrations is https://integrate.rootfi.dev/oauth/callback For the KSA (Kingdom of Saudi Arabia) region, the callback URL is https://app.sa.rootfi.dev/oauth/callback

​
What’s New in V4

V4 introduces a unified, world-class API standardization across all domains. The key improvements help you migrate seamlessly from V3 with better consistency and richer data models.

​
Payments API

FeatureV3V4
Payments, Refunds, Credit NotesSeparate endpointsUnified Transaction model
Payment LinksSeparate modelEmbedded in Invoice
ProductsSeparate modelItems with embedded Variants
Transaction HistorySeparate callsEmbedded in Invoice/Subscription
Subscription TrackingBasic fieldsinvoice_ids, transaction_ids, billing dates
Status EnumsMixed case (e.g., ACTIVE, Pending)Lowercase (e.g., active, pending)
Migration Examples:
V3 EndpointV4 Endpoint
GET /v3/payments/paymentsGET /v4/payments/transactions?type=payment
GET /v3/payments/refundsGET /v4/payments/transactions?type=refund
GET /v3/payments/credit-notesGET /v4/payments/transactions?type=credit_note
GET /v3/payments/productsGET /v4/payments/items

​
E-commerce API

FeatureV3V4
Payments & RefundsSeparate endpointsUnified Transaction model with type filter
ProductsSeparate model, no variantsItems with embedded Variants (sizes, colors, pricing)
OrdersBasic structureEmbedded fulfillments, transactions, and addresses
Fulfillment StatusLimited statesEnhanced states: in_transit, delivered, returned
Inventory StatusBasic availabilityin_stock, low_stock, out_of_stock, discontinued
Status EnumsMixed caseLowercase (e.g., active, archived)
Migration Examples:
V3 EndpointV4 Endpoint
GET /v3/ecommerce/paymentsGET /v4/ecommerce/transactions?type=payment
GET /v3/ecommerce/refundsGET /v4/ecommerce/transactions?type=refund
GET /v3/ecommerce/productsGET /v4/ecommerce/items
Key Improvements:
  • Orders now include fulfillments[] and transactions[] arrays directly in the response
  • Items include variants[] with individual SKUs, pricing, and inventory status
  • Use expand=fulfillments,transactions to get complete order data in a single call

​
Accounting API

FeatureV3V4
Invoice/Bill StatusMixed values (e.g., OPEN, Paid)Standardized: draft, submitted, partially_paid, paid, overdue, void
Contact StatusLimited trackingFull lifecycle: active, inactive, suspended, archived
Contact TypeBasicClear enum: customer, vendor, both
Item TypeLimitedStandardized: inventory, non_inventory, service, digital
Account CategoryPlatform-specificUnified: asset, liability, equity, income, expense
Expandable AttributesLimitedRich expansion: currency, line_items, contact, documents, payments
Status Enum Mapping (Invoices, Bills, Credit Notes, Purchase Orders, Sales Orders):
V3 StatusV4 Status
OPEN / Open / Pendingsubmitted
PAID / Paidpaid
PARTIAL / PartiallyPaidpartially_paid
OVERDUE / Overdueoverdue
DRAFT / Draftdraft
VOID / Voided / Cancelledvoid
Key Improvements:
  • All status and type enums are lowercase for consistency
  • Use expand parameter to include related objects (e.g., expand=contact,line_items)
  • submitted replaces various “open/pending” states across platforms
  • unknown value available when platform data cannot be mapped

​
Cross-API Standardization

V4 ensures consistency across Payments, E-commerce, and Accounting:
FeatureStandardization
All EnumsLowercase values (e.g., active, paid, pending)
Transaction TypesUnified: payment, refund, chargeback, credit_note, fee, payout, adjustment
Payment MethodsUnified: card, bank_transfer, wire_transfer, paypal, apple_pay, google_pay, cash, check, crypto
Contact/Customer TypeUnified: customer, vendor, both, unknown
Contact/Customer StatusUnified: active, inactive, suspended, archived, unknown
Item TypeUnified: inventory, non_inventory, service, digital, unknown
Address TypeUnified: billing, shipping, warehouse

​
Backward Compatibility

V4 maintains backward compatibility through endpoint aliasing for 6 months:
  • Legacy V3 endpoints continue to work but return V3-formatted responses
  • We recommend migrating to V4 endpoints for new integrations
  • Deprecated endpoints are marked in the documentation with migration guides

​
Support

For questions or issues with the API: