Build on CatalogHub

CatalogHub offers three integration surfaces. Suppliers use the REST API or MCP to maintain their own catalogue and propose products to connected buyers. Buying organisations use the separate ordering agent API to search products and build orders.

Each surface has its own credential. Choose by who is acting and where the integration runs.

Supplier API access is off by default. Complete these steps once per supplier.

1. 1Create a supplier account and verify its account email. A CatalogHub administrator then verifies the supplier's identity.
2. 2Connect the supplier to each buying organisation and confirm the trade relationship through the existing supplier or administrator workflow.
3. 3As a supplier manager or administrator, open Products › Supplier API access, enable access and create a named key with only the scopes you need. Copy the key when it is shown; it cannot be retrieved later.
4. 4Store the key in your secret store and send it over HTTPS in the Authorization header. For MCP, connect your assistant instead and approve the requested scopes.

curl https://cataloghub.hopshq.com/api/supplier/v1/me \
  -H "Authorization: Bearer $CATALOGHUB_SUPPLIER_KEY"

Every supplier REST request carries a supplier API key as a bearer token.

Authorization: Bearer chsup_xxxxxxxx…

• Keys expire after 90 days by default. You can choose between 1 and 365 days when creating a key.
• A supplier can have up to ten active keys. Give each integration its own named key so it can be revoked independently.
• CatalogHub stores only a hash of each key and a short display prefix. The full key is shown once, at creation.
• Every request re-checks that the supplier is verified, API access is enabled, the key owner's email is verified and the owner is still a supplier manager or administrator.
• Revoking a key or disabling API access stops it immediately. Re-enabling access does not restore old keys.

All supplier endpoints are relative to the base path below and return JSON.

Base URLhttps://cataloghub.hopshq.com/api/supplier/v1

• POST/imports/file-preview

  Preview import without saving

  Scopecatalog:write
• POST/imports/preview

  Preview import without saving

  Scopecatalog:write
• POST/imports/commit

  Save reviewed import

  Scopecatalog:write
• GET/trade-relationships/{relationshipId}/catalogue

  Read customer catalogue

  Scoperelationships:read
• PUT/trade-relationships/{relationshipId}/catalogue

  Save customer selection and tier

  Scopecatalog:write
• GET/trade-relationships/{relationshipId}/catalogue/preview

  Preview customer prices

  Scoperelationships:read
• POST/trade-relationships/{relationshipId}/catalogue/publications

  Propose saved catalogue for buyer review

  Scopecatalog:publish
• GET/products/{productId}/allergen-evidence

  Read immutable allergen evidence revisions for a supplier product.

  Scopecatalog:read
• POST/products/{productId}/allergen-evidence

  Submit a new supplier-attested allergen evidence revision.

  Scopecatalog:write
• POST/trade-relationships/{relationshipId}/allergen-publications

  Share selected revisions for the buyer’s declaration review.

  Scopecatalog:publish
• GET/me

  Returns the supplier ID and the key's scopes.

  Scopecatalog:read
• GET/products

  Lists the full catalogue, including private reference prices and archived products.

  Scopecatalog:read
• GET/products?visibility=public

  Lists the supplier's active public listings, with its private reference prices.

  Scopecatalog:read
• PUT/products

  Creates or updates up to 500 products by SKU in one atomic batch.

  Scopecatalog:write
• GET/trade-relationships

  Lists trade relationships, buyer identities, currency, status and product counts.

  Scoperelationships:read
• GET/trade-relationships/{relationshipId}/products

  Returns the latest proposed offers and the accepted buyer products and prices, separately.

  Scoperelationships:read
• POST/trade-relationships/{relationshipId}/publications

  Creates a buyer catalogue review and schedules the review notification.

  Scopecatalog:publish

Exact request and response schemas are published in the supplier OpenAPI specification, linked under Resources.

List endpoints use offset pagination.

• limit accepts 1 to 100 and defaults to 100.
• offset defaults to 0.
• Catalogue and relationship lists return total, limit and offset. Keep requesting until offset reaches total.
• Relationship product reads return offers and accepted products with separate totals, both paged by the same offset. Continue until both totals are exhausted.

Read the supplier's own catalogue to reconcile it with your source system.

• Without a filter, the response includes private and archived products and the supplier's private reference prices.
• With visibility=public, only active products explicitly marked public are returned. Private reference prices are still included because the caller is the supplier.

curl "https://cataloghub.hopshq.com/api/supplier/v1/products?limit=100&offset=0" \
  -H "Authorization: Bearer $CATALOGHUB_SUPPLIER_KEY"

