Integrate a marketplace service

This guide describes how sellers, offers, inventory, prices, and orders move between commercetools and an external marketplace service through a Connect Connector. That service can be a platform such as Mirakl, Marketplacer, or Convictional, a channel manager, or a service your organization runs itself. The approach is the same for all of them, because the commercetools side of the contract doesn't change.

Some related topics are covered in other guides.

The third row is a hard boundary. When an order management system (OMS) is part of your topology, it owns Delivery, Parcel, and tracking. The marketplace fulfillment application reads that data and forwards it to the marketplace, but never writes it. If two systems write the same Delivery and tracking data, the result is a data-integrity bug.

Before you begin, make sure you have the following:

• a commercetools Project
• access to Connect
• credentials for a marketplace test environment
• an agreed owner for each data domain, as described in Fix the role and the direction

Define the marketplace integration requirements

Marketplace integrations usually fail in the modeling, not in the transport. Record the following decisions before you select, configure, or build anything. Each one changes which applications you need and what they write.

• Marketplace service and API access: identify the service, the account environment, the credentials, and how the service delivers changes. Webhooks that the service calls map to a service application. Endpoints you poll and batch feeds map to a job application.
• Seller count and growth: record how many sellers you have today and how many you expect. Published limits, not preference, decide whether a Store per seller is viable.
• Seller isolation: decide whether sellers need separate storefronts, separate Merchant Center permissions, or separate assortments. Isolation is the only reason to create a Store per seller.
• Same-SKU sellers: decide whether several sellers can sell the same SKU. This is the most consequential decision in the design, and Model sellers and offers covers it.
• Which entities synchronize: for seller records, offer content, inventory, prices, orders, and fulfillment status, record whether each one moves in, out, or not at all.
• Order direction: decide whether marketplace orders arrive in commercetools, whether commercetools Orders are routed out to sellers, or both.
• Onboarding and offboarding: decide what creates a seller, what suspends one, and what a departed seller leaves behind. Offboarding means deactivation, not deletion, for the reason given in Offboard a seller by deactivating it.
• Latency and drift tolerance: these set your reconciliation schedule and your alerting thresholds.
• Region, Project, and Stores: record these, along with any multi-currency, multi-market, or business-to-business requirements.

If a requirement doesn't fit one of these categories, record it as its own item rather than forcing it into one. Cross-border tax obligations, seller-specific shipping contracts, and per-seller returns policies each change the design.

Fix the role and the direction

Your role and the direction of the data determine which applications you build. Decide both before any other architectural question, because everything that follows depends on the row you select.

Name the source of truth per domain

Don't answer "which system is authoritative" once for the whole integration. Offer content, stock, price, orders, and the seller record are usually mastered on different sides, so a single global answer creates sync loops. Assign exactly one owner per data domain, and make the other side read-only for that domain.

Where an OMS is present, it owns the fulfillment row in both roles, and the marketplace application forwards what the OMS wrote.

Keep the two roles in separate deployments

If you operate in both roles, build two sets of applications and deploy them separately. Don't build one application with a mode flag. Combining the roles creates constraints that neither role has on its own.

• Keep Channel roles separate. An operator's seller Channels carry InventorySupply and ProductDistribution. The OrderExport destination is a different Channel again, and a seller-role import destination carries OrderImport. If one Channel carries all four roles, a syncInfo entry can't tell an export from an import.
• syncInfo becomes shared state. Both the outbound and the inbound application read it, so filter entries by Channel and role before you act on them. Otherwise an inbound import marker satisfies an outbound export check, and the Order is never routed.
• Loop risk doubles. A domain that's inbound in one role and outbound in the other becomes a two-way domain, even though neither application is bidirectional on its own. Apply the self-change filter in both directions.

Model sellers and offers

Settle the modeling before the transport. If you choose the wrong transport, you rewrite one application. If you choose the wrong model, you splinter the catalog, and you can't undo that on data that already exists.

commercetools has no seller resource. Instead, you assemble a seller from primitives that already exist.

Answer the same-SKU question first

