Marketplace

info

Platform note. Marketplace ships on the Modo (Ecomm 1.0) stack today. Ecomm 2.0 maintains backward compatibility with Modo and the platform team will add Marketplace to the Ecomm 2.0 OpenAPI specification in the upcoming work cycle. Until then, the order_line_items / seller_id shape documented below is canonical.

Overview

Marketplaces are businesses that provide a centralised platform for trading, enabling customers to compare and purchase products or services from multiple sellers in a single order.

The Charge API supports marketplaces by allowing per-seller line items within a single order. Each line item carries the seller's identifier and the item's attributes (quantity, unit price), plus an open item_extra_fields array for any merchant-defined metadata used in downstream reconciliation.

note

For the operational Marketplace API (balance, payout requests, payout responses), see Marketplace API. This page covers the Charge API extension that captures marketplace order line items at point of payment.

How to use marketplace order line items

The order_line_items array allows marketplaces to break a single order into multiple per-seller entries. Each entry describes one seller's contribution to the order, including the seller identifier, the items purchased, and any extra fields the merchant wishes to attach.

Payload

{
  "order_request": {
    "order_line_items": [
      {
        "details_format": "details",
        "order_line_item_type": "seller_line_item",
        "order_line_item_details": [
          {
            "seller_id": "e67a0b0b-695a-47f9-ad93-680ec190c70c",
            "total_price": { "value": 300 },
            "extra_fields": [
              { "key": "customerEmail", "value": "customer@example.com" },
              { "key": "internalId", "value": "ORD-A-3456" }
            ]
          }
        ]
      },
      {
        "details_format": "details",
        "order_line_item_type": "seller_line_item",
        "order_line_item_details": [
          {
            "seller_id": "32ca8dd8-ea60-444d-af0c-fe085616ae9e",
            "total_price": { "value": 600 },
            "extra_fields": [
              { "key": "customerEmail", "value": "customer@example.com" },
              { "key": "internalId", "value": "ORD-B-8837" }
            ]
          }
        ]
      }
    ]
  }
}

Fields

Field	Type	Validation	Description
details_format	string (enum)	details or encrypted	Maintains consistency with the existing Charge API schema's details_format convention.
order_line_item_type	string (enum)	product_line_item or seller_line_item	Differentiates standard product line items from marketplace seller line items. Use seller_line_item for marketplace orders.
order_line_item_details	array	Mandatory	Array of seller line item objects matching the schema below.
order_line_item_details[].seller_id	string (UUID)	Mandatory	UUID of the seller, generated by DMG at seller onboarding.
order_line_item_details[].total_price	object	Mandatory	The total price for the seller's contribution to the order. Uses the same { value } structure as other price fields in the Charge API.
order_line_item_details[].extra_fields	array	Optional	Key-value pairs for any merchant-defined metadata associated with this line item. DMG does not use these fields operationally; they are passed through and made available at settlement for the merchant's reconciliation.

Settlement

The extra_fields entries are exported at settlement alongside the standard transaction record, enabling marketplaces to reconcile incoming funds with their per-seller order data. See the Settlement API for the response shape and sample transactions that include marketplace line items.