curl "https://cataloghub.hopshq.com/api/supplier/v1/products?visibility=public&limit=100&offset=100" \
  -H "Authorization: Bearer $CATALOGHUB_SUPPLIER_KEY"

Send the complete intended state of each product. Products are matched by SKU.

• SKUs are supplier-scoped, trimmed and case-insensitive. Updating, archiving or restoring a SKU keeps its product ID. Changing a SKU creates another product; archive the previous SKU if needed.
• Fields replace the stored product. Omitted optional description, pack, unit and sizing fields are cleared.
• Omitted public visibility becomes private, and omitted active status becomes active. Products you do not send are left unchanged.
• A batch holds up to 500 products with unique SKUs. Any invalid product rejects the whole batch, so nothing is partially written.
• Upserting never changes any buyer's catalogue.

• Prices are non-negative JSON numbers with at most two decimal places, up to 99,999,999.99.
• Reference and negotiated prices are net prices per ordering unit. The currency of a buyer-specific price comes from the buying organisation in that relationship.
• Category is the supplier's own text. During review it is matched to the receiving organisation's active category taxonomy.
• Structured sizing is optional. Use consistent type and unit pairs (Unit with Units, Weight with Grams, Volume with Millilitres) and the canonical container names.
• The outer container name and its positive whole-number count must be supplied together.

curl -X PUT https://cataloghub.hopshq.com/api/supplier/v1/products \
  -H "Authorization: Bearer $CATALOGHUB_SUPPLIER_KEY" \
  -H "Content-Type: application/json" \
  -d @products.json

The response returns the stored products, with stable product IDs and prices as decimal strings. Request bodies are limited to 2 MiB.

Relationships connect the supplier to buying organisations. Use them to choose where to propose products and to see what each buyer has accepted.

• The relationship list includes the buyer, currency, lifecycle status and product counts.
• A relationship's products separate the latest proposed offers from the products and prices the buyer has accepted.
• Each buyer receives its own negotiated prices; proposing to one buyer does not affect another.

curl "https://cataloghub.hopshq.com/api/supplier/v1/trade-relationships?limit=100&offset=0" \
  -H "Authorization: Bearer $CATALOGHUB_SUPPLIER_KEY"

curl "https://cataloghub.hopshq.com/api/supplier/v1/trade-relationships/<relationship-id>/products?limit=100&offset=0" \
  -H "Authorization: Bearer $CATALOGHUB_SUPPLIER_KEY"

A publication sends selected products at buyer-specific net prices to one buying organisation as a catalogue review.

• The supplier must be verified.
• The relationship must be confirmed: supplier_confirmedadmin_confirmed
• Its status must be one of: approvedterms_setcatalogue_enabledordering_enabled
• Every product must belong to the calling supplier and be active.
• Prospects, inferred or unconfirmed relationships, suspended relationships and company-only relationships cannot receive proposals.

• An idempotency key is required. Use 8 to 120 letters, numbers, dots, underscores, colons or hyphens.
• A new proposal returns HTTP 201 with publication, catalogue request and submission IDs and an initial pending review status.
• An exact retry returns HTTP 200 with the same IDs and marks the result as idempotent. Retries are safe even when they run concurrently.
• Reusing a key with different items, prices or notes returns HTTP 409.
• Item order does not affect identity. The returned status describes the initial proposal only; read the relationship's products for the current review status.

curl -X POST https://cataloghub.hopshq.com/api/supplier/v1/trade-relationships/<relationship-id>/publications \
  -H "Authorization: Bearer $CATALOGHUB_SUPPLIER_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: proposal-00000001" \
  -d '{
    "items": [{ "productId": "<product-id-from-upsert>", "price": 4.25 }],
    "notes": "New products and agreed prices for your review."
  }'

1. 1Product data and prices are copied into the review. Later catalogue edits do not change it.
2. 2The buyer reviews each product; their decisions stay staged until the review is completed.
3. 3Completing the review saves the accepted products and prices to the buyer's catalogue.
4. 4Publishing to Hops remains a separate step and still requires the supplier link, category and account mapping, tax mapping and sizing checks.

The primary catalogue holds every supplier product. Mark selected items isPublic for the public base catalogue; basePrice is standard RRP excluding tax per ordering unit. Anonymous public discovery still excludes prices. A customer catalogue stores selected primary products and one percentage-off-RRP tier for a confirmed trade relationship.

Send revision 0 to create; use the returned revision for edits. discountedProductIds: null discounts all shared items; an array discounts only that subset. Other shared items keep RRP. Use 0–100%, at most two decimal places. Prices round half up to cents. There are no quantity tiers or currency conversions.

