This page walks through the complete life of a Gateway API adapter, from registration to a processed submission. All requests carry the Authorization: Bearer {token} header (see Authentication and Tokens), and all paths are relative to your environment's base URL, for example https://pdx-preprod.stibosystems.com/api/v1/adapter-gateway.

1. Register the channel

POST /external/channels
{
  "id": "acme-marketplace",
  "name": "Acme Marketplace",
  "description": "Publishes products to the Acme Marketplace feed.",
  "logoURL": "https://example.com/acme-logo.svg",
  "currentDatastandardVersionId": "1.0.0",
  "requiredClientAttributes": [
    { "id": "apiKey", "name": "Acme API key", "type": "password" }
  ]
}

id, name, logoURL, and currentDatastandardVersionId are required. requiredClientAttributes declares the credentials a PDX user must enter to connect an account to your channel — they are delivered back to you in authentication events. See Required Client Attributes and the API reference for the full schema.

You can verify the result with GET /external/channels/{channelId}.

2. Register the datastandard

The datastandard defines the attributes, categories, and validation your channel expects. Push it with the version declared in the channel:

POST /external/channels/acme-marketplace/datastandard
{
  "versionId": "1.0.0",
  "attributes": [ ... ],
  "categories": [ ... ],
  "attributeGroups": [ ... ]
}

See Data Standard Implementation for how to model attributes, families, and categories.

Every change is a new version

A datastandard version is immutable once registered: every change must ship with a new versionId, and the gateway rejects attempts to re-push the currently registered version. Run the registration check on every adapter startup:

GET /external/channels/acme-marketplace/datastandard

If the current versionId equals the version your adapter ships with, there is nothing to do. If it differs, POST the new version (and update currentDatastandardVersionId on the channel to match).

3. Poll for events

GET /external/events?limit=100

With the defaults, returned events are acknowledged automatically as part of the poll — the same pattern the Adapter SDK uses. Process every event of the returned batch; see Polling for Events for the acknowledgment details and options.

4. Handle an authentication event

When a PDX user connects an account to your channel, you receive an AUTHENTICATION_EVENT containing the client, channel, account, and the values of your requiredClientAttributes. Validate them against the target system, then report the result:

POST /external/authentication
{
  "clientId": "{from the event}",
  "channelId": "acme-marketplace",
  "accountId": "{from the event}",
  "status": "Success"
}

Report "Failure" with erroneousProperties listing the offending attribute IDs when validation fails, so the PDX user knows which field to correct. The response to a failed validation is what the user sees in the PDX UI — make it actionable.

5. Handle a submit event

A SUBMIT_EVENT payload contains the submissionId. Process it:

GET  /external/submission/{submissionId}                     # submission details
GET  /external/submission/{submissionId}/familyIds           # families in the submission
GET  /external/submissions/{submissionId}/families/{familyId}/ids   # product IDs per family
POST /external/submission/{submissionId}/products            # fetch product payloads

Mind the two product ID namespaces and the receiver split — both are covered in Fetching Submission Data.

Transform the fetched products into the target system's format and deliver them.

6. Report status

Report progress so the PDX user can follow the submission:

POST /external/submit/status
{
  "channelId": "acme-marketplace",
  "submissionId": "{submissionId}",
  "status": "..."
}

Use POST /external/submit/items to report per-product outcomes. Status semantics (states, ordering, per-item reporting) are shared with SDK adapters and described in Status Handling.

Startup checklist

Every time your adapter starts, it should:

1. Verify the channel exists (GET /external/channels/{channelId}), create it if not.
2. Compare the registered datastandard version with the version the adapter ships; register a new version only on change.
3. Enter the polling loop and process every event of each returned batch.