Build your own connector

MerchantOps ships with built-in connectors (see VTEX), but you can also build your own. This is the right approach when the destination is an internal system — an ERP, a proprietary pricing platform, a custom storefront extension — that a built-in target can’t reach. A custom connector is a small service you run. It never connects to MerchantOps internals. Instead it talks to a pull-based HTTP API: MerchantOps holds the approved, versioned records; your connector polls for the ones fanned out to your target, pushes them into your system, and reports each outcome back. Everything is scoped to your organization by an API key, so a misconfigured connector can never touch another tenant’s data.

The loop

Every connector, regardless of destination, runs the same loop:

Poll for pending records

Ask MerchantOps for records that have been approved and routed to your target but not yet reported as done.

Transform

Map each MerchantOps record onto whatever shape your system expects (field names, units, identifiers).

Push to your system

Write the record into your destination — call its API, update your database, drop a file, whatever your system needs.

Report the outcome

Tell MerchantOps whether each record succeeded, failed, or was skipped. Reported records drop out of the next poll; unreported ones come back so you can retry. Re-sending an outcome you already delivered is safe — see Retries and idempotency below.

Today the pull-based connector API covers pricing publishing — the loop applies to price records routed to your target. For catalog publishing, use a built-in connector such as VTEX.

Setup

In Settings › Publish Targets, add an integration for your custom target with a target key (for example custom) and a poll delivery mode. No credentials for your system are stored on the MerchantOps side — your connector authenticates to your system itself.

Create an API key with a role that grants the connector permissions

The connector API is gated on two permissions:

Permission	Purpose
`pricing.publish.outcome:read`	Poll for pending records
`pricing.publish.outcome:write`	Report outcomes

Settings › API Keys has no scope picker. You create a key and assign it one or more roles, and the key inherits whatever permissions those roles bundle. Roles themselves are defined for your organization by MerchantOps, not in the app.The standard Owner / Admin / Editor / Viewer roles don’t include the connector permissions — so unless your organization already has a purpose-built connector role, ask your MerchantOps contact to set one up bundling the two permissions above, then assign it when you create the key.

The poll endpoint accepts either permission; reporting an outcome requires pricing.publish.outcome:write specifically. A read-only monitoring key can therefore be granted only pricing.publish.outcome:read.

Run your connector

Your service holds the key and calls MerchantOps over HTTPS with:

Authorization: Bearer <your-api-key>

The key is organization-scoped — your connector only ever sees records that belong to your organization.

Poll for pending publishes

Request the records routed to your target that haven’t been reported yet:

GET /api/pricing/pending-publishes?target_key=custom&limit=50
Authorization: Bearer <your-api-key>

The response lists up to limit records with the fields you need to publish them:

{
  "target_key": "custom",
  "count": 1,
  "items": [
    {
      "record_key": "pr-a0861877922e",
      "product_key": "1000035585",
      "product_name": "24/7 Compression Socks",
      "variant_key": "1000035585-001-L2",
      "upc_code": "841052014203",
      "amount": 32.85,
      "currency": "USD",
      "price_type": "map",
      "effective_from": "2026-04-27",
      "batch_key": "pb-16cbebb322bd"
    }
  ]
}

Records are deduplicated by outcome state: once you report an outcome for a record, it drops out of this query. A recommended cadence is a poll every 30–60 seconds, backing off to a few minutes when the response is empty. batch_key is the batch this delivery belongs to — the one whose progress your outcomes advance. For a batch that re-delivers existing price records (a republished batch, or one promoted to another environment) that is the batch being published now, not the batch the record was originally created in.

Report an outcome

For each record, POST back what happened:

POST /api/pricing/records/{record_key}/publish-outcome
Authorization: Bearer <your-api-key>
Content-Type: application/json

{
  "target_key": "custom",
  "status": "success",
  "response_code": 200,
  "duration_ms": 145,
  "attempts": 1,
  "external_id": "YOUR-SYSTEM-ID-42"
}

string

required

The target you configured (for example custom).

string

required

One of success, failed, or skipped. All three are terminal: the record is done for this run, drops out of the next poll, and counts toward the batch’s completion.Use skipped when the record simply does not apply to your system — nothing went wrong, but nothing was published either. A skip is never counted as a publish, so it weighs against the batch’s success ratio exactly like a failure: a batch where more than 5% of records are skipped finishes as Partial, not Published.