{
  "revision": 0,
  "name": "Customer standard",
  "productIds": [
    "<shared-product-id>",
    "<second-shared-product-id>"
  ],
  "discountPercent": 10,
  "discountedProductIds": [
    "<shared-product-id>"
  ]
}

curl -X PUT https://cataloghub.hopshq.com/api/supplier/v1/trade-relationships/<relationship-id>/catalogue \
  -H "Authorization: Bearer $CATALOGHUB_SUPPLIER_KEY" -H "Content-Type: application/json" -d @customer-catalogue.json

curl https://cataloghub.hopshq.com/api/supplier/v1/trade-relationships/<relationship-id>/catalogue/preview \
  -H "Authorization: Bearer $CATALOGHUB_SUPPLIER_KEY"

curl -X POST https://cataloghub.hopshq.com/api/supplier/v1/trade-relationships/<relationship-id>/catalogue/publications \
  -H "Authorization: Bearer $CATALOGHUB_SUPPLIER_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: customer-00000001" \
  -d '{"previewHash":"<hash-from-preview>"}'

POST imports/file-preview with a CSV/XLS/XLSX file, or imports/preview with JSON products. Neither saves products. Ambiguous file headers return mappingRequired; resubmit a mapping from source headers to canonical fields. Correct returned products and row issues, then POST imports/commit with baseline, products and Idempotency-Key. Omitted fields retain existing metadata and visibility; new products default private. Stale baselines return 409. Commit is atomic and exact retries return the original products.

curl -X POST https://cataloghub.hopshq.com/api/supplier/v1/imports/file-preview \
  -H "Authorization: Bearer $CATALOGHUB_SUPPLIER_KEY" -F 'file=@supplier-catalogue.csv'

curl -X POST https://cataloghub.hopshq.com/api/supplier/v1/imports/commit \
  -H "Authorization: Bearer $CATALOGHUB_SUPPLIER_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: import-00000001" \
  -d @reviewed-import.json

Store reusable supplier-attested evidence against an exact supplier product. Supplier identity verification does not independently verify allergen content. Each immutable revision records the source reference, exact wording, submitting account and SHA-256 hash.

curl -X POST https://cataloghub.hopshq.com/api/supplier/v1/products/<product-id>/allergen-evidence \
  -H "Authorization: Bearer $CATALOGHUB_SUPPLIER_KEY" \
  -H "Idempotency-Key: allergen-00000001" \
  -H "Content-Type: application/json" \
  -d @allergen-evidence.json

{
  "supplierAttested": true,
  "source": {
    "reference": "<supplier-specification-reference>",
    "description": "<source-description>",
    "issuedOn": "2026-10-14"
  },
  "completeness": "partial",
  "statements": [
    {
      "allergenCode": "milk",
      "statementType": "contains",
      "exactText": "<exact-source-wording>"
    }
  ]
}

After the buyer accepts a catalogue item, share a selected evidence revision with its exact accepted product ID. Up to 100 items per evidence publication. The buyer opens Supplier requests in Allergens, reviews the source and product match, confirms statements and closes the declaration. Hops then requires its separate mapped-product preview and human approval.

{
  "items": [
    {
      "productId": "<supplier-product-id>",
      "revisionId": "<evidence-revision-id>",
      "restaurantCatalogItemId": "<accepted-buyer-product-id>"
    }
  ]
}

Anyone can discover a verified supplier's public listings without credentials.

• No authentication is required. Pagination works the same way as the supplier API.
• Only active products explicitly marked public are returned, and every price field is excluded.
• Public visibility is optional. Private products can still be proposed to connected buyers.

curl "https://cataloghub.hopshq.com/api/public/suppliers/<supplier-id>/catalog?limit=100&offset=0"

Errors include an English message, a stable machine code and a message key for localised display. Handle them by code, not by message text.

• Up to 500 products per upsert.
• Request bodies up to 2 MiB.
• Up to 120 requests per minute on the bearer API.
• Up to 100 results per page.
• Authenticated responses are sent with Cache-Control: no-store. Do not cache them in shared caches.

The CatalogHub Model Context Protocol server lets AI assistants read and update a supplier catalogue and propose products, on behalf of the person who connected it.

• Endpoint: https://cataloghub.hopshq.com/api/mcp
• Streamable HTTP with stateless JSON responses. Send JSON-RPC 2.0 requests with POST.
• Call it from your assistant or server. Browser requests from other websites are rejected.
• Tools apply the same validation, limits and review workflow as the REST API.

curl https://cataloghub.hopshq.com/api/mcp \
  -H "Authorization: Bearer $CATALOGHUB_OAUTH_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d @request.json

