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)Standardized per model (for example transaction statuses use PAID, 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 caseUppercase schema values (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, UNKNOWN
Contact StatusLimited trackingFull lifecycle: ACTIVE, INACTIVE, SUSPENDED, ARCHIVED, UNKNOWN
Contact TypeBasicClear enum: CUSTOMER, VENDOR, BOTH, UNKNOWN
Item TypeLimitedStandardized: INVENTORY, NON_INVENTORY, SERVICE, DIGITAL, UNKNOWN
Account CategoryPlatform-specificUnified: ASSET, EXPENSE, LIABILITY, EQUITY, INCOME, BANK, UNKNOWN
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:
  • Enum values are standardized per model schema, and transaction enums use uppercase values such as PAYMENT, PAID, and CARD
  • Use expand parameter to include related objects (e.g., expand=contact,line_items)
  • SUBMITTED replaces various “open/pending” states across platforms
  • UNKNOWN value is available on applicable models when platform data cannot be mapped

​
Cross-API Standardization

V4 ensures consistency across Payments, E-commerce, and Accounting:
FeatureStandardization
All EnumsStandardized to the documented schema for each model
Transaction TypesUnified: PAYMENT, REFUND, CREDIT_NOTE, FEE, CHARGEBACK, PAYOUT, ADJUSTMENT
Payment MethodsUnified: CARD, BANK_TRANSFER, WIRE_TRANSFER, PAYPAL, APPLE_PAY, GOOGLE_PAY, CHECK, CASH, CRYPTO, OTHER, UNKNOWN
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: SHIPPING, BILLING, COMPANY, 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: