Introduction

The marketplace commissions matrix is the operator-managed table that defines the commission rate retained by the marketplace owner for each supplier. These rates feed directly into the commission split computed at the capture of every card payment.

The marketplace commission rate is configurable by the operator on a per-supplier basis, in contrast with the platform commission, which is set contractually with Djust at the tenant level.

Key Concepts

What is the Marketplace Commission?

In a marketplace context, the marketplace commission is the share of each captured payment that is routed to the marketplace owner's balance account, on top of the platform commission paid to Djust. The remaining amount is the supplier share, credited to the supplier's balance account.

Component	Recipient
Platform commission	Djust platform balance account
Marketplace commission	Marketplace owner balance account (tenant)
Supplier share	Supplier balance account

Per-Supplier Rate

Each line of the matrix associates one active supplier with a single commission rate. A supplier can have at most one active line in the matrix.

The matrix is consumed at capture time. Historical transactions are never recomputed when a rate changes — every capture freezes the rates effective at that moment.

Access Control

The matrix is restricted to operator users. Suppliers and account customer users cannot read or write their own commission rate. This protects the contractual rate negotiated by the operator.

Client	Permissions
`OPERATOR`	Read, create, update, delete, change status
`ACCOUNT`	None — `403 Forbidden` (`F-E-030`)
`SUPPLIER`	None — `403 Forbidden` (`F-E-030`)

Resource Model

A marketplace commission line carries the following information:

Field	Type	Description
`supplierId`	string	External ID of the supplier (must be active)
`supplierName`	string	Human-readable supplier name
`commissionRate`	number	Decimal rate, strictly greater than `0` and strictly lower than `1`
`status`	string	`ACTIVE` or `INACTIVE`
`updatedAt`	datetime	Last modification timestamp
`updatedBy`	string	Identifier of the operator who applied the change

{
  "supplierId": "SUP-48712",
  "supplierName": "ACME Logistics",
  "commissionRate": 0.025,
  "status": "ACTIVE",
  "updatedAt": "2026-04-27T10:12:33Z",
  "updatedBy": "[email protected]"
}

Managing the Matrix via API

The CRUD endpoints follow Djust standard conventions and are restricted to OPERATOR.

Action	Method & Path	OperationId
Create a line	`POST /v1/payments/marketplace-commissions`	ADM-PAY-103
List all lines	`GET /v1/payments/marketplace-commissions`	ADM-PAY-550
Read one line	`GET /v1/payments/marketplace-commissions/{supplierId}`	ADM-PAY-500
Update a rate	`PUT /v1/payments/marketplace-commissions/{supplierId}`	ADM-PAY-200
Update status	`PATCH /v1/payments/marketplace-commissions/{supplierId}`	ADM-PAY-201
Delete a line	`DELETE /v1/payments/marketplace-commissions/{supplierId}`	ADM-PAY-300

Listing and Filtering

The list endpoint (ADM-PAY-550) supports the following sort fields and filters:

Sort fields (format `sort=field:direction`)
`createdAt` (default: `desc`)
`supplierName`

Filter	Behavior
`supplierId`	Multi-valued, comma-separated
`supplierName`	Multi-valued, comma-separated
`commissionRateMin`	Lower bound (inclusive) on the rate
`commissionRateMax`	Upper bound (inclusive) on the rate

Invalid sort entries are silently ignored, following the standard Djust convention.

Lifecycle

Creating a Line

A supplier can have at most one line in the matrix. Attempting to create a second line for the same supplier returns 409 Conflict (F-E-003).

The supplier must exist and be active. Otherwise, the call returns 404 Not Found (F-E-002).

Updating a Rate or Status

Updating a line records the operation in the audit trail (date, operator, before/after values). The change applies only to future captures — historical transactions are never recomputed.

The PATCH endpoint (ADM-PAY-201) toggles the line between ACTIVE and INACTIVE. An INACTIVE line is preserved for traceability but is ignored when computing splits at capture.

Deleting a Line

Deletion permanently removes the line and disables it for future captures. Existing captures and their recorded splits are unaffected.

Validation Rules

The marketplace commission rate follows the same validation rules as the platform commission rate, ensuring consistency across all commission types in Djust Pay:

Rule	Detail
Range	Strictly greater than `0` and strictly lower than `1`. A rate of `1.0` is rejected.
Precision	The stored rate is the exact decimal representation. No rounding is applied at storage.
Input precision	API input may be limited to 4 decimal places.
Format	Decimal number — for example `0.025` for `2.5%`.
Supplier reference	The `supplierId` field must be the supplier external ID.

Error Codes

HTTP	Code	Typical message
400	`F-E-012`	Field does not respect expected format.
401	`F-E-032`	Unauthorized. Missing or invalid authentication token.
403	`F-E-030`	Caller is not allowed to perform this action.
404	`F-E-002`	Supplier not found for the provided identifier.
409	`F-E-003`	A commission line already exists for this supplier.
422	`F-E-006`	Negative value not allowed.
422	`F-E-007`	Value out of allowed range.

Audit Trail

Every write operation (create, update, status change, delete) records:

The timestamp of the change
The operator who performed the change
The operation type
On updates, the before/after values

This trail is used for reconciliation and contractual audits.

Commission Split Calculation — how the marketplace rate is combined with the platform rate at capture
Managing Card Payments — full card payment lifecycle

Marketplace Commissions Matrix