Most MCP clients perform discovery, sign-in, initialisation and tool listing automatically when you add the endpoint URL. The raw requests are shown for clients you build yourself.

MCP access is bound to a CatalogHub user. The assistant never sees the user's password or a supplier API key.

1. 1Discover the authorisation server from the protected resource metadata.
2. 2Register your client dynamically with its redirect URIs, or reuse an existing registration.
3. 3Create a random code verifier and send its SHA-256 challenge (S256) with the requested scopes and the MCP resource.
4. 4The user signs in to CatalogHub and approves or declines the requested access on the consent screen.
5. 5Exchange the authorisation code and verifier for an access token and refresh token.
6. 6Send the access token as a bearer token to the MCP endpoint, refresh it when it expires, and revoke it when access is no longer needed.

curl https://cataloghub.hopshq.com/.well-known/oauth-protected-resource/api/mcp
curl https://cataloghub.hopshq.com/.well-known/oauth-authorization-server

• Access tokens are valid for 1 hour.
• Refresh tokens last 30 days and rotate: each refresh returns a new refresh token. Reusing an old refresh token revokes the connection.
• Disconnect from the Connect an AI agent panel in CatalogHub, or revoke a token at the revocation endpoint.
• Redirect URIs must use HTTPS, HTTP on a loopback address, or a native app's private scheme.

Request only the scopes the assistant needs. Each OAuth scope mirrors a supplier API key scope.

The consent screen shows read access, product changes and buyer proposals as separate choices, with changes and proposals unchecked by default. Existing connections never gain new scopes automatically; reconnect to grant supplier permissions.

