Product configurator API: generate quotes with Spokbee

Spokbee's product configurator API lets your own software list products, check a set of selections against your engineering rules, price them and create a quote, all in a few HTTPS calls. Every endpoint runs the same configuration and pricing engines as the configurator your buyers use on your website, so a quote created by your dealer portal, your ERP or an AI agent carries the same validated configuration and the same price.

This guide is for developers. It covers authentication, the endpoints you call to discover products and read their options, the request and response shapes for configure and quote, the errors you need to handle, and the webhooks that push quote events to your server. The REST APIs and webhooks on the integrations page are the starting point; the developer documentation opens inside your workspace once you sign in.

What is a product configurator API?

A product configurator API is a web service that exposes a configurable product the way a buyer experiences it: the options, the rules that decide which combinations are allowed, the price for each valid combination and a quote for the chosen one. Spokbee gives every published product this interface, scoped to your workspace, and it answers with JSON.

The old way of connecting a configurator to the rest of the business is a person: a dealer emails a spec sheet, a rep re-keys it into a spreadsheet, an engineer checks it can be built, and a quote goes out days later. Every hop can quote a product that cannot be made or price it wrong.

With Spokbee the rules live in one place. You define parameters, constraints and pricing rules once in the product builder. The website configurator, the API and the MCP tools for AI agents evaluate the same rules, so your application never re-implements an engineering rule.

Every endpoint sits under a workspace-scoped base URL. Replace the workspace slug with the one shown in Settings > General.

https://app.spokbee.com/{workspace}/api/v1/

How do you authenticate with the Spokbee API?

Every request carries a Bearer token in the Authorization header. Workspace API keys start with spk_ and come from Settings > API Keys. Agent keys start with spka_, come from Settings > Agent Keys and carry scoped permissions: catalog, configure, quote, checkout and export. The quote and export endpoints only answer to a key that holds the matching permission.

curl https://app.spokbee.com/acme/api/v1/discovery \
  -H "Authorization: Bearer spk_your_api_key"

Use a workspace API key for your own back-office integrations. Use an agent key when a third party, such as a dealer's procurement system or an AI assistant, calls Spokbee on your behalf: you grant only the permissions it needs, watch its request counts and last-used time, and rotate it at any time. Rotation issues a new key and the old one stops working immediately.

Requests are rate-limited per key. When a key goes over its limit the API answers with HTTP 429 and a Retry-After header that tells you how many seconds to wait. Public catalog and configure calls accept browser requests from any origin; quote and checkout calls require a valid key and respect the origin allowlist you set in Settings > API Keys. API access is included from the Professional plan, listed on the pricing section of the Spokbee home page.

How do you find products and read their options?

Call GET /discovery to list the published products in the workspace, then GET /{product}/catalog for the one you want to configure. The catalog is the complete published schema: every parameter with its options or numeric range, the constraints between them and the pricing rules. Cache it and refresh when you receive a configurator.published webhook.

GET /acme/api/v1/discovery

{
  "products": [
    {
      "slug": "workshop-cabinet",
      "name": "Workshop Cabinet",
      "description": "Modular steel cabinet with configurable drawers",
      "published": true
    }
  ]
}

The product slug in the response is the one you use in every later path. The catalog is the same schema that drives the configurator page, so a parameter you add in the builder appears in the API the moment you publish. If you prefer a generated client, GET /{product}/openapi.json returns an OpenAPI 3.0 document that most API tooling imports directly.

How do you validate and price a configuration?

Send the buyer's selections to POST /{product}/configure. Spokbee evaluates the constraints and visibility rules, prices the valid selections and answers with valid, complete, the list of violations, the missing_required parameters, the remaining_options per parameter and a price breakdown with base price, line items, total and currency. The call is read-only, so call it on every change.

Selections are a flat object of parameter IDs to string values. Parameter IDs and option values come from the catalog.

POST /acme/api/v1/workshop-cabinet/configure

{
  "selections": {
    "width": "48",
    "finish": "graphite",
    "drawers": "6"
  }
}

{
  "valid": true,
  "complete": true,
  "violations": [],
  "missing_required": [],
  "remaining_options": {
    "finish": ["graphite", "red", "blue"],
    "drawers": ["4", "5", "6"]
  },
  "numeric_ranges": {},
  "price": {
    "basePrice": 899,
    "lineItems": [
      { "label": "Graphite powder coat", "amount": 120, "type": "surcharge" },
      { "label": "Six-drawer layout", "amount": 165, "type": "option" }
    ],
    "total": 1184,
    "currency": "USD"
  },
  "product": "Workshop Cabinet"
}

Two fields do the work in a guided flow. violations holds the human-readable rule each disallowed selection broke, so your interface can tell the buyer why six drawers do not fit a 24-inch cabinet instead of showing a generic error. remaining_options lists what is still allowed for every parameter, so you can grey out the rest before the buyer clicks. valid means no rule is broken; complete means every required parameter has a value. Wait for both before you quote.

The price breakdown is itemised. Each line item carries a signed amount and a type naming the pricing rule that produced it, such as surcharge, discount, tiered or formula. The numbers in the example are illustrative.

How do you generate a quote from a configuration?

Call POST /{product}/quote with the same selections and a buyer object holding a name and an email, plus an optional company. Spokbee prices the configuration, stores the quote and returns a reference, the product name, the configuration, the pricing breakdown, a created_at timestamp and the status new. The quote appears in your Quotes dashboard beside the quotes your website produces.

