{ "openapi": "3.0.0", "info": { "title": "Marzipan API", "version": "1.0.0" }, "components": { "securitySchemes": { "tenantAuth": { "type": "http", "scheme": "bearer", "description": "Bearer authentication header of the form `Bearer `, where `` is your API token.", "bearerFormat": "JWT" }, "accountAuth": { "type": "http", "scheme": "bearer", "description": "Bearer authentication header of the form `Bearer `, where `` is the account token returned from the `Login` endpoint." } }, "schemas": { "Product": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the product" }, "name": { "type": "string", "description": "Product name" }, "slug": { "type": "string", "description": "URL-friendly product identifier" }, "url": { "type": "string", "description": "Full URL to the product page" }, "description": { "type": "string", "description": "Product description" }, "productType": { "type": "string", "enum": [ "physical", "event", "subscription", "bundle" ], "description": "Type of product" }, "subscriptionType": { "type": "string", "enum": [ "picknmix", "variable" ], "description": "Type of subscription. Only present for subscription products" }, "sku": { "type": "string", "description": "Stock Keeping Unit" }, "collections": { "type": "array", "items": { "$ref": "#/components/schemas/Collection" }, "description": "Collections this product belongs to" }, "status": { "type": "string", "enum": [ "active", "inactive", "out_of_stock" ], "description": "Product status - automatically set to out_of_stock when quantity is 0" }, "images": { "type": "object", "properties": { "product": { "type": "array", "items": { "$ref": "#/components/schemas/ProductImage" }, "description": "Main product images" }, "labels": { "type": "object", "properties": { "front": { "type": "array", "items": { "$ref": "#/components/schemas/ProductImage" }, "description": "Front label images" }, "back": { "type": "array", "items": { "$ref": "#/components/schemas/ProductImage" }, "description": "Back label images" } } } }, "description": "Product images organized by type" }, "primaryImage": { "$ref": "#/components/schemas/ProductImage", "description": "Primary product image" }, "price": { "type": "string", "description": "Formatted price (e.g., £10.00). For pick-and-mix subscriptions with per-item pricing, may show 'from £X.XX'" }, "salePrice": { "type": "string", "nullable": true, "description": "Formatted sale price if on sale" }, "subscriberPrice": { "type": "string", "nullable": true, "description": "Special price for subscribers. Not shown for subscription products" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "storeSlug": { "type": "string", "description": "Store URL slug" }, "subscriptionsSlug": { "type": "string", "description": "Subscriptions URL slug" }, "availability": { "type": "string", "enum": [ "all", "subscribers" ], "description": "Product availability" }, "upsellProducts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Product ID" }, "name": { "type": "string", "description": "Product name" }, "sku": { "type": "string", "description": "Product SKU" }, "price": { "type": "string", "description": "Formatted price" }, "salePrice": { "type": "string", "nullable": true, "description": "Formatted sale price" }, "subscriberPrice": { "type": "string", "nullable": true, "description": "Formatted subscriber price" } } }, "description": "Upsell products with simplified data" }, "linkedSubscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedSubscription" }, "description": "Full details of linked subscriptions. Only included when requested via the include query parameter." }, "billingFrequency": { "type": "integer", "description": "Billing frequency in months. Only present for subscription products" }, "billingFrequencies": { "type": "array", "items": { "type": "integer" }, "description": "Available billing frequencies. Only present for subscription products" }, "pricingType": { "type": "string", "enum": [ "fixed", "per_item" ], "description": "Pricing type for subscriptions. Only present for subscription products" }, "bundleItems": { "type": "array", "items": { "type": "object" }, "description": "Items included in bundle. Only present for bundle products" }, "attributes": { "type": "array", "items": { "type": "object" }, "description": "Product attributes like color, size, etc." }, "options": { "type": "array", "items": { "type": "object" }, "description": "Product options with their possible values" }, "relatedProducts": { "type": "array", "items": { "type": "object" }, "description": "Related products" }, "awards": { "type": "array", "items": { "type": "object" }, "description": "Product awards" }, "reviews": { "type": "array", "items": { "type": "object" }, "description": "Product reviews" }, "metaTitle": { "type": "string", "description": "SEO meta title" }, "metaDescription": { "type": "string", "description": "SEO meta description" }, "metaImage": { "type": "string", "nullable": true, "description": "SEO meta image URL (1200x630)" }, "linkedSubscription": { "type": "boolean", "description": "Whether product has linked subscriptions. Only present if product has linked subscriptions" }, "storeName": { "type": "string", "description": "Store name" } } }, "ProductSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the product" }, "name": { "type": "string", "description": "Product name" }, "slug": { "type": "string", "description": "URL-friendly product identifier" }, "price": { "type": "number", "format": "float", "description": "Product price" }, "productType": { "type": "string", "enum": [ "physical", "event", "subscription" ], "description": "Type of product" } } }, "ProductImage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the image" }, "path": { "type": "string", "description": "Relative path to the image file" }, "src": { "type": "string", "format": "uri", "description": "Full URL to access the image" }, "alt": { "type": "string", "nullable": true, "description": "Alternative text for accessibility" }, "mimeType": { "type": "string", "description": "MIME type of the image (e.g., image/jpeg, image/png)" }, "filename": { "type": "string", "description": "Original filename of the uploaded image" } } }, "LinkedSubscription": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Subscription ID" }, "name": { "type": "string", "description": "Subscription name" }, "options": { "type": "object", "description": "Subscription options" }, "status": { "type": "string", "description": "Subscription status" }, "startDate": { "type": "string", "format": "date", "description": "Subscription start date" }, "endDate": { "type": "string", "format": "date", "description": "Subscription end date" }, "nextBillingDate": { "type": "string", "format": "date", "description": "Next billing date" }, "billingInterval": { "type": "integer", "description": "Billing interval in months" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } } }, "Collection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the collection" }, "name": { "type": "string", "description": "Collection name" }, "description": { "type": "string", "description": "Collection description" }, "slug": { "type": "string", "description": "URL-friendly collection identifier" }, "attributes": { "type": "array", "items": { "type": "object" }, "description": "Collection attributes" } } }, "SubscriptionPackage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the subscription package" }, "subscriptionType": { "type": "string", "enum": [ "picknmix", "variable" ], "description": "Type of subscription package" }, "name": { "type": "string", "description": "Package name" }, "slug": { "type": "string", "description": "URL-friendly package identifier" }, "sku": { "type": "string", "description": "Stock Keeping Unit" }, "url": { "type": "string", "description": "Full URL to the package page" }, "status": { "type": "string", "enum": [ "active", "inactive", "out_of_stock" ], "description": "Package status" }, "availability": { "type": "string", "enum": [ "all", "subscribers" ], "description": "Who can purchase this package" }, "productType": { "type": "string", "enum": [ "subscription" ], "description": "Always 'subscription' for packages" }, "description": { "type": "string", "description": "Package description" }, "metaTitle": { "type": "string", "description": "SEO meta title" }, "metaDescription": { "type": "string", "description": "SEO meta description" }, "collections": { "type": "array", "items": { "$ref": "#/components/schemas/Collection" }, "description": "Collections this package belongs to" }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/ProductImage" }, "description": "Package images" }, "primaryImage": { "$ref": "#/components/schemas/ProductImage", "description": "Primary package image" }, "price": { "type": "object", "properties": { "value": { "type": "integer", "description": "Price in cents" }, "formatted": { "type": "string", "description": "Formatted price with currency" }, "currency": { "type": "string", "description": "Currency code" } }, "description": "Package price information" }, "salePrice": { "type": "object", "nullable": true, "properties": { "value": { "type": "integer", "description": "Sale price in cents" }, "formatted": { "type": "string", "description": "Formatted sale price with currency" }, "currency": { "type": "string", "description": "Currency code" } }, "description": "Sale price information if on sale" }, "billingFrequency": { "type": "integer", "description": "Default billing frequency in months" }, "billingFrequencies": { "type": "array", "items": { "type": "integer" }, "description": "Available billing frequencies in months" }, "pricingType": { "type": "string", "enum": [ "fixed", "per_item" ], "description": "How the subscription is priced" }, "autoRenew": { "type": "boolean", "description": "Whether the subscription auto-renews" }, "minimumItems": { "type": "integer", "description": "Minimum number of items required for pick & mix" }, "availableItems": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionAvailableItem" }, "description": "Available items for pick & mix subscriptions. Only present for picknmix type" }, "attributes": { "type": "array", "items": { "type": "object" }, "description": "Package attributes" }, "options": { "type": "array", "items": { "type": "object" }, "description": "Package options" }, "relatedProducts": { "type": "array", "items": { "type": "object" }, "description": "Related products" }, "subscribers": { "type": "integer", "description": "Number of subscribers. Only included when using ?include=subscribers parameter" } } }, "SubscriptionPackageCollection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the subscription package" }, "subscriptionType": { "type": "string", "enum": [ "picknmix", "variable" ], "description": "Type of subscription package" }, "name": { "type": "string", "description": "Package name" }, "slug": { "type": "string", "description": "URL-friendly package identifier" }, "subscriptionsSlug": { "type": "string", "description": "Subscriptions URL slug" }, "url": { "type": "string", "description": "Full URL to the package page" }, "description": { "type": "string", "description": "Package description" }, "productType": { "type": "string", "enum": [ "subscription" ], "description": "Always 'subscription' for packages" }, "sku": { "type": "string", "description": "Stock Keeping Unit" }, "collection": { "type": "string", "nullable": true, "description": "Primary collection name" }, "status": { "type": "string", "enum": [ "active", "inactive", "out_of_stock" ], "description": "Package status" }, "image": { "$ref": "#/components/schemas/ProductImage", "description": "Primary package image" }, "price": { "type": "object", "properties": { "value": { "type": "integer", "description": "Price in cents" }, "formatted": { "type": "string", "description": "Formatted price with currency" }, "currency": { "type": "string", "description": "Currency code" } }, "description": "Package price information" }, "salePrice": { "type": "object", "nullable": true, "properties": { "value": { "type": "integer", "description": "Sale price in cents" }, "formatted": { "type": "string", "description": "Formatted sale price with currency" }, "currency": { "type": "string", "description": "Currency code" } }, "description": "Sale price information if on sale" }, "attributes": { "type": "array", "items": { "type": "object" }, "description": "Package attributes. Only included when using ?include=attributes parameter" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } } }, "SubscriptionAvailableItem": { "type": "object", "properties": { "itemId": { "type": "string", "format": "uuid", "description": "Product ID of the available item" }, "itemName": { "type": "string", "description": "Name of the available item" }, "itemSku": { "type": "string", "description": "SKU of the available item" }, "itemDescription": { "type": "string", "description": "Description of the available item" }, "minQty": { "type": "integer", "description": "Minimum quantity allowed" }, "maxQty": { "type": "integer", "description": "Maximum quantity allowed" }, "defaultQty": { "type": "integer", "description": "Default quantity" }, "sortOrder": { "type": "integer", "description": "Display order" }, "image": { "$ref": "#/components/schemas/ProductImage", "description": "Primary item image" }, "collections": { "type": "array", "items": { "$ref": "#/components/schemas/Collection" }, "description": "Collections this item belongs to" }, "status": { "type": "string", "enum": [ "active", "inactive", "out_of_stock" ], "description": "Item availability status" }, "attributes": { "type": "array", "items": { "type": "object" }, "description": "Item attributes" }, "relatedProducts": { "type": "array", "items": { "type": "object" }, "description": "Related products" } } }, "CmsPage": { "type": "object", "properties": { "slug": { "type": "string", "description": "URL-friendly page identifier" }, "name": { "type": "string", "description": "Page title/name" }, "metaTitle": { "type": "string", "description": "SEO meta title" }, "metaDescription": { "type": "string", "description": "SEO meta description" }, "status": { "type": "string", "enum": [ "published", "draft" ], "description": "Page publication status" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "publishedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Publication timestamp" } } }, "CmsPageDetail": { "type": "object", "properties": { "slug": { "type": "string", "description": "URL-friendly page identifier" }, "name": { "type": "string", "description": "Page title/name" }, "content": { "type": "string", "description": "Page content/body" }, "seo": { "type": "object", "properties": { "title": { "type": "string", "description": "SEO meta title" }, "description": { "type": "string", "description": "SEO meta description" }, "ogImage": { "type": "string", "nullable": true, "description": "Open Graph image URL (1200x630)" } }, "description": "SEO metadata" }, "status": { "type": "string", "enum": [ "published", "draft" ], "description": "Page publication status" }, "fields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom fields as key-value pairs" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "publishedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Publication timestamp" } } }, "CmsCollection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the collection" }, "name": { "type": "string", "description": "Collection name" }, "slug": { "type": "string", "description": "URL-friendly collection identifier" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CmsItem" }, "description": "Collection items sorted by order" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } } }, "CmsItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the item" }, "name": { "type": "string", "description": "Item name" }, "content": { "type": "string", "description": "Item content (may contain HTML)" }, "order": { "type": "integer", "description": "Display order within collection" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } } }, "SearchResult": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the result" }, "type": { "type": "string", "enum": [ "product", "page", "collection", "event", "subscription_package" ], "description": "Type of search result" }, "title": { "type": "string", "description": "Title or name of the result" }, "slug": { "type": "string", "description": "URL-friendly identifier" }, "url": { "type": "string", "description": "URL to the result" }, "excerpt": { "type": "string", "nullable": true, "description": "Brief excerpt or description" }, "image": { "$ref": "#/components/schemas/ProductImage", "nullable": true, "description": "Associated image if available" }, "price": { "type": "string", "nullable": true, "description": "Formatted price for product results" }, "status": { "type": "string", "description": "Status of the result" } } }, "LoginResponse": { "type": "object", "properties": { "token": { "type": "string", "description": "Authentication token for API access" }, "isSubscriber": { "type": "boolean", "description": "Whether the user has an active subscription" } } }, "Error": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } }, "required": [ "message" ] }, "ValidationError": { "type": "object", "properties": { "message": { "type": "string", "description": "Validation error message" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field-specific validation errors" } }, "required": [ "message", "errors" ] }, "Market": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "currencyCode": { "type": "string" }, "currencySymbol": { "type": "string" }, "isPrimary": { "type": "boolean" } } }, "StorefrontSettings": { "type": "object", "description": "Storefront configuration payload used to initialise web components and checkout.", "properties": { "name": { "type": "string", "description": "The store / tenant name." }, "storeUrl": { "type": "string" }, "logo": { "type": "string", "nullable": true, "description": "Absolute URL to the store logo, or null if none is set." }, "defaultCurrency": { "type": "string" }, "markets": { "type": "array", "description": "Active markets that allow currency switching, primary first.", "items": { "$ref": "#/components/schemas/Market" } }, "currentMarket": { "allOf": [ { "$ref": "#/components/schemas/Market" } ], "nullable": true, "description": "The market resolved for the current request via geo-detection. Omitted when no market could be resolved." } } }, "MarketDetection": { "type": "object", "properties": { "market": { "allOf": [ { "$ref": "#/components/schemas/Market" } ], "nullable": true, "description": "The detected market, or null when none could be resolved for the visitor." }, "detectedCountry": { "type": "string", "nullable": true, "description": "ISO country code detected for the visitor, if any." } } }, "WebComponentSettings": { "type": "object", "description": "Web-component display settings for the tenant's storefront, grouped by area. Nested option groups control styling and behaviour of the embeddable components.", "properties": { "cssVariables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "CSS custom properties applied to the web components (colours, radii, fonts, etc.)." }, "layout": { "type": "object", "description": "Legacy layout options, retained for backward compatibility.", "properties": { "collectionColumnsMobile": { "type": "integer" }, "collectionColumnsTablet": { "type": "integer" }, "collectionColumnsDesktop": { "type": "integer" }, "logoPosition": { "type": "string" }, "logoHeight": { "type": "string" }, "productCardStyle": { "type": "string" }, "productCardAlignment": { "type": "string" }, "productImageRadius": { "type": "string" } } }, "labels": { "type": "object", "description": "Shared, site-wide display label strings.", "properties": { "subscriberPriceLabel": { "type": "string", "nullable": true }, "saleBadgeText": { "type": "string", "nullable": true }, "subscriberBadgeText": { "type": "string", "nullable": true }, "addToCartText": { "type": "string", "nullable": true }, "bundleText": { "type": "string", "nullable": true }, "waitlistText": { "type": "string", "nullable": true }, "salesClosedText": { "type": "string", "nullable": true }, "showMoreText": { "type": "string", "nullable": true }, "backInStockText": { "type": "string", "nullable": true } } }, "collection": { "type": "object", "description": "Collection component layout and behaviour.", "properties": { "columnsMobile": { "type": "integer" }, "columnsTablet": { "type": "integer" }, "columnsDesktop": { "type": "integer" }, "productCardStyle": { "type": "string" }, "productCardAlignment": { "type": "string" }, "productImageRadius": { "type": "string" }, "showQuantity": { "type": "boolean" }, "showMoreLink": { "type": "string", "nullable": true }, "showDescription": { "type": "boolean", "nullable": true }, "showSubscriberPricing": { "type": "boolean", "nullable": true }, "redirectToCart": { "type": "boolean" } } }, "product": { "type": "object", "description": "Product component behaviour.", "properties": { "backInStockEnabled": { "type": "boolean" }, "showSubscriberPricing": { "type": "boolean", "nullable": true }, "showQuantity": { "type": "boolean", "nullable": true }, "redirectToCart": { "type": "boolean" } } }, "checkout": { "type": "object", "description": "Checkout component options.", "properties": { "logoPosition": { "type": "string" }, "logoHeight": { "type": "string" }, "phoneRequired": { "type": "boolean" }, "referralSources": { "type": "object", "nullable": true, "description": "Referral-source ('how did you hear about us') configuration, or null when disabled.", "properties": { "enabled": { "type": "boolean" }, "allowOther": { "type": "boolean" }, "options": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "followUp": { "type": "string", "nullable": true } } } } } } } }, "cart": { "type": "object", "description": "Cart component options, including related products and free-shipping notifications.", "properties": { "relatedProductsEnabled": { "type": "boolean" }, "relatedProductsCount": { "type": "integer" }, "relatedProductsTitle": { "type": "string", "nullable": true }, "freeShippingNotificationEnabled": { "type": "boolean" }, "freeShippingMessages": { "type": "object" }, "freeShippingThresholds": { "type": "object", "description": "Map of market id to free-shipping threshold in minor units (integer), or null.", "additionalProperties": { "type": "integer", "nullable": true } }, "backgroundEnabled": { "type": "boolean" }, "backgroundColor": { "type": "string" }, "borderEnabled": { "type": "boolean" }, "borderColor": { "type": "string" } } }, "productDisplay": { "type": "object", "description": "Product detail display configuration (quick attributes, accordion sections, events).", "properties": { "quickAttributes": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "maxCount": { "type": "integer" }, "maxLength": { "type": "integer" }, "attributeNames": { "type": "array", "items": { "type": "string" } } } }, "accordion": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "type": { "type": "string" }, "enabled": { "type": "boolean" }, "attributeNames": { "type": "array", "items": { "type": "string" } }, "attributeName": { "type": "string", "nullable": true }, "textContent": { "type": "string", "nullable": true }, "defaultOpen": { "type": "boolean" } } } } } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "enabled": { "type": "boolean" } } } }, "thumbnailPosition": { "type": "string" }, "showImageOverlay": { "type": "boolean" }, "billingFrequencyStyle": { "type": "string" }, "events": { "type": "object", "properties": { "defaultView": { "type": "string" }, "occurrenceCount": { "type": "integer" } } } } }, "account": { "type": "object", "description": "Customer account area options.", "properties": { "subscriptionUpsell": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "collectionId": { "type": "string", "format": "uuid", "nullable": true }, "heading": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true }, "columns": { "type": "object", "properties": { "mobile": { "type": "integer" }, "tablet": { "type": "integer" }, "desktop": { "type": "integer" } } } } } } }, "tracking": { "type": "object", "properties": { "fathomSiteId": { "type": "string", "nullable": true } } } } }, "Visit": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The stored visit id." }, "sessionId": { "type": "string", "description": "Session id used for touchpoint tracking; echoes the supplied value or a newly generated one." } } }, "Address": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the address" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": "string", "nullable": true }, "city": { "type": "string" }, "state": { "type": "string", "nullable": true, "description": "State/county value" }, "county": { "type": "string", "nullable": true, "description": "Alias of state" }, "postcode": { "type": "string" }, "countryName": { "type": "string", "description": "Full country name" }, "country": { "type": "string", "description": "ISO country code" }, "type": { "type": "string", "nullable": true, "description": "Address type" }, "defaultAddress": { "type": "boolean" }, "deliveryInstructions": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true } } }, "AddressInput": { "type": "object", "required": [ "firstName", "lastName", "addressLine1", "city", "postcode", "country" ], "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": "string", "nullable": true }, "city": { "type": "string" }, "state": { "type": "string", "nullable": true }, "postcode": { "type": "string" }, "country": { "type": "string", "description": "ISO country code" }, "phone": { "type": "string", "nullable": true, "description": "Must be a valid phone number for the given country" }, "defaultAddress": { "type": "boolean", "description": "Set this address as the customer's default" } } }, "OrderItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "price": { "type": "string", "description": "Formatted unit price, or '-' for zero" }, "quantity": { "type": "integer" }, "lineTotal": { "type": "string", "description": "Formatted line total" }, "options": { "type": "array", "items": { "type": "object" } }, "bundledItems": { "type": "array", "items": { "type": "object" } }, "type": { "type": "string", "description": "Product type" }, "sku": { "type": "string", "nullable": true }, "image": { "type": "object", "nullable": true, "description": "Primary product image" } } }, "OrderDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "ref": { "type": "string", "description": "Public order reference" }, "email": { "type": "string", "format": "email" }, "currencyCode": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } }, "subtotal": { "type": "string" }, "shipping": { "type": "string" }, "tax": { "type": "string" }, "discount": { "type": "string", "nullable": true }, "discountCodes": { "type": "string" }, "pointsRedeemed": { "type": "integer" }, "pointsDiscount": { "type": "string", "nullable": true }, "total": { "type": "string" }, "totalRaw": { "type": "number" }, "status": { "type": "string" }, "paymentMethod": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string" }, "provider": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "string" }, "amountRaw": { "type": "number" }, "card": { "type": "object", "nullable": true, "properties": { "last4": { "type": "string" }, "type": { "type": "string" }, "expiryMonth": { "type": "integer" }, "expiryYear": { "type": "integer" }, "wallet": { "type": "string", "nullable": true } } }, "failureReason": { "type": "string", "nullable": true } } }, "paymentStatus": { "type": "string", "nullable": true }, "shippingAddress": { "type": "object", "properties": { "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "addressLine1": { "type": "string", "nullable": true }, "addressLine2": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "county": { "type": "string", "nullable": true }, "postcode": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true, "description": "Full country name" }, "countryCode": { "type": "string", "nullable": true } } }, "billingAddress": { "type": "object", "properties": { "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "addressLine1": { "type": "string", "nullable": true }, "addressLine2": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "county": { "type": "string", "nullable": true }, "postcode": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true, "description": "Full country name" }, "countryCode": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true } } }, "shippingMethod": { "type": "string", "nullable": true }, "tracking": { "type": "object", "nullable": true, "properties": { "courier": { "type": "string", "nullable": true }, "reference": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true }, "shippedAt": { "type": "string", "nullable": true }, "deliveredAt": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true } } }, "deliveryInstructions": { "type": "string", "nullable": true }, "giftMessage": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "paymentProviders": { "type": "object", "description": "Enabled payment provider configuration (paypal, stripe, payfast) for paying the order" } } }, "PaymentMethod": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "provider": { "type": "string" }, "paymentMethod": { "type": "string", "description": "e.g. card" }, "providerId": { "type": "string", "description": "Provider token/reference" }, "cardType": { "type": "string", "nullable": true }, "cardLast4": { "type": "string", "nullable": true }, "cardExpMonth": { "type": "integer", "nullable": true }, "cardExpYear": { "type": "integer", "nullable": true }, "default": { "type": "boolean" } } }, "PickupLocation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "method": { "type": "string" }, "amount": { "type": "string", "description": "Formatted price" }, "countries": { "type": "array", "items": { "type": "object" }, "description": "Up to four applicable countries" }, "countryCount": { "type": "integer" }, "remainingCountries": { "type": "array", "items": { "type": "string" } }, "countriesWithZones": { "type": "array", "nullable": true, "items": { "type": "object" } }, "status": { "type": "boolean" } } }, "AccountSubscription": { "type": "object", "description": "Full detail of a customer subscription.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Subscription ID" }, "subscriptionType": { "type": "string", "enum": [ "variable", "picknmix" ], "description": "Type of subscription" }, "email": { "type": "string", "description": "Customer email address" }, "name": { "type": "string", "description": "Subscription / product name" }, "quantity": { "type": "integer", "description": "Subscription quantity" }, "status": { "type": "string", "description": "Subscription status" }, "createdAt": { "type": "string", "description": "Creation date (DD/MM/YYYY) or relative time if today" }, "options": { "type": "object", "description": "Subscription options" }, "availableItems": { "type": "array", "description": "Available pick & mix items. Only present for picknmix subscriptions", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "sku": { "type": "string" }, "defaultQty": { "type": "integer" }, "minQty": { "type": "integer" }, "maxQty": { "type": "integer" }, "sortOrder": { "type": "integer" }, "price": { "type": "string", "description": "Formatted price" }, "status": { "type": "string" }, "image": { "type": "object", "nullable": true } } } }, "pickAndMixItems": { "type": "array", "description": "Currently selected pick & mix items. Only present for picknmix subscriptions", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "sku": { "type": "string" }, "quantity": { "type": "integer" }, "image": { "type": "object", "nullable": true } } } }, "batchedShipments": { "type": "boolean", "description": "Whether shipments are batched" }, "upcomingShipments": { "type": "array", "description": "Upcoming (non-skipped) scheduled shipments", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "items": { "type": "array", "items": { "type": "object" } }, "status": { "type": "string" }, "nextBillingDate": { "type": "string", "nullable": true }, "processingDate": { "type": "string", "nullable": true, "description": "DD/MM/YYYY" }, "shippingDate": { "type": "string", "nullable": true, "description": "DD/MM/YYYY" }, "deliveryDate": { "type": "string", "nullable": true, "description": "DD/MM/YYYY" } } } }, "currentPeriodStart": { "type": "string", "description": "Current billing period start (DD/MM/YYYY)" }, "currentPeriodEnd": { "type": "string", "description": "Current billing period end (DD/MM/YYYY)" }, "expiresAt": { "type": "string", "description": "Subscription end date (DD/MM/YYYY)" }, "billingInterval": { "type": "integer", "description": "Billing interval in months" }, "billingIntervalFriendly": { "type": "string", "description": "Human-friendly billing interval" }, "nextBillingDate": { "type": "string", "nullable": true, "description": "Next billing date (DD/MM/YYYY)" }, "upcomingAdditionalItems": { "type": "array", "nullable": true, "description": "Additional one-off items on the next shipment", "items": { "type": "object" } }, "hasProcessingShipment": { "type": "boolean", "description": "Whether a shipment is currently being processed" }, "failedRenewal": { "type": "object", "nullable": true, "description": "Present only when an active subscription's last renewal failed", "properties": { "message": { "type": "string", "description": "Customer-facing explanation" }, "action": { "type": "string", "description": "Suggested action, e.g. update_payment_method" }, "attemptsRemaining": { "type": "integer" } } }, "price": { "type": "object", "properties": { "friendly": { "type": "string", "description": "Formatted price" }, "raw": { "type": "number", "description": "Price in major currency units" } } }, "preferredDeliveryOption": { "type": "string", "nullable": true, "enum": [ "pickup", "delivery" ], "description": "Preferred shipping option" }, "preferredDeliveryAddress": { "type": "object", "nullable": true, "description": "Preferred delivery address" }, "preferredPickupLocation": { "type": "object", "nullable": true, "description": "Preferred pickup location", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true } } }, "defaultPaymentMethod": { "type": "object", "nullable": true, "description": "Default payment method for the subscription" }, "paymentProvider": { "type": "string", "description": "Payment provider for the default payment method" }, "paymentProviders": { "type": "object", "description": "Configuration for each payment provider enabled on the tenant (stripe, paypal, payfast)" } } }, "RewardStatus": { "type": "object", "description": "Customer rewards status. When the programme is disabled only `enabled` is present.", "properties": { "enabled": { "type": "boolean", "description": "Whether the rewards programme is enabled for the tenant" }, "subscribersOnly": { "type": "boolean", "description": "Whether rewards are restricted to subscribers" }, "subscribersOnlyMessage": { "type": "string", "nullable": true }, "subscribersOnlyButtonText": { "type": "string", "nullable": true }, "subscriptionsUrl": { "type": "string", "nullable": true, "description": "Path to the subscriptions page when rewards are subscribers-only" }, "isSubscriber": { "type": "boolean", "description": "Whether the customer has an active subscription" }, "points": { "type": "integer", "description": "Current points balance" }, "currentTier": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string", "nullable": true }, "badgeColor": { "type": "string", "nullable": true }, "badgeIcon": { "type": "string", "nullable": true }, "pointsThreshold": { "type": "integer" } } }, "totalPoints": { "type": "integer", "description": "Current points balance" }, "lifetimePoints": { "type": "integer", "description": "Lifetime points earned" }, "nextTier": { "type": "object", "nullable": true, "description": "Progress toward the next tier", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "badgeColor": { "type": "string", "nullable": true }, "pointsThreshold": { "type": "integer" }, "pointsNeeded": { "type": "integer", "description": "Points still needed to reach the next tier" }, "progressPercent": { "type": "number", "description": "Percentage progress toward the next tier" } } }, "redemption": { "type": "object", "nullable": true, "description": "Points redemption info, present only when redemption is enabled", "properties": { "enabled": { "type": "boolean" }, "rate": { "type": "number", "nullable": true, "description": "Points required per unit of currency" }, "rateDescription": { "type": "string", "nullable": true }, "currencyCode": { "type": "string" } } } } }, "RewardTier": { "type": "object", "description": "A rewards tier with the customer's status against it.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Tier ID" }, "name": { "type": "string", "description": "Tier name" }, "slug": { "type": "string", "description": "URL-friendly tier identifier" }, "description": { "type": "string", "nullable": true, "description": "Tier description" }, "pointsThreshold": { "type": "integer", "description": "Lifetime points required to reach this tier" }, "badgeColor": { "type": "string", "nullable": true, "description": "Badge colour" }, "badgeIcon": { "type": "string", "nullable": true, "description": "Badge icon" }, "isCurrent": { "type": "boolean", "description": "Whether this is the customer's current tier" }, "isAchieved": { "type": "boolean", "description": "Whether the customer has achieved this tier" }, "perks": { "type": "array", "description": "Active perks for the tier", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true } } } } } }, "RewardTransaction": { "type": "object", "description": "A single rewards points transaction.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Transaction ID" }, "customerId": { "type": "string", "format": "uuid", "description": "Customer ID" }, "orderId": { "type": "string", "format": "uuid", "nullable": true, "description": "Related order ID, if any" }, "points": { "type": "integer", "description": "Points added (positive) or removed (negative)" }, "balanceAfter": { "type": "integer", "description": "Points balance after the transaction" }, "type": { "type": "string", "enum": [ "order", "adjustment", "bonus", "refund", "redemption", "redemption_reversal" ], "description": "Transaction type" }, "description": { "type": "string", "nullable": true, "description": "Transaction description" }, "metadata": { "type": "object", "nullable": true, "description": "Additional transaction metadata" }, "order": { "type": "object", "nullable": true, "description": "Related order summary, when loaded", "properties": { "id": { "type": "string", "format": "uuid" }, "orderId": { "type": "string", "description": "Human-facing order number" } } }, "createdAt": { "type": "string", "format": "date-time", "description": "Transaction timestamp" } } }, "Cart": { "type": "object", "description": "A storefront shopping cart with its items, totals and applied discounts. Monetary amounts are expressed in the cart currency's minor units (e.g. pence/cents).", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the cart." }, "cartCount": { "type": "integer", "description": "Total quantity of items in the cart." }, "customerId": { "type": "string", "format": "uuid", "nullable": true, "description": "Identifier of the customer associated with the cart, if any." }, "email": { "type": "string", "format": "email", "nullable": true, "description": "Email address associated with the cart." }, "billingAddress": { "type": "object", "description": "Billing address details." }, "shippingAddress": { "type": "object", "description": "Shipping address details." }, "shippingMethod": { "type": "object", "nullable": true, "description": "The selected shipping method." }, "shippingMethodId": { "type": "string", "format": "uuid", "nullable": true, "description": "Identifier of the selected shipping method." }, "deliveryInstructions": { "type": "string", "nullable": true, "description": "Delivery instructions for the order." }, "requiresShipping": { "type": "boolean", "description": "Whether the cart contains any shippable items." }, "items": { "type": "array", "description": "The line items in the cart.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Line item identifier." }, "productType": { "type": "string", "description": "The type of product." }, "name": { "type": "string", "description": "Product name." }, "quantity": { "type": "integer", "description": "Quantity of this line item." }, "price": { "type": "number", "description": "Unit price in minor currency units." }, "originalPrice": { "type": "number", "nullable": true, "description": "Original unit price before any discount, in minor currency units." }, "lineTotal": { "type": "number", "description": "Total price for this line, in minor currency units." }, "isFreeItem": { "type": "boolean", "description": "Whether this line was added as a free item." } } } }, "giftMessage": { "type": "string", "nullable": true, "description": "Optional gift message." }, "discounts": { "type": "array", "description": "Discounts applied to the cart.", "items": { "type": "object" } }, "subTotal": { "type": "number", "description": "Subtotal before discounts, shipping and tax, in minor currency units." }, "discount": { "type": "number", "description": "Total discount amount, in minor currency units." }, "pointsToRedeem": { "type": "integer", "description": "Number of reward points currently applied to the cart." }, "pointsDiscountValue": { "type": "number", "description": "Monetary value of the applied points discount, in minor currency units." }, "shipping": { "type": "number", "description": "Shipping cost, in minor currency units." }, "tax": { "type": "number", "description": "Tax amount, in minor currency units." }, "grandTotal": { "type": "number", "description": "Final total payable, in minor currency units." }, "currency": { "type": "object", "description": "The cart's currency.", "properties": { "code": { "type": "string", "description": "ISO currency code." }, "symbol": { "type": "string", "description": "Currency symbol." } } }, "market": { "type": "object", "nullable": true, "description": "The market the cart is currently in.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Market identifier." }, "name": { "type": "string", "description": "Market name." }, "currencyCode": { "type": "string", "description": "Market currency code." }, "currencySymbol": { "type": "string", "description": "Market currency symbol." } } }, "attribution": { "type": "object", "nullable": true, "description": "Marketing attribution data." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the cart was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the cart was last updated." } } }, "FreeShippingUpsell": { "type": "object", "description": "The free shipping upsell state for a cart.", "properties": { "show": { "type": "boolean", "description": "Whether to display a free shipping upsell prompt." }, "qualifies": { "type": "boolean", "description": "Whether the cart already qualifies for free shipping." }, "type": { "type": "string", "enum": [ "value", "volume" ], "description": "Whether the upsell threshold is based on order value or item volume." }, "amountNeeded": { "type": "number", "nullable": true, "description": "For value-based upsells, the additional spend required to qualify, in minor currency units. Null for volume-based upsells." }, "itemsNeeded": { "type": "integer", "nullable": true, "description": "For volume-based upsells, the additional item volume required to qualify. Null for value-based upsells." } }, "required": [ "show" ] }, "CmsPost": { "type": "object", "description": "Summary of a published blog post, as returned in list responses.", "properties": { "slug": { "type": "string", "description": "URL-friendly post identifier." }, "title": { "type": "string", "description": "Post title." }, "excerpt": { "type": "string", "description": "Short summary of the post." }, "featuredImage": { "type": "string", "nullable": true, "description": "Featured image URL (800x600), or null." }, "author": { "type": "object", "description": "The post's author.", "properties": { "name": { "type": "string", "description": "Author name." } } }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp." } } }, "CmsPostDetail": { "type": "object", "description": "Full detail of a published blog post.", "properties": { "slug": { "type": "string", "description": "URL-friendly post identifier." }, "title": { "type": "string", "description": "Post title." }, "excerpt": { "type": "string", "description": "Short summary of the post." }, "content": { "type": "string", "description": "Full post content/body (HTML)." }, "featuredImage": { "type": "string", "nullable": true, "description": "Featured image URL (1200x800). Falls back to the tenant's social image if none is set." }, "author": { "type": "object", "description": "The post's author.", "properties": { "name": { "type": "string", "description": "Author name." } } }, "seo": { "type": "object", "description": "SEO metadata for the post.", "properties": { "title": { "type": "string", "description": "SEO meta title." }, "description": { "type": "string", "description": "SEO meta description." }, "ogImage": { "type": "string", "nullable": true, "description": "Open Graph image URL (1200x630)." } } }, "collections": { "type": "array", "description": "Collections this post belongs to.", "items": { "type": "object", "properties": { "slug": { "type": "string", "description": "Collection slug." }, "name": { "type": "string", "description": "Collection name." } } } }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp." } } }, "Form": { "type": "object", "description": "Definition of a storefront form, used to render it and validate submissions.", "properties": { "name": { "type": "string", "description": "Form name." }, "fields": { "type": "array", "description": "The form's fields, in display order.", "items": { "$ref": "#/components/schemas/FormField" } }, "settings": { "type": "object", "description": "Display settings for the form.", "properties": { "successMessage": { "type": "string", "description": "Message shown after a successful submission." } } } } }, "FormField": { "type": "object", "description": "A single field within a form definition.", "properties": { "name": { "type": "string", "description": "Field name; used as the key when submitting the form." }, "label": { "type": "string", "description": "Human-readable field label." }, "type": { "type": "string", "enum": [ "text", "email", "phone", "textarea", "select", "checkbox", "radio", "date", "hidden" ], "description": "Field input type, which determines how the value is validated." }, "required": { "type": "boolean", "description": "Whether a value is required for this field." }, "placeholder": { "type": "string", "description": "Placeholder text for the field." }, "options": { "type": "array", "description": "Allowed values for select, radio and checkbox fields.", "items": { "type": "string" } } } }, "SubscriptionConfiguration": { "type": "object", "description": "Configuration options for a subscription package.", "properties": { "subscriptionType": { "type": "string", "nullable": true, "description": "The subscription type (e.g. 'picknmix', 'variable')." }, "pricingType": { "type": "string", "description": "How the subscription is priced (e.g. 'calculated', 'fixed')." }, "fixedPrice": { "type": "number", "nullable": true, "description": "Fixed price (in major currency units) when pricingType is 'fixed', otherwise null." }, "frequencies": { "type": "array", "description": "Available billing frequencies in months.", "items": { "type": "integer" } }, "defaultFrequency": { "type": "integer", "description": "The default billing frequency in months." }, "availableItems": { "type": "array", "description": "Items that can be selected for pick & mix subscriptions.", "items": { "$ref": "#/components/schemas/SubscriptionConfigItem" } }, "minItems": { "type": "integer", "nullable": true, "description": "Minimum number of items required for a pick & mix subscription." } } }, "SubscriptionConfigItem": { "type": "object", "description": "An item available to select within a pick & mix subscription configuration.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Product id of the item." }, "name": { "type": "string", "description": "Item name." }, "sku": { "type": "string", "description": "Item SKU." }, "image": { "type": "string", "nullable": true, "description": "Primary item image, or null." }, "price": { "type": "number", "description": "List price in major currency units." }, "salePrice": { "type": "number", "nullable": true, "description": "Sale price in major currency units, or null." }, "subscriberPrice": { "type": "number", "nullable": true, "description": "Subscriber price in major currency units, or null." }, "description": { "type": "string", "description": "Item description." }, "status": { "type": "string", "description": "Item availability status." }, "minQuantity": { "type": "integer", "description": "Minimum selectable quantity." }, "maxQuantity": { "type": "integer", "nullable": true, "description": "Maximum selectable quantity, or null for no limit." }, "defaultQuantity": { "type": "integer", "description": "Default selected quantity." } } }, "EventAvailability": { "type": "object", "description": "Ticket availability for an event.", "properties": { "available": { "type": "boolean", "description": "Whether tickets are currently available." }, "ticketsAvailable": { "type": "integer", "description": "The number of tickets available." }, "waitlistEnabled": { "type": "boolean", "description": "Whether the waitlist is enabled for the event." }, "waitlistCount": { "type": "integer", "description": "The number of entries currently on the waitlist." }, "message": { "type": "string", "description": "An explanatory message, present when the event is unavailable or does not occur on the requested date." } } }, "EventStats": { "type": "object", "description": "Aggregate statistics for an event. Revenue values are in the store's major currency unit.", "properties": { "ticketsSold": { "type": "integer", "description": "The total number of tickets sold." }, "ticketsAvailable": { "type": "integer", "description": "The number of tickets still available." }, "maxTickets": { "type": "integer", "nullable": true, "description": "The maximum ticket capacity, or null if uncapped." }, "maxTicketsPerOrder": { "type": "integer", "nullable": true, "description": "The maximum tickets allowed per order." }, "totalRevenue": { "type": "number", "description": "Total revenue from tickets sold." }, "outstandingRevenue": { "type": "number", "description": "Outstanding balances still due." }, "checkedIn": { "type": "integer", "description": "The number of attendees checked in." }, "attending": { "type": "integer", "description": "The number of tickets attending." }, "waitlist": { "type": "integer", "description": "The number of pending waitlist entries." }, "cancelled": { "type": "integer", "description": "The number of cancelled or refunded tickets." } } }, "EventOccurrence": { "type": "object", "description": "A single occurrence of a recurring event.", "properties": { "id": { "type": "string", "format": "uuid", "description": "The occurrence identifier." }, "date": { "type": "string", "format": "date", "description": "The occurrence date (YYYY-MM-DD)." }, "formattedDate": { "type": "string", "description": "A human-readable date, e.g. \"Aug 15, 2026\"." }, "startTime": { "type": "string", "nullable": true, "description": "The start time (HH:MM)." }, "endTime": { "type": "string", "nullable": true, "description": "The end time (HH:MM)." }, "status": { "type": "string", "enum": [ "active", "cancelled", "postponed" ], "description": "The occurrence status." }, "location": { "type": "string", "nullable": true, "description": "The occurrence location." }, "maxTickets": { "type": "integer", "nullable": true, "description": "The maximum ticket capacity for the occurrence." }, "ticketsSold": { "type": "integer", "description": "The number of tickets sold for the occurrence." }, "ticketsAvailable": { "type": "integer", "description": "The number of tickets still available." }, "isSoldOut": { "type": "boolean", "description": "Whether the occurrence is sold out." } } }, "EventOccurrenceRecord": { "type": "object", "description": "The stored record for an event occurrence, as returned after an update.", "properties": { "id": { "type": "string", "format": "uuid", "description": "The occurrence identifier." }, "eventId": { "type": "string", "format": "uuid", "description": "The parent event identifier." }, "occurrenceDate": { "type": "string", "format": "date", "description": "The occurrence date." }, "startTime": { "type": "string", "nullable": true, "description": "The start time (HH:MM)." }, "endTime": { "type": "string", "nullable": true, "description": "The end time (HH:MM)." }, "status": { "type": "string", "enum": [ "active", "cancelled", "postponed" ], "description": "The occurrence status." }, "maxTickets": { "type": "integer", "nullable": true, "description": "The maximum ticket capacity." }, "ticketsSold": { "type": "integer", "description": "The number of tickets sold." }, "locationOverride": { "type": "string", "nullable": true, "description": "A location overriding the parent event's location." }, "notes": { "type": "string", "nullable": true, "description": "Internal notes for the occurrence." } } }, "RecurringDate": { "type": "object", "description": "An available date for a recurring event product.", "properties": { "id": { "type": "string", "format": "uuid", "description": "The occurrence identifier." }, "date": { "type": "string", "format": "date", "description": "The occurrence date (YYYY-MM-DD)." }, "startDate": { "type": "string", "format": "date", "description": "The occurrence start date (YYYY-MM-DD)." }, "endDate": { "type": "string", "format": "date", "description": "The occurrence end date (YYYY-MM-DD)." }, "startTime": { "type": "string", "nullable": true, "description": "The start time (HH:MM)." }, "endTime": { "type": "string", "nullable": true, "description": "The end time (HH:MM)." }, "location": { "type": "string", "nullable": true, "description": "The occurrence location." }, "status": { "type": "string", "enum": [ "active", "cancelled", "postponed" ], "description": "The occurrence status." }, "ticketsAvailable": { "type": "integer", "description": "The number of tickets available." }, "isSoldOut": { "type": "boolean", "description": "Whether the occurrence is sold out." }, "formattedDateTime": { "type": "string", "description": "A human-readable date and time for display." } } }, "OccurrenceAvailability": { "type": "object", "description": "Ticket availability for a specific event occurrence.", "properties": { "available": { "type": "boolean", "description": "Whether tickets are currently available." }, "ticketsAvailable": { "type": "integer", "description": "The number of tickets available." }, "ticketsSold": { "type": "integer", "description": "The number of tickets sold." }, "maxTickets": { "type": "integer", "nullable": true, "description": "The maximum ticket capacity." }, "waitlistEnabled": { "type": "boolean", "description": "Whether the waitlist is enabled for the event." }, "occurrenceDate": { "type": "string", "format": "date", "description": "The occurrence date (YYYY-MM-DD)." }, "status": { "type": "string", "enum": [ "active", "cancelled", "postponed" ], "description": "The occurrence status." } } }, "WaitlistEntry": { "type": "object", "description": "An entry on an event's waitlist.", "properties": { "id": { "type": "string", "format": "uuid", "description": "The waitlist entry identifier." }, "eventId": { "type": "string", "format": "uuid", "description": "The identifier of the event." }, "email": { "type": "string", "format": "email", "description": "The customer's email address." }, "name": { "type": "string", "description": "The customer's name." }, "phone": { "type": "string", "nullable": true, "description": "The customer's phone number." }, "quantity": { "type": "integer", "description": "The number of tickets requested." }, "position": { "type": "integer", "nullable": true, "description": "The position in the waitlist, for pending entries." }, "status": { "type": "string", "enum": [ "pending", "promoted", "claimed", "expired", "cancelled" ], "description": "The entry status." }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When a promoted spot expires." } } }, "WaitlistStatus": { "type": "object", "description": "A customer's waitlist status for an event.", "properties": { "success": { "type": "boolean" }, "onWaitlist": { "type": "boolean", "description": "Whether the customer is on the waitlist." }, "status": { "type": "string", "enum": [ "pending", "promoted", "claimed", "expired", "cancelled" ], "description": "The entry status." }, "quantity": { "type": "integer", "description": "The number of tickets requested." }, "position": { "type": "integer", "description": "The waitlist position. Present for pending entries." }, "ahead": { "type": "integer", "description": "The number of pending entries ahead. Present for pending entries." }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the promoted spot expires. Present for promoted entries." }, "canClaim": { "type": "boolean", "description": "Whether the promoted spot can currently be claimed. Present for promoted entries." } } }, "WaitlistCheckout": { "type": "object", "description": "Checkout data returned when a promoted waitlist spot is claimed.", "properties": { "productId": { "type": "string", "format": "uuid", "description": "The identifier of the event product." }, "quantity": { "type": "integer", "description": "The number of tickets reserved." }, "email": { "type": "string", "format": "email", "description": "The customer's email address." }, "name": { "type": "string", "description": "The customer's name." }, "waitlistEntryId": { "type": "string", "format": "uuid", "description": "The identifier of the waitlist entry." }, "reservedUntil": { "type": "string", "format": "date-time", "description": "When the reservation expires (15 minutes after claiming)." } } } } }, "servers": [ { "url": "https://api.marzipan.co/v1" } ], "security": [ { "tenantAuth": [] } ], "tags": [ { "name": "Account", "description": "Account management endpoints including registration, login, and user details" }, { "name": "Carts", "description": "Shopping cart management endpoints" }, { "name": "Products", "description": "Product catalog and search endpoints" }, { "name": "Subscriptions", "description": "Subscription management and renewal endpoints" }, { "name": "CMS", "description": "Content management system endpoints" }, { "name": "Messaging", "description": "Message and communication endpoints" }, { "name": "Search", "description": "Search functionality endpoints" }, { "name": "Settings", "description": "Storefront settings and market detection used to configure the web components and checkout." }, { "name": "Analytics", "description": "Storefront visit and attribution tracking." }, { "name": "Rewards", "description": "Loyalty and rewards programme endpoints for the authenticated customer, covering points balance, tier status, perks, exclusive products and transaction history." }, { "name": "Forms", "description": "Render and submit dynamic storefront forms defined in the CMS." }, { "name": "Events", "description": "Check event availability, browse occurrences and recurring dates, generate ticket QR codes, and manage event waitlists (join, leave, check status, and claim promoted spots)." } ], "paths": { "/account/register": { "parameters": [], "post": { "tags": [ "Account" ], "summary": "Register", "description": "Register a new user account with an email address. A verification email will be sent to complete the registration process.", "security": [ { "tenantAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "string" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } } } } } } } }, "/account/login": { "parameters": [], "post": { "tags": [ "Account" ], "summary": "Login", "description": "Authenticate a user with their email address and receive an authentication token for API access.", "security": [ { "tenantAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "string" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } } } } } } } }, "/account/logout": { "parameters": [], "post": { "tags": [ "Account" ], "summary": "Logout", "description": "Invalidate the current authentication token and log out the user from their session.", "security": [ { "accountAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "string" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/account/password": { "parameters": [], "post": { "tags": [ "Account" ], "summary": "Password Reset", "description": "Request a password reset link to be sent to the user's email address. The user can use the link to set a new password.", "security": [ { "tenantAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "string" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "returnUrl": { "type": "string", "format": "uri" } } } } } } } }, "/account/orders": { "parameters": [], "get": { "tags": [ "Account" ], "summary": "Orders", "description": "Retrieve a list of all orders associated with the authenticated user's account, including order status and payment information.", "security": [ { "accountAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "ref": { "type": "string" }, "items": { "type": "integer" }, "amount": { "type": "string" }, "status": { "type": "string" }, "paymentStatus": { "type": "string" }, "createdAt": { "type": "string" } } } } } }, "example": { "data": [ { "id": "73d5c504-adbb-43ac-891e-9b3dd4900de4", "ref": "1010744", "items": 2, "amount": "£96.98", "status": "processing", "paymentStatus": "paid", "createdAt": "2024-06-08T22:07:53.000000Z" }, { "id": "6326728d-05e1-4fc5-92fb-c40b5aa0e52f", "ref": "1010961", "items": 1, "amount": "£9.99", "status": "shipped", "paymentStatus": "paid", "createdAt": "2024-10-07T12:12:58.000000Z" }, { "id": "835152d7-a1a7-4aa1-941e-1114acae24df", "ref": "1010985", "items": 5, "amount": "£281.89", "status": "shipped", "paymentStatus": "paid", "createdAt": "2024-10-25T09:03:10.000000Z" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "string" } } } } } } }, "/account/subscriptions": { "parameters": [], "get": { "tags": [ "Account" ], "summary": "Subscriptions", "description": "Get all active and inactive subscriptions for the authenticated user, including subscription details and renewal dates.", "security": [ { "accountAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "subscriptionType": { "type": "string" }, "name": { "type": "string" }, "productId": { "type": "string" }, "price": { "type": "string" }, "status": { "type": "string" }, "startDate": { "type": "string" }, "endDate": { "type": "string" }, "renewalDate": { "type": "string" }, "billingInterval": { "type": "integer" } } } } } }, "example": { "data": [ { "id": "1224f9ef-8caf-4564-9474-023f95819949", "subscriptionType": "variable", "name": "Discovery Club", "productId": "084b80ef-d16d-4531-a25f-40b7ff4c744b", "price": "£9.99", "status": "active", "startDate": "2024-10-07T12:12:58.000000Z", "endDate": "2030-10-07T12:12:58.000000Z", "renewalDate": "2025-01-07T12:12:58.000000Z", "billingInterval": 3 }, { "id": "feb40b5e-bde2-4494-a547-12f6ab368ca9", "subscriptionType": "variable", "name": "Premium Wine Selection", "productId": "0b0210cb-5180-49b8-81f0-82ea693fcc37", "price": "£24.99", "status": "active", "startDate": "2025-05-05T15:31:18.000000Z", "endDate": "2031-05-05T15:31:18.000000Z", "renewalDate": "2025-09-05T15:31:18.000000Z", "billingInterval": 1 } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "string" } } } } } } }, "/account/details": { "parameters": [], "get": { "tags": [ "Account" ], "summary": "Details", "description": "Retrieve the authenticated user's account details including personal information and marketing preferences.", "security": [ { "accountAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "marketing": { "type": "array", "items": { "type": "string" } } } } } }, "example": { "data": { "firstName": "Demo", "lastName": "User", "email": "demo@marzipan.uk", "phone": "+44 7700 900123", "marketing": [] } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "string" } } } } } }, "post": { "tags": [ "Account" ], "summary": "Update details", "description": "Update the authenticated user's account information such as name and email address.", "security": [ { "accountAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "string" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string", "format": "email" } } } } } } } }, "/carts": { "parameters": [], "post": { "x-excluded": true, "tags": [ "Carts" ], "summary": "Create Cart", "description": "Create a new shopping cart session. The cart can be used to add items and proceed to checkout.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "items": { "type": "array", "items": { "type": "object" } }, "total": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } }, "example": { "id": "uuid", "items": [], "total": "£0.00", "createdAt": "2025-01-01T00:00:00.000000Z" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object" } } }, "example": { "message": "string", "errors": { "field.name": [ "string" ] } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "string" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "options": { "type": "object" }, "price": { "type": "integer" } } } } } } } } } }, "/carts/{cartId}": { "parameters": [ { "name": "cartId", "in": "path", "required": true, "description": "The unique identifier for the cart", "schema": { "type": "string", "format": "uuid" }, "example": "893ff86d-4453-4134-9f62-5c9b7a70d74e" } ], "get": { "x-excluded": true, "tags": [ "Carts" ], "summary": "Get Cart", "description": "Retrieve the contents and details of a specific cart including all items, totals, and applied discounts.", "parameters": [], "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "string" } } } } } }, "put": { "x-excluded": true, "tags": [ "Carts" ], "summary": "Update Cart", "description": "Update cart details such as the customer email address associated with the cart.", "security": [ { "tenantAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "string" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } } } } } } }, "delete": { "x-excluded": true, "tags": [ "Carts" ], "summary": "Clear All Cart Items", "description": "Remove all items from the cart, effectively emptying it while keeping the cart session active.", "parameters": [], "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "string" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/carts/{cartId}/items": { "parameters": [ { "name": "cartId", "in": "path", "required": true, "description": "The unique identifier for the cart", "schema": { "type": "string", "format": "uuid" }, "example": "2ec7d69b-c40b-40fd-9f66-8e81130b5bb5" } ], "post": { "x-excluded": true, "tags": [ "Carts" ], "summary": "Add Item to Cart", "description": "Add one or more items to the cart with specified quantities and product types.", "parameters": [], "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "string" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "quantity": { "type": "integer" }, "productType": { "type": "string" } } } } } } } } } } }, "/carts/{cartId}/items/{itemId}": { "parameters": [ { "name": "cartId", "in": "path", "required": true, "description": "The unique identifier for the cart", "schema": { "type": "string", "format": "uuid" }, "example": "8bb107dd-4b10-4b19-ac7d-c88d21e49909" }, { "name": "itemId", "in": "path", "required": true, "description": "The unique identifier for the cart item", "schema": { "type": "string", "format": "uuid" }, "example": "39e460ed-c517-4bbc-b358-c05f8abcccca" } ], "put": { "x-excluded": true, "tags": [ "Carts" ], "summary": "Update Cart Item Quantity", "description": "Update the quantity of a specific item in the cart. Set quantity to zero to remove the item.", "parameters": [], "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "string" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "quantity": { "type": "integer" } } } } } } }, "delete": { "x-excluded": true, "tags": [ "Carts" ], "summary": "Remove Cart Item", "description": "Remove a specific item from the cart completely regardless of quantity.", "parameters": [], "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "string" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/carts/{cartId}/discount": { "parameters": [ { "name": "cartId", "in": "path", "required": true, "description": "The unique identifier for the cart", "schema": { "type": "string", "format": "uuid" }, "example": "21047fd2-b068-41ed-b70c-1689af54368f" } ], "post": { "x-excluded": true, "tags": [ "Carts" ], "summary": "Apply Discount to Cart", "description": "Apply a discount code to the cart to receive promotional pricing or special offers.", "parameters": [], "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "string" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "discountCode": { "type": "string" } } } } } } } }, "/carts/{cartId}/checkout": { "parameters": [ { "name": "cartId", "in": "path", "required": true, "description": "The unique identifier for the cart", "schema": { "type": "string", "format": "uuid" }, "example": "2beaa641-3076-49bc-a0f7-e91e7143e1f9" } ], "post": { "x-excluded": true, "tags": [ "Carts" ], "summary": "Checkout Cart", "description": "Process the cart for payment and convert it to an order. Supports multiple payment providers including PayPal.", "parameters": [], "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "string" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentProvider": { "type": "string" }, "paypal": { "type": "object", "properties": { "payerId": { "type": "string" }, "orderId": { "type": "string" } } } } } } } } } }, "/carts/{cartId}/shippingMethods": { "parameters": [ { "name": "cartId", "in": "path", "required": true, "description": "The unique identifier for the cart", "schema": { "type": "string", "format": "uuid" }, "example": "43341d73-e9b5-4cd6-a35f-245e6c0e9aac" } ], "get": { "x-excluded": true, "tags": [ "Carts" ], "summary": "Get Cart Shipping Methods", "description": "Retrieve available shipping methods and rates for the items in the cart based on the destination.", "parameters": [], "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "string" } } } } } } }, "/carts/{cartId}/countries": { "parameters": [ { "name": "cartId", "in": "path", "required": true, "description": "The unique identifier for the cart", "schema": { "type": "string", "format": "uuid" }, "example": "2ec7d69b-c40b-40fd-9f66-8e81130b5bb5" } ], "get": { "x-excluded": true, "tags": [ "Carts" ], "summary": "Get Cart Countries", "description": "Get a list of countries available for shipping for the items in the current cart.", "parameters": [], "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "string" } } } } } } }, "/carts/{cartId}/createSetupIntent": { "parameters": [ { "name": "cartId", "in": "path", "required": true, "description": "The unique identifier for the cart", "schema": { "type": "string", "format": "uuid" }, "example": "d9c2f45b-f62f-4d60-8d1d-48929b662c6a" } ], "post": { "x-excluded": true, "tags": [ "Carts" ], "summary": "Create Cart Setup Intent", "description": "Create a payment setup intent for saving payment methods for future use with this cart.", "parameters": [], "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "string" } } } } } } }, "/cms/pages": { "parameters": [], "get": { "tags": [ "CMS" ], "summary": "Pages", "description": "Retrieve a list of all CMS pages including their metadata, status, and publication dates.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CmsPage" } }, "example": { "data": [ { "slug": "about-us", "name": "About Us", "metaTitle": "About Our Wine Collection", "metaDescription": "Learn about our carefully curated wine selection and subscription services", "status": "published", "createdAt": "2024-01-15T10:30:00.000000Z", "updatedAt": "2024-02-01T14:20:00.000000Z", "publishedAt": "2024-01-15T10:30:00.000000Z" }, { "slug": "wine-guide", "name": "Wine Guide", "metaTitle": "Complete Wine Tasting Guide", "metaDescription": "Your comprehensive guide to wine tasting, pairing, and appreciation", "status": "published", "createdAt": "2024-01-20T09:00:00.000000Z", "updatedAt": "2024-01-25T16:45:00.000000Z", "publishedAt": "2024-01-20T09:00:00.000000Z" } ] } } } } } } }, "/cms/pages/{pageSlug}": { "parameters": [ { "name": "pageSlug", "in": "path", "required": true, "description": "The unique slug identifier for the page", "schema": { "type": "string" }, "example": "about-us" } ], "get": { "tags": [ "CMS" ], "summary": "Page", "description": "Get the full content and details of a specific CMS page by its slug identifier.", "parameters": [], "responses": { "200": { "description": "CMS page details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CmsPageDetail" }, "example": { "slug": "about-us", "name": "About Us", "content": "

About Our Wine Collection

We are passionate about bringing you the finest wines from around the world. Our carefully curated selection includes premium vintages and exclusive discoveries that you won't find anywhere else.

Founded in 2020, our mission is to make exceptional wines accessible through our subscription service and expert recommendations.

", "seo": { "title": "About Our Wine Collection - Premium Wines & Subscriptions", "description": "Learn about our carefully curated wine selection and subscription services. Discover premium vintages and exclusive wines delivered to your door.", "ogImage": "https://marzipan-cloud-dev.b-cdn.net/1/ea9f0c5b-e517-4e24-99a1-90d40dcb1c79.jpg" }, "status": "published", "fields": { "heroImage": "https://marzipan-cloud-dev.b-cdn.net/1/3bc26391-8cc1-4d20-a636-1c2ec55ef10d.jpg", "teamPhoto": "https://marzipan-cloud-dev.b-cdn.net/1/0736c529-a33d-4b8c-8126-eb69779dcdad.jpg" }, "createdAt": "2024-01-15T10:30:00.000000Z", "updatedAt": "2024-02-01T14:20:00.000000Z", "publishedAt": "2024-01-15T10:30:00.000000Z" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "string" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "string" } } } } } } }, "/cms/collections/{collectionName}": { "parameters": [ { "name": "collectionName", "in": "path", "required": true, "description": "The unique name identifier for the collection", "schema": { "type": "string" }, "example": "faqs" } ], "get": { "tags": [ "CMS" ], "summary": "Collection", "description": "Retrieve all items from a specific CMS collection by its name.", "parameters": [], "responses": { "200": { "description": "CMS collection with items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CmsCollection" }, "example": { "id": "30ce94bf-230e-460e-97f8-c5807515c5d0", "name": "FAQs", "slug": "faqs", "items": [ { "id": "cbcb30f9-e88b-475b-a458-47380cdb6b10", "name": "How do wine subscriptions work?", "content": "Our wine subscriptions deliver carefully selected wines to your door on a regular basis. You can choose monthly, quarterly, or bi-annual deliveries. Each shipment includes tasting notes and information about the vineyard and winemaker.", "order": 1, "createdAt": "2025-08-05T15:44:33.000000Z", "updatedAt": "2025-08-05T15:44:33.000000Z" }, { "id": "11faa766-21bc-4cb0-989d-7abb93a2a3e0", "name": "Can I skip a delivery?", "content": "Yes, you can skip any delivery up to 7 days before your next shipment date. Simply log into your account and manage your subscription settings. You can also pause your subscription for up to 3 months.", "order": 2, "createdAt": "2025-08-05T15:44:33.000000Z", "updatedAt": "2025-08-05T15:44:33.000000Z" }, { "id": "bb28663d-d37b-469c-bad2-235c5a86d6a7", "name": "What if I do not like a wine?", "content": "We offer a satisfaction guarantee. If you are not happy with any wine in your shipment, contact us within 30 days and we will provide a credit or replacement. We want you to love every bottle!", "order": 3, "createdAt": "2025-08-05T15:44:33.000000Z", "updatedAt": "2025-08-05T15:44:33.000000Z" }, { "id": "18e6da9f-86a4-43e1-8667-8a19aa5057f6", "name": "Do you ship internationally?", "content": "Currently we ship within the UK only. We are working on expanding to EU countries in 2025. UK shipping is free on all subscription orders and orders over £50.", "order": 4, "createdAt": "2025-08-05T15:44:33.000000Z", "updatedAt": "2025-08-05T15:44:33.000000Z" }, { "id": "e58aef3b-fcea-4444-88b6-441ee059263f", "name": "How do I cancel my subscription?", "content": "You can cancel your subscription at any time through your account settings. There are no cancellation fees or commitments. If you cancel before your next billing date, you won't be charged for future shipments.", "order": 5, "createdAt": "2025-08-05T15:44:33.000000Z", "updatedAt": "2025-08-05T15:44:33.000000Z" } ], "createdAt": "2025-08-05T15:44:33.000000Z", "updatedAt": "2025-08-05T15:44:33.000000Z" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "string" } } } } } } }, "/products": { "parameters": [], "get": { "tags": [ "Products" ], "summary": "Products", "description": "Get a paginated list of all products with filtering and sorting options. Returns product details including pricing and availability.", "parameters": [ { "name": "collection", "in": "query", "required": false, "description": "Filter products by collection slug or name. Products will be ordered by their position in the collection.", "schema": { "type": "string" }, "example": "featured-products" }, { "name": "attr", "in": "query", "required": false, "description": "Filter products by attributes using deep object notation. Each attribute filter accepts comma-separated values for OR matching.\n\nFormat: attr[attribute_slug]=value1,value2\n\nExample: attr[color]=red,blue&attr[size]=large\nThis returns products that are (red OR blue) AND large.", "schema": { "type": "object", "additionalProperties": { "type": "string" } }, "style": "deepObject", "explode": true, "example": { "color": "red,blue", "size": "large" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort products by field and direction. Format: field.direction (e.g., price.asc, name.desc). Multiple sort options can be comma-separated.", "schema": { "type": "string" }, "example": "price.asc,name.desc" }, { "name": "limit", "in": "query", "required": false, "description": "Limit the number of results returned. Maximum 50 per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 }, "example": 10 }, { "name": "page", "in": "query", "required": false, "description": "Page number for pagination.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, { "name": "perPage", "in": "query", "required": false, "description": "Number of items per page. Default is 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 50 } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of related resources to include in the response.\n\n Available options: linkedSubscriptions (includes full subscription details for products with linked subscriptions).", "schema": { "type": "string", "enum": [ "linkedSubscriptions" ] }, "example": "linkedSubscriptions" } ], "responses": { "200": { "description": "products", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "links": { "type": "object", "properties": { "first": { "type": "string", "format": "uri" }, "last": { "type": "string", "format": "uri", "nullable": true }, "prev": { "type": "string", "format": "uri", "nullable": true }, "next": { "type": "string", "format": "uri", "nullable": true } } }, "meta": { "type": "object", "properties": { "currentPage": { "type": "integer" }, "from": { "type": "integer" }, "path": { "type": "string", "format": "uri" }, "perPage": { "type": "integer" }, "to": { "type": "integer" } } } } }, "example": { "data": [ { "id": "2e2805a1-738e-4118-8a8b-f9431f0e210c", "name": "Cellar Selection Malbec", "slug": "cellar-selection-malbec-2015", "description": "Id laboris ad aliqua exercitation dolore. Ad, aliqua exercitation dolore est culpa. Dolore est culpa id duis duis labore dolore do ex.", "productType": "physical", "sku": "CSMALBC2015", "collection": "Store", "status": "active", "image": { "id": "0736c529-a33d-4b8c-8126-eb69779dcdad", "path": "1/0736c529-a33d-4b8c-8126-eb69779dcdad.jpg", "src": "https://marzipan-cloud-dev.b-cdn.net/1/0736c529-a33d-4b8c-8126-eb69779dcdad.jpg", "alt": "Cellar Selection Malbec 2015 bottle", "mimeType": "image/jpeg", "filename": "0736c529-a33d-4b8c-8126-eb69779dcdad.jpg" }, "price": "£24.99", "salePrice": null, "subscriberPrice": null, "createdAt": "2024-02-05T23:22:56.000000Z", "updatedAt": "2024-02-05T23:22:56.000000Z", "storeSlug": "store", "subscriptionsSlug": null, "availability": "all", "upsellProducts": [] }, { "id": "df0d13db-1332-4461-b3d1-b2774d47ff5f", "name": "Chardonnay", "slug": "chardonnay-2015", "description": "Lorem sed id, culpa. Culpa id duis duis labore dolore do ex. Duis duis labore, dolore.", "productType": "physical", "sku": "CHARD2015", "collection": "Store", "status": "active", "image": { "id": "1b978a90-3ecb-4f37-b480-9fb81882176e", "path": "1/1b978a90-3ecb-4f37-b480-9fb81882176e.jpg", "src": "https://marzipan-cloud-dev.b-cdn.net/1/1b978a90-3ecb-4f37-b480-9fb81882176e.jpg", "alt": "Chardonnay 2015 bottle", "mimeType": "image/jpeg", "filename": "1b978a90-3ecb-4f37-b480-9fb81882176e.jpg" }, "price": "£23.99", "salePrice": null, "subscriberPrice": null, "createdAt": "2024-02-05T23:22:56.000000Z", "updatedAt": "2024-02-05T23:22:56.000000Z", "storeSlug": "store", "subscriptionsSlug": null, "availability": "all", "upsellProducts": [] }, { "id": "084b80ef-d16d-4531-a25f-40b7ff4c744b", "name": "Discovery Club", "slug": "discovery-club", "description": "Laborum adipiscing, tempor cillum. Cillum exercitation sed officia mollit do dolore.", "productType": "subscription", "sku": "DISCCLUB", "collection": "Club", "status": "active", "image": { "id": "bc1a0d61-e7f9-44d3-ae53-1475b5f9395d", "path": "1/bc1a0d61-e7f9-44d3-ae53-1475b5f9395d.jpg", "src": "https://marzipan-cloud-dev.b-cdn.net/1/bc1a0d61-e7f9-44d3-ae53-1475b5f9395d.jpg", "alt": "Discovery Club subscription box", "mimeType": "image/jpeg", "filename": "bc1a0d61-e7f9-44d3-ae53-1475b5f9395d.jpg" }, "price": "from £0.00", "salePrice": null, "subscriberPrice": null, "createdAt": "2024-02-05T23:22:56.000000Z", "updatedAt": "2024-02-05T23:22:56.000000Z", "storeSlug": null, "subscriptionsSlug": "club", "availability": "all", "upsellProducts": [], "billingFrequency": 6, "pricingType": "per_item" } ], "links": { "first": "https://api.marzipan.co/v1/products?page=1", "last": "https://api.marzipan.co/v1/products?page=5", "prev": null, "next": "https://api.marzipan.co/v1/products?page=2" }, "meta": { "currentPage": 1, "from": 1, "path": "https://api.marzipan.co/v1/products", "perPage": 15, "to": 15 } } } } } } } }, "/products/{productId}": { "parameters": [ { "name": "productId", "in": "path", "required": true, "description": "The unique identifier for the product", "schema": { "type": "string", "format": "uuid" }, "example": "2e2805a1-738e-4118-8a8b-f9431f0e210c" } ], "get": { "tags": [ "Products" ], "summary": "Product", "description": "Retrieve detailed information about a specific product by its unique identifier.", "parameters": [ { "name": "include", "in": "query", "required": false, "description": "Comma-separated list of related resources to include in the response. Available options: linkedSubscriptions (includes full subscription details for products with linked subscriptions).", "schema": { "type": "string", "enum": [ "linkedSubscriptions" ] }, "example": "linkedSubscriptions" } ], "responses": { "200": { "description": "Product details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" }, "example": { "id": "2e2805a1-738e-4118-8a8b-f9431f0e210c", "name": "Cellar Selection Malbec", "slug": "cellar-selection-malbec-2015", "url": "https://api.marzipan.co/products/cellar-selection-malbec-2015", "description": "Id laboris ad aliqua exercitation dolore. Ad, aliqua exercitation dolore est culpa. Dolore est culpa, nostrud. Nostrud ad sed mollit, fugiat. Mollit fugiat, irure adipiscing ipsum id. Adipiscing ipsum id ea cillum deserunt, ipsum lorem.", "productType": "physical", "sku": "CSMALBC2015", "collections": [ { "id": "885ea507-690b-4598-a8fc-095c0528be24", "name": "Store", "slug": "store", "description": "Store collection" } ], "status": "active", "images": { "product": [ { "id": "0736c529-a33d-4b8c-8126-eb69779dcdad", "path": "1/0736c529-a33d-4b8c-8126-eb69779dcdad.jpg", "src": "https://marzipan-cloud-dev.b-cdn.net/1/0736c529-a33d-4b8c-8126-eb69779dcdad.jpg", "alt": "Cellar Selection Malbec 2015 bottle", "mimeType": "image/jpeg", "filename": "0736c529-a33d-4b8c-8126-eb69779dcdad.jpg" } ], "labels": { "front": [], "back": [] } }, "primaryImage": { "id": "0736c529-a33d-4b8c-8126-eb69779dcdad", "path": "1/0736c529-a33d-4b8c-8126-eb69779dcdad.jpg", "src": "https://marzipan-cloud-dev.b-cdn.net/1/0736c529-a33d-4b8c-8126-eb69779dcdad.jpg", "alt": "Cellar Selection Malbec 2015 bottle", "mimeType": "image/jpeg", "filename": "0736c529-a33d-4b8c-8126-eb69779dcdad.jpg" }, "price": "£24.99", "salePrice": null, "subscriberPrice": null, "createdAt": "2024-02-05T23:22:56.000000Z", "updatedAt": "2024-02-05T23:22:56.000000Z", "storeSlug": "store", "subscriptionsSlug": null, "availability": "all", "upsellProducts": [], "attributes": [], "options": [], "relatedProducts": [], "awards": [], "reviews": [], "metaTitle": "Cellar Selection Malbec 2015", "metaDescription": "Cupidatat quis reprehenderit, exercitation quis cillum nulla do.", "metaImage": null, "storeName": "Wine Collection" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "string" } } } } } } }, "/subscription-packages": { "parameters": [], "get": { "tags": [ "Subscriptions" ], "summary": "Packages", "description": "List all available subscription packages including pricing and subscription type information. Supports filtering and sorting similar to products endpoint.", "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Filter by subscription type (picknmix, variable)", "schema": { "type": "string", "enum": [ "picknmix", "variable" ] } }, { "name": "collection", "in": "query", "required": false, "description": "Filter packages by collection slug or name", "schema": { "type": "string" } }, { "name": "attr", "in": "query", "required": false, "description": "Filter packages by attributes using deep object notation", "schema": { "type": "object", "additionalProperties": { "type": "string" } }, "style": "deepObject", "explode": true }, { "name": "sort", "in": "query", "required": false, "description": "Sort packages by field and direction (e.g., price.asc, name.desc)", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Limit the number of results returned", "schema": { "type": "integer", "minimum": 1 } }, { "name": "page", "in": "query", "required": false, "description": "Page number for pagination", "schema": { "type": "integer", "minimum": 1 } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of items per page", "schema": { "type": "integer", "minimum": 1 } }, { "name": "include", "in": "query", "required": false, "description": "Include additional data. Available: attributes, subscribers", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionPackageCollection" } }, "links": { "type": "object", "properties": { "first": { "type": "string", "format": "uri" }, "last": { "type": "string", "format": "uri", "nullable": true }, "prev": { "type": "string", "format": "uri", "nullable": true }, "next": { "type": "string", "format": "uri", "nullable": true } } }, "meta": { "type": "object", "properties": { "currentPage": { "type": "integer" }, "from": { "type": "integer" }, "path": { "type": "string", "format": "uri" }, "perPage": { "type": "integer" }, "to": { "type": "integer" } } } } }, "example": { "data": [ { "id": "084b80ef-d16d-4531-a25f-40b7ff4c744b", "subscriptionType": "variable", "name": "Discovery Club", "slug": "discovery-club", "subscriptionsSlug": "club", "url": "https://api.marzipan.co/subscription-packages/discovery-club", "description": "Laborum adipiscing, tempor cillum. Cillum exercitation sed officia mollit do dolore. Sed officia mollit do dolore do ex.", "productType": "subscription", "sku": "DISCCLUB", "collection": "Club", "status": "active", "image": { "id": "bc1a0d61-e7f9-44d3-ae53-1475b5f9395d", "path": "1/bc1a0d61-e7f9-44d3-ae53-1475b5f9395d.jpg", "src": "https://marzipan-cloud-dev.b-cdn.net/1/bc1a0d61-e7f9-44d3-ae53-1475b5f9395d.jpg", "alt": "Discovery Club subscription box", "mimeType": "image/jpeg", "filename": "bc1a0d61-e7f9-44d3-ae53-1475b5f9395d.jpg" }, "price": { "value": 0, "formatted": "£0.00", "currency": "GBP" }, "salePrice": null, "createdAt": "2024-02-05T23:22:56.000000Z", "updatedAt": "2024-02-05T23:22:56.000000Z" } ], "links": { "first": "https://api.marzipan.co/v1/subscription-packages?page=1", "last": "https://api.marzipan.co/v1/subscription-packages?page=1", "prev": null, "next": null }, "meta": { "currentPage": 1, "from": 1, "path": "https://api.marzipan.co/v1/subscription-packages", "perPage": 15, "to": 1 } } } } } } } }, "/subscription-packages/{packageId}": { "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "The unique identifier (UUID) or slug for the subscription package", "schema": { "type": "string" }, "examples": { "uuid": { "value": "550e8400-e29b-41d4-a716-446655440000", "description": "Using a UUID" }, "slug": { "value": "discovery-club", "description": "Using a slug" } } } ], "get": { "tags": [ "Subscriptions" ], "summary": "Package", "description": "Get detailed information about a specific subscription package by its unique identifier (UUID) or slug.", "parameters": [ { "name": "include", "in": "query", "required": false, "description": "Include additional data. Available: subscribers", "schema": { "type": "string", "enum": [ "subscribers" ] } } ], "responses": { "200": { "description": "Subscription package details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPackage" }, "example": { "id": "084b80ef-d16d-4531-a25f-40b7ff4c744b", "subscriptionType": "variable", "name": "Discovery Club", "slug": "discovery-club", "sku": "DISCCLUB", "url": "https://api.marzipan.co/subscription-packages/discovery-club", "status": "active", "availability": "all", "productType": "subscription", "description": "Laborum adipiscing, tempor cillum. Cillum exercitation sed officia mollit do dolore. Sed officia mollit do dolore do ex officia mollit. Mollit irure adipiscing ipsum id lorem sunt. Ipsum id lorem sunt dolore magna aliqua.", "metaTitle": "Discovery Club - Premium Wine Subscription", "metaDescription": "Join our Discovery Club and explore exceptional wines delivered monthly to your door.", "collections": [ { "id": "46759fdd-1b5b-4339-a175-af0569c1ca73", "name": "Club", "slug": "club", "description": "Club products" } ], "images": [ { "id": "bc1a0d61-e7f9-44d3-ae53-1475b5f9395d", "path": "1/bc1a0d61-e7f9-44d3-ae53-1475b5f9395d.jpg", "src": "https://marzipan-cloud-dev.b-cdn.net/1/bc1a0d61-e7f9-44d3-ae53-1475b5f9395d.jpg", "alt": "Discovery Club subscription box", "mimeType": "image/jpeg", "filename": "bc1a0d61-e7f9-44d3-ae53-1475b5f9395d.jpg" } ], "primaryImage": { "id": "bc1a0d61-e7f9-44d3-ae53-1475b5f9395d", "path": "1/bc1a0d61-e7f9-44d3-ae53-1475b5f9395d.jpg", "src": "https://marzipan-cloud-dev.b-cdn.net/1/bc1a0d61-e7f9-44d3-ae53-1475b5f9395d.jpg", "alt": "Discovery Club subscription box", "mimeType": "image/jpeg", "filename": "bc1a0d61-e7f9-44d3-ae53-1475b5f9395d.jpg" }, "price": { "value": 0, "formatted": "£0.00", "currency": "GBP" }, "salePrice": null, "billingFrequency": 6, "billingFrequencies": [ 1, 3, 6, 12 ], "pricingType": "per_item", "autoRenew": true, "minimumItems": 2, "availableItems": [ { "itemId": "2e2805a1-738e-4118-8a8b-f9431f0e210c", "itemName": "Cellar Selection Malbec", "itemSku": "CSMALBC2015", "itemDescription": "Premium Malbec with rich, full-bodied flavor profile", "minQty": 1, "maxQty": 3, "defaultQty": 1, "sortOrder": 1, "status": "active" }, { "itemId": "df0d13db-1332-4461-b3d1-b2774d47ff5f", "itemName": "Chardonnay", "itemSku": "CHARD2015", "itemDescription": "Elegant white wine with crisp citrus notes", "minQty": 1, "maxQty": 2, "defaultQty": 1, "sortOrder": 2, "status": "active" } ], "attributes": [], "options": [], "relatedProducts": [] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "string" } } } } } } }, "/subscriptions/renew": { "parameters": [], "post": { "tags": [ "Subscriptions" ], "x-excluded": true, "summary": "Renew", "description": "Renew an existing subscription using a renewal token and signature. Used for subscription extensions and renewals.", "parameters": [], "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "string" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "renewal": { "type": "string" }, "expires": { "type": "string", "format": "utc-millisec" }, "signature": { "type": "string" } } } } } } } }, "/search": { "parameters": [], "get": { "tags": [ "Search" ], "summary": "Search", "description": "Search across products, pages, and other content using a query string. Returns relevant results based on the search term.", "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search term to find matching content", "schema": { "type": "string", "minLength": 1 }, "example": "malbec" }, { "name": "type", "in": "query", "required": false, "description": "Filter results by content type. If not specified, searches all types", "schema": { "type": "string", "enum": [ "products", "pages", "collections", "events", "subscription_packages" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results to return per type", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "The search query that was executed" }, "totalResults": { "type": "integer", "description": "Total number of results found across all types" }, "results": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" }, "description": "Product search results" }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" }, "description": "Page search results" }, "collections": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" }, "description": "Collection search results" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" }, "description": "Event search results" }, "subscriptionPackages": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" }, "description": "Subscription package search results" } }, "description": "Search results organized by content type" } } }, "example": { "query": "malbec", "totalResults": 3, "results": { "products": [ { "id": "2e2805a1-738e-4118-8a8b-f9431f0e210c", "type": "product", "title": "Cellar Selection Malbec", "slug": "cellar-selection-malbec-2015", "url": "https://api.marzipan.co/products/cellar-selection-malbec-2015", "excerpt": "Premium Malbec with rich, full-bodied flavor profile and notes of dark fruit", "image": { "id": "0736c529-a33d-4b8c-8126-eb69779dcdad", "path": "1/0736c529-a33d-4b8c-8126-eb69779dcdad.jpg", "src": "https://marzipan-cloud-dev.b-cdn.net/1/0736c529-a33d-4b8c-8126-eb69779dcdad.jpg", "alt": "Cellar Selection Malbec 2015 bottle", "mimeType": "image/jpeg", "filename": "0736c529-a33d-4b8c-8126-eb69779dcdad.jpg" }, "price": "£24.99", "status": "active" } ], "pages": [ { "id": "page-wine-guide", "type": "page", "title": "Malbec Wine Guide", "slug": "malbec-wine-guide", "url": "https://api.marzipan.co/pages/malbec-wine-guide", "excerpt": "Learn about Malbec wines, their origins, flavor profiles, and perfect food pairings", "image": null, "price": null, "status": "published" } ], "collections": [ { "id": "885ea507-690b-4598-a8fc-095c0528be24", "type": "collection", "title": "Red Wine Collection", "slug": "red-wines", "url": "https://api.marzipan.co/collections/red-wines", "excerpt": "Our carefully curated selection of premium red wines including Malbec, Cabernet, and more", "image": { "id": "1b978a90-3ecb-4f37-b480-9fb81882176e", "src": "https://marzipan-cloud-dev.b-cdn.net/1/1b978a90-3ecb-4f37-b480-9fb81882176e.jpg", "alt": "Red wine collection" }, "price": null, "status": "active" } ], "events": [], "subscriptionPackages": [] } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "string" } } } } } } }, "/settings": { "get": { "tags": [ "Settings" ], "summary": "Storefront settings", "description": "Retrieve the storefront settings payload used to configure the web components and checkout, including the store name, logo, available markets and the market resolved for the current request.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontSettings" }, "example": { "name": "Marzipan Bakery", "storeUrl": "https://shop.marzipan.co", "logo": "https://cdn.marzipan.co/media/logo.png", "defaultCurrency": "GBP", "markets": [ { "id": "9b1c2d3e-4f5a-6b7c-8d9e-0a1b2c3d4e5f", "name": "United Kingdom", "currencyCode": "GBP", "currencySymbol": "£", "isPrimary": true }, { "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "name": "Eurozone", "currencyCode": "EUR", "currencySymbol": "€", "isPrimary": false } ], "currentMarket": { "id": "9b1c2d3e-4f5a-6b7c-8d9e-0a1b2c3d4e5f", "name": "United Kingdom", "currencyCode": "GBP", "currencySymbol": "£", "isPrimary": true } } } } } } } }, "/market": { "get": { "tags": [ "Settings" ], "summary": "Detect market", "description": "Detect the visitor's market and currency/region from their geolocation. Returns a null market and the detected country code when no market could be resolved.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketDetection" }, "example": { "market": { "id": "9b1c2d3e-4f5a-6b7c-8d9e-0a1b2c3d4e5f", "name": "United Kingdom", "currencyCode": "GBP", "currencySymbol": "£", "isPrimary": true }, "detectedCountry": "GB" } } } } } } }, "/settings/components": { "get": { "tags": [ "Settings" ], "summary": "Web component settings", "description": "Retrieve the web-components display settings for the storefront, grouped into layout, labels, collection, product, checkout, cart, product display, account and tracking option groups.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebComponentSettings" }, "example": { "cssVariables": { "--mz-primary-color": "#111827", "--mz-radius": "0.5rem" }, "layout": { "collectionColumnsMobile": 2, "collectionColumnsTablet": 3, "collectionColumnsDesktop": 4, "logoPosition": "left", "logoHeight": "3rem", "productCardStyle": "minimal", "productCardAlignment": "center", "productImageRadius": "0.5rem" }, "labels": { "subscriberPriceLabel": "Subscriber price", "saleBadgeText": "Sale", "subscriberBadgeText": null, "addToCartText": "Add to cart", "bundleText": null, "waitlistText": null, "salesClosedText": "Tickets no longer available", "showMoreText": null, "backInStockText": "Notify me when available" }, "collection": { "columnsMobile": 2, "columnsTablet": 3, "columnsDesktop": 4, "productCardStyle": "minimal", "productCardAlignment": "center", "productImageRadius": "0.5rem", "showQuantity": false, "showMoreLink": null, "showDescription": null, "showSubscriberPricing": null, "redirectToCart": false }, "product": { "backInStockEnabled": true, "showSubscriberPricing": null, "showQuantity": null, "redirectToCart": false }, "checkout": { "logoPosition": "left", "logoHeight": "3rem", "phoneRequired": false, "referralSources": { "enabled": true, "allowOther": true, "options": [ { "label": "Instagram", "followUp": null }, { "label": "Friend", "followUp": "Who referred you?" } ] } }, "cart": { "relatedProductsEnabled": true, "relatedProductsCount": 4, "relatedProductsTitle": "You may also like", "freeShippingNotificationEnabled": true, "freeShippingMessages": { "qualified": "You've unlocked free shipping!" }, "freeShippingThresholds": { "9b1c2d3e-4f5a-6b7c-8d9e-0a1b2c3d4e5f": 5000 }, "backgroundEnabled": false, "backgroundColor": "#ffffff", "borderEnabled": false, "borderColor": "#e5e7eb" }, "productDisplay": { "quickAttributes": { "enabled": true, "maxCount": 4, "maxLength": 30, "attributeNames": [ "Weight", "Origin" ] }, "accordion": { "enabled": true, "sections": [ { "id": "ingredients", "title": "Ingredients", "type": "attribute", "enabled": true, "attributeNames": [], "attributeName": "ingredients", "textContent": null, "defaultOpen": false } ] }, "sections": [ { "id": "reviews", "enabled": true }, { "id": "awards", "enabled": true }, { "id": "press", "enabled": true } ], "thumbnailPosition": "side", "showImageOverlay": true, "billingFrequencyStyle": "worded", "events": { "defaultView": "list", "occurrenceCount": 14 } }, "account": { "subscriptionUpsell": { "enabled": false, "collectionId": null, "heading": null, "message": null, "columns": { "mobile": 1, "tablet": 2, "desktop": 3 } } }, "tracking": { "fathomSiteId": "ABCDEFGH" } } } } } } } }, "/visits": { "post": { "tags": [ "Analytics" ], "summary": "Record a visit", "description": "Record a storefront visit for attribution and analytics. At least one UTM parameter is required, and the endpoint is throttled. Returns the stored visit id and the session id used for touchpoint tracking.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "utmSource": { "type": "string", "maxLength": 255, "nullable": true }, "utmMedium": { "type": "string", "maxLength": 255, "nullable": true }, "utmCampaign": { "type": "string", "maxLength": 255, "nullable": true }, "utmTerm": { "type": "string", "maxLength": 255, "nullable": true }, "utmContent": { "type": "string", "maxLength": 255, "nullable": true }, "landingPage": { "type": "string", "maxLength": 2048, "nullable": true }, "referrer": { "type": "string", "maxLength": 2048, "nullable": true }, "sessionId": { "type": "string", "maxLength": 64, "nullable": true, "description": "Existing session id to continue touchpoint tracking; a new one is generated when omitted." } } }, "example": { "utmSource": "instagram", "utmMedium": "social", "utmCampaign": "summer-sale", "landingPage": "https://shop.marzipan.co/collections/cakes", "referrer": "https://instagram.com", "sessionId": "s_a1b2c3d4e5f6" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Visit" }, "example": { "id": "7f3d9c1a-2b4e-4c6d-8e0f-1a2b3c4d5e6f", "sessionId": "s_a1b2c3d4e5f6" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/account/addresses": { "parameters": [], "get": { "tags": [ "Account" ], "summary": "List addresses", "description": "Retrieve all saved delivery addresses belonging to the authenticated customer, ordered by creation date.", "security": [ { "accountAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Address" } }, "example": [ { "id": "9c1f7b2e-3d4a-4c1b-8f2a-1a2b3c4d5e6f", "firstName": "Jane", "lastName": "Doe", "addressLine1": "12 Baker Street", "addressLine2": "Flat 2", "city": "London", "state": "Greater London", "county": "Greater London", "postcode": "W1U 6TU", "countryName": "United Kingdom", "country": "GB", "type": "shipping", "defaultAddress": true, "deliveryInstructions": "Leave with the neighbour", "phone": "+447700900123" } ] } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } } } }, "post": { "tags": [ "Account" ], "summary": "Create address", "description": "Add a new delivery address to the authenticated customer's account. Returns the full updated list of addresses.", "security": [ { "accountAuth": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressInput" }, "example": { "firstName": "Jane", "lastName": "Doe", "addressLine1": "12 Baker Street", "addressLine2": "Flat 2", "city": "London", "state": "Greater London", "postcode": "W1U 6TU", "country": "GB", "phone": "+447700900123", "defaultAddress": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Address" } }, "example": [ { "id": "9c1f7b2e-3d4a-4c1b-8f2a-1a2b3c4d5e6f", "firstName": "Jane", "lastName": "Doe", "addressLine1": "12 Baker Street", "addressLine2": "Flat 2", "city": "London", "state": "Greater London", "county": "Greater London", "postcode": "W1U 6TU", "countryName": "United Kingdom", "country": "GB", "type": "shipping", "defaultAddress": true, "deliveryInstructions": null, "phone": "+447700900123" } ] } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "The first name field is required.", "errors": { "firstName": [ "The first name field is required." ] } } } } } } } }, "/account/addresses/{address}": { "parameters": [ { "name": "address", "in": "path", "required": true, "description": "The address ID", "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Account" ], "summary": "Get address", "description": "Retrieve a single saved address by its ID for the authenticated customer.", "security": [ { "accountAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Address" }, "example": { "id": "9c1f7b2e-3d4a-4c1b-8f2a-1a2b3c4d5e6f", "firstName": "Jane", "lastName": "Doe", "addressLine1": "12 Baker Street", "addressLine2": "Flat 2", "city": "London", "state": "Greater London", "county": "Greater London", "postcode": "W1U 6TU", "countryName": "United Kingdom", "country": "GB", "type": "shipping", "defaultAddress": true, "deliveryInstructions": null, "phone": "+447700900123" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } }, "404": { "description": "Address not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "No query results for model." } } } } } }, "put": { "tags": [ "Account" ], "summary": "Update address", "description": "Update an existing address belonging to the authenticated customer. Returns the full updated list of addresses.", "security": [ { "accountAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressInput" }, "example": { "firstName": "Jane", "lastName": "Doe", "addressLine1": "12 Baker Street", "addressLine2": "Flat 2", "city": "London", "state": "Greater London", "postcode": "W1U 6TU", "country": "GB", "phone": "+447700900123", "defaultAddress": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Address" } }, "example": [ { "id": "9c1f7b2e-3d4a-4c1b-8f2a-1a2b3c4d5e6f", "firstName": "Jane", "lastName": "Doe", "addressLine1": "12 Baker Street", "addressLine2": "Flat 2", "city": "London", "state": "Greater London", "county": "Greater London", "postcode": "W1U 6TU", "countryName": "United Kingdom", "country": "GB", "type": "shipping", "defaultAddress": true, "deliveryInstructions": null, "phone": "+447700900123" } ] } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } }, "404": { "description": "Address not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "No query results for model." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "The postcode field is required.", "errors": { "postcode": [ "The postcode field is required." ] } } } } } } }, "delete": { "tags": [ "Account" ], "summary": "Delete address", "description": "Remove a saved address belonging to the authenticated customer.", "security": [ { "accountAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "Address deleted" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } }, "404": { "description": "Address not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "No query results for model." } } } } } } }, "/account/orders/{orderId}": { "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "The public order reference (order_id)", "schema": { "type": "string" } } ], "get": { "tags": [ "Account" ], "summary": "Get order", "description": "Retrieve the full detail of a single order belonging to the authenticated customer, including items, addresses, payment and tracking information.", "security": [ { "accountAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDetail" }, "example": { "id": "73d5c504-adbb-43ac-891e-9b3dd4900de4", "ref": "1010744", "email": "jane@example.com", "currencyCode": "GBP", "items": [ { "id": "1f2e3d4c-5b6a-7980-a1b2-c3d4e5f60718", "name": "Sea Salt Caramels", "price": "£9.99", "quantity": 2, "lineTotal": "£19.98", "options": [], "bundledItems": [], "type": "physical", "sku": "SSC-100", "image": null } ], "subtotal": "£19.98", "shipping": "£3.50", "tax": "£0.00", "discount": null, "discountCodes": "", "pointsRedeemed": 0, "pointsDiscount": null, "total": "£23.48", "totalRaw": 2348, "status": "processing", "paymentMethod": null, "paymentStatus": "paid", "shippingAddress": { "firstName": "Jane", "lastName": "Doe", "addressLine1": "12 Baker Street", "addressLine2": "Flat 2", "city": "London", "county": "Greater London", "postcode": "W1U 6TU", "country": "United Kingdom", "countryCode": "GB" }, "billingAddress": { "firstName": "Jane", "lastName": "Doe", "addressLine1": "12 Baker Street", "addressLine2": "Flat 2", "city": "London", "county": "Greater London", "postcode": "W1U 6TU", "country": "United Kingdom", "countryCode": "GB", "phone": "+447700900123", "email": "jane@example.com" }, "shippingMethod": "Standard Delivery", "tracking": null, "deliveryInstructions": null, "giftMessage": null, "createdAt": "08/06/2024", "updatedAt": "08/06/2024", "paymentProviders": {} } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } }, "404": { "description": "Order not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Order not found" } } } } } } }, "/account/orders/{orderId}/createPaymentIntent": { "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "The internal order ID", "schema": { "type": "string", "format": "uuid" } } ], "post": { "tags": [ "Account" ], "summary": "Create payment intent for order", "description": "Create a Stripe payment intent so the authenticated customer can pay an outstanding (unpaid) order. Returns the client secrets needed to confirm payment.", "security": [ { "accountAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentIntentId": { "type": "string" }, "clientSecret": { "type": "string" }, "customerSessionSecret": { "type": "string" } } }, "example": { "paymentIntentId": "pi_3QabcDEF1234567890", "clientSecret": "pi_3QabcDEF1234567890_secret_XyZ", "customerSessionSecret": "cuss_1QabcDEF_secret_AbC" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } }, "404": { "description": "Order not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Order not found" } } } } } } }, "/account/orders/{orderId}/buy-again": { "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "The public order reference (order_id)", "schema": { "type": "string" } } ], "post": { "tags": [ "Account" ], "summary": "Buy again", "description": "Add the reorderable items from a previous order back into the authenticated customer's cart. Subscription and balance-payment line items are excluded.", "security": [ { "accountAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "cartId": { "type": "string", "format": "uuid" }, "itemsAdded": { "type": "integer" }, "itemsSkipped": { "type": "integer" }, "skippedReasons": { "type": "array", "items": { "type": "string" } }, "redirectUrl": { "type": "string" }, "cart": { "type": "object", "description": "The updated cart resource" } } }, "example": { "success": true, "cartId": "b2c3d4e5-6f70-8192-a3b4-c5d6e7f80912", "itemsAdded": 2, "itemsSkipped": 1, "skippedReasons": [ "'Limited Edition Truffles' is no longer available" ], "redirectUrl": "/cart", "cart": {} } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } }, "404": { "description": "Order not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Order not found" } } } }, "422": { "description": "No items could be reordered", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "itemsAdded": { "type": "integer" }, "itemsSkipped": { "type": "integer" } } }, "example": { "success": false, "message": "No items from this order can be reordered.", "itemsAdded": 0, "itemsSkipped": 2 } } } } } } }, "/account/payments/methods": { "parameters": [], "get": { "tags": [ "Account" ], "summary": "List payment methods", "description": "Retrieve the saved (non-wallet) payment methods for the authenticated customer.", "security": [ { "accountAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethod" } }, "example": [ { "id": "a1b2c3d4-e5f6-7890-a1b2-c3d4e5f60718", "provider": "stripe", "paymentMethod": "card", "providerId": "pm_1QabcDEF1234567890", "cardType": "visa", "cardLast4": "4242", "cardExpMonth": 12, "cardExpYear": 2028, "default": true } ] } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } } } } }, "/account/payments/createSetupIntent": { "parameters": [], "post": { "tags": [ "Account" ], "summary": "Create setup intent", "description": "Create a Stripe setup intent so the authenticated customer can securely save a new card for future payments.", "security": [ { "accountAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "clientSecret": { "type": "string" }, "customerSessionSecret": { "type": "string" } } }, "example": { "clientSecret": "seti_1QabcDEF_secret_XyZ", "customerSessionSecret": "cuss_1QabcDEF_secret_AbC" } } } }, "400": { "description": "Customer not found or missing Stripe ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } }, "example": { "error": "Customer not found or missing Stripe ID" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } } } } }, "/account/payments/addPaymentMethod": { "parameters": [], "post": { "tags": [ "Account" ], "summary": "Add payment method", "description": "Save a Stripe payment method to the authenticated customer's account after it has been collected client-side.", "security": [ { "accountAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "provider", "paymentMethod", "paymentMethodId" ], "properties": { "provider": { "type": "string", "example": "stripe" }, "paymentMethod": { "type": "string", "example": "card" }, "paymentMethodId": { "type": "string", "example": "pm_1QabcDEF1234567890" } } }, "example": { "provider": "stripe", "paymentMethod": "card", "paymentMethodId": "pm_1QabcDEF1234567890" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "customerPaymentId": { "type": "string", "format": "uuid" } } }, "example": { "customerPaymentId": "a1b2c3d4-e5f6-7890-a1b2-c3d4e5f60718" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "The payment method id field is required.", "errors": { "paymentMethodId": [ "The payment method id field is required." ] } } } } } } } }, "/account/payments/payfast/setup": { "parameters": [], "post": { "tags": [ "Account" ], "summary": "Create PayFast setup identifier", "description": "Generate a PayFast tokenization identifier so the authenticated customer can save a payment method, optionally linked to a subscription.", "security": [ { "accountAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptionId": { "type": "string", "format": "uuid", "description": "Optional subscription to link the new payment method to" } } }, "example": { "subscriptionId": "c3d4e5f6-7890-a1b2-c3d4-e5f607182930" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "identifier": { "type": "string" }, "engineUrl": { "type": "string" } } }, "example": { "identifier": "b1234567-89ab-cdef-0123-456789abcdef", "engineUrl": "https://sandbox.payfast.co.za/onsite/engine.js" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } }, "404": { "description": "Subscription not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } }, "example": { "error": "Subscription not found" } } } } } } }, "/account/countries": { "parameters": [], "get": { "tags": [ "Account" ], "summary": "List countries", "description": "Retrieve the list of countries as a map of ISO country code to country name. Optional query flags return grouped or full-detail variants.", "security": [ { "accountAuth": [] } ], "parameters": [ { "name": "grouped", "in": "query", "required": false, "description": "Return countries grouped by continent", "schema": { "type": "boolean" } }, { "name": "fullList", "in": "query", "required": false, "description": "Return the full country dataset instead of code/name pairs", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "countries": { "type": "object", "additionalProperties": { "type": "string" } } } }, "example": { "countries": { "GB": "United Kingdom", "ZA": "South Africa", "US": "United States" } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } } } } }, "/account/pickup-locations": { "parameters": [], "get": { "tags": [ "Account" ], "summary": "List pickup locations", "description": "Retrieve the active pickup shipping methods (collection points) available to the authenticated customer.", "security": [ { "accountAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PickupLocation" } } } }, "example": { "data": [ { "id": "d4e5f607-1829-30a1-b2c3-d4e5f6071829", "name": "London Warehouse", "description": "Collect in person from our London warehouse", "method": "pickup", "amount": "£0.00", "countries": [], "countryCount": 0, "remainingCountries": [], "countriesWithZones": null, "status": true } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } } } } }, "/account/reset-password": { "parameters": [], "post": { "tags": [ "Account" ], "summary": "Change password", "description": "Change the authenticated customer's password by confirming their current password. Used from the logged-in account area.", "security": [ { "accountAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "currentPassword", "password", "passwordConfirmation" ], "properties": { "currentPassword": { "type": "string", "format": "password" }, "password": { "type": "string", "format": "password", "description": "Minimum 8 characters, must include an uppercase letter, a lowercase letter and a number" }, "passwordConfirmation": { "type": "string", "format": "password" } } }, "example": { "currentPassword": "OldPass123", "password": "NewPass456", "passwordConfirmation": "NewPass456" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" } } }, "example": { "status": true } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "Please enter your current password.", "errors": { "currentPassword": [ "Please enter your current password." ] } } } } } } } }, "/account/verify-email": { "parameters": [], "post": { "tags": [ "Account" ], "summary": "Verify email", "description": "Verify the authenticated customer's email address using the verification code sent to their inbox.", "security": [ { "accountAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "description": "The 6-digit verification code emailed to the customer" } } }, "example": { "code": "482913" } } } }, "responses": { "204": { "description": "Email verified successfully" }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } }, "422": { "description": "Invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Invalid token" } } } } } } }, "/account/password/reset": { "parameters": [], "post": { "tags": [ "Account" ], "summary": "Set new password from reset token", "description": "Set a new password using the token from a password reset email. This is a public endpoint used before the customer is logged in.", "security": [ { "tenantAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token", "email", "password", "passwordConfirmation" ], "properties": { "token": { "type": "string", "description": "The password reset token from the emailed link" }, "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password", "description": "Minimum 8 characters, must include an uppercase letter, a lowercase letter and a number" }, "passwordConfirmation": { "type": "string", "format": "password" } } }, "example": { "token": "a1b2c3d4e5f6", "email": "jane@example.com", "password": "NewPass456", "passwordConfirmation": "NewPass456" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } }, "example": { "status": "Your password has been reset." } } } }, "422": { "description": "Invalid or expired token, or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "This password reset token has expired. Please request a new password reset link.", "errors": { "email": [ "The email field is required." ] } } } } } } } }, "/account/subscriptions/{subscriptionId}": { "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Subscription ID" } ], "get": { "tags": [ "Subscriptions" ], "summary": "Get a subscription", "description": "Retrieve full detail for one of the authenticated customer's subscriptions, including pick & mix items, upcoming shipments, additional items, billing period, preferred shipping options, payment method and any failed-renewal information.", "security": [ { "accountAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountSubscription" }, "example": { "id": "1224f9ef-8caf-4564-9474-023f95819949", "subscriptionType": "picknmix", "email": "customer@example.com", "name": "Discovery Club", "quantity": 1, "status": "active", "createdAt": "07/10/2024", "options": {}, "availableItems": [ { "id": "084b80ef-d16d-4531-a25f-40b7ff4c744b", "name": "House Red", "sku": "WINE-RED-01", "defaultQty": 1, "minQty": 0, "maxQty": 6, "sortOrder": 1, "price": "£9.99", "status": "active", "image": { "url": "https://cdn.marzipan.co/images/house-red.jpg" } } ], "pickAndMixItems": [ { "id": "084b80ef-d16d-4531-a25f-40b7ff4c744b", "name": "House Red", "sku": "WINE-RED-01", "quantity": 2, "image": { "url": "https://cdn.marzipan.co/images/house-red.jpg" } } ], "batchedShipments": false, "upcomingShipments": [ { "id": "c2b0f3d1-1111-2222-3333-444455556666", "name": "January Shipment", "items": [], "status": "scheduled", "nextBillingDate": null, "processingDate": "01/02/2026", "shippingDate": "03/02/2026", "deliveryDate": "04/02/2026" } ], "currentPeriodStart": "07/10/2025", "currentPeriodEnd": "07/01/2026", "expiresAt": "07/10/2030", "billingInterval": 3, "billingIntervalFriendly": "every 3 months", "nextBillingDate": "07/01/2026", "upcomingAdditionalItems": [], "hasProcessingShipment": false, "price": { "friendly": "£9.99", "raw": 9.99 }, "preferredDeliveryOption": "delivery", "preferredDeliveryAddress": { "id": "aa11bb22-cc33-dd44-ee55-ff6677889900", "line1": "1 High Street", "city": "London", "postcode": "SW1A 1AA" }, "defaultPaymentMethod": { "cardType": "visa", "cardLast4": "4242", "cardExpMonth": 12, "cardExpYear": 2028 }, "paymentProvider": "stripe", "paymentProviders": { "stripe": { "publishableKey": "pk_live_xxx", "accountId": "acct_xxx", "currency": "gbp" } } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Subscription not found" } } } } } } }, "/account/subscriptions/upsell": { "parameters": [], "get": { "tags": [ "Subscriptions" ], "summary": "Get subscription upsell", "description": "Return the configured subscription upsell content shown to customers who have no subscriptions. Includes the promotional heading and message and the slug of the collection of products to promote, if enabled.", "security": [ { "accountAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether subscription upsell is enabled for the tenant" }, "heading": { "type": "string", "nullable": true, "description": "Upsell heading" }, "message": { "type": "string", "nullable": true, "description": "Upsell message" }, "collection": { "type": "string", "nullable": true, "description": "Slug of the collection to promote, or null if none configured" }, "columns": { "type": "integer", "description": "Number of columns to display the collection in. Only present when a collection is configured" } } }, "example": { "enabled": true, "heading": "Join a club", "message": "Get hand-picked bottles delivered every month.", "collection": "subscription-boxes", "columns": 3 } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } } } } }, "/account/subscriptions/frequencies": { "parameters": [], "get": { "tags": [ "Subscriptions" ], "summary": "List billing frequencies", "description": "Return the billing frequencies available for subscriptions, keyed by the number of months in the interval with a human-friendly label.", "security": [ { "accountAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "frequencies": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Map of billing interval (in months) to friendly label" } } }, "example": { "frequencies": { "1": "every month", "3": "every 3 months", "6": "every 6 months", "12": "every 12 months" } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } } } } }, "/account/subscriptions/{subscriptionId}/frequency": { "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Subscription ID" } ], "patch": { "tags": [ "Subscriptions" ], "summary": "Update billing frequency", "description": "Update the billing frequency of a subscription. The frequency must be one of the supported intervals (1, 3, 6 or 12 months).", "security": [ { "accountAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "billingFrequency" ], "properties": { "billingFrequency": { "type": "integer", "enum": [ 1, 3, 6, 12 ], "description": "New billing interval in months" } } }, "example": { "billingFrequency": 6 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "subscription": { "type": "object", "description": "The updated subscription record" }, "effectiveBillingInterval": { "type": "integer", "description": "Effective billing interval in months after the update" }, "billingIntervalFriendly": { "type": "string", "description": "Human-friendly description of the billing interval" } } }, "example": { "message": "Billing frequency updated successfully", "subscription": { "id": "1224f9ef-8caf-4564-9474-023f95819949", "billingInterval": 6, "status": "active" }, "effectiveBillingInterval": 6, "billingIntervalFriendly": "every 6 months" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Subscription not found" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/account/subscriptions/{subscriptionId}/pick-mix-items": { "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Subscription ID" } ], "post": { "tags": [ "Subscriptions" ], "summary": "Set pick & mix items", "description": "Replace the pick & mix items on a subscription. Enforces each item's minimum and maximum quantity and the package's minimum item count. Optionally updates the billing frequency at the same time.", "security": [ { "accountAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "description": "Selected pick & mix items", "items": { "type": "object", "required": [ "id", "quantity", "name", "sku" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Product ID of the item" }, "quantity": { "type": "integer", "minimum": 0, "description": "Quantity selected" }, "name": { "type": "string", "description": "Item name" }, "sku": { "type": "string", "description": "Item SKU" }, "price": { "type": "number", "nullable": true, "description": "Optional item price" } } } }, "billingFrequency": { "type": "integer", "nullable": true, "enum": [ 1, 3, 6, 12 ], "description": "Optionally update the billing interval in months" } } }, "example": { "items": [ { "id": "084b80ef-d16d-4531-a25f-40b7ff4c744b", "quantity": 2, "name": "House Red", "sku": "WINE-RED-01", "price": 9.99 } ], "billingFrequency": 3 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "subscription": { "type": "object", "description": "The updated subscription including its pick & mix items" } } }, "example": { "message": "Pick and mix items updated successfully", "subscription": { "id": "1224f9ef-8caf-4564-9474-023f95819949", "pickAndMixItems": [ { "itemId": "084b80ef-d16d-4531-a25f-40b7ff4c744b", "itemName": "House Red", "itemSku": "WINE-RED-01", "qty": 2 } ] } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Subscription not found" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/account/subscriptions/{subscriptionId}/additional-items": { "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Subscription ID" } ], "post": { "tags": [ "Subscriptions" ], "summary": "Set additional items", "description": "Add or replace additional one-off items on the subscription's next shipment. Sending an empty items array removes the additional items (for the given shipment if a shipment_id is supplied). Additional items cannot be changed while the next shipment is being processed.", "security": [ { "accountAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "Additional items. An empty array clears existing additional items", "items": { "type": "object", "required": [ "id", "quantity" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Product ID of the additional item" }, "quantity": { "type": "number", "minimum": 0, "description": "Quantity of the item" } } } }, "shipmentId": { "type": "string", "format": "uuid", "nullable": true, "description": "Optional shipment to scope the additional items to" } } }, "example": { "items": [ { "id": "084b80ef-d16d-4531-a25f-40b7ff4c744b", "quantity": 1 } ], "shipmentId": null } } } }, "responses": { "201": { "description": "Additional items updated", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Subscription not found" } } } }, "422": { "description": "Validation error, or the next shipment is being processed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "Your next shipment is being processed — additional items can't be changed until it's completed." } } } } } } }, "/account/subscriptions/{subscriptionId}/updatePaymentMethod": { "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Subscription ID" } ], "post": { "tags": [ "Subscriptions" ], "summary": "Update payment method", "description": "Set the default payment method for the subscription. The payment method is looked up from Stripe using the supplied payment method ID and stored against the customer.", "security": [ { "accountAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "paymentMethodId" ], "properties": { "paymentMethodId": { "type": "string", "description": "Stripe payment method identifier" } } }, "example": { "paymentMethodId": "pm_1QabcXYZ" } } } }, "responses": { "201": { "description": "Payment method updated", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Subscription not found" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/account/subscriptions/{subscriptionId}/skip": { "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Subscription ID" } ], "post": { "tags": [ "Subscriptions" ], "summary": "Skip next shipment", "description": "Skip the next shipment or renewal for the subscription. Advances the next billing date by one cycle and clears any additional items on the skipped shipment. An optional comment can be recorded.", "security": [ { "accountAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "comments": { "type": "string", "nullable": true, "description": "Optional reason for skipping" } } }, "example": { "comments": "Away on holiday" } } } }, "responses": { "200": { "description": "Shipment skipped", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "Shipment successfully skipped" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Subscription not found" } } } } } } }, "/account/subscriptions/{subscriptionId}/cancel": { "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Subscription ID" } ], "post": { "tags": [ "Subscriptions" ], "summary": "Cancel subscription", "description": "Cancel the subscription at the customer's request. Sets the status to cancelled, clears the next billing date and records the cancellation.", "security": [ { "accountAuth": [] } ], "responses": { "201": { "description": "Subscription cancelled", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Subscription not found" } } } } } } }, "/account/subscriptions/{subscriptionId}/shipping": { "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Subscription ID" } ], "post": { "tags": [ "Subscriptions" ], "summary": "Update shipping options", "description": "Update the preferred shipping option for the subscription. Choose delivery (with a saved customer address) or pickup (with a shipping method / pickup location).", "security": [ { "accountAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "shippingOption" ], "properties": { "shippingOption": { "type": "string", "enum": [ "pickup", "delivery" ], "description": "Preferred shipping option" }, "shippingAddress": { "type": "string", "format": "uuid", "nullable": true, "description": "Customer address ID. Required when shipping_option is delivery" }, "pickupLocation": { "type": "string", "format": "uuid", "nullable": true, "description": "Shipping method / pickup location ID. Required when shipping_option is pickup" } } }, "example": { "shippingOption": "delivery", "shippingAddress": "aa11bb22-cc33-dd44-ee55-ff6677889900", "pickupLocation": null } } } }, "responses": { "201": { "description": "Shipping options updated", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Subscription not found" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/account/rewards/status": { "parameters": [], "get": { "tags": [ "Rewards" ], "summary": "Rewards status", "description": "Get the authenticated customer's current rewards status, including points balance, current and next tier, progress and redemption information. When the rewards programme is disabled for the tenant, only `enabled: false` is returned.\n\nNote: `/account/membership/*` is a deprecated alias of `/account/rewards/*` and maps to the same endpoints; use `/account/rewards/*` for new integrations.", "security": [ { "accountAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RewardStatus" } } }, "example": { "data": { "enabled": true, "subscribersOnly": false, "subscribersOnlyMessage": null, "subscribersOnlyButtonText": null, "subscriptionsUrl": null, "isSubscriber": true, "points": 320, "currentTier": { "id": "3f0d5a2c-1111-2222-3333-444455556666", "name": "Silver", "slug": "silver", "description": "Silver tier members", "badgeColor": "#C0C0C0", "badgeIcon": "star", "pointsThreshold": 100 }, "totalPoints": 320, "lifetimePoints": 540, "nextTier": { "id": "7a1e9b3d-7777-8888-9999-000011112222", "name": "Gold", "slug": "gold", "badgeColor": "#FFD700", "pointsThreshold": 750, "pointsNeeded": 210, "progressPercent": 72 }, "redemption": { "enabled": true, "rate": 100, "rateDescription": "100 points = £1", "currencyCode": "GBP" } } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } } } } }, "/account/rewards/points-history": { "parameters": [], "get": { "tags": [ "Rewards" ], "summary": "Points history", "description": "Get the authenticated customer's paginated points transaction history, most recent first. When the rewards programme is disabled for the tenant, only `enabled: false` is returned.", "security": [ { "accountAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/RewardTransaction" } }, "meta": { "type": "object", "properties": { "currentPage": { "type": "integer" }, "lastPage": { "type": "integer" }, "perPage": { "type": "integer" }, "total": { "type": "integer" } } } } }, "example": { "enabled": true, "data": [ { "id": "b1c2d3e4-1111-2222-3333-444455556666", "customerId": "aa11bb22-cc33-dd44-ee55-ff6677889900", "orderId": "9c8b7a6d-5555-4444-3333-222211110000", "points": 40, "balanceAfter": 320, "type": "order", "description": "Points earned on order #1042", "metadata": null, "order": { "id": "9c8b7a6d-5555-4444-3333-222211110000", "orderId": "1042" }, "createdAt": "2026-06-30T14:12:00.000000Z" } ], "meta": { "currentPage": 1, "lastPage": 3, "perPage": 20, "total": 45 } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } } } } }, "/account/rewards/perks": { "parameters": [], "get": { "tags": [ "Rewards" ], "summary": "Tier perks", "description": "Get the perks available to the authenticated customer at their current tier. When the rewards programme is disabled for the tenant, only `enabled: false` is returned.", "security": [ { "accountAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "tier": { "type": "string", "nullable": true, "description": "Name of the customer's current tier" }, "perks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "perkType": { "type": "string" }, "configuration": { "type": "object", "nullable": true, "description": "Perk-specific configuration" } } } } } }, "example": { "enabled": true, "tier": "Silver", "perks": [ { "id": "d4e5f6a7-1111-2222-3333-444455556666", "name": "Free shipping", "description": "Free delivery on every order", "perkType": "free_shipping", "configuration": {} } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } } } } }, "/account/rewards/exclusive-products": { "parameters": [], "get": { "tags": [ "Rewards" ], "summary": "Exclusive products", "description": "Get the products available exclusively to the authenticated customer based on their rewards tier. When the rewards programme is disabled for the tenant, only `enabled: false` is returned.", "security": [ { "accountAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "price": { "type": "number" }, "image": { "type": "string", "nullable": true, "description": "Product image URL" } } } } } }, "example": { "enabled": true, "products": [ { "id": "084b80ef-d16d-4531-a25f-40b7ff4c744b", "name": "Members Reserve Red", "slug": "members-reserve-red", "price": 29.99, "image": "https://cdn.marzipan.co/images/reserve-red.jpg" } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } } } } }, "/account/rewards/tiers": { "parameters": [], "get": { "tags": [ "Rewards" ], "summary": "List tiers", "description": "Get all active rewards tiers and their thresholds, flagging which tier the authenticated customer is currently on and which they have achieved. When the rewards programme is disabled for the tenant, only `enabled: false` is returned.", "security": [ { "accountAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "currentPoints": { "type": "integer", "description": "Customer's current points balance" }, "lifetimePoints": { "type": "integer", "description": "Customer's lifetime points earned" }, "tiers": { "type": "array", "items": { "$ref": "#/components/schemas/RewardTier" } } } }, "example": { "enabled": true, "currentPoints": 320, "lifetimePoints": 540, "tiers": [ { "id": "3f0d5a2c-1111-2222-3333-444455556666", "name": "Silver", "slug": "silver", "description": "Silver tier members", "pointsThreshold": 100, "badgeColor": "#C0C0C0", "badgeIcon": "star", "isCurrent": true, "isAchieved": true, "perks": [ { "id": "d4e5f6a7-1111-2222-3333-444455556666", "name": "Free shipping", "description": "Free delivery on every order" } ] }, { "id": "7a1e9b3d-7777-8888-9999-000011112222", "name": "Gold", "slug": "gold", "description": "Gold tier members", "pointsThreshold": 750, "badgeColor": "#FFD700", "badgeIcon": "crown", "isCurrent": false, "isAchieved": false, "perks": [] } ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } } } } }, "/carts/{cartId}/points": { "parameters": [ { "name": "cartId", "in": "path", "required": true, "description": "The unique identifier for the cart", "schema": { "type": "string", "format": "uuid" }, "example": "893ff86d-4453-4134-9f62-5c9b7a70d74e" } ], "post": { "tags": [ "Carts" ], "summary": "Redeem Reward Points", "description": "Redeem a customer's reward points against the cart, applying a points-based discount. The cart must have a customer associated with it (via login or email). The number of points is validated against the customer's available balance and the store's reward tier rules.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "points" ], "properties": { "points": { "type": "integer", "minimum": 1, "description": "The number of reward points to redeem against the cart." } } }, "example": { "points": 500 } } } }, "responses": { "200": { "description": "Points applied. Returns the recalculated cart along with the number of points redeemed and the resulting discount value.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Cart" }, "pointsApplied": { "type": "integer", "description": "The number of points actually redeemed." }, "pointsDiscount": { "type": "number", "description": "The monetary discount value granted by the redeemed points." } } }, "example": { "data": { "id": "893ff86d-4453-4134-9f62-5c9b7a70d74e", "cartCount": 2, "customerId": "4b1d2c3a-9f8e-4a7b-8c6d-1e2f3a4b5c6d", "email": "customer@example.com", "subTotal": 4500, "discount": 0, "pointsToRedeem": 500, "pointsDiscountValue": 500, "shipping": 0, "tax": 0, "grandTotal": 4000, "currency": { "code": "GBP", "symbol": "£" } }, "pointsApplied": 500, "pointsDiscount": 500 } } } }, "404": { "description": "Cart or customer not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Customer not found." } } } }, "422": { "description": "Validation failed, no customer is attached to the cart, or the points could not be applied (e.g. insufficient balance).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "The points field is required.", "errors": { "points": [ "The points field is required." ] } } } } } } }, "delete": { "tags": [ "Carts" ], "summary": "Remove Reward Points", "description": "Remove any redeemed reward points from the cart and recalculate its totals.", "parameters": [], "responses": { "200": { "description": "Points removed. Returns the recalculated cart.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Cart" } } }, "example": { "data": { "id": "893ff86d-4453-4134-9f62-5c9b7a70d74e", "cartCount": 2, "email": "customer@example.com", "subTotal": 4500, "discount": 0, "pointsToRedeem": 0, "pointsDiscountValue": 0, "shipping": 0, "tax": 0, "grandTotal": 4500, "currency": { "code": "GBP", "symbol": "£" } } } } } }, "404": { "description": "Cart not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "No query results for model [Cart]." } } } } } } }, "/carts/{cartId}/market": { "parameters": [ { "name": "cartId", "in": "path", "required": true, "description": "The unique identifier for the cart", "schema": { "type": "string", "format": "uuid" }, "example": "893ff86d-4453-4134-9f62-5c9b7a70d74e" } ], "post": { "tags": [ "Carts" ], "summary": "Switch Cart Market", "description": "Change the cart's market, updating its currency and exchange rate. Shipping is cleared and every line item is repriced in the new market's currency. Returns the recalculated cart.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "marketId" ], "properties": { "marketId": { "type": "string", "format": "uuid", "description": "The identifier of the market to switch the cart to." } } }, "example": { "marketId": "0c9a1b2d-3e4f-5061-7283-94a5b6c7d8e9" } } } }, "responses": { "200": { "description": "Market switched. Returns the recalculated cart in the new market's currency.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Cart" } } }, "example": { "data": { "id": "893ff86d-4453-4134-9f62-5c9b7a70d74e", "cartCount": 2, "subTotal": 5600, "shipping": 0, "tax": 0, "grandTotal": 5600, "currency": { "code": "USD", "symbol": "$" }, "market": { "id": "0c9a1b2d-3e4f-5061-7283-94a5b6c7d8e9", "name": "United States", "currencyCode": "USD", "currencySymbol": "$" } } } } } }, "404": { "description": "Cart not found, or the market is not found or unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Market not found or not available." } } } }, "422": { "description": "The market_id was not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Market ID is required." } } } } } } }, "/carts/{cartId}/express-checkout-intent": { "parameters": [ { "name": "cartId", "in": "path", "required": true, "description": "The unique identifier for the cart", "schema": { "type": "string", "format": "uuid" }, "example": "893ff86d-4453-4134-9f62-5c9b7a70d74e" } ], "post": { "tags": [ "Carts" ], "summary": "Create Express Checkout Intent", "description": "Create a Stripe payment intent for express checkout flows such as Apple Pay and Google Pay. Returns the client secret used to confirm the payment on the client.", "parameters": [], "responses": { "200": { "description": "Payment intent created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "clientSecret": { "type": "string", "description": "The Stripe payment intent client secret used to confirm the express checkout payment." } } }, "example": { "clientSecret": "pi_3QabcXY2eZvKYlo21n4kD8Fg_secret_Nq9mR7sTuVwXyZ012345aBcD" } } } } } } }, "/carts/{cartId}/updatePaymentIntent": { "parameters": [ { "name": "cartId", "in": "path", "required": true, "description": "The unique identifier for the cart", "schema": { "type": "string", "format": "uuid" }, "example": "893ff86d-4453-4134-9f62-5c9b7a70d74e" } ], "post": { "tags": [ "Carts" ], "summary": "Update Payment Intent Amount", "description": "Synchronise an existing Stripe payment intent's amount with the cart's current grand total. Call this after the cart changes (items, shipping, discounts) so the payment intent reflects the latest amount due.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The Stripe payment intent identifier to update." } } }, "example": { "id": "pi_3QabcXY2eZvKYlo21n4kD8Fg" } } } }, "responses": { "200": { "description": "Payment intent updated. Returns the Stripe payment intent status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "The Stripe payment intent status after the update.", "example": "requires_payment_method" } } }, "example": { "status": "requires_payment_method" } } } }, "404": { "description": "Cart not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "No query results for model [Cart]." } } } }, "422": { "description": "The payment intent id was not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "The id field is required.", "errors": { "id": [ "The id field is required." ] } } } } } } } }, "/carts/{cartId}/freeShippingUpsell": { "parameters": [ { "name": "cartId", "in": "path", "required": true, "description": "The unique identifier for the cart", "schema": { "type": "string", "format": "uuid" }, "example": "893ff86d-4453-4134-9f62-5c9b7a70d74e" } ], "get": { "tags": [ "Carts" ], "summary": "Get Free Shipping Upsell", "description": "Determine whether the cart is eligible for a free shipping upsell prompt and, if so, how much more the customer needs to spend (value-based) or how many more items are needed (volume-based) to qualify. When no upsell applies, or the amount needed exceeds the store's display threshold, `show` is `false`.", "parameters": [], "responses": { "200": { "description": "The free shipping upsell state for the cart.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreeShippingUpsell" }, "example": { "show": true, "qualifies": false, "type": "value", "amountNeeded": 1500, "itemsNeeded": null } } } } } } }, "/carts/{cartId}/relatedProducts": { "parameters": [ { "name": "cartId", "in": "path", "required": true, "description": "The unique identifier for the cart", "schema": { "type": "string", "format": "uuid" }, "example": "893ff86d-4453-4134-9f62-5c9b7a70d74e" } ], "get": { "tags": [ "Carts" ], "summary": "Get Related Products", "description": "Retrieve active related products for the items currently in the cart. Products already in the cart are excluded and results are de-duplicated. The number returned defaults to the store's configured related-products count and can be overridden with the `limit` query parameter.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of related products to return. Defaults to the store's configured related-products count.", "schema": { "type": "integer" }, "example": 4 } ], "responses": { "200": { "description": "A list of related products.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSummary" } } } }, "example": { "data": [ { "id": "7f2a1c3b-9d8e-4f6a-b1c2-3d4e5f6a7b8c", "name": "Sea Salt Caramel Truffles", "slug": "sea-salt-caramel-truffles", "price": 1200, "productType": "physical" } ] } } } }, "404": { "description": "Cart not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "No query results for model [Cart]." } } } } } } }, "/carts/{cartId}/payfast/identifier": { "parameters": [ { "name": "cartId", "in": "path", "required": true, "description": "The unique identifier for the cart", "schema": { "type": "string", "format": "uuid" }, "example": "893ff86d-4453-4134-9f62-5c9b7a70d74e" } ], "post": { "tags": [ "Carts" ], "summary": "Generate PayFast Checkout Identifier", "description": "Generate a PayFast checkout for the cart. An onsite payment identifier (for the PayFast modal) is attempted first; if that is unavailable the response falls back to a redirect URL. The cart must have billing information (name and email) before calling this.", "parameters": [], "responses": { "200": { "description": "A PayFast checkout was generated. The `mode` field indicates whether to open the onsite modal or redirect the customer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "onsite", "redirect" ], "description": "Which checkout flow to use." }, "identifier": { "type": "string", "description": "The PayFast onsite payment identifier (present when mode is `onsite`)." }, "engineUrl": { "type": "string", "format": "uri", "description": "The PayFast onsite engine script URL (present when mode is `onsite`)." }, "redirectUrl": { "type": "string", "format": "uri", "description": "The PayFast redirect checkout URL (present when mode is `redirect`)." } } }, "example": { "mode": "onsite", "identifier": "01ab23cd45ef67ab89cd01ef23ab45cd", "engineUrl": "https://www.payfast.co.za/onsite/engine.js" } } } }, "400": { "description": "The cart is missing required billing information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Cart is missing required billing information" } } } }, "404": { "description": "Cart not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "No query results for model [Cart]." } } } } } } }, "/carts/{cartId}/payfast/status": { "parameters": [ { "name": "cartId", "in": "path", "required": true, "description": "The unique identifier for the cart", "schema": { "type": "string", "format": "uuid" }, "example": "893ff86d-4453-4134-9f62-5c9b7a70d74e" } ], "get": { "tags": [ "Carts" ], "summary": "Check PayFast Payment Status", "description": "Poll the payment status for a cart after the PayFast modal closes. Returns `pending` while awaiting confirmation, `complete` once payment has succeeded (in which case the cart has been converted to an order), or `failed` with a message if the payment did not go through.", "parameters": [], "responses": { "200": { "description": "The current PayFast payment status for the cart.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "complete", "failed" ], "description": "The payment status." }, "order": { "type": "object", "nullable": true, "description": "The created order (present when the cart was converted to an order on completion)." }, "paymentId": { "type": "string", "nullable": true, "description": "The PayFast payment identifier (present on completion when the cart still exists)." }, "message": { "type": "string", "description": "The failure reason (present when status is `failed`)." } }, "required": [ "status" ] }, "example": { "status": "pending" } } } } } } }, "/cms/posts": { "get": { "tags": [ "CMS" ], "summary": "List blog posts", "description": "Returns all published blog posts, ordered by creation date (newest first), each with its author and featured image. This endpoint is not paginated and accepts no query parameters; the full published set is returned in a single `data` array. Responses are cached (fresh for 10 minutes, served stale for up to 1 hour).", "responses": { "200": { "description": "A list of published blog posts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CmsPost" } } } }, "example": { "data": [ { "slug": "welcome-to-our-store", "title": "Welcome to our store", "excerpt": "A short introduction to what we do.", "featuredImage": "https://cdn.marzipan.co/media/800x600/welcome.jpg", "author": { "name": "Jane Doe" }, "createdAt": "2026-05-01T09:00:00Z", "updatedAt": "2026-05-02T11:30:00Z" } ] } } } } } } }, "/cms/posts/{slug}": { "get": { "tags": [ "CMS" ], "summary": "Get a blog post", "description": "Returns the full detail of a single published blog post by its slug, including the rendered content body, SEO metadata and any collections the post belongs to. Responses are cached (fresh for 10 minutes, served stale for up to 1 hour).", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "URL-friendly identifier of the blog post.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The requested blog post.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CmsPostDetail" }, "example": { "slug": "welcome-to-our-store", "title": "Welcome to our store", "excerpt": "A short introduction to what we do.", "content": "

Full HTML content of the post.

", "featuredImage": "https://cdn.marzipan.co/media/1200x800/welcome.jpg", "author": { "name": "Jane Doe" }, "seo": { "title": "Welcome to our store", "description": "Everything you need to know to get started.", "ogImage": "https://cdn.marzipan.co/media/1200x630/welcome.jpg" }, "collections": [ { "slug": "news", "name": "News" } ], "createdAt": "2026-05-01T09:00:00Z", "updatedAt": "2026-05-02T11:30:00Z" } } } }, "404": { "description": "No published post with the given slug exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Post not found" } } } } } } }, "/cms/pages/{page}/purge-cache": { "post": { "tags": [ "CMS" ], "summary": "Purge a page's cache", "description": "Triggers a cache purge for the CMS page identified by `page` (its id). If a `url` is supplied in the body it is purged directly; otherwise the page's primary domain is used to derive the URL. The caller must have access to the page's tenant.", "parameters": [ { "name": "page", "in": "path", "required": true, "description": "The id of the CMS page to purge.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Explicit URL to purge. If omitted, the page's primary domain is used to build one." } } }, "example": { "url": "https://shop.example.com/page/about-us" } } } }, "responses": { "200": { "description": "Cache purge was triggered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "url": { "type": "string", "description": "The URL that was purged." } } }, "example": { "success": true, "message": "Cache purge triggered for page", "url": "https://shop.example.com/page/about-us" } } } } } } }, "/forms/{slug}": { "get": { "tags": [ "Forms" ], "summary": "Get a form definition", "description": "Returns the definition of an active form by slug so a storefront can render it: the field list (with names, labels, types, options and whether each is required) plus display settings such as the success message.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "URL-friendly identifier of the form.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The form definition.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Form" }, "example": { "name": "Contact us", "fields": [ { "name": "name", "label": "Your Name", "type": "text", "required": true, "placeholder": "", "options": [] }, { "name": "email", "label": "Email", "type": "email", "required": true, "placeholder": "", "options": [] }, { "name": "message", "label": "Message", "type": "textarea", "required": true, "placeholder": "", "options": [] } ], "settings": { "successMessage": "Thank you for your submission!" } } } } }, "404": { "description": "No active form with the given slug exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "No query results for model [Form]." } } } } } } }, "/forms/{slug}/submit": { "post": { "tags": [ "Forms" ], "summary": "Submit a form", "description": "Submits an active form. The request body is a free-form object keyed by the form's field `name`s (as returned by `GET /forms/{slug}`); values are validated dynamically against each field's definition (required/nullable, email format, `in:` for select/radio, array for checkbox, date for date fields). Include the honeypot field `_hp_name` as an empty string — if it is filled the submission is rejected as spam. Depending on the form type the submission may also create a contact message, subscribe the customer to a marketing list, and trigger notifications.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "URL-friendly identifier of the form.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Object keyed by the form's field names. Keys and validation rules are determined by the form definition.", "additionalProperties": true, "properties": { "_hp_name": { "type": "string", "description": "Honeypot field. Must be left empty; a non-empty value causes the submission to be rejected as spam." } } }, "example": { "name": "Ada Lovelace", "email": "ada@example.com", "message": "Do you ship internationally?", "_hp_name": "" } } } }, "responses": { "200": { "description": "The form was submitted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "description": "The form's configured success message." } } }, "example": { "success": true, "message": "Thank you for your submission!" } } } }, "404": { "description": "No active form with the given slug exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "No query results for model [Form]." } } } }, "422": { "description": "The submitted data failed validation, or spam was detected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "The email field must be a valid email address.", "errors": { "email": [ "The email field must be a valid email address." ] } } } } } } } }, "/messages": { "post": { "tags": [ "Messaging" ], "summary": "Send a message", "description": "Submits a message to the store (for example from a contact form). A customer record is found or created from the email address, the message is logged, and admin users who opt in are notified.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "email", "subject", "message", "source" ], "properties": { "name": { "type": "string", "description": "Sender's full name." }, "email": { "type": "string", "format": "email", "description": "Sender's email address." }, "subject": { "type": "string", "description": "Message subject." }, "message": { "type": "string", "description": "Message body." }, "source": { "type": "string", "description": "Where the message originated (e.g. the page URL or form name)." }, "company": { "type": "string", "description": "Optional company name for the sender." } } }, "example": { "name": "Ada Lovelace", "email": "ada@example.com", "subject": "Wholesale enquiry", "message": "Do you offer wholesale pricing?", "source": "contact-page", "company": "Analytical Engines Ltd" } } } }, "responses": { "200": { "description": "The message was logged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } }, "example": { "success": true, "message": "Message has been logged." } } } }, "422": { "description": "The submitted data failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "The email field is required.", "errors": { "email": [ "The email field is required." ] } } } } } } } }, "/products/{product}/back-in-stock": { "post": { "tags": [ "Products" ], "summary": "Register for a back-in-stock notification", "description": "Registers an email address to be notified when the given product is back in stock. Subscriptions are only accepted for products that are out of stock (unless the product allows overselling); requesting one for an in-stock product returns a 422. If a customer is authenticated the subscription is linked to their account.", "parameters": [ { "name": "product", "in": "path", "required": true, "description": "The id of the product to subscribe to.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "Email address to notify when the product is back in stock." }, "market": { "type": "string", "description": "Optional market/region identifier for the notification context." } } }, "example": { "email": "ada@example.com", "market": "uk" } } } }, "responses": { "200": { "description": "The email was registered for a back-in-stock notification.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "You will be notified when this product is back in stock." } } } }, "422": { "description": "Validation failed, or the product is currently in stock.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "The email field is required.", "errors": { "email": [ "The email field is required." ] } } } } } } } }, "/subscription-packages/{productId}/configuration": { "get": { "tags": [ "Subscriptions" ], "summary": "Get subscription configuration options", "description": "Returns the options for configuring a subscription package: its subscription and pricing types, billing frequencies, and — for pick & mix subscriptions — the list of available items with their quantity constraints and pricing. Responses are cached (fresh for 5 minutes, served stale for up to 30 minutes).", "parameters": [ { "name": "productId", "in": "path", "required": true, "description": "The id of the subscription product.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The subscription configuration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SubscriptionConfiguration" } } }, "example": { "data": { "subscriptionType": "picknmix", "pricingType": "calculated", "fixedPrice": null, "frequencies": [ 1, 3, 6 ], "defaultFrequency": 1, "availableItems": [ { "id": "9b2f1c4e-1a2b-4c3d-8e9f-0a1b2c3d4e5f", "name": "House Blend 250g", "sku": "COF-HB-250", "image": null, "price": 8.5, "salePrice": null, "subscriberPrice": 7.5, "description": "Our signature house blend.", "status": "active", "minQuantity": 1, "maxQuantity": 5, "defaultQuantity": 1 } ], "minItems": 3 } } } } }, "404": { "description": "The product does not exist or is not a subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Product is not a subscription" } } } } } } }, "/subscription-packages/calculate-price": { "post": { "tags": [ "Subscriptions" ], "summary": "Calculate a configured subscription price", "description": "Prices a configured pick & mix subscription for a given billing frequency and set of selected items. Item prices use the effective price (sale, subscriber or list price) and are converted to the active market's currency. Returns the raw and formatted subtotal plus currency information.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "productId", "frequency", "items" ], "properties": { "productId": { "type": "string", "format": "uuid", "description": "The id of the pick & mix subscription product." }, "frequency": { "type": "integer", "enum": [ 1, 3, 6, 12 ], "description": "Billing frequency in months." }, "items": { "type": "array", "minItems": 1, "description": "The selected items and their quantities.", "items": { "type": "object", "required": [ "id", "quantity" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The id of the selected item product." }, "quantity": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Quantity of this item." } } } } } }, "example": { "productId": "2c1d0e9f-8a7b-4c6d-9e5f-1a2b3c4d5e6f", "frequency": 3, "items": [ { "id": "9b2f1c4e-1a2b-4c3d-8e9f-0a1b2c3d4e5f", "quantity": 2 } ] } } } }, "responses": { "200": { "description": "The calculated price for the configuration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "priceRaw": { "type": "integer", "description": "Subtotal in the currency's minor units (e.g. pence)." }, "priceFormatted": { "type": "string", "description": "Human-readable formatted subtotal including currency symbol." }, "currency": { "type": "object", "properties": { "code": { "type": "string", "description": "ISO currency code." }, "symbol": { "type": "string", "description": "Currency symbol." } } } } }, "example": { "priceRaw": 1700, "priceFormatted": "£17.00", "currency": { "code": "GBP", "symbol": "£" } } } } }, "400": { "description": "The product is not a pick & mix subscription, or the selected frequency is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Product is not a pick & mix subscription" } } } }, "422": { "description": "The submitted data failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "The frequency field is required.", "errors": { "frequency": [ "The frequency field is required." ] } } } } } } } }, "/events/{event}/availability": { "parameters": [ { "name": "event", "in": "path", "required": true, "description": "The unique identifier of the event.", "schema": { "type": "string", "format": "uuid" }, "example": "b7a4c2e1-8f3d-4a6b-9c2e-1d5f7a8b3c4d" } ], "get": { "tags": [ "Events" ], "summary": "Check Event Availability", "description": "Check ticket availability for an event, optionally for a specific date. For recurring events, an invalid date returns `available: false` with a message. Includes waitlist status and count.", "parameters": [ { "name": "date", "in": "query", "required": false, "description": "The date to check availability for (YYYY-MM-DD). Defaults to the event's start date. Used to validate a date against a recurring event's schedule.", "schema": { "type": "string", "format": "date" }, "example": "2026-08-15" } ], "responses": { "200": { "description": "Availability details for the event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventAvailability" }, "example": { "available": true, "ticketsAvailable": 42, "waitlistEnabled": true, "waitlistCount": 3 } } } }, "404": { "description": "Event not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "No query results for model [Event]." } } } } } } }, "/events/{event}/check-dates": { "parameters": [ { "name": "event", "in": "path", "required": true, "description": "The unique identifier of the event.", "schema": { "type": "string", "format": "uuid" }, "example": "b7a4c2e1-8f3d-4a6b-9c2e-1d5f7a8b3c4d" } ], "get": { "tags": [ "Events" ], "summary": "Check Event Dates", "description": "Check whether an event is available on a specific search date. For non-recurring events the search date is matched against the event's start date; for recurring events it is validated against the recurrence pattern. Returns the availability details along with the requested and scheduled dates.", "parameters": [ { "name": "searchDate", "in": "query", "required": true, "description": "The date to check (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" }, "example": "2026-08-15" } ], "responses": { "200": { "description": "Availability for the requested date.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventAvailability" }, { "type": "object", "properties": { "searchDate": { "type": "string", "format": "date", "description": "The date that was searched." }, "eventDate": { "type": "string", "format": "date", "description": "The event's scheduled start date." } } } ] }, "example": { "available": true, "ticketsAvailable": 42, "waitlistEnabled": true, "waitlistCount": 3, "searchDate": "2026-08-15", "eventDate": "2026-08-15" } } } }, "404": { "description": "Event not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "No query results for model [Event]." } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "The search date field is required.", "errors": { "searchDate": [ "The search date field is required." ] } } } } } } } }, "/events/{event}/stats": { "parameters": [ { "name": "event", "in": "path", "required": true, "description": "The unique identifier of the event.", "schema": { "type": "string", "format": "uuid" }, "example": "b7a4c2e1-8f3d-4a6b-9c2e-1d5f7a8b3c4d" } ], "get": { "tags": [ "Events" ], "summary": "Get Event Statistics", "description": "Retrieve aggregate statistics for an event, including tickets sold and available, revenue totals, check-in and attendance counts, waitlist size, and cancellations. Revenue values are returned in the store's major currency unit.", "parameters": [], "responses": { "200": { "description": "Event statistics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventStats" }, "example": { "ticketsSold": 58, "ticketsAvailable": 42, "maxTickets": 100, "maxTicketsPerOrder": 6, "totalRevenue": 2320.0, "outstandingRevenue": 150.0, "checkedIn": 12, "attending": 58, "waitlist": 3, "cancelled": 4 } } } }, "404": { "description": "Event not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "No query results for model [Event]." } } } } } } }, "/events/recurring/{product}/dates": { "parameters": [ { "name": "product", "in": "path", "required": true, "description": "The unique identifier of the event product.", "schema": { "type": "string", "format": "uuid" }, "example": "3f1c9d20-5b8e-4c11-a2d7-6e9f0a1b2c3d" } ], "get": { "tags": [ "Events" ], "summary": "Get Recurring Event Dates", "description": "List the upcoming active occurrences for a recurring event product within an optional date range. If the product is not a recurring event, an empty list is returned with an explanatory message.", "parameters": [ { "name": "startDate", "in": "query", "required": false, "description": "Start of the date range (YYYY-MM-DD). Defaults to today.", "schema": { "type": "string", "format": "date" }, "example": "2026-08-01" }, { "name": "endDate", "in": "query", "required": false, "description": "End of the date range (YYYY-MM-DD). Defaults to three months from today.", "schema": { "type": "string", "format": "date" }, "example": "2026-11-01" } ], "responses": { "200": { "description": "The list of available occurrence dates.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RecurringDate" } } } }, "example": { "data": [ { "id": "9a2b3c4d-5e6f-4071-8a9b-0c1d2e3f4a5b", "date": "2026-08-15", "startDate": "2026-08-15", "endDate": "2026-08-15", "startTime": "19:00", "endTime": "22:00", "location": "The Grand Hall", "status": "active", "ticketsAvailable": 42, "isSoldOut": false, "formattedDateTime": "Sat 15 Aug 2026, 7:00 PM" } ] } } } }, "404": { "description": "Product not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "No query results for model [Product]." } } } } } } }, "/events/tickets/{ticket}/qr-code": { "parameters": [ { "name": "ticket", "in": "path", "required": true, "description": "The unique identifier of the event ticket.", "schema": { "type": "string", "format": "uuid" }, "example": "c4d5e6f7-8a9b-40c1-92d3-e4f5a6b7c8d9" } ], "get": { "tags": [ "Events" ], "summary": "Get Ticket QR Code", "description": "Generate (if necessary) and return a scannable QR code for an event ticket. The QR code is returned as a base64-encoded SVG data URI suitable for direct display.", "parameters": [], "responses": { "200": { "description": "The ticket QR code.", "content": { "application/json": { "schema": { "type": "object", "properties": { "qrCode": { "type": "string", "description": "Base64-encoded SVG data URI of the QR code image." }, "ticketId": { "type": "string", "format": "uuid", "description": "The identifier of the ticket." } } }, "example": { "qrCode": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0i...", "ticketId": "c4d5e6f7-8a9b-40c1-92d3-e4f5a6b7c8d9" } } } }, "404": { "description": "Ticket not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "No query results for model [EventTicket]." } } } } } } }, "/events/{event}/occurrences": { "parameters": [ { "name": "event", "in": "path", "required": true, "description": "The unique identifier of the event.", "schema": { "type": "string", "format": "uuid" }, "example": "b7a4c2e1-8f3d-4a6b-9c2e-1d5f7a8b3c4d" } ], "get": { "tags": [ "Events" ], "summary": "List Event Occurrences", "description": "List the occurrences of a recurring event, optionally filtered by date range and status. When no start date or status filter is supplied, only upcoming occurrences are returned. If the event is not recurring, an empty list is returned with an explanatory message.", "parameters": [ { "name": "startDate", "in": "query", "required": false, "description": "Only include occurrences on or after this date (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" }, "example": "2026-08-01" }, { "name": "endDate", "in": "query", "required": false, "description": "Only include occurrences on or before this date (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" }, "example": "2026-11-01" }, { "name": "status", "in": "query", "required": false, "description": "Filter occurrences by status.", "schema": { "type": "string", "enum": [ "active", "cancelled", "postponed" ] }, "example": "active" } ], "responses": { "200": { "description": "The list of occurrences.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventOccurrence" } }, "total": { "type": "integer", "description": "The number of occurrences returned." } } }, "example": { "data": [ { "id": "9a2b3c4d-5e6f-4071-8a9b-0c1d2e3f4a5b", "date": "2026-08-15", "formattedDate": "Aug 15, 2026", "startTime": "19:00", "endTime": "22:00", "status": "active", "location": "The Grand Hall", "maxTickets": 100, "ticketsSold": 58, "ticketsAvailable": 42, "isSoldOut": false } ], "total": 1 } } } }, "404": { "description": "Event not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "No query results for model [Event]." } } } } } } }, "/events/occurrences/{occurrence}/availability": { "parameters": [ { "name": "occurrence", "in": "path", "required": true, "description": "The unique identifier of the event occurrence.", "schema": { "type": "string", "format": "uuid" }, "example": "9a2b3c4d-5e6f-4071-8a9b-0c1d2e3f4a5b" } ], "get": { "tags": [ "Events" ], "summary": "Check Occurrence Availability", "description": "Check ticket availability for a specific occurrence of a recurring event, including tickets sold and remaining, capacity, waitlist status, and the occurrence date.", "parameters": [], "responses": { "200": { "description": "Availability details for the occurrence.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OccurrenceAvailability" }, "example": { "available": true, "ticketsAvailable": 42, "ticketsSold": 58, "maxTickets": 100, "waitlistEnabled": true, "occurrenceDate": "2026-08-15", "status": "active" } } } }, "404": { "description": "Occurrence not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "No query results for model [EventOccurrence]." } } } } } } }, "/events/occurrences/{occurrence}": { "parameters": [ { "name": "occurrence", "in": "path", "required": true, "description": "The unique identifier of the event occurrence.", "schema": { "type": "string", "format": "uuid" }, "example": "9a2b3c4d-5e6f-4071-8a9b-0c1d2e3f4a5b" } ], "put": { "tags": [ "Events" ], "summary": "Update Event Occurrence", "description": "Update a single occurrence of a recurring event. Capacity cannot be reduced below the number of tickets already sold. All fields are optional and only supplied fields are updated.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "cancelled", "postponed" ], "description": "The occurrence status." }, "maxTickets": { "type": "integer", "minimum": 0, "description": "Maximum tickets for the occurrence. Cannot be set below tickets already sold." }, "locationOverride": { "type": "string", "nullable": true, "description": "A location that overrides the parent event's location for this occurrence." }, "notes": { "type": "string", "nullable": true, "description": "Internal notes for the occurrence." }, "occurrenceDate": { "type": "string", "format": "date", "description": "The date of the occurrence (YYYY-MM-DD)." } } }, "example": { "status": "postponed", "maxTickets": 120, "locationOverride": "The Riverside Marquee", "notes": "Moved outdoors due to demand.", "occurrenceDate": "2026-08-22" } } } }, "responses": { "200": { "description": "The updated occurrence.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "occurrence": { "$ref": "#/components/schemas/EventOccurrenceRecord" } } }, "example": { "success": true, "occurrence": { "id": "9a2b3c4d-5e6f-4071-8a9b-0c1d2e3f4a5b", "eventId": "b7a4c2e1-8f3d-4a6b-9c2e-1d5f7a8b3c4d", "occurrenceDate": "2026-08-22", "startTime": "19:00", "endTime": "22:00", "status": "postponed", "maxTickets": 120, "ticketsSold": 58, "locationOverride": "The Riverside Marquee", "notes": "Moved outdoors due to demand." } } } } }, "404": { "description": "Occurrence not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "No query results for model [EventOccurrence]." } } } }, "422": { "description": "Validation error, or an attempt to reduce capacity below tickets already sold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "The selected status is invalid.", "errors": { "status": [ "The selected status is invalid." ] } } } } } } } }, "/events/waitlist/validate": { "post": { "tags": [ "Events" ], "summary": "Validate Waitlist Claim Link", "description": "Validate a signed waitlist claim link and return the entry details needed to complete a claim. The link is verified against its signature and expiry, and the entry must be in a claimable (promoted) state.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "eventWaitlist", "expires", "signature" ], "properties": { "eventWaitlist": { "type": "string", "format": "uuid", "description": "The identifier of the waitlist entry." }, "expires": { "type": "string", "description": "The expiry timestamp from the signed URL." }, "signature": { "type": "string", "description": "The signature from the signed URL." } } }, "example": { "eventWaitlist": "1a2b3c4d-5e6f-4071-8a9b-0c1d2e3f4a5b", "expires": "1786000000", "signature": "9f8e7d6c5b4a3928170615243342515e6d7c8b9a0f1e2d3c4b5a6978" } } } }, "responses": { "200": { "description": "The claim link is valid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "quantity": { "type": "integer", "description": "The number of tickets held for the entry." }, "eventName": { "type": "string", "description": "The name of the event product." }, "eventId": { "type": "string", "format": "uuid", "description": "The identifier of the event product." }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the promoted spot expires." } } }, "example": { "valid": true, "quantity": 2, "eventName": "Summer Jazz Night", "eventId": "3f1c9d20-5b8e-4c11-a2d7-6e9f0a1b2c3d", "expiresAt": "2026-08-10T18:00:00Z" } } } }, "422": { "description": "The link is invalid, expired, or the spot is no longer claimable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "The event waitlist field is required.", "errors": { "eventWaitlist": [ "The event waitlist field is required." ] } } } } } } } }, "/events/waitlist/claim": { "post": { "tags": [ "Events" ], "summary": "Claim Waitlist Spot via Signed Link", "description": "Claim a promoted waitlist spot using a signed link, automatically adding the event to a cart. If no cart is supplied, a new cart is created. If the event has a deposit enabled, the deposit amount is used as the line price. Returns the resulting cart.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "eventWaitlist", "expires", "signature" ], "properties": { "eventWaitlist": { "type": "string", "format": "uuid", "description": "The identifier of the waitlist entry." }, "expires": { "type": "string", "description": "The expiry timestamp from the signed URL." }, "signature": { "type": "string", "description": "The signature from the signed URL." }, "cartId": { "type": "string", "format": "uuid", "description": "An existing cart to add the event to. If omitted, a new cart is created." } } }, "example": { "eventWaitlist": "1a2b3c4d-5e6f-4071-8a9b-0c1d2e3f4a5b", "expires": "1786000000", "signature": "9f8e7d6c5b4a3928170615243342515e6d7c8b9a0f1e2d3c4b5a6978", "cartId": "893ff86d-4453-4134-9f62-5c9b7a70d74e" } } } }, "responses": { "200": { "description": "The waitlist spot was claimed and the event added to the cart.", "content": { "application/json": { "schema": { "type": "object", "description": "The cart resource with the event added.", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "subtotal": { "type": "number" }, "grandTotal": { "type": "number" } } }, "example": { "id": "893ff86d-4453-4134-9f62-5c9b7a70d74e", "email": "alex@example.com", "subtotal": 80.0, "grandTotal": 80.0 } } } }, "422": { "description": "The link is invalid or expired, the spot is no longer claimable, or the event is no longer available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "The event waitlist field is required.", "errors": { "eventWaitlist": [ "The event waitlist field is required." ] } } } } } } } }, "/events/{product}/waitlist": { "parameters": [ { "name": "product", "in": "path", "required": true, "description": "The unique identifier of the event product.", "schema": { "type": "string", "format": "uuid" }, "example": "3f1c9d20-5b8e-4c11-a2d7-6e9f0a1b2c3d" } ], "post": { "tags": [ "Events" ], "summary": "Join Event Waitlist", "description": "Join the waitlist for a sold-out event. Requires the event to have its waitlist enabled and to be sold out, and the customer must not already be on the waitlist. Returns the assigned waitlist position.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "name", "quantity" ], "properties": { "email": { "type": "string", "format": "email", "description": "The customer's email address." }, "name": { "type": "string", "maxLength": 255, "description": "The customer's name." }, "phone": { "type": "string", "maxLength": 50, "nullable": true, "description": "The customer's phone number." }, "quantity": { "type": "integer", "minimum": 1, "maximum": 10, "description": "The number of tickets requested." } } }, "example": { "email": "alex@example.com", "name": "Alex Rivera", "phone": "+44 7700 900123", "quantity": 2 } } } }, "responses": { "200": { "description": "Added to the waitlist.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "position": { "type": "integer", "description": "The assigned position in the waitlist." }, "message": { "type": "string" } } }, "example": { "success": true, "position": 4, "message": "Added to waitlist at position 4" } } } }, "404": { "description": "Product not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "No query results for model [Product]." } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "The email field is required.", "errors": { "email": [ "The email field is required." ] } } } } } } } }, "/events/{product}/waitlist/status": { "parameters": [ { "name": "product", "in": "path", "required": true, "description": "The unique identifier of the event product.", "schema": { "type": "string", "format": "uuid" }, "example": "3f1c9d20-5b8e-4c11-a2d7-6e9f0a1b2c3d" } ], "get": { "tags": [ "Events" ], "summary": "Get Waitlist Status", "description": "Look up a customer's waitlist status for an event by email. For pending entries, the response includes the position and the number of people ahead; for promoted entries, it includes the expiry time and whether the spot can be claimed.", "parameters": [ { "name": "email", "in": "query", "required": true, "description": "The email address to look up on the waitlist.", "schema": { "type": "string", "format": "email" }, "example": "alex@example.com" } ], "responses": { "200": { "description": "The customer's waitlist status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaitlistStatus" }, "example": { "success": true, "onWaitlist": true, "status": "pending", "quantity": 2, "position": 4, "ahead": 3 } } } }, "404": { "description": "The email address was not found on the waitlist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Not found on waitlist" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "message": "The email field is required.", "errors": { "email": [ "The email field is required." ] } } } } } } } }, "/events/{product}/waitlist/{entry}": { "parameters": [ { "name": "product", "in": "path", "required": true, "description": "The unique identifier of the event product.", "schema": { "type": "string", "format": "uuid" }, "example": "3f1c9d20-5b8e-4c11-a2d7-6e9f0a1b2c3d" }, { "name": "entry", "in": "path", "required": true, "description": "The unique identifier of the waitlist entry.", "schema": { "type": "string", "format": "uuid" }, "example": "1a2b3c4d-5e6f-4071-8a9b-0c1d2e3f4a5b" } ], "delete": { "tags": [ "Events" ], "summary": "Leave Event Waitlist", "description": "Remove a waitlist entry, leaving the event's waitlist. Only pending or promoted entries can be removed. If an email is supplied it must match the entry's email.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Optional email to verify ownership of the entry." } } }, "example": { "email": "alex@example.com" } } } }, "responses": { "204": { "description": "The entry was removed from the waitlist." }, "404": { "description": "Product or waitlist entry not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "No query results for model [EventWaitlistEntry]." } } } } } } }, "/events/{product}/waitlist/{entry}/claim": { "parameters": [ { "name": "product", "in": "path", "required": true, "description": "The unique identifier of the event product.", "schema": { "type": "string", "format": "uuid" }, "example": "3f1c9d20-5b8e-4c11-a2d7-6e9f0a1b2c3d" }, { "name": "entry", "in": "path", "required": true, "description": "The unique identifier of the waitlist entry.", "schema": { "type": "string", "format": "uuid" }, "example": "1a2b3c4d-5e6f-4071-8a9b-0c1d2e3f4a5b" } ], "post": { "tags": [ "Events" ], "summary": "Claim Promoted Waitlist Spot", "description": "Claim a promoted waitlist spot, reserving the tickets for checkout. The entry must be in a claimable (promoted, unexpired) state. If an email is supplied it must match the entry's email. Returns checkout data with a short reservation window.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Optional email to verify ownership of the entry." } } }, "example": { "email": "alex@example.com" } } } }, "responses": { "200": { "description": "The spot was reserved for checkout.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "checkout": { "$ref": "#/components/schemas/WaitlistCheckout" } } }, "example": { "success": true, "message": "Waitlist spot reserved for checkout", "checkout": { "productId": "3f1c9d20-5b8e-4c11-a2d7-6e9f0a1b2c3d", "quantity": 2, "email": "alex@example.com", "name": "Alex Rivera", "waitlistEntryId": "1a2b3c4d-5e6f-4071-8a9b-0c1d2e3f4a5b", "reservedUntil": "2026-08-10T18:15:00Z" } } } } }, "404": { "description": "Product or waitlist entry not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "No query results for model [EventWaitlistEntry]." } } } } } } } } }