Every supplier tool takes a supplier_id. First call cataloghub_list_my_accounts, granted with the feedback scope, to find the suppliers the signed-in user can act for. tools/list returns only the tools your token’s scopes allow. Argument names use snake_case; product and item objects use the same camelCase fields as the REST API.

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "cataloghub_list_my_accounts",
    "arguments": {}
  }
}

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "cataloghub_list_supplier_catalog",
    "arguments": {
      "supplier_id": "<supplier-id>",
      "limit": 100,
      "offset": 0,
      "visibility": "public"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "cataloghub_upsert_supplier_products",
    "arguments": {
      "supplier_id": "<supplier-id>",
      "products": [
        {
          "sku": "ONIONS-1KG",
          "productName": "Onions 1kg",
          "description": "Fresh onions",
          "category": "Vegetables",
          "unitOfMeasure": "kg",
          "packSize": 1,
          "basePrice": 9,
          "isPublic": true,
          "isActive": true,
          "sizing": {
            "baseUomType": "Weight",
            "baseUom": "Grams",
            "baseNumber": 1000,
            "baseContainer": "Bag"
          }
        }
      ]
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 13,
  "method": "tools/call",
  "params": {
    "name": "cataloghub_list_supplier_trade_relationships",
    "arguments": {
      "supplier_id": "<supplier-id>",
      "limit": 100,
      "offset": 0
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 14,
  "method": "tools/call",
  "params": {
    "name": "cataloghub_get_supplier_trade_catalog",
    "arguments": {
      "supplier_id": "<supplier-id>",
      "relationship_id": "<relationship-id>",
      "limit": 100,
      "offset": 0
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 15,
  "method": "tools/call",
  "params": {
    "name": "cataloghub_publish_supplier_products",
    "arguments": {
      "supplier_id": "<supplier-id>",
      "relationship_id": "<relationship-id>",
      "items": [
        {
          "productId": "<product-id-from-upsert>",
          "price": 4.25
        }
      ],
      "notes": "New products and agreed prices for your review.",
      "idempotency_key": "proposal-00000001"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 16,
  "method": "tools/call",
  "params": {
    "name": "cataloghub_list_supplier_allergen_evidence",
    "arguments": {
      "supplier_id": "<supplier-id>",
      "product_id": "<product-id>",
      "limit": 100,
      "offset": 0
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 17,
  "method": "tools/call",
  "params": {
    "name": "cataloghub_submit_supplier_allergen_evidence",
    "arguments": {
      "supplier_id": "<supplier-id>",
      "product_id": "<product-id>",
      "evidence": {
        "supplierAttested": true,
        "source": {
          "reference": "<supplier-specification-reference>",
          "description": "<source-description>",
          "issuedOn": "2026-10-14"
        },
        "completeness": "partial",
        "statements": [
          {
            "allergenCode": "milk",
            "statementType": "contains",
            "exactText": "<exact-source-wording>"
          }
        ]
      },
      "idempotency_key": "allergen-00000001"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 18,
  "method": "tools/call",
  "params": {
    "name": "cataloghub_publish_supplier_allergen_evidence",
    "arguments": {
      "supplier_id": "<supplier-id>",
      "relationship_id": "<relationship-id>",
      "items": [
        {
          "productId": "<supplier-product-id>",
          "revisionId": "<evidence-revision-id>",
          "restaurantCatalogItemId": "<accepted-buyer-product-id>"
        }
      ],
      "idempotency_key": "allergen-00000002"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 19,
  "method": "tools/call",
  "params": {
    "name": "cataloghub_get_customer_catalogue",
    "arguments": {
      "supplier_id": "<supplier-id>",
      "relationship_id": "<relationship-id>"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 20,
  "method": "tools/call",
  "params": {
    "name": "cataloghub_save_customer_catalogue",
    "arguments": {
      "supplier_id": "<supplier-id>",
      "relationship_id": "<relationship-id>",
      "catalogue": {
        "revision": 0,
        "name": "Customer standard",
        "productIds": [
          "<product-id>"
        ],
        "discountPercent": 10,
        "discountedProductIds": null
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 21,
  "method": "tools/call",
  "params": {
    "name": "cataloghub_preview_customer_catalogue",
    "arguments": {
      "supplier_id": "<supplier-id>",
      "relationship_id": "<relationship-id>"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 22,
  "method": "tools/call",
  "params": {
    "name": "cataloghub_publish_customer_catalogue",
    "arguments": {
      "supplier_id": "<supplier-id>",
      "relationship_id": "<relationship-id>",
      "previewHash": "<hash-from-preview>",
      "idempotency_key": "customer-00000001"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 23,
  "method": "tools/call",
  "params": {
    "name": "cataloghub_preview_supplier_import",
    "arguments": {
      "supplier_id": "<supplier-id>",
      "products": [
        {
          "sku": "ONIONS-1KG",
          "productName": "Onions 1kg",
          "description": "Fresh onions",
          "category": "Vegetables",
          "unitOfMeasure": "kg",
          "packSize": 1,
          "basePrice": 9,
          "isPublic": true,
          "isActive": true,
          "sizing": {
            "baseUomType": "Weight",
            "baseUom": "Grams",
            "baseNumber": 1000,
            "baseContainer": "Bag"
          }
        }
      ]
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 24,
  "method": "tools/call",
  "params": {
    "name": "cataloghub_commit_supplier_import",
    "arguments": {
      "supplier_id": "<supplier-id>",
      "baseline": "<baseline-from-preview>",
      "products": [
        {
          "sku": "ONIONS-1KG",
          "productName": "Onions 1kg",
          "description": "Fresh onions",
          "category": "Vegetables",
          "unitOfMeasure": "kg",
          "packSize": 1,
          "basePrice": 9,
          "isPublic": true,
          "isActive": true,
          "sizing": {
            "baseUomType": "Weight",
            "baseUom": "Grams",
            "baseNumber": 1000,
            "baseContainer": "Bag"
          }
        }
      ],
      "idempotency_key": "import-00000001"
    }
  }
}

MCP tools act as the signed-in user, never as a broader service account.

• Tools work only for suppliers the user currently belongs to directly. Reading needs any verified member; product changes and proposals need a manager or administrator.
• Supplier tools require OAuth. Supplier REST keys and personal MCP access tokens cannot use them.
• Membership, roles and supplier status are checked live on every call. Removing a user from a supplier stops access immediately, even if their token has not expired.
• Reseller access and support impersonation never grant supplier tool authority, and administrators’ view-as sessions do not carry over to tokens.
• The existing rules still apply: the user’s email and the supplier must be verified, and Supplier API access must be enabled.
• Proposals follow the same relationship eligibility, idempotency and buyer review rules as the REST API.
• No tool publishes to Hops or changes a buyer's live catalogue directly.

Buying organisations can let a purchasing agent search their suppliers' products, build baskets and, when permitted, submit orders. This API is separate from the supplier catalogue API.

• A buying organisation administrator creates the agent and gives it a dedicated ordering agent token.
• Agents either propose baskets for people to review and send, or submit orders within spending limits and approval thresholds.
• Agents see only suppliers and products that the organisation can already order from.

curl "https://cataloghub.hopshq.com/api/agent/v1/products?q=olive%20oil" \
  -H "Authorization: Bearer $CATALOGHUB_ORDERING_AGENT_TOKEN"

Machine-readable references for code generation, testing and AI assistants.

Supplier catalogue API and MCP

Ordering agent API

Specifications and protocol identifiers are published in English so that they match the API exactly.