Using the Public API

Guide for stores and website developers

Connect your website to mybridal to display your product catalogue or send appointment requests into your diary. This guide explains the store settings, the information to give your website developer, and how to check the connection before making it live.

Choose the connection you need

Products: read product descriptions, images, sizes, colours, stock and optional prices to build or update a website catalogue. Your website needs an importer or a custom integration to turn the data into pages.

Diary requests: send details from a custom website enquiry or appointment form into mybridal as an appointment request. Staff then review the request in mybridal.

Online booking: if you want customers to choose from the booking system’s available appointments, use the mybridal booking page or embed. Find it under Settings > Account > Store Booking System URL. The menu offers Copy URL, Copy Embed Code and Settings. You do not need to expose an API key to use this booking page.

The products feed is read-only. It does not send website sales back to mybridal, reserve stock or provide two-way stock synchronisation. The appointment-request endpoint is not a general diary API for listing, editing or cancelling appointments.

Before you start

Agree which website and store are being connected, who will maintain the integration, whether prices should be displayed, and how often the catalogue should refresh. A website developer can complete the technical steps below. You do not need to change code in mybridal.

This guide reflects the implementation checked on 13 October 2026. Check that the matching features are available in your deployed account before setting up the website. The examples were checked against the code; no live catalogue connection or appointment request was made while preparing this guide.

Get your API key

1. Sign in as an account owner or administrator and open Settings > Account.

2. Find API KEY. Use the eye icon to reveal it or the copy icon to copy it. Open the three-dot menu and choose API Documentation for the interactive reference.

3. Give the key to the developer through a private channel. The key belongs to the company account, rather than a single store, and is shared by the products and appointment-request integrations.

4. Store it in the website’s server configuration or a private server-side integration setting. Send requests from that server. Do not paste the key into Versoly page content, embed code, browser JavaScript, public repositories or a URL.

The examples use a placeholder. Replace it privately in your integration. A normal web page should call your website’s backend; the backend adds the key when it contacts mybridal.

Replacing an existing key

The key menu also offers Rotate API key. Rotating immediately stops the old key from working. Update every connected catalogue importer and appointment form with the replacement. Do not rotate the key merely to add another connection.

Prepare your products in mybridal

Choose which products appear

Open Products. Select the products you want to change and use Show / Hide on website. Read the confirmation before continuing: the action toggles the selected products, so a mixed selection can show some products and hide others. The eye indicator shows each product’s website visibility.

Hidden products stay in mybridal but are excluded from the feed. Your website importer must also remove or unpublish its existing copy when a product disappears from the feed. Hiding a product does not directly edit the website.

The feed includes visible products with at least one size/colour variation. Discontinued products are not automatically excluded. Agree how the website should handle discontinued and out-of-stock products; hide products explicitly when they should no longer appear.

Add a website description

Open a product and expand API beneath Notes. Enter the public copy in Website description and save the product. This is returned as notes in the API. The ordinary in-store Notes field is separate.

Check the product code, designer, category, images and variations before importing. The API’s name is the saved product code. If the website needs a different display title, agree that mapping with the developer.

Choose whether to include prices

Open Settings > Defaults > Products > API / Website Tags. As an owner or administrator, enable Hide prices on public products API to remove selling prices from the feed. This setting applies across the company.

When enabled, prices are omitted, even if an API request explicitly asks for them. Missing prices must not be displayed as zero. Purchase prices are never included. Remove any previously imported prices from the website, including product metadata and cached pages, if they should no longer be public.

Add website filters with grouped tags

Inside the product’s API panel, select a group and value, then choose Add Tag. For example, use a collection group with Autumn, or a material group with Lace. Use New Group + or New Value + to create an option, then save the product.

Manage the saved options under Settings > Defaults > Products > API / Website Tags. Use the + controls to add groups or values, or select an existing chip to edit it. Renaming or deleting these options also changes the corresponding tags on products in the company, so coordinate changes with the website developer.