The consequence of getting this wrong goes beyond performance. Search returns several near-identical products. Ratings and reviews split across those duplicates, and reporting counts the same item several times. Recommendation and merchandising features treat the duplicates as unrelated products. Merging them later means rewriting the catalog, the search index, and your historical reporting.

The per-seller difference lives on the price and the stock record, not on the Product:

• Every seller price is a Standalone Price that carries that seller's distribution Channel. A price written without a channel isn't a seller price at all. Diagnose common failures describes what you see when that happens.
• Every seller stock record is an Inventory Entry that carries that seller's supply Channel. An Inventory Entry written without a supply channel isn't scoped to a seller, and it behaves as global stock for the SKU.

Choose Channel-per-seller before Store-per-seller

Start with a Channel per seller. A Channel scopes both price and stock, which covers what most operators need, and no per-Project limit on Channels constrains a marketplace in practice.

Four published limits apply to a Store-based design, and two of them are decisive.

• A Project holds up to 300 000 Stores.
• A Store references up to 100 supply Channels.
• A Store references up to 100 distribution Channels.
• A Store holds up to 100 Product Selections.

The two channel-count limits rule out one shared Store that lists every seller Channel. That design works during a pilot, then stops accepting sellers as soon as the count passes the limit.

Offboard a seller by deactivating it

Plan offboarding as deactivation from the beginning:

• Stop the inbound offer and inventory sync for that seller.
• Set the seller's Inventory Entries to zero, or remove them where no Order references them.
• Remove the seller's Standalone Prices, or remove the seller's Products from the Product Selections that publish them.
• Remove the Channel from any Store that references it.
• Mark the seller inactive on the Channel Custom Field and in the seller Custom Object, and leave the Channel in place.

Choose an integration path

Rule out the built-in capabilities first

commercetools models multi-party assortments without any external service. Check these capabilities before you plan a Connector, because a Connector adds another system to own, secure, monitor, and pay for.

Check for a deployable Connector

GET https://connect.{region}.commercetools.com/connectors/search?integrationTypes=marketplace&private=false

Confirm a root connect.yaml before treating a listing as deployable

A listing in the Marketplaces category doesn't mean that Connect can deploy it. The category also lists partner-operated platforms that you configure entirely in the vendor's own dashboard, accelerators that deploy as cloud functions or serverless handlers on infrastructure you supply, and iPaaS middleware that connects the two systems from outside. None of these deploy through Connect, and none of them hand you a mapping that you own.

Two further checks protect against a common mistake:

• Recency doesn't mean deployability. For a given marketplace platform, the most recently updated artifact is often the cloud-function accelerator rather than the Connect application. If you compare candidates by last-commit date, you select the one that Connect can't deploy.
• Read how the repository describes its own runtime. If an artifact describes its endpoint as a cloud function, a serverless handler, or an on-premises web service, that's its deployment model, whatever category the listing sits in.

Work down the ladder

Choose the first path that satisfies the requirements:

1. Configure an existing deployable Connector when one exists for your marketplace service and its seller, offer, order, and fulfillment coverage fits.
2. Prove that a gap is not configuration before you fork. Field mappings, the Message selection, the publish-or-stage decision, and the Store and Channel keys are often settings rather than code.
3. Fork a deployable Connector when the gap is genuine and the license permits it. Add only the missing behavior, keep the existing language and framework, and deploy the result as an Organization Connector. If you port the codebase to another language, you discard the mapping that was the reason to fork.
4. Build the applications when no deployable Connector exists for your marketplace service.

Assemble the integration from Channels, Stores, Product Selections, Inventory, and Order Import. These are the primitives that the pattern depends on.

Design and configure the Connector

Keep every flow off the cart hot path

That leaves the two resource types an Extension can target in this domain:

• Don't register marketplace order export on an order Extension. An Extension runs synchronously inside the API request that creates the Order, so marketplace latency or an outage delays or blocks Order creation. Export belongs in an event application driven by a Subscription.
• Check cross-seller cart validation against the Extension time budget. Validating a multi-seller Cart is the one case where a synchronous Extension is arguable. By default, the platform allows 1 second to connect and 2 seconds to respond, and the documented target is to answer within 50 ms. See API Extension time limits before you commit to it, and keep that Extension separate from the sync applications.

