# BenjiPays Documentation

> Documentation for BenjiPays

Append .md to any documentation page URL to get its markdown version.

## Guides
- [Authentication](https://developer.benjipays.com/docs/authentication.md): Authenticate with an x-api-key (merchant-scoped) or Auth0 M2M tokens.
- [Errors](https://developer.benjipays.com/docs/errors.md): RFC 7807 problem details, common status codes, and how to interpret error bodies.
- [Getting Started](https://developer.benjipays.com/docs/getting-started.md): A 5-minute overview of the Benji Pays API for new integrators.
- [Idempotency](https://developer.benjipays.com/docs/idempotency.md): Make POST/PATCH/PUT requests safe to retry with the Idempotency-Key header.
- [Pagination](https://developer.benjipays.com/docs/pagination.md): Offset-based pagination, response envelope, and how to iterate through pages.
- [Rate Limits](https://developer.benjipays.com/docs/rate-limits.md): Sliding-window rate limits and how to read the X-RateLimit headers and 429 responses.
- [Request Tracing](https://developer.benjipays.com/docs/request-tracing.md): Use X-Request-ID and X-Correlation-ID to trace individual requests and distributed flows.
- [MCP Server](https://developer.benjipays.com/docs/mcp.md): Connect AI clients directly to the Benji Pays API using the Model Context Protocol (MCP).
- [Dates and Times](https://developer.benjipays.com/docs/dates-and-times.md): How date-range filters and response timestamps work in the Benji Pays API.

## API Reference
- [Get current actor information](https://developer.benjipays.com/reference/get_v2-whoami-1.md): **Access:** Requires any authenticated actor (Auth0 JWT or organization API key)  Returns authenticated actor details and permissions. Accepts either an Auth0 Bearer token or an organization-scoped `x-api-key`.
- [List payment gateways for an Organization](https://developer.benjipays.com/reference/get_v2-gateways.md): Returns enabled payment gateways for the organization associated with the authenticated API key.
- [List invoices for an Organization](https://developer.benjipays.com/reference/get_v2-invoices.md): Returns paginated Benji-controlled camelCase invoice summaries for the authenticated organization. Field names match filter/query params (`invoiceNumber`, `dueDate`, `customerId` → `customer.id`). List responses never include the stored invoice object — use GET /invoices/:invoiceId?include=accounting for that.
- [Get a single invoice by accounting ID](https://developer.benjipays.com/reference/get_v2-invoices-invoiceid.md): Returns the Benji summary DTO for an invoice by its accounting system ID (`id` on the invoice object). Pass `?include=accounting` to nest the full stored invoice under `data.accounting` (fields from the accounting system plus our own).
- [List customers for an Organization](https://developer.benjipays.com/reference/get_v2-customers.md): Returns paginated Benji-controlled camelCase customer summaries for the organization associated with the authenticated API key. Mirrors the data set shown in the merchant-app customers table. List responses never include the stored customer object — use GET /customers/:customerId?include=accounting for that.
- [Get a single customer by accounting ID](https://developer.benjipays.com/reference/get_v2-customers-customerid.md): Returns the Benji summary DTO for a customer by its accounting system ID (`id` on the customer object). Pass `?include=accounting` to nest the full stored customer under `data.accounting` (fields from the accounting system plus our own).
- [List note categories](https://developer.benjipays.com/reference/get_v2-notes-categories.md): Returns enabled system categories plus custom categories for the authenticated organization only.
- [List note statuses](https://developer.benjipays.com/reference/get_v2-notes-statuses.md): Returns enabled system statuses plus custom statuses for the authenticated organization only.
- [List customer note threads](https://developer.benjipays.com/reference/get_v2-customers-customerid-notes.md): Lists paginated root note threads with reply counts and latest activity for a customer.
- [Create a customer note thread](https://developer.benjipays.com/reference/post_v2-customers-customerid-notes.md)
- [Get a customer note thread](https://developer.benjipays.com/reference/get_v2-customers-customerid-notes-noteid.md)
- [Update a root note or comment](https://developer.benjipays.com/reference/patch_v2-customers-customerid-notes-noteid.md)
- [Soft-delete a root note or comment](https://developer.benjipays.com/reference/delete_v2-customers-customerid-notes-noteid.md): Comments may be deleted only by their author or a full admin, and only before a later reply exists.
- [Add a comment to a customer note thread](https://developer.benjipays.com/reference/post_v2-customers-customerid-notes-noteid-replies.md): Adds a one-level comment to a root note. Replying to another comment is rejected.
- [Set root note status](https://developer.benjipays.com/reference/post_v2-customers-customerid-notes-noteid-status.md)
- [Pin a root note as customer alert](https://developer.benjipays.com/reference/post_v2-customers-customerid-alert.md)
- [Remove customer alert](https://developer.benjipays.com/reference/delete_v2-customers-customerid-alert.md): Unpins the standing customer alert without deleting the note.
- [List payment methods for an Organization](https://developer.benjipays.com/reference/get_v2-payment-methods.md): Returns paginated saved payment methods (profiles) for the organization associated with the authenticated API key. Filter by accounting `customerId` (QuickBooks Id, Xero ContactID, etc.) to list methods for one customer — the same pattern as the legacy `/api/profiles/list` route. Each item includes an internal Benji Pays profile `id`; there is no accounting-system payment-method identifier to address a single resource by path.
- [Create an unapplied (no-invoice) payment link](https://developer.benjipays.com/reference/post_v2-payment-links-unapplied.md): Creates a no-invoice payment link for the organization associated with the authenticated API key. The payment will be added to the payment to apply table. Does not create/attach an accounting invoice and does not email the link — the caller sends `url` to the payer. Requires `organizations:payment-links:create`.
- [Create an applied (invoice-tied) payment link](https://developer.benjipays.com/reference/post_v2-payment-links-applied-invoiceid.md): Creates a tokenized payment link tied to an existing accounting invoice for the organization associated with the authenticated API key. After pay, the payment applies to that invoice. For security, we recommend passing `allowSavedPaymentMethods: false` unless you have independently authenticated the user and are certain they are authorized to use the invoice customer’s saved payment methods. Setting it to `true` may display existing on-file payment methods and allows the user to pay with them. Does not email the link — the caller sends `url`. Requires `organizations:payment-links:create`.
- [List transactions for an Organization](https://developer.benjipays.com/reference/get_v2-transactions.md): Returns paginated payment transactions for the organization associated with the authenticated API key. Matches the data visible in the merchant-app transaction reporting table, including enriched settlement fields. Filter by date range, transaction type/status, accounting customer, gateway, and more.
- [Get profile for an Organization](https://developer.benjipays.com/reference/get_v2-organization.md): Returns the normalized profile for the organization associated with the authenticated API key.
- [List users for an Organization](https://developer.benjipays.com/reference/get_v2-users.md): Returns a paginated list of login accounts for the organization associated with the authenticated API key, including MFA enabled status.
- [List sent emails for an Organization](https://developer.benjipays.com/reference/get_v2-emails.md): Returns paginated sent emails for the organization associated with the authenticated API key. Matches the merchant-app email history, restricted to merchant-facing email types. Filter by customer, type, status, and sent-date range.
- [Get a single sent email](https://developer.benjipays.com/reference/get_v2-emails-emailid.md): Returns a single sent email by its `id` (from the list endpoint), including the body content and the full delivery event timeline. Scoped to the authenticated organization and restricted to merchant-facing email types.
- [List the auto-processing forecast for an Organization](https://developer.benjipays.com/reference/get_v2-autoprocessing-forecast.md): Returns a paginated auto-processing forecast: for each open invoice, whether it will be auto-charged on the supplied run date and the reasons behind that decision. Matches the merchant-app batch forecast report. Requires a connected accounting system.
- [Get settings for an Organization](https://developer.benjipays.com/reference/get_v2-settings.md): Returns the normalized settings for the organization associated with the authenticated API key.
- [Get current actor information](https://developer.benjipays.com/reference/get_v2-whoami.md): **Access:** Requires any authenticated actor (Auth0 JWT or organization API key)  Returns authenticated actor details and permissions. Accepts either an Auth0 Bearer token or an organization-scoped `x-api-key`.
- [Echo request body](https://developer.benjipays.com/reference/post_v2-whoami-echo.md): **Access:** Requires any authenticated actor (DISTRIBUTOR, PARTNER, or ORGANIZATION)  Validates and echoes back the request body. Requires JWT authentication.
- [List plans for authenticated distributor](https://developer.benjipays.com/reference/get_v2-plans.md): **Access:** Requires DISTRIBUTOR actor type  Returns a paginated list of plans visible to the authenticated distributor. Plans can be filtered by status and partnerId (for custom-priced plans).  **Visibility:** - Distributors see plans with their distributorExternalId - Can optionally filter by partnerId for partner-specific custom pricing  Requires JWT authentication and 'partners:plans:read' scope.
- [Get a single plan by ID](https://developer.benjipays.com/reference/get_v2-plans-planid.md): **Access:** Requires DISTRIBUTOR actor type  Returns details for a specific plan by its MongoDB ObjectId. The plan must be visible to the authenticated distributor.  **Visibility:** - Returns 404 if plan doesn't exist or doesn't belong to the distributor (prevents enumeration)  Requires JWT authentication and 'partners:plans:read' scope.
- [Create a new Partner](https://developer.benjipays.com/reference/post_v2-partners.md): **Access:** Requires DISTRIBUTOR actor type  Creates a Partner entity (MSP, accountant, ISO) under the authenticated distributor. The authenticated distributor's external ID becomes the distributorExternalId for the new Partner.  **Important:** - externalId must be unique per distributor - Status is automatically set to 'active' - Returns 409 Conflict if externalId already exists  Requires JWT authentication and 'partners:accounts:create' scope.
- [List all partners for authenticated distributor](https://developer.benjipays.com/reference/get_v2-partners.md): **Access:** Requires DISTRIBUTOR actor type  Lists all Partners (MSP, accountant, ISO) under the authenticated distributor with pagination and optional filtering.  **Features:** - Sorted alphabetically by name - Filter by status or externalId - Includes organization count for each partner  Requires JWT authentication and 'partners:accounts:read' scope.
- [Get a specific partner by ID](https://developer.benjipays.com/reference/get_v2-partners-partnerid.md): **Access:** Requires DISTRIBUTOR actor type  Retrieves details for a specific Partner by its MongoDB ObjectId. Only returns partners that belong to the authenticated distributor (enforces isolation).  **Note:**  - To search by externalId, use GET /v2/partners?externalId=xyz instead - Returns 404 if partner doesn't exist or doesn't belong to this distributor (prevents enumeration)  Requires JWT authentication and 'partners:accounts:read' scope.
- [List Organizations](https://developer.benjipays.com/reference/get_v2-organizations.md): **Access:** Requires DISTRIBUTOR or PARTNER actor type.  Lists Organizations with optional filtering and pagination.  - **Distributor:** Returns all organizations under the distributor. Use `partnerId` to filter by a specific partner, or `directOnly=true` to return only distributor-direct organizations. - **Partner:** Returns only the partner's own organizations. The `partnerId` and `directOnly` query params are ignored.
- [Create a new Organization](https://developer.benjipays.com/reference/post_v2-organizations.md): **Access:** Requires DISTRIBUTOR or PARTNER actor type.  Creates an Organization (Benji Pays company). Supports three flows: - **Distributor direct** (no `partnerId` in body) — org owned directly by distributor - **Partner direct** (caller is a partner) — org owned by the calling partner - **Distributor on behalf of partner** (`partnerId` in body) — org owned by the specified partner  Requires JWT authentication and `partners:organizations:create` scope.
- [Get single Organization by ID](https://developer.benjipays.com/reference/get_v2-organizations-organizationid.md): **Access:** Requires DISTRIBUTOR or PARTNER actor type  Gets details for a specific Organization.  - **Distributor:** Can access any organization under their distributor. - **Partner:** Can only access organizations under their own partner account.
- [Suspend an Organization](https://developer.benjipays.com/reference/post_v2-organizations-organizationid-suspend.md): **Access:** Requires DISTRIBUTOR actor type  Suspends an Organization by disabling access and billing. Used when a Partner (MSP) is not paying their distributor bill.  Requires JWT authentication and 'partners:organizations:suspend' scope.
- [Activate an Organization](https://developer.benjipays.com/reference/post_v2-organizations-organizationid-activate.md): **Access:** Requires DISTRIBUTOR actor type  Re-activates a suspended Organization by enabling access and billing.  Requires JWT authentication and 'partners:organizations:activate' scope.
- [Close an Organization](https://developer.benjipays.com/reference/post_v2-organizations-organizationid-close.md): **Access:** Requires DISTRIBUTOR actor type  Closes an Organization by disabling access, billing, and marking as closed. This is a permanent state change (unlike suspend which is temporary).  **Updates:** - `enabled: false` - `billing.enabled: false` - `closed: true` - `lastUpdated: new Date()`  **Activity Log:** - Creates activity log entry with reason  **Note:** Cannot close an already closed organization (returns 409).  Requires JWT authentication and 'partners:organizations:close' scope.
- [Change organization plan](https://developer.benjipays.com/reference/patch_v2-organizations-organizationid-plan.md): **Access:** Requires DISTRIBUTOR actor type  Changes the billing plan assigned to an Organization. Used when an MSP upgrades or downgrades a customer's subscription.  **Workflow:** 1. Validates organization belongs to authenticated distributor 2. Validates new plan is visible to distributor (in their plan catalog) 3. Checks that new plan is different from current plan 4. Updates `billing.planId` and `billing.details` on organization 5. Creates activity log entry with previous and new plan details  **Billing Implications:** - Plan change takes effect immediately - Current month billed at new plan rate (no proration for now) - Usage/overages calculated against new plan's included transactions  **Validations:** - Cannot change to the same plan (returns 409) - New plan must belong to distributor's catalog (returns 404 if not) - Organization must belong to distributor (returns 404 if not)  Requires JWT authentication and 'partners:organizations:change-plan' scope.
- [Resend admin invite for an Organization](https://developer.benjipays.com/reference/post_v2-organizations-organizationid-resend-invite.md): **Access:** Requires DISTRIBUTOR actor type  Resends the admin onboarding invite email for an Organization. Deletes any existing incomplete invites and creates a new one.  **Workflow:** 1. Deletes existing incomplete invite(s) from loginInvites collection 2. Creates and sends new invite using existing inviteUser() flow 3. Creates activity log entry  **Email:** - If `email` provided in request body, uses that email - Otherwise, uses organization's existing admin email  **Requirements:** - Organization must be in `pending_activation` status - Cannot resend invite to already activated organization (returns 409) - Organization must belong to authenticated distributor  Requires JWT authentication and 'partners:organizations:resend-invite' scope.
- [Get usage snapshot for a month](https://developer.benjipays.com/reference/get_v2-usage.md): **Access:** Requires DISTRIBUTOR actor type  Returns usage data for all Organizations under the authenticated distributor for a specified month. Used by distributors (e.g., Sherweb) to show consumption in marketplace dashboards.  **Important Notes:** - Always calculates for entire month (MTD if current month, full month if past) - endDate is validated but effectively ignored for calculation - NFR plans are represented as $0 plans, no separate flag - Each organization may have 1+ items: base plan SKU + one row per overage tier (BENJI-{PLAN}-OVERAGE-TIER{n})  **Calculation:** - Uses existing billing.js helpers (getPlanTypeFromUser) - Queries results collection for transaction counts - Uses user.billing.details for plan info (priceRanges) - Integrates with autopay.isCompanyInFreeTrial() for trial status  Requires JWT authentication and 'partners:usage:read' scope.
- [Get finalized billing data for a month](https://developer.benjipays.com/reference/get_v2-billing.md): **Access:** Requires DISTRIBUTOR actor type  Returns finalized billing data for a completed month. Used by distributors for invoicing and reconciliation. Data is locked and should match what was actually billed.  **Key Differences from Usage API:** - Usage API: Real-time calculation for dashboard visibility (can query current month) - Billing API: Finalized/locked data for invoicing (only completed months)  **Availability:** - Period must be a completed month (not current or future month) - Data available after billing runs on 1st of month (~2-3am) - Returns 404 if billing not yet run for period  **Implementation:** - Queries billingInvoices collection by apiParent.distributorExternalId and period - Optional filters: partnerId (apiParent.partnerId), organizationId (userId) - Offset-based pagination (limit, offset) - Returns finalized pricing (unitPrice, total) with apiParent (type, distributorExternalId, partnerExternalId, partnerId)  **Note:** NFR plans are represented as $0 plans (unitPrice: 0), no separate flag.  Requires JWT authentication and 'partners:billing:read' scope.