Merchants

Authentication

Requests require authentication using your API key in the `X-API-Key` header. See the Authentication guide.

For organization-level settings, pricing, and metrics, prefer the Organizations API when your integration key is org-scoped.

Endpoints

Get merchant details

Retrieves detailed information about a specific merchant account.

Endpoint: `GET /merchants/{id}`

Path parameters:

Example response (200 OK):

{
  "data": {
    "merchant_id": "904d003c-3736-41d4-90a5-9de74d404fd7",
    "name": "Test Merchant",
    "email": "merchant@example.com",
    "phone_number": "+123456789",
    "country": "SN",
    "mrr": 50000, // In smallest currency unit
    "arr": 600000, // In smallest currency unit
    "merchant_lifetime_value": 14250, // Predicted per-customer LTV in org default currency
    "retry_payment_every": 3,
    "total_retries": 5,
    "metadata": {
      "industry": "e-commerce"
    },
    "created_at": "2023-01-15T10:30:00Z",
    "updated_at": "2023-02-20T14:45:00Z"
  }
}

(See Data Models for property descriptions)

Possible error responses:

Get merchant monthly recurring revenue (MRR)

Retrieves the current MRR for a merchant.

Endpoint: `GET /merchants/{id}/mrr`

Path parameters:

Example response (200 OK):

{
  "data": {
    "merchant_id": "904d003c-3736-41d4-90a5-9de74d404fd7",
    "mrr": 50000, // In smallest currency unit
    "currency_code": "XOF",
    "as_of_date": "2023-04-01T00:00:00Z"
  }
}

Possible error responses:

Get merchant annual recurring revenue (ARR)

Retrieves the current ARR for a merchant.

Endpoint: `GET /merchants/{id}/arr`

Path parameters:

Example response (200 OK):

{
  "data": {
    "merchant_id": "904d003c-3736-41d4-90a5-9de74d404fd7",
    "arr": 600000, // In smallest currency unit
    "currency_code": "XOF",
    "as_of_date": "2023-04-01T00:00:00Z"
  }
}

Possible error responses:

Get merchant account balance

Retrieves the current account balance for a merchant in a specific currency.

Endpoint: `GET /merchants/{id}/balance`

Path parameters:

Query parameters:

Example response (200 OK):

{
  "data": {
    "merchant_id": "904d003c-3736-41d4-90a5-9de74d404fd7",
    "currency_code": "XOF",
    "balance": 250000, // In smallest currency unit
    "as_of_date": "2023-04-01T12:30:45Z"
  }
}

Possible error responses:

Implementation notes

• Organization scoping: Merchant details, MRR, and ARR are always returned for the organization bound to your API key. If a merchant belongs to multiple organizations, you only see metrics for the org your key is linked to — never cross-org data.
• Cached organization metrics (`mrr`, `arr`, `merchant_lifetime_value`, transaction and customer counts) are refreshed daily at 03:00 UTC for live data, and again when subscriptions change. `as_of_date` on MRR/ARR responses reflects the last refresh; balance `as_of_date` is the account `updated_at`.
• `mrr` / `arr` are the linked organization's Monthly / Annual Recurring Revenue from active subscriptions, in the org default currency.
• `merchant_lifetime_value` is a predicted per-customer LTV for the linked organization (live environment): Customer Value (net revenue per paying customer) multiplied by Average Lifespan (derived from repeat purchase behavior, capped at 5x). Refreshed with other cached metrics. This is not platform profit from the merchant (admin-only).
• All monetary values are returned in the smallest currency unit (e.g., cents for USD, XOF represents the base unit directly).
• Dates and times are returned in ISO 8601 format (`YYYY-MM-DDTHH:mm:ssZ`).
• See the Errors guide for general error handling information.