Spa Parts Vortex Catalogue API

Details supplied by Spa Parts Vortex

Your Spa Parts Vortex account manager will provide:

• your complete catalogue URL;
• your API key;
• the response format: JSON, XML, or CSV;
• the catalogue refresh frequency; and
• any feed-specific field definitions.

API keys are issued separately to each customer and unique to them. If your key is disabled, revoked, or you think that it may have been compromised, please contact us. Do not share your API keys with any other party.

Base URLs

Use the website matching your trade account.

New catalogue feeds use this path:

/catalogue-feeds/<endpoint>

For example:

https://www.spapartsvortex.uk/catalogue-feeds/json/uk-premier-trade

Always use the complete URL supplied by Spa Parts Vortex. Endpoint paths are case-sensitive and may contain more than one path segment.

Authentication

Bearer token — recommended

Send your API key in the HTTP Authorization header:

curl --fail --silent --show-error \
  -H "Authorization: Bearer <api_key>" \
  "https://www.spapartsvortex.uk/catalogue-feeds/<endpoint>"

X-API-Key header

If your integration cannot send a bearer token, use X-API-Key:

curl --fail --silent --show-error \
  -H "X-API-Key: <api_key>" \
  "https://www.spapartsvortex.uk/catalogue-feeds/<endpoint>"

Query-string fallback

For clients that cannot send custom headers, the key can be supplied as an access_token query parameter:

curl --fail --silent --show-error \
  "https://www.spapartsvortex.uk/catalogue-feeds/<endpoint>?access_token=<api_key>"

Use this only as a fallback. URLs may be stored in browser history, proxy logs, monitoring systems, and analytics tools which may expose your API keys to unintended parties.

Logged-in browser access

Some customers may also be permitted to access a catalogue through their authenticated Spa Parts Vortex portal session. Log in to the correct UK or EU website, then open the supplied catalogue URL in the same browser.

Portal access and API-key access are controlled separately. Being able to log in does not necessarily mean browser access has been enabled for your feed.

Response formats

The response format is fixed for each URL.

The exact fields may vary by catalogue. Use the field specification supplied with your endpoint as the authoritative contract.

Example JSON

{
  "catalog": [
    {
      "name": "Example Product",
      "sku": "ABC-123",
      "discontinued": "0",
      "status": "Enabled",
      "weight": 1500.0,
      "weight_kg": 1.5,
      "qty": 10,
      "store": "Vortex UK",
      "prices": {
        "buy": 21.2,
        "retail": 35.0
      }
    }
  ]
}

Example XML

<catalog>
  <product>
    <name>Example Product</name>
    <sku>ABC-123</sku>
    <discontinued>0</discontinued>
    <status>Enabled</status>
    <weight>1500.0</weight>
    <weight_kg>1.5</weight_kg>
    <qty>10</qty>
    <store>Vortex UK</store>
    <prices>
      <buy>21.2</buy>
      <retail>35.0</retail>
    </prices>
  </product>
</catalog>

Example CSV

Name,SKU,Discontinued,Status,Weight (g),Weight (kg),Quantity,Store,Buy Price,Retail Price
Example Product,ABC-123,0,Enabled,1500.0,1.5,10,Vortex UK,21.2,35.0

Python example

from pathlib import Path

import requests

url = "https://www.spapartsvortex.uk/catalogue-feeds/<endpoint>"
api_key = "<api_key>"

response = requests.get(
    url,
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=60,
)
response.raise_for_status()

Path("catalogue-feed").write_bytes(response.content)

For a JSON feed, the response can be decoded directly:

catalogue = response.json()

JavaScript example

API keys should normally be used in server-side code, not public browser code.

const response = await fetch(
  "https://www.spapartsvortex.uk/catalogue-feeds/<endpoint>",
  {
    headers: {
      Authorization: "Bearer <api_key>",
    },
  }
);

if (!response.ok) {
  throw new Error(`Catalogue request failed: ${response.status}`);
}

const content = await response.text();

Efficient polling with ETag

Catalogue responses include an ETag. Store it and send it with your next request using If-None-Match:

curl -i \
  -H "Authorization: Bearer <api_key>" \
  -H 'If-None-Match: "<etag>"' \
  "https://www.spapartsvortex.uk/catalogue-feeds/<endpoint>"

If the catalogue has not changed, the API returns 304 Not Modified without resending the full file. A 304 response is successful and has no response body.

The API serves the latest generated catalogue snapshot. Requesting the URL does not trigger regeneration. Poll no more frequently than the refresh interval agreed with us.

HTTP status codes

For 401, 403, and 404 responses, do not repeatedly retry. Check your URL and credentials or contact Spa Parts Vortex. A temporary 503 may be retried later with a sensible delay.