Fan out inside the handler, never per seller

Declare the applications in connect.yaml

Keep each direction in its own application. If one application both receives seller offers and pushes orders out, it's harder to scale, harder to debug when one direction fails, and it can't use a different retry policy for each direction.

deployAs:
  - name: marketplace-inbound
    applicationType: service
    endpoint: /marketplace
    scripts:
      postDeploy: npm run connector:post-deploy
      preUndeploy: npm run connector:pre-undeploy
    configuration:
      standardConfiguration:
        - key: MARKETPLACE_BASE_URL
          description: Base URL of the marketplace service
          required: true
        - key: SELLER_CHANNEL_KEY_PREFIX
          description: Prefix applied to seller Channel keys
          required: true
        - key: PUBLISH_MODE
          description: Whether imported offers publish immediately or stage for review
          required: true
        - key: DEFAULT_CURRENCY
          description: Fallback currency when an offer payload omits one
          required: true
      securedConfiguration:
        - key: MARKETPLACE_API_KEY
          description: API key for outbound marketplace calls
          required: true
        - key: INBOUND_WEBHOOK_SECRET
          description: Shared secret used to authenticate inbound marketplace requests
          required: true
  - name: order-router
    applicationType: event
    endpoint: /orders
    scripts:
      postDeploy: npm run connector:post-deploy
      preUndeploy: npm run connector:pre-undeploy
    configuration:
      standardConfiguration:
        - key: MARKETPLACE_BASE_URL
          description: Base URL of the marketplace service
          required: true
        - key: ORDER_EXPORT_CHANNEL_KEY
          description: Key of the Channel carrying the OrderExport role
          required: true
      securedConfiguration:
        - key: MARKETPLACE_API_KEY
          description: API key for outbound marketplace calls
          required: true
  - name: reconciler
    applicationType: job
    endpoint: /reconcile
    configuration:
      standardConfiguration:
        - key: RECONCILE_PAGE_SIZE
          description: Page size for each reconciliation batch
          required: true
inheritAs:
  apiClient:
    scopes:
      - manage_subscriptions
      - manage_products
      - manage_orders
      - manage_standalone_prices
      - manage_key_value_documents
      # Add manage_stores only when the design creates a Store per seller.

Create the correlation Channels before the first order moves

The operator round trip

Implement the sync applications

Upsert by the marketplace identifier

One rule applies to every application: key each commercetools resource on a stable identifier from the marketplace, and write it as an upsert rather than a create. Duplicate-resource failures in this domain almost always trace back to a handler that created unconditionally.

Sync sellers

Authenticate every inbound request before it reaches any handler logic. The endpoint is reachable from the internet, and it creates Channels, Products, and Orders in your Project. Verify a shared secret, or fully validate a token including its signature, issuer, audience, and expiry. Keep the secret in secured configuration, and leave only a liveness route unauthenticated.

For each seller record:

1. Get the Channel by the seller key. On a match, update it with the returned version. On no match, create it.
2. Set the roles the seller needs: InventorySupply always, and ProductDistribution when the seller sets its own prices.
3. Write filterable seller attributes to Channel Custom Fields, so that predicates can select on them.
4. Write the free-form seller profile to the Custom Object container, which needs no prior read.
5. Where Store-per-seller applies, create or update the Store and reference the seller Channel from it.

The seller Channel and its roles must exist before you write any offer, price, or inventory for that seller, because both stock and price scope to it.

Sync offers, inventory, and prices

For each offer:

1. Resolve the seller Channel by key. Stop and record a failure if it does not exist, rather than writing an unscoped price or stock record.
2. Resolve the Product. For a shared SKU, find the existing Product rather than creating a second one.
3. Write the price as a Standalone Price carrying the seller's distribution Channel.
4. Write the stock as an Inventory Entry carrying the seller's supply Channel and a deterministic key.
5. Apply the publish-or-stage decision you recorded. If you publish every imported offer without review, unreviewed seller content reaches the storefront.
6. Handle delisting as an explicit action. A seller that stops carrying an item sends a removal or a zero quantity, and in batch contracts, omission from the next feed is also a delisting signal. An integration that only ever adds keeps selling items that no seller carries.

