Skip to content
API, security & troubleshooting

Connect a custom website, catalog and native cart

Use a versioned adapter to connect your own product API, configurator and visitor cart, with explicit confirmation for cart changes.

CCorthex product guidesUpdated October 28, 20264 min read
Where to find itAgent → Integrations → Custom website & webshop
In this article

Before you begin

Use a test environment and the smallest necessary access. Keep workspace API keys and signing secrets on your server, outside browser code and public screenshots.

Example workspace · Demo data. Example developer setup using public Deurwebshop URLs. No connection was created; map and test your native handlers before activation. Select the image to enlarge it.
Custom website setup with catalog, configuration and native cart capability switches

Example workspace · Demo data. Example developer setup using public Deurwebshop URLs. No connection was created; map and test your native handlers before activation. Select the image to enlarge it.

Step by step

  1. 1

    Choose the correct agent and capabilities

    A workspace administrator opens Custom website & webshop in the agent's Integrations or Settings → Connections. Enter the exact HTTPS website and connector base URL. Catalog is required; enable configuration and cart only when your website implements them.

  2. 2

    Create and save server credentials

    Create the connector. Save the one-time environment variables in your website's secret manager. They expire after 90 days and cannot be retrieved later. Never paste them into an AI chat, widget code or browser storage. Rotate them if lost.

  3. 3

    Download the starter and copy the setup prompt

    The starter includes a dependency-free Node 22+ SDK, tests, a language-neutral OpenAPI contract and a detailed README. Give the secret-free generated prompt to a developer or AI working in your website's repository. It must inspect the actual catalog, session, cart access and configuration rules before implementing handlers. The demo uses fictitious data and cannot activate a production connector.

  4. 4

    Implement native handlers

    Map published products and exact IDs to catalog handlers. Map configuration to your native server price and validation engine. Resolve the real visitor/account/cart server-side. Cart proposals must not mutate; confirmed updates must preserve native access, stock, prices, hooks and durable idempotency. The README documents every handler, unit and signature.

  5. 5

    Install the website proxy and widget

    Mount /corthex/v2/*, /corthex/session and /corthex/chat on your website. Replace the generic widget embed for this agent with the provided storefront.js snippet. Bind native browser-storage carts only through the same-origin server handler. Refresh the session after login/logout and refresh the native cart provider on corthex:cart-updated.

  6. 6

    Test and activate

    Run the packaged protocol tests, then test two independent visitors on staging, native configuration, invalid choices, explicit cart confirmation, duplicate clicks, expiry, revocation, login/logout and mobile. Test connector verifies signed connectivity, live mode and selected capabilities. Another active store must be revoked explicitly. Configuration edits pause access until verified again.

Developer resources

Download: https://www.corthex.app/api/plugins/custom?action=download

OpenAPI: https://www.corthex.app/api/plugins/custom?action=schema

The package README explains all handler return shapes, signature algorithms, durable receipts, native cart binding, workflow usage, troubleshooting and the Deurwebshop implementation map.

Good to know

The website owns checkout, payments and its native business rules. This integration exposes no refunds, arbitrary customer/order access or silent cart writes.

A live health check verifies the connector contract; it does not replace native merchant acceptance tests. No automatic Deurwebshop installation is implied.

Existing workflows can route on public page context, collect choices and guide enabled catalog/configuration tools. A cart proposal still requires a visitor click.

Check the result

Check the response, relevant delivery history and organisation scope. Use the Public REST API reference in this Help Center for the technical contract.

Questions & troubleshooting

Where are the downloads?

Use Download starter in the setup screen: /api/plugins/custom?action=download. The contract is /api/plugins/custom?action=schema. The ZIP README contains the complete implementation guide and executable tests.

How does the Deurwebshop example work?

The generated prompt for deurwebshop.nl includes findings from the inspected Next.js/Payload repository: public agent-catalog, native configurator validation, millimeter dimensions, eurocent prices and same-origin cartSecret binding. The website developer must implement and test that mapping; browser WebMCP tools are not automatically remote Corthex tools.

Why are cart tools missing?

Enable cart capability and agent commerce tools, install the signed same-origin proxy and use storefront.js. Unsigned generic widgets cannot impersonate a custom-store customer. A revoked/expired connection or disabled commerce blocks confirmation.

Does the AI add products directly?

No. It prepares an expiring, session-bound confirmation card. Only the visitor's explicit confirmation reaches the native mutation, after current permission and native validation checks. Duplicate proposal IDs must return the same durable receipt.

What if a quote or credential expires?

Obtain a fresh native quote/proposal. Rotate expired server credentials in the setup screen, update the website environment and test again. Never substitute guessed options or a different price.

Was this article helpful?

Rate this guide on this device. Ratings are not sent to Corthex.