Skip to main content

Credit limits (credit_limits)

The Credit Limit payment method. Admins grant a per-Organization limit; Customers consume it at checkout. Reservations are atomic and idempotently released on invoice paid or order cancellation.

Public surface​

All admin routes are gated by the credit_limits:manage permission.

Verb + PathAudiencePurpose
GET /api/v1/me/credit-limitcustomerView granted limit + currently reserved (404 CREDIT_LIMIT_NOT_GRANTED if none)
GET /api/v1/admin/credit-limitsadminRoster of every granted limit with active reservations
GET /api/v1/admin/organizations/:id/credit-limitadminOne organization's limit + reservations
POST /api/v1/admin/organizations/:id/credit-limitadminGrant initial limit
PATCH /api/v1/admin/organizations/:id/credit-limitadminAdjust amount (rejects below active reservations unless allowOverAllocation)

Storefront UX: the Account profile and Checkout page render a CreditLimitWidget (granted / available / reservation breakdown) when the limit exists; credit_limit-kind payment methods are filtered out of Checkout when no limit is granted or the cart total exceeds the available credit.

Which reservations a customer sees: the limit is shared, so the granted amount, the available amount and activeReservationCount are always the Organization's figures. The activeReservations list holds only the reservations of orders the customer may read: their own orders, or every order of the Organization when their organization role holds orders.view_organization (the Administrator role holds it implicitly). The admin routes always list every reservation.

Every listed reservation carries orderBusinessId, its order's customer-facing number (null for an order the orders module did not return), on the customer's route and on the three admin views. The admin credit-limit screen shows that number in its reservation table, linked to the order.

Concurrency model​

CreditLimitService.reserve() opens a SELECT … FOR UPDATE on the credit_limits row, then inserts the reservation. Two simultaneous orders that would together exceed the limit are serialized; one succeeds and the other receives 409 LIMIT_INSUFFICIENT. See backend/test/contract/credit_limits/concurrent-race.test.ts.

Entities​

CreditLimit, CreditLimitReservation (status: active | released). Index on (credit_limit_id, status) keeps the available-balance query fast.

Events emitted​

credit_limit.granted.v1, credit_limit.adjusted.v1. These are events on the in-process event bus. credit_limit.adjusted.v1 is also offered to outbound webhooks (next section); credit_limit.granted.v1 is not. Releasing a reservation emits no event.

Event offered to outbound webhooks​

The module contributes one event type to the webhooks module's webhookEventRegistry, so a webhook subscription can name it while both modules are switched on. The payload is sent whole; the strict schema is CreditLimitAdjustedEventV1Schema in @endora-commerce/contracts.

EventSent whenPayload, beside eventId and occurredAt
credit_limit.adjusted.v1An administrator adjusts an Organization's limit, or a settled return is credited to it.organizationId (UUID) — the Organization that holds the limit; amount (number) — the granted limit after the change.
  • amount is the new total, not the difference, in the limit's own currency. The currency is not in the payload, and neither are the reserved or available amounts, the reason given, or who made the change.
  • One Organization's data. A platform-wide subscription receives every Organization's events. A subscription bound to an Organization receives only the events whose organizationId is that Organization — never another's. An Organization that inherits a parent's limit is not named: the event names the Organization the limit was granted to.
  • After the commit. The event is sent for an adjustment that was committed. An adjustment that is refused (below the active reservations) or rolled back sends nothing, and a return that was already credited is not announced a second time.
  • While the module is switched off the type is not offered and a new subscription to it is refused; stored subscriptions are kept and receive nothing until it is back on.

In the audit log​

Granting, adjusting and crediting a limit from a return are each one entry in the platform-wide audit log (credit_limit.grant, credit_limit.adjust, credit_limit.credit_from_return), recorded against the Organization. The audit log is read by everybody holding audit_log:read whatever Organizations they may see, so an entry names what changed — changedFields: ['grantedAmount'], and the return case's id for a credit — and holds no amount. The current limit is on the Organization's credit-limit screen. Entries recorded before this change keep the amounts they were written with.

Extension points​

  • Release reasons — releaseByOrder(reason) accepts 'invoice_paid', 'order_cancelled' and 'admin_revocation' today. New reasons (e.g. 'manual_override') are added by extending the enum and wiring the caller.