number

The HTTP status or internal result code your system returned. Helps debugging.

number

How long your call took.

number

1 for a first-try success; higher if you retried.

string

A short failure summary — shown in the publish status UI when the status is failed.

string

The record’s ID in your downstream system, if it has one.

The response confirms what was recorded:

{
  "record_key": "pr-a0861877922e",
  "target_key": "custom",
  "status": "success",
  "counted": true,
  "batch_final_status": null
}

boolean

Whether this POST advanced the batch and job counters. true on the first report for a record in a publish run. false when the outcome was already counted for that run (your retry was deduplicated) or when the record does not belong to a batch — in both cases the outcome is still stored and visible, it just doesn’t move the counters a second time.

string | null

null while other records in the batch are still outstanding, and "published" or "partial" when your outcome is the one that completes the batch. See batch-level rollup for which of the two you get.

Retries and idempotency

Your connector owns its retry logic entirely. A record stays pending until you POST a terminal outcome, so if your connector crashes mid-run, the record is still pending on the next poll — just pick it up again. Outcome POSTs are counted once per record per publish run. Re-sending an outcome after an ambiguous response (a timeout, a dropped connection) is safe: the visible outcome is refreshed with whatever you send, the batch and job counters do not move again, and the response comes back with "counted": false so an at-least-once connector can see that its redelivery was deduplicated.

Don’t infer delivery from a record’s absence in one poll response. pending-publishes is capped by limit and has no cursor, so on a batch larger than limit a record can be missing from a page simply because it didn’t fit.

A minimal connector

The whole contract fits in one loop:

import os, time, httpx

API_BASE = os.environ["MERCHANTOPS_API_URL"]
API_KEY  = os.environ["MERCHANTOPS_API_KEY"]
TARGET   = "custom"

headers = {"Authorization": f"Bearer {API_KEY}"}

def publish_to_your_system(record: dict) -> tuple[bool, str, int]:
    # Your integration code. Returns (ok, error_message, elapsed_ms).
    ...

def loop():
    with httpx.Client(base_url=API_BASE, headers=headers, timeout=30.0) as client:
        while True:
            resp = client.get(
                "/api/pricing/pending-publishes",
                params={"target_key": TARGET, "limit": 50},
            )
            resp.raise_for_status()
            records = resp.json()["items"]

            if not records:
                time.sleep(60)
                continue

            for r in records:
                ok, err, ms = publish_to_your_system(r)
                outcome = {
                    "target_key": TARGET,
                    "status": "success" if ok else "failed",
                    "duration_ms": ms,
                }
                if not ok:
                    outcome["error"] = err
                # Safe to re-send after an ambiguous response: the outcome is
                # counted once per record per run, and a repeat comes back
                # with "counted": false.
                client.post(
                    f"/api/pricing/records/{r['record_key']}/publish-outcome",
                    json=outcome,
                )

if __name__ == "__main__":
    loop()

What you get

Isolation. Your connector talks to MerchantOps only over HTTPS. No shared infrastructure, no special client libraries.
Org scoping. Your key can only read and update your organization’s records — there’s no way to affect another tenant.
The same monitoring surface. Your publishes appear in publish status exactly like built-in connectors: per-target breakdown, per-record outcomes, job progress, and the batch-level rollup to Published or Partial once every record has reported.

Rate-limit yourself to roughly two polls per second per connector. Running multiple connectors for the same target at once can hand you duplicate records (there is no per-worker record lease yet), so run a single connector per target for now.

Get Started

Catalog

Data ingestion

Enrichment

Pricing

Publishing

Jobs & monitoring

Settings & administration

Agents & Tools

Build your own connector

The loop

Setup

Poll for pending publishes

Report an outcome

Retries and idempotency

A minimal connector

What you get

Next steps

VTEX (reference connector)

Reading publish status

​The loop

​Setup

​Poll for pending publishes

​Report an outcome

​Retries and idempotency

​A minimal connector

​What you get

​Next steps

VTEX (reference connector)

Reading publish status

The loop

Setup

Poll for pending publishes

Report an outcome

Retries and idempotency

A minimal connector

What you get

Next steps