Regular Product Tags remain available for everyday tags. Grouped tags give the website separate filter lists through tagGroups:

Connect the products feed

Use the API origin shown by your account’s API Documentation link. For the standard API address, the two catalogue URLs are:

products returns one record per product, with sizes and colours nested inside its items array. Start here when each dress or style should have one website page.

product-items returns one record per size/colour variation. Use it when the importer needs a separate row for each variation. Its productId identifies the parent product.

Make the first request

Configure the server-side importer with method GET, the x-api-key header and these query values. No request body is needed:

Use items as the response data path. On the products endpoint, the outer items array contains products; each product’s own items array contains its variations. They serve different purposes.

The response includes total, size, page, totalPages and hasMore. It also includes itemCount, limit and offset for compatible importers. The default page size is 100 and the maximum is 500.

Read page 1, then page 2, and continue until hasMore is false. Keep the filters, sort and page size the same throughout the import. Do not stop after the first page. Offset pagination is also supported; use one pagination method consistently.

Map the website fields

Unique import key: id. Keep this as text and use it to update the same website record on later imports. On the flat endpoint it identifies a variation; on the products endpoint it identifies a product.

Title: name or code. Designer: supplierName. Category: categoryName. Description: notes. Images: images[].url.

Product variations: items[].id, items[].size and items[].colour. Selling prices, when enabled, are in items[].price. On the flat endpoint use size, colour and price directly.

Quantities: stock and samples, also available on nested variations. Website filters: tagGroups.<group>. Dates: createdAt and updatedAt.

Stock is company-wide across stores. Samples are separate from stock. Prices are base variation prices, rather than a selected store’s price override. There is no store-specific public catalogue feed. Check currency and price presentation with the store instead of inferring them from a numeric price.

Optional filters and sorting

category: category ID or name. tags: partial tag matching. in_stock=true: select positive stock; this does not mean sample-only availability.

minPrice and maxPrice: non-negative price bounds. sizes and colours: comma-separated values on the product-items endpoint only.

sortBy: code, price, createdAt or updatedAt. sortDesc=false: ascending order. The default is descending code. fields: a comma-separated list of top-level fields to return; keep id and any fields needed by your importer.

URL-encode filter values containing spaces or special characters. Pass each parameter once with a single value. Use true or false for booleans, and positive whole numbers for page and limit.

Refresh the website without creating duplicates

Run the first import on a private test website. Confirm that a second import updates the same records and preserves their URLs. Agree the refresh schedule with the store; the API does not push catalogue changes to your website.

The products quota is 100 requests per company per minute in the cluster deployment, shared by that company’s integrations. Use scheduled imports and cached website data instead of fetching the whole catalogue for every visitor. If a request returns 429, pause and retry with increasing delays.

Products can change while pages are being read. This is not a fixed snapshot or a change-event feed. Complete a periodic full reconciliation to detect products that have been hidden or removed. Only reconcile missing records after every page has succeeded; a failed page or invalid key must not empty the website catalogue.

Moving an existing website

For a new connection, use id. An existing website may need a reviewed externalId mapping to keep its current pages. Do not switch import keys without checking that mapping, or the importer may create duplicates.

External IDs are optional. A product ID and a variation ID are different. Keep them as text, including leading zeroes, and map each at the correct level. External IDs do not automatically retrieve or migrate data from another system.

For WordPress or another website platform, verify that the chosen importer supports the items response path, all pages, nested variations, grouped tags and image URLs. Having an API feed does not by itself install a connector or guarantee that a particular plugin can perform the full import without custom work.

Send an appointment request to the diary

Use this route for a custom website form that collects a preferred appointment time. A successful response creates an appointment request. It does not confirm an appointment, take a payment or promise that staff or fitting rooms are available.

For a customer-facing availability and booking journey, use the hosted booking form or its embed. The request endpoint checks diary blocks, but does not reproduce all the portal’s availability, opening-hours and capacity checks.

Prepare the request

Send the request from your website backend using POST, the same private x-api-key header and Content-Type: application/json. The diary URL does not contain /products-api or /api/v1:

