Introduction

In a marketplace context, DJUST Pay determines which orders are eligible for supplier payouts. A supplier payout is an outgoing payment from the supplier's balance account to the supplier's external bank account.

This page explains how to configure payout eligibility rules and marketplace banking mode via API.

Key Concepts

What is a Supplier Payout?

A supplier payout is an outgoing payment from the supplier's balance account to the supplier's external bank account. It is triggered for orders that meet specific eligibility criteria defined at the tenant level.

Payout Eligibility

An order is eligible for a supplier payout when all of the following conditions are met:

• Payment status = SETTLED
• Logistic status is included in the list of allowed statuses (configurable per tenant, default: SHIPPED)
• The order is not already included in a successfully executed payout (SETTLED)

📘

Re-eligibility

Orders associated with a payout that resulted in FAILED, INSUFFICIENT_FUNDS, or SKIPPED remain eligible for a future payout calculation.

⚠️

Important

Payout eligibility is independent of the balance account's available funds. An order can be eligible even if the supplier's balance is insufficient — the payout will be attempted and may result in an INSUFFICIENT_FUNDS status.

Marketplace Banking Mode

The marketplaceBankingMode setting controls whether the marketplace balance account can advance funds to cover supplier payouts when the supplier's balance is insufficient.

Configuration

Reading the current configuration

Use the following endpoint to retrieve the current payout settings for your tenant:

GET /v1/settings/payouts — operationId: ADM-SETTINGS-507

• Access: dj-client: OPERATOR
• Response: 200 OK

{
  "supplierPayoutEligibility": {
    "allowedLogisticOrderStatuses": ["SHIPPED"]
  },
  "marketplaceBankingMode": "DISABLED",
  "updatedAt": null
}

📘

Note

When no configuration has been explicitly stored, the API returns the default values: allowedLogisticOrderStatuses: ["SHIPPED"], marketplaceBankingMode: "DISABLED", and updatedAt: null.

Updating the configuration

Use the following endpoint to update the payout settings:

PUT /v1/settings/payouts — operationId: ADM-SETTINGS-207

• Access: dj-client: OPERATOR
• Response: 204 No Content

⚠️

Full replacement

This endpoint replaces the entire payout settings configuration. Both supplierPayoutEligibility and marketplaceBankingMode must be provided in every request. Partial updates are not supported.

Request body example

{
  "supplierPayoutEligibility": {
    "allowedLogisticOrderStatuses": ["SHIPPED", "DELIVERED"]
  },
  "marketplaceBankingMode": "DISABLED"
}

This configuration means that orders with a logistic status of either SHIPPED or DELIVERED will be eligible for supplier payouts, and the marketplace balance account will not be used to advance funds.

Validation rules

• Each entry in allowedLogisticOrderStatuses must be a non-empty string.
• Duplicate statuses are silently ignored.
• Unknown logistic statuses are silently ignored — but if all provided statuses are unknown, the API returns a 422 error.
• marketplaceBankingMode must be either ENABLED or DISABLED.

For error codes, see: Error / Warning codes

Typical Workflow

flowchart LR

%% Styles (Readme)
classDef create   fill:#e8f1ff,stroke:#2f6feb,stroke-width:2px,color:#0b3d91;
classDef read     fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#1e1b4b;
classDef update   fill:#e0f7fa,stroke:#06b6d4,stroke-width:2px,color:#0c4a6e;
classDef add      fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#064e3b;
classDef remove   fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#7f1d1d;
classDef decision fill:#fff4e5,stroke:#f59e0b,stroke-width:2px,color:#7a3e00;
classDef place    fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d;
classDef sys      fill:#f2f4f7,stroke:#475569,stroke-width:2px,color:#111827;
classDef ok       fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#064e3b;
classDef stop     fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#7f1d1d;

A[📘 Read current config<br>GET /v1/settings/payouts] --> B{Adjust needed?}
B -->|Yes| C[✏️ Update config<br>PUT /v1/settings/payouts]
B -->|No| D[✅ Config is up to date]
C --> E[📘 Verify new config<br>GET /v1/settings/payouts]
E --> D

class A read
class B decision
class C update
class D place
class E read

style A rx:8,ry:8
style C rx:8,ry:8
style D rx:8,ry:8
style E rx:8,ry:8

Business Rules

Example Scenarios

Scenario 1: Default configuration (ship-then-pay)

The marketplace wants to pay suppliers as soon as orders are shipped (default behavior).

{
  "supplierPayoutEligibility": {
    "allowedLogisticOrderStatuses": ["SHIPPED"]
  },
  "marketplaceBankingMode": "DISABLED"
}

An order becomes eligible for supplier payout when its payment status is SETTLED and its logistic status reaches SHIPPED.

Scenario 2: Pay only after delivery confirmation

The marketplace wants to wait for delivery confirmation before paying suppliers.

{
  "supplierPayoutEligibility": {
    "allowedLogisticOrderStatuses": ["DELIVERED"]
  },
  "marketplaceBankingMode": "DISABLED"
}

Only orders with logistic status DELIVERED are eligible. Orders that are SHIPPED but not yet DELIVERED are excluded.

Scenario 3: Multiple eligible statuses with marketplace advance

The marketplace accepts both SHIPPED and COMPLETED as eligible statuses, and allows the marketplace balance account to advance funds when a supplier's balance is insufficient.

{
  "supplierPayoutEligibility": {
    "allowedLogisticOrderStatuses": ["SHIPPED", "COMPLETED"]
  },
  "marketplaceBankingMode": "ENABLED"
}

Scenario 4: Temporarily block all payouts

The marketplace needs to temporarily suspend all supplier payouts (e.g., during a financial audit).

{
  "supplierPayoutEligibility": {
    "allowedLogisticOrderStatuses": []
  },
  "marketplaceBankingMode": "DISABLED"
}

⚠️

Warning

With an empty list, no orders will be eligible for payouts until the configuration is updated again.

Best Practices

• Review your payout configuration before going live with a new marketplace tenant.
• Use the GET endpoint to verify the current configuration before making changes.
• If you need to temporarily block all payouts, set allowedLogisticOrderStatuses to an empty list [].
• Align the allowed logistic statuses with your business process — e.g., only enable DELIVERED if you want to wait for delivery confirmation before paying suppliers.
• Always send both supplierPayoutEligibility and marketplaceBankingMode in every PUT request, since the endpoint performs a full replacement.

Common Mistakes