POST /acme/api/v1/workshop-cabinet/quote

{
  "selections": {
    "width": "48",
    "finish": "graphite",
    "drawers": "6"
  },
  "buyer": {
    "name": "Dana Ortiz",
    "email": "dana@example.com",
    "company": "Ortiz Fabrication"
  }
}

{
  "reference": "Q-2026-A7K3M",
  "product": "Workshop Cabinet",
  "configuration": { "width": "48", "finish": "graphite", "drawers": "6" },
  "pricing": {
    "basePrice": 899,
    "lineItems": [
      { "label": "Graphite powder coat", "amount": 120, "type": "surcharge" },
      { "label": "Six-drawer layout", "amount": 165, "type": "option" }
    ],
    "total": 1184,
    "currency": "USD"
  },
  "created_at": "2026-10-30T09:14:02.000Z",
  "status": "new"
}

Store the reference. It is the identifier your sales team sees in the Quotes dashboard, where the quote lifecycle moves through New, Viewed, Accepted and Rejected and every status change is recorded as an analytics event. Because the quote endpoint writes a record and counts toward your monthly quote allowance, call configure until the configuration is valid and complete, then quote once.

The same request shape works whether the caller is your ERP, a dealer portal or an AI agent holding an agent key with the quote permission. Spokbee's MCP server, described in the guide to letting AI agents quote from your product catalog, calls the same quote logic.

How do webhooks tell your systems about quote events?

Webhooks push events from Spokbee to an HTTPS endpoint you own, so your CRM, ERP or notification system reacts the moment something happens on the configurator. Add an endpoint in Settings > Webhooks, pick the events, and Spokbee sends a signed JSON payload for each one and retries failed deliveries up to five times.

Every delivery has the same envelope: the event name, an ISO timestamp, your workspace ID and an event-specific data object. For quote.created the data carries the quote reference, product ID, buyer name and email, configuration and pricing breakdown, enough to open a CRM opportunity or an ERP sales order without a second call.

{
  "event": "quote.created",
  "timestamp": "2026-10-30T09:14:02.000Z",
  "workspace_id": "ws_01HZX…",
  "data": {
    "quote_reference": "Q-2026-A7K3M",
    "product_id": "prod_01HZX…",
    "buyer_name": "Dana Ortiz",
    "buyer_email": "dana@example.com",
    "configuration": { "width": "48", "finish": "graphite", "drawers": "6" },
    "pricing": { "basePrice": 899, "lineItems": [], "total": 1184, "currency": "USD" }
  }
}

Three rules keep a webhook integration reliable:

• Verify the signature. Each delivery carries an X-Spokbee-Signature header, an HMAC-SHA256 hex digest of the raw body computed with the endpoint's signing secret. Recompute it and compare with a constant-time check before you parse the payload. X-Spokbee-Event names the event and X-Spokbee-Delivery-Id gives you a deduplication key.
• Answer fast. Return a 2xx status within 10 seconds and do the real work in a queue. Failed deliveries are retried with exponential backoff at 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours.
• Test before going live. The "Send Test" button delivers a realistic payload flagged test: true, and the delivery log shows status, response code, request body and the first kilobyte of your response for every attempt. A rotated signing secret keeps the old secret valid for 24 hours.

Webhooks are listed with the Business plan on the pricing section. The Stripe connection on the integrations documentation page uses the same mechanism in the other direction: payment status flows back into Spokbee by webhook in real time.

What errors does the API return and how do you handle them?

The API uses standard HTTP status codes with a JSON body that names the problem. Authentication failures return 401, a key without the needed permission returns 403, a missing product returns 404, a bad request body returns 400, a configuration that breaks a rule returns 422 with the violations listed, and a rate-limited key returns 429 with Retry-After.

Treat configure as idempotent and quote as a commit. Before retrying a quote call that timed out, check the Quotes dashboard so one buyer does not end up with two quotes.

When should you use the API instead of embedding the configurator?

Embed the configurator when a human buyer should see and choose in 3D; use the API when software chooses, or when a quote has to be created from a system that already knows the specification. Most manufacturers do both: the website runs the embedded configurator, and the API feeds the same quotes into the systems behind it.

The guide to embedding a 3D configurator on Shopify, WordPress or Webflow covers the first row; this post covers the rest. Because every path runs the same engines, you never maintain two versions of a rule: change a constraint or a price in the builder, publish, and the website, the API, the webhooks and the AI agents see it at once.

Sources

• Spokbee, CAD and API integrations: REST APIs for configuration, pricing and quotes; webhooks for events such as a new quote or a published configurator; MCP tools. Checked October 2026.
• Spokbee, Agentic selling and MCP tools: the four MCP tools, validation responses and the statement that the same configuration and pricing engines evaluate every selection. Checked October 2026.
• Spokbee documentation, Quotes: quote flow, dashboard and the New, Viewed, Accepted, Rejected lifecycle. Checked October 2026.
• Spokbee documentation, Integrations: Stripe payment status synced by webhook. Checked October 2026.
• Spokbee documentation, Constraints and Pricing: the rules the configure endpoint evaluates. Checked October 2026.
• Spokbee, pricing section of the home page: API access listed with the Professional plan, webhooks with the Business plan. Checked October 2026.
• Spokbee developer documentation (REST API, Agent Keys, Webhooks), linked from the documentation index and opened inside a signed-in workspace: base URL, endpoints, key prefixes and permissions, rate limiting, CORS, webhook events, signing, retries and secret rotation. Checked October 2026.