> ## Documentation Index
> Fetch the complete documentation index at: https://integrations.docs.commenda.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Learn how to use the Commenda Integrations APIs - Version 4

## 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**: Status and type fields use uppercase schema values where applicable (for example `ACTIVE`, `DRAFT`, `PAID`, `PENDING`)

***

## Environments

Default API endpoint is [`https://api.integrations.commenda.io/v4`](https://api.integrations.commenda.io/v4)

KSA (Kingdom of Saudi Arabia) region API endpoint is [`https://api.integrations.sa.commenda.io/v4`](https://api.integrations.sa.commenda.io/v4)

***

## Authentication

All API requests require authentication using an API key. Include your API key in the `api_key` header:

```bash theme={null}
curl -X GET "https://api.integrations.commenda.io/v4/core/companies/1/shared/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://sdk.integrations.commenda.io/oauth/callback`

For the KSA (Kingdom of Saudi Arabia) region, the callback URL is `https://sdk.integrations.sa.commenda.io/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

| Feature                         | V3                                     | V4                                                                              |
| ------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------- |
| Payments, Refunds, Credit Notes | Separate endpoints                     | Unified Transaction model                                                       |
| Payment Links                   | Separate model                         | Embedded in Invoice                                                             |
| Products                        | Separate model                         | Items with embedded Variants                                                    |
| Transaction History             | Separate calls                         | Embedded in Invoice/Subscription                                                |
| Subscription Tracking           | Basic fields                           | `invoice_ids`, `transaction_ids`, billing dates                                 |
| Status Enums                    | Mixed case (e.g., `ACTIVE`, `Pending`) | Standardized per model (for example transaction statuses use `PAID`, `PENDING`) |

**Migration Examples:**

| V3 Endpoint                     | V4 Endpoint                                                                |
| ------------------------------- | -------------------------------------------------------------------------- |
| `GET /v3/payments/payments`     | `GET /v4/core/companies/{company_id}/shared/transactions?type=PAYMENT`     |
| `GET /v3/payments/refunds`      | `GET /v4/core/companies/{company_id}/shared/transactions?type=REFUND`      |
| `GET /v3/payments/credit-notes` | `GET /v4/core/companies/{company_id}/shared/transactions?type=CREDIT_NOTE` |
| `GET /v3/payments/products`     | `GET /v4/core/companies/{company_id}/shared/items`                         |

***

### E-commerce API

| Feature            | V3                          | V4                                                      |
| ------------------ | --------------------------- | ------------------------------------------------------- |
| Payments & Refunds | Separate endpoints          | Unified Transaction model with `type` filter            |
| Products           | Separate model, no variants | Items with embedded Variants (sizes, colors, pricing)   |
| Orders             | Basic structure             | Embedded fulfillments, transactions, and addresses      |
| Fulfillment Status | Limited states              | Enhanced states: `IN_TRANSIT`, `DELIVERED`, `RETURNED`  |
| Inventory Status   | Basic availability          | `IN_STOCK`, `LOW_STOCK`, `OUT_OF_STOCK`, `DISCONTINUED` |
| Status Enums       | Mixed case                  | Uppercase schema values (e.g., `ACTIVE`, `ARCHIVED`)    |

**Migration Examples:**

| V3 Endpoint                  | V4 Endpoint                                                            |
| ---------------------------- | ---------------------------------------------------------------------- |
| `GET /v3/ecommerce/payments` | `GET /v4/core/companies/{company_id}/shared/transactions?type=PAYMENT` |
| `GET /v3/ecommerce/refunds`  | `GET /v4/core/companies/{company_id}/shared/transactions?type=REFUND`  |
| `GET /v3/ecommerce/products` | `GET /v4/core/companies/{company_id}/shared/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

| Feature               | V3                                  | V4                                                                                         |
| --------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------ |
| Invoice/Bill Status   | Mixed values (e.g., `OPEN`, `Paid`) | Standardized: `DRAFT`, `SUBMITTED`, `PARTIALLY_PAID`, `PAID`, `OVERDUE`, `VOID`, `UNKNOWN` |
| Contact Status        | Limited tracking                    | Full lifecycle: `ACTIVE`, `INACTIVE`, `SUSPENDED`, `ARCHIVED`, `UNKNOWN`                   |
| Contact Type          | Basic                               | Clear enum: `CUSTOMER`, `VENDOR`, `BOTH`, `UNKNOWN`                                        |
| Item Type             | Limited                             | Standardized: `INVENTORY`, `NON_INVENTORY`, `SERVICE`, `DIGITAL`, `UNKNOWN`                |
| Account Category      | Platform-specific                   | Unified: `ASSET`, `EXPENSE`, `LIABILITY`, `EQUITY`, `INCOME`, `BANK`, `UNKNOWN`            |
| Expandable Attributes | Limited                             | Rich expansion: `currency`, `line_items`, `contact`, `documents`, `payments`               |

**Status Enum Mapping (Invoices, Bills, Credit Notes, Purchase Orders, Sales Orders):**

| V3 Status                       | V4 Status        |
| ------------------------------- | ---------------- |
| `OPEN` / `Open` / `Pending`     | `SUBMITTED`      |
| `PAID` / `Paid`                 | `PAID`           |
| `PARTIAL` / `PartiallyPaid`     | `PARTIALLY_PAID` |
| `OVERDUE` / `Overdue`           | `OVERDUE`        |
| `DRAFT` / `Draft`               | `DRAFT`          |
| `VOID` / `Voided` / `Cancelled` | `VOID`           |

**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:

| Feature                     | Standardization                                                                                                                       |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **All Enums**               | Standardized to the documented schema for each model                                                                                  |
| **Transaction Types**       | Unified: `PAYMENT`, `REFUND`, `CREDIT_NOTE`, `FEE`, `CHARGEBACK`, `PAYOUT`, `ADJUSTMENT`                                              |
| **Payment Methods**         | Unified: `CARD`, `BANK_TRANSFER`, `WIRE_TRANSFER`, `PAYPAL`, `APPLE_PAY`, `GOOGLE_PAY`, `CHECK`, `CASH`, `CRYPTO`, `OTHER`, `UNKNOWN` |
| **Contact/Customer Type**   | Unified: `CUSTOMER`, `VENDOR`, `BOTH`, `UNKNOWN`                                                                                      |
| **Contact/Customer Status** | Unified: `ACTIVE`, `INACTIVE`, `SUSPENDED`, `ARCHIVED`, `UNKNOWN`                                                                     |
| **Item Type**               | Unified: `INVENTORY`, `NON_INVENTORY`, `SERVICE`, `DIGITAL`, `UNKNOWN`                                                                |
| **Address Type**            | Unified: `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:

* Documentation: [https://integrations.docs.commenda.io](https://integrations.docs.commenda.io)
* Support Email: [support@commenda.io](mailto:support@commenda.io)
* API Status: [https://commenda.betteruptime.com/](https://commenda.betteruptime.com/)