Three mapping details cause defects that are hard to trace:

• Money is an integer in minor units. Multiply, then round. A floating-point cast drops or inflates cents on every offer, with no error and no exception.
• Derive currency, locale, country, and Region. Don't hardcode them. A hardcoded value works for the first seller and the first market, then breaks for every other one.
• Localized fields follow the payload locale. If you derive them from a single default, the catalog is correct in one language and empty in the rest.

Import marketplace orders

This flow applies to the seller or channel role, where the marketplace captures the order and commercetools records it.

1. Authenticate the caller and validate the payload. The platform accepts negative prices and negative quantities on an import, so validate those yourself rather than relying on an error.
2. Query Orders by orderNumber set to the marketplace order identifier. Import only when no match exists.
3. Build an OrderImportDraft. Set orderNumber to the marketplace identifier, and set totalPrice explicitly. commercetools doesn't calculate totalPrice from the Line Item and Custom Line Item totals, so an incorrect value produces a wrong Order with no error.
4. Set the per-line supplyChannel and distributionChannel, and record the marketplace line identifier in a per-line Custom Field so that later status updates can address a single line.
5. Choose the InventoryMode deliberately. The marketplace already committed the stock, so any mode other than None decrements it a second time. For the behavior of each inventory mode, see Inventory modes.
6. Record the correlation with Update SyncInfo against a Channel carrying the OrderImport role, which postDeploy created.

Order Import produces the Order Imported Message, not Order Created. Every downstream Subscription that reacts to an imported Order must include that Message type.

Route order lines to sellers

This flow applies to the operator role, where a shopper buys from several sellers in one Order.

1. Subscribe to both OrderCreated and OrderImported. An order-routing application subscribed only to OrderCreated silently skips every imported Order, with no error and no failed delivery. Add the recurring-order Message where Orders generated on a schedule must also route.
2. Decode the envelope. The delivery carries base64-encoded data, so a handler that treats it as JSON crashes or logs unreadable output. Validate the Message type, and acknowledge anything this application doesn't act on.
3. Get the Order by resource.id. Don't map from the payload. Subscriptions deliver at least once with no ordering guarantee, so a payload can describe an older state. If a payload exceeds the queue size limit, it's omitted entirely and arrives with payloadNotIncluded, which means your largest multi-seller Orders are the ones that fail.
4. Read syncInfo before you push anything. Skip every seller Channel already recorded there. This is the platform's own already-exported marker, and it survives a restart, which an in-process set does not.
5. Group Line Items by supply channel, or by whatever seller reference the Cart set at add-to-cart time. Build one payload per seller, carrying only that seller's lines.
6. Record each success immediately. Write Update SyncInfo per seller Channel with the version you read. On a 409 ConcurrentModification conflict, re-read the Order and re-evaluate which sellers still need a push. Partial failure is normal. If seller A succeeds and seller B fails, the syncInfo entry for A must persist before the retry, so that the retry reaches only the missing seller instead of submitting to A twice.
7. Acknowledge deliberately. Acknowledge only once every seller is either recorded or deliberately left for redelivery. Unacknowledged messages are retained for 7 days, and push backoff applies after sustained negative acknowledgments. For details, see Event application behavior. Event applications and API Extensions use different response contracts, and the acknowledgment status codes are defined in Acknowledge deliberately. Don't reuse acknowledgment logic between the two application types.

Forward fulfillment status

Where no OMS is present, this application owns per-line state and Deliveries, and the same guide supplies the mechanism.

Reconcile drift