Identify the store with its full storeId, or a confirmed exact storeName. Use one unambiguous store selector. The other supported selectors are location (a store-name alternative), storePostcode and storeCity. A city or postcode may be ambiguous in a multi-store account. The short code in a public booking link is not the full storeId.

Send a complete customer name, or both firstName and lastName, plus startTime. Include phone or email so staff can reply. The following JSON is a template: replace the store name, customer details and date with an agreed test before sending it.

Dates and optional fields

Use the store’s timezone and a consistent date format. The example uses 24-hour time and explicitly supplies appDateFormat. Without it, the default format is DD-MM-YYYY hha, such as 20-10-2026 2pm. The legacy parser changes 12am to 12pm, so use the explicit 24-hour format for clarity.

If endTime is omitted, the request lasts one hour. Custom end times require particular care: the current implementation does not parse endTime through the same store-timezone path as startTime. Verify the saved start, end and duration in the diary before using a custom duration, including dates around daylight-saving changes.

Optional fields include phone, email, type (the appointment type name), notes and source. If collecting weddingDate, the default format is DD-MM-YYYY; use weddingDateFormat when supplying a different format. Validate dates on your website before submitting.

Handle the result

A successful request returns HTTP 201 with this message:

Show the customer “Your appointment request has been sent” only after the successful response. Explain that the store will confirm the appointment. This response does not include a booking reference or confirmed appointment ID.

Prevent repeated clicks while submission is in progress. This endpoint does not provide an idempotency key to make repeated submissions safe. If a network timeout leaves the outcome uncertain, check for the request before resending; an automatic retry can create a duplicate.

Requests may trigger the account’s appointment-request notifications. Using the interactive documentation to send a request has the same effect as submitting from the website. Agree the test with the store and check the request in its diary afterwards.

Test before publishing

1. Confirm the account, store, API address and private key. Check that no key appears in page source, browser requests or public URLs.

2. Import a small catalogue on a private test site. Check images, descriptions, designer, categories, grouped tags, every size/colour and the agreed price display.

3. Test a catalogue larger than one page. Confirm that every page imports and that running it again updates existing records without duplicates.

4. Change a description and hide a test product in mybridal, then refresh the importer. Confirm that the website updates or unpublishes the corresponding page. Check how stock-only, sample-only and discontinued products are handled.

5. If prices are hidden, verify the API response, visible pages and stored website price metadata. Confirm that a missing price does not become a zero price.

6. For diary integration, submit one agreed test with your own contact details. Check the correct store, customer name, date, local time, duration and request status. Check any notifications, then remove or archive the test through the store’s normal workflow.

7. Test a blocked diary time, invalid input and a failed connection. Confirm that the website does not show success for a failed submission or send repeated requests while waiting.

8. Enable the tested website integration and its agreed schedule. Record who maintains it and how to stop the import or restore the previous setup if a problem occurs.

Troubleshooting

401 or authentication failure: check the key, header and account. If the key was rotated, update every integration using the old one.

400 on a product request: check numeric ranges, true/false values, repeated parameters and minPrice versus maxPrice. 429: slow down the importer and check for overlapping scheduled jobs.

Missing products: check website visibility, variations, filters and pagination. Missing description: fill Website description inside the product’s API panel. Ordinary Notes are not used for website copy.

Missing prices: check the company’s Hide prices setting and the correct field path. Wrong quantities: remember stock and samples are separate and the catalogue is company-wide.

Diary request rejected: check the store selector, complete customer name, startTime, date format and diary blocks. Keep the API error available privately for the developer, while showing the customer a clear message.

Wrong appointment time: check timezone and appDateFormat, then verify any custom endTime. Duplicate requests: check repeat clicks and automatic retries.

404 or an HTML page instead of JSON: check the API origin and endpoint path. Products use /products-api/api/v1; diary requests use /appointmentRequests. If the products feature or settings are unavailable in your account, contact mybridal support before continuing.