Use this guide to add Benchmark's iframe ring builder to a retailer's Thinkspace website.
Bootstrap 4 and Hybrid websites use the same Page Template path and Page options.
Before you begin
Confirm that:
- The Benchmark ring-builder templates are deployed to the retailer's MT runtime. Admin records alone do not deploy the templates.
- Benchmark supplied the retailer-specific iframe key.
- Benchmark confirmed the production item API base URL. The fallback demo API is for testing only.
- The website's Shopping Cart is enabled in Commerce preferences and checkout is configured.
Security requirement
The TSJ cart API key is rendered in the storefront page so the browser can call the custom-item cart API. Use only a dedicated, least-privilege storefront API user. Never use a staff or administrator user's key, and never save a real key in this article or in source control.
1. Create the TSJ custom-item cart API key
Keep the two keys separate: Benchmark supplies the iframe_key. Thinkspace generates the api_token used by the TSJ cart.
- Sign in to Thinkspace admin for the retailer website.
- Confirm that a dedicated, least-privilege storefront API user exists. Do not select a staff or administrator user.
- Open Auth Token > Tokens. If it is not shown in navigation, open
/admin/authtoken/token/on the retailer's domain. - Select Add Token.
- Select the dedicated storefront API user.
- Save. Thinkspace generates the API key automatically.
- Copy the generated key from the Tokens list and store it using the approved credential-handling process until it is entered in Page options.
Each user can have only one token. If the user already has one, use the existing approved key or follow the established rotation process. Deleting or replacing a token immediately breaks every Page or integration still using the old value.
Paste only the generated key into api_token. Do not add Token, quotation marks, or extra spaces. The template adds the authorization prefix.
2. Create the Page Template
Open Pages > Page Templates, select Add Page Template, and enter:
| Field | Value |
|---|---|
| Name | Benchmark Ring Builder |
| Slug | benchmark-ring-builder |
| Template Path | pages/tspages/vendor/benchmark/ring-builder.html |
Save the Page Template. Use the relative path exactly as shown; do not include a theme templates directory or a leading slash.
Note: The Update Page Templates templates button does not create this record. Add it manually.
3. Define the Page Template options
Open Benchmark Ring Builder and select Edit Options. Add these three Short text options:
| Name | Type | Purpose |
|---|---|---|
iframe_key | Short text | Benchmark's retailer-specific key. Required for the builder to load. |
api_token | Short text | The TSJ custom-item cart API key created in step 1. Required for Add to Cart. |
item_api_url | Short text | Benchmark's production API base URL, normally ending in /api/. A blank value uses the demo API. |
Recommended help text
iframe_key: Retailer-specific Benchmark iframe key. Required.api_token: Dedicated TSJ custom-item cart API key. Enter the key only; do not include the Token prefix.item_api_url: Benchmark item API base URL ending in /api/. Do not leave blank on a production Page.
4. Create the retailer Page
Open Pages > Pages, select Add Page, and leave Published off while configuring.
| Field | Example |
|---|---|
| Page Title | Design Your Benchmark Ring |
| Template | Benchmark Ring Builder |
| Page Slug | benchmark-ring-builder |
| Page URL | /benchmark-ring-builder/ |
Add the SEO title and meta description, choose a Page Group if needed, and save the Page.
5. Configure the retailer Page options
From the Pages list, select the Page's Edit Options cog and enter:
- Iframe Key: The retailer-specific key supplied by Benchmark.
- API Token: Only the TSJ custom-item cart API key generated in step 1.
- Item API URL: The production base URL supplied by Benchmark, such as
https://vendor-host.example/api/.
Do not publish a production Page with a blank Item API URL. A blank value intentionally falls back to Benchmark's demo environment.
6. Add optional content and navigation
Use Edit Contents to add optional content to either dock:
content-header: Appears above the ring builder.content-footer: Appears below the ring builder.
The builder does not require a widget. Add the final Page URL to the appropriate menu if it should appear in site navigation.
7. Test before publishing
- Open the Page using the site's approved unpublished-page preview workflow.
- Confirm the builder loads without a red configuration error.
- Change the design and confirm the URL receives state parameters such as
_bmsku,_bme, and_bmet. - Configure one ring without engraving and another with engraving.
- Select Add to Cart.
- Confirm the Benchmark item request returns
200and/api/custom_item/add_to_cart/succeeds. - Confirm the browser redirects to
/cart/. - Confirm the cart line shows the correct SKU, retail price, and image.
- Open the cart item's product link and confirm the saved configuration resumes.
- Complete the normal cart and checkout smoke test without submitting a real payment unless the test plan requires one.
Publish only after testing with the production iframe key and production item API URL on desktop and mobile.
Troubleshooting
| Problem | What to check |
|---|---|
| Builder is not configured | The Page's iframe_key is missing. |
| Add to Cart is absent | The Page's api_token is blank. |
| Benchmark returns 400 | Confirm that Benchmark accepts the selected engraving type and text. |
| Benchmark returns 404 | Confirm the SKU and make sure item_api_url points to the correct environment. |
| Benchmark authorization or browser error | Confirm the iframe key, API URL, and Benchmark's browser/CORS authorization for the retailer domain. |
| TSJ returns 401 or 403 | Enter only the generated key. Remove any Token prefix, quotation marks, or extra spaces. The key may also have been rotated or created for the wrong user. |
| Page Template is missing | Confirm the code release is deployed and the path is pages/tspages/vendor/benchmark/ring-builder.html. |
Current limitation
The integration handles cart:add, but not cart:update or Benchmark lineID values. Adding a resumed design creates a new TSJ cart line instead of updating an existing line.
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article