• Route repairs through the same handlers as the event path. Repairs are then upserts by construction, and the reconciler can't develop its own divergent write behavior.
• Checkpoint after each page, so that an interrupted run resumes rather than restarting.
• Handle overlapping runs yourself. Connect doesn't document whether a scheduled run finishes before the next one starts, and a job has a 30-minute execution limit. Take a durable lock with a time-to-live longer than that limit, and release it at the end, so that two runs can't repair the same records at once.
• Size the reconciler against the job ceiling. A job application uses a maximum of 2 CPU and 4 GB memory, and Connect advises against job applications for bulk or batch operations that demand more extensive processing or high memory.
• Re-push Orders with no matching syncInfo entry through the routing handler.
• Keep the initial migration separate. The first bulk load has a different volume, time budget, and failure tolerance from ongoing reconciliation. Running it through the reconciler makes both harder to reason about.

Test the applications

You can run these tests without a deployed Connector and without marketplace credentials. Mock the outbound boundary, then assert on what the code decided: which endpoint it called, what it sent, and what it did with the response.

Test the modeling and mapping behavior:

• A second seller for the same SKU adds a Standalone Price and an Inventory Entry, and creates no second Product.
• Every written price carries a distribution channel, and every written Inventory Entry carries a supply channel and a deterministic key.
• Money conversion is asserted on a value with non-zero cents, and on a value that rounds.
• Currency, locale, and country are read from the payload and from configuration, and no test passes with a hardcoded value.
• A seller payload that arrives before its Channel exists creates the Channel with its roles before any price or stock write.
• A delisting payload removes the offer rather than leaving it sellable.

Test the order behavior:

• A redelivered Order Created Message pushes nothing to the marketplace, because syncInfo already records every seller.
• A multi-seller Order produces one payload per seller, and each payload carries only that seller's lines.
• A partial failure retries only the failed seller and does not resubmit the successful one.
• An Order Imported Message reaches the routing handler, rather than being filtered out with the Messages the application ignores.
• A duplicate marketplace order identifier imports once, and the second attempt is recognized by the query rather than by the rejection.
• An import draft sets totalPrice explicitly, and a draft carrying a negative price or quantity is rejected by your validation.
• A payloadNotIncluded delivery still results in a complete push, because the handler fetched the Order.

Test the operational behavior:

• Running the deployment scripts more than once leaves one Subscription and one correlation Channel per role, with no duplicates.
• The undeploy script removes the Subscriptions and leaves the Channels.
• Reconciliation resumes from its checkpoint after an interrupted run, and a second concurrent run does not start while the lock is held.
• An inbound request without a valid signature is rejected before any write.

Verify and operate the integration

1. Verify the seller. Send a seller payload and read the Channel by its key. The key matches the marketplace identifier, and the roles include InventorySupply, plus ProductDistribution where the seller prices independently. Send the same payload again and confirm that one Channel exists, not two. A seller that exists only as a Custom Object is an incomplete model, because stock and price have nothing to scope to.
2. Verify that the offer is sellable. The Product existing is not evidence. Add the SKU to a Cart in the seller's context, with the seller's distribution channel, and confirm that the Line Item resolves the seller's price. If the offer can't be added at the seller's price, it isn't synchronized, however successful the import log looks.
3. Verify the shared SKU. Send an offer for the same SKU from a second seller. One Product exists, two Standalone Prices exist with different channels, and two Inventory Entries exist with different supply channels.
4. Verify delisting. Send a removal or a zero quantity and confirm that the offer stops being sellable at that seller's price.
5. Verify the order flow once. For the operator role, place a multi-seller Order and confirm one push per seller, each carrying only that seller's lines, and one syncInfo entry per seller Channel. For the seller role, deliver a marketplace order and confirm one imported Order, an explicit totalPrice, and a syncInfo entry against the OrderImport Channel.
6. Verify redelivery. Deliver the same Order Message twice and confirm that the second delivery pushes nothing and creates nothing.
7. Verify the fulfillment split. Advance one seller's lines and confirm that the marketplace receives status for that seller only, and that the other seller's lines are unchanged.
8. Verify offboarding. Deactivate a seller through the procedure in Offboard a seller by deactivating it and confirm that its offers stop selling while its Orders remain intact.

Keep secrets and personal data out of logs, and return a status rather than a stack trace from the inbound endpoint. A marketplace payload carries buyer names, addresses, and contact details, and an error response that echoes the payload publishes them.

Diagnose common failures

Several correct platform behaviors in this domain look like defects. Start from the symptom.