{ "openapi": "3.0.0", "paths": { "/storefront/auth/sign-in": { "post": { "operationId": "auth_signIn", "summary": "Customer sign in with credentials", "description": "Authenticate a storefront customer using email and password", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticateCustomerCredentials" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokensResponse" } } } } }, "tags": [ "Auth" ] } }, "/storefront/auth/oauth": { "post": { "operationId": "auth_oauth", "summary": "Customer OAuth sign in", "description": "Authenticate or register a storefront customer using an OAuth provider (e.g. Google)", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticateCustomerOauth" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokensResponse" } } } } }, "tags": [ "Auth" ] } }, "/storefront/auth/sign-up": { "post": { "operationId": "auth_signUp", "summary": "Register a new customer", "description": "Create a new customer account on the storefront and send a verification email", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterCustomer" } } } }, "responses": { "204": { "description": "" } }, "tags": [ "Auth" ] } }, "/storefront/auth/request-email-verification": { "post": { "operationId": "auth_requestEmailVerification", "summary": "Request customer email verification", "description": "Send a verification email to the customer for account activation within the store context", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestEmailVerification" } } } }, "responses": { "204": { "description": "" } }, "tags": [ "Auth" ] } }, "/storefront/auth/verify-email": { "post": { "operationId": "auth_verifyEmail", "summary": "Verify customer email", "description": "Confirm customer email ownership using the verification token and return auth tokens", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyEmail" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokensResponse" } } } } }, "tags": [ "Auth" ] } }, "/storefront/auth/refresh": { "get": { "operationId": "auth_refresh", "summary": "Refresh customer tokens", "description": "Exchange a valid customer refresh token for a new pair of access and refresh tokens", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokensResponse" } } } } }, "tags": [ "Auth" ] } }, "/storefront/auth/request-password-reset": { "post": { "operationId": "auth_requestPasswordReset", "summary": "Request customer password reset", "description": "Send a password reset email to the customer within the store context", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestPasswordReset" } } } }, "responses": { "204": { "description": "" } }, "tags": [ "Auth" ] } }, "/storefront/auth/reset-password": { "post": { "operationId": "auth_resetPassword", "summary": "Reset customer password", "description": "Reset the customer password using a valid reset token received via email", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResetPassword" } } } }, "responses": { "204": { "description": "" } }, "tags": [ "Auth" ] } }, "/storefront/auth/resolve-link": { "get": { "operationId": "auth_resolveLink", "summary": "Resolve a magic link token", "description": "Validate a magic link token, authenticate the customer, and return redirect information", "parameters": [ { "name": "token", "required": true, "in": "query", "description": "Magic link token", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveLinkResponse" } } } } }, "tags": [ "Auth" ] } }, "/storefront/auth/request-login-code": { "post": { "operationId": "auth_requestLoginCode", "summary": "Request a login code", "description": "Send a 6-digit login code to the customer email for passwordless authentication", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestLoginCode" } } } }, "responses": { "204": { "description": "" } }, "tags": [ "Auth" ] } }, "/storefront/auth/verify-login-code": { "post": { "operationId": "auth_verifyLoginCode", "summary": "Verify a login code", "description": "Verify the 6-digit login code and return auth tokens for passwordless sign-in", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyLoginCode" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokensResponse" } } } } }, "tags": [ "Auth" ] } }, "/storefront/self-service/profile": { "get": { "operationId": "selfService_getProfile", "summary": "Get current customer profile", "parameters": [], "responses": { "200": { "description": "Customer profile returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelfServiceProfileResponse" } } } }, "401": { "description": "Unauthorized" } }, "tags": [ "Self-Service" ], "security": [ { "bearer": [] } ] }, "put": { "operationId": "selfService_updateProfile", "summary": "Update current customer profile", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomerProfile" } } } }, "responses": { "200": { "description": "Profile updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelfServiceProfileResponse" } } } }, "401": { "description": "Unauthorized" } }, "tags": [ "Self-Service" ], "security": [ { "bearer": [] } ] } }, "/storefront/self-service/marketing-consent": { "get": { "operationId": "selfService_getMarketingConsent", "summary": "Get current customer marketing consent", "parameters": [], "responses": { "200": { "description": "Marketing consent returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketingConsentResponse" } } } }, "401": { "description": "Unauthorized" } }, "tags": [ "Self-Service" ], "security": [ { "bearer": [] } ] }, "put": { "operationId": "selfService_updateMarketingConsent", "summary": "Update current customer marketing consent", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketingConsentInput" } } } }, "responses": { "200": { "description": "Marketing consent updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketingConsentResponse" } } } }, "401": { "description": "Unauthorized" } }, "tags": [ "Self-Service" ], "security": [ { "bearer": [] } ] } }, "/storefront/self-service/password": { "put": { "operationId": "selfService_changePassword", "summary": "Change current customer password", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomerPassword" } } } }, "responses": { "200": { "description": "Password changed successfully" }, "401": { "description": "Unauthorized" } }, "tags": [ "Self-Service" ], "security": [ { "bearer": [] } ] } }, "/storefront/appointments": { "post": { "operationId": "appointment_create", "summary": "Create appointment", "description": "Creates a new appointment for a customer. Authentication is optional - if authenticated, the appointment will be associated with the logged-in user.", "parameters": [], "requestBody": { "required": true, "description": "Appointment details to create", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAppointment" } } } }, "responses": { "201": { "description": "The appointment has been successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentCreatedResponse" } } } } }, "tags": [ "Appointments" ], "security": [ { "bearer": [] } ] }, "get": { "operationId": "appointment_list", "summary": "List customer appointments", "description": "Returns all appointments for the authenticated customer with pagination", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "Page number for pagination", "schema": { "minimum": 1, "default": 1, "example": 1, "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Number of items to return per page. Maximum allowed value is 100.", "schema": { "minimum": 1, "maximum": 100, "default": 50, "example": 50, "type": "number" } }, { "name": "status", "required": false, "in": "query", "description": "List of appointment status types to filter by", "schema": { "example": [ "scheduled", "completed" ], "type": "array", "items": { "type": "string", "enum": [ "pending", "scheduled", "completed", "canceled" ] } } }, { "name": "staffMembers", "required": false, "in": "query", "description": "List of staff member IDs to filter by", "schema": { "example": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "array", "items": { "type": "string" } } }, { "name": "products", "required": false, "in": "query", "description": "List of product/service IDs to filter by", "schema": { "example": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "array", "items": { "type": "string" } } }, { "name": "locations", "required": false, "in": "query", "description": "List of location IDs to filter by", "schema": { "example": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "array", "items": { "type": "string" } } }, { "name": "date", "required": false, "in": "query", "description": "Date to filter appointments by in YYYY-MM-DD format", "schema": { "pattern": "\\d{4}\\-(0[1-9]|1[012])\\-(0[1-9]|[12][0-9]|3[01])", "example": "2025-06-08", "type": "string" } }, { "name": "orderBy", "required": false, "in": "query", "description": "Field to order the results by", "schema": { "example": "from", "enum": [ "from", "to", "productId", "staffMemberId", "customerId", "createdAt" ], "type": "string" } }, { "name": "order", "required": false, "in": "query", "description": "Sort direction", "schema": { "default": "ASC", "example": "DESC", "enum": [ "ASC", "DESC" ], "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of items per page", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Collection of customer appointments", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AppointmentListItemResponse" } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" } } } } } } }, "tags": [ "Appointments" ], "security": [ { "bearer": [] } ] } }, "/storefront/appointments/{appointmentId}": { "get": { "operationId": "appointment_find", "summary": "Get appointment by ID", "description": "Returns a single appointment by ID for the authenticated customer", "parameters": [ { "name": "appointmentId", "required": true, "in": "path", "description": "Appointment unique identifier", "schema": { "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "The appointment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentDetailResponse" } } } } }, "tags": [ "Appointments" ], "security": [ { "bearer": [] } ] } }, "/storefront/appointments/by-external-order-name/{externalOrderName}": { "get": { "operationId": "appointment_findByExternalOrderName", "summary": "Get appointment by external order name", "description": "Returns a single appointment by its external order name. Useful for integrations with external payment or ordering systems.", "parameters": [ { "name": "externalOrderName", "required": true, "in": "path", "description": "External order name identifier", "schema": { "example": "order_123456789", "type": "string" } } ], "responses": { "200": { "description": "The appointment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentDetailResponse" } } } } }, "tags": [ "Appointments" ], "security": [ { "bearer": [] } ] } }, "/storefront/appointments/{appointmentId}/reschedule": { "put": { "operationId": "appointment_reschedule", "summary": "Reschedule appointment", "description": "Reschedules an existing appointment to a new time. Subject to reschedule_gap restrictions defined in the service configuration.", "parameters": [ { "name": "appointmentId", "required": true, "in": "path", "description": "Appointment unique identifier", "schema": { "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "requestBody": { "required": true, "description": "New appointment time details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RescheduleAppointment" } } } }, "responses": { "200": { "description": "The rescheduled appointment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentResponse" } } } } }, "tags": [ "Appointments" ], "security": [ { "bearer": [] } ] } }, "/storefront/appointments/{appointmentId}/cancel": { "put": { "operationId": "appointment_cancel", "summary": "Cancel appointment", "description": "Cancels an existing appointment. Subject to cancel_gap restrictions defined in the service configuration.", "parameters": [ { "name": "appointmentId", "required": true, "in": "path", "description": "Appointment unique identifier", "schema": { "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "requestBody": { "required": true, "description": "Cancellation details including reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelAppointment" } } } }, "responses": { "200": { "description": "The canceled appointment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentResponse" } } } } }, "tags": [ "Appointments" ], "security": [ { "bearer": [] } ] } }, "/storefront/appointments/{appointmentId}/feedback": { "post": { "operationId": "appointment_feedback", "summary": "Submit appointment feedback", "description": "Allows customers to submit feedback for a completed appointment", "parameters": [ { "name": "appointmentId", "required": true, "in": "path", "description": "Appointment unique identifier", "schema": { "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "requestBody": { "required": true, "description": "Feedback answers from the customer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackQuestionAnswers" } } } }, "responses": { "201": { "description": "The feedback has been successfully submitted", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FeedbackQuestionAnswerResponse" } } } } } }, "tags": [ "Appointments" ], "security": [ { "bearer": [] } ] } }, "/storefront/appointments/{appointmentId}/guests": { "post": { "operationId": "appointment_addGuest", "summary": "Add a guest to an appointment", "description": "Adds a guest (by email) to an appointment. Guests are copied on appointment notifications.", "parameters": [ { "name": "appointmentId", "required": true, "in": "path", "description": "Appointment unique identifier", "schema": { "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "requestBody": { "required": true, "description": "Guest email to add", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddGuest" } } } }, "responses": { "201": { "description": "Guest added to appointment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentGuestResponse" } } } } }, "tags": [ "Appointments" ], "security": [ { "bearer": [] } ] } }, "/storefront/appointments/{appointmentId}/guests/{guestId}": { "delete": { "operationId": "appointment_removeGuest", "summary": "Remove a guest from an appointment", "description": "Removes a guest from an appointment and (by default) notifies them of the removal.", "parameters": [ { "name": "appointmentId", "required": true, "in": "path", "description": "Appointment unique identifier", "schema": { "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } }, { "name": "guestId", "required": true, "in": "path", "description": "Guest unique identifier", "schema": { "example": "123e4567-e89b-12d3-a456-426614174111", "type": "string" } }, { "name": "notify", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Guest removed from appointment" } }, "tags": [ "Appointments" ], "security": [ { "bearer": [] } ] } }, "/storefront/appointments/preferences/booking-history": { "get": { "operationId": "appointment_getBookingPreferences", "summary": "Get customer booking preferences", "description": "Returns frequently booked services, locations, and staff members based on customer booking history. Results are cached for 24 hours to optimize performance.", "parameters": [], "responses": { "200": { "description": "Customer booking preferences and history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerBookingPreferencesResponse" } } } } }, "tags": [ "Appointments" ], "security": [ { "bearer": [] } ] } }, "/storefront/orders": { "get": { "operationId": "order_list", "summary": "List customer orders", "description": "Returns all orders for the authenticated customer with pagination", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "Page number for pagination (1-indexed)", "schema": { "minimum": 1, "default": 1, "example": 1, "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Number of items to return per page. Maximum allowed value is 100.", "schema": { "minimum": 1, "maximum": 100, "default": 50, "example": 50, "type": "number" } }, { "name": "name", "required": false, "in": "query", "description": "Filter orders by name", "schema": { "example": "1001", "type": "string" } }, { "name": "paymentStatuses", "required": false, "in": "query", "description": "Filter appointments by payment status", "schema": { "example": [ "paid" ], "type": "array", "items": { "type": "string", "enum": [ "unpaid", "paid", "partially-paid" ] } } }, { "name": "fulfillmentStatuses", "required": false, "in": "query", "description": "Filter appointments by fulfillment status", "schema": { "example": [ "unfulfilled", "partially-fulfilled" ], "type": "array", "items": { "type": "string", "enum": [ "partially-fulfilled", "fulfilled", "unfulfilled" ] } } }, { "name": "customers", "required": false, "in": "query", "description": "Filter orders by customer IDs", "schema": { "example": [ "123e4567-e89b-12d3-a456-426614174002" ], "type": "array", "items": { "type": "string" } } }, { "name": "services", "required": false, "in": "query", "description": "Filter orders by appointment services IDs", "schema": { "example": [ "123e4567-e89b-12d3-a456-426614174002" ], "type": "array", "items": { "type": "string" } } }, { "name": "staffMembers", "required": false, "in": "query", "description": "Filter orders by appointment staff member IDs", "schema": { "example": [ "123e4567-e89b-12d3-a456-426614174002" ], "type": "array", "items": { "type": "string" } } }, { "name": "locations", "required": false, "in": "query", "description": "Filter orders by appointment location IDs", "schema": { "example": [ "123e4567-e89b-12d3-a456-426614174002" ], "type": "array", "items": { "type": "string" } } }, { "name": "orderBy", "required": false, "in": "query", "description": "Field to order results by", "schema": { "example": "createdAt", "enum": [ "customerId", "createdAt" ], "type": "string" } }, { "name": "order", "required": false, "in": "query", "description": "Order direction", "schema": { "default": "ASC", "example": "DESC", "enum": [ "ASC", "DESC" ], "type": "string" } } ], "responses": { "200": { "description": "Collection of customer orders", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrderListItemResponse" } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" } } } } } } }, "tags": [ "Orders" ], "security": [ { "bearer": [] } ] } }, "/storefront/orders/{orderId}": { "get": { "operationId": "order_find", "summary": "Get order by ID", "description": "Returns a single order by ID for the authenticated customer", "parameters": [ { "name": "orderId", "required": true, "in": "path", "description": "Order unique identifier", "schema": { "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "The order details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDetailResponse" } } } } }, "tags": [ "Orders" ], "security": [ { "bearer": [] } ] } }, "/storefront/cart": { "post": { "operationId": "cart_createOrGet", "summary": "Create or fetch cart", "parameters": [ { "name": "X-Cart-Id", "required": true, "in": "header", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Cart created or fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartResponse" } } } } }, "tags": [ "Cart" ], "security": [ { "bearer": [] } ] }, "get": { "operationId": "cart_get", "summary": "Fetch cart", "parameters": [ { "name": "X-Cart-Id", "required": true, "in": "header", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Cart fetched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartResponse" } } } } }, "tags": [ "Cart" ], "security": [ { "bearer": [] } ] } }, "/storefront/cart/items": { "post": { "operationId": "cart_addItem", "summary": "Add appointment to cart", "parameters": [ { "name": "X-Cart-Id", "required": true, "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCartItem" } } } }, "responses": { "201": { "description": "Item added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartResponse" } } } } }, "tags": [ "Cart" ], "security": [ { "bearer": [] } ] } }, "/storefront/cart/items/{itemId}": { "delete": { "operationId": "cart_removeItem", "summary": "Remove cart item", "parameters": [ { "name": "itemId", "required": true, "in": "path", "description": "Cart item ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Item removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartResponse" } } } } }, "tags": [ "Cart" ], "security": [ { "bearer": [] } ] } }, "/storefront/cart/extend": { "post": { "operationId": "cart_extendExpiration", "summary": "Extend cart expiration by 5 minutes", "parameters": [ { "name": "X-Cart-Id", "required": true, "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cart expiration extended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartResponse" } } } } }, "tags": [ "Cart" ], "security": [ { "bearer": [] } ] } }, "/storefront/cart/items/{cartItemId}/add-ons": { "post": { "operationId": "cart_addAddOn", "summary": "Add an add-on to a cart item", "parameters": [ { "name": "cartItemId", "required": true, "in": "path", "description": "Cart item ID", "schema": { "type": "string" } }, { "name": "X-Cart-Id", "required": true, "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddCartAddOn" } } } }, "responses": { "201": { "description": "Add-on added to cart item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartResponse" } } } } }, "tags": [ "Cart" ], "security": [ { "bearer": [] } ] } }, "/storefront/cart/add-ons/{cartAddOnItemId}": { "patch": { "operationId": "cart_updateAddOnQuantity", "summary": "Update quantity of a cart add-on item", "parameters": [ { "name": "cartAddOnItemId", "required": true, "in": "path", "description": "Cart add-on item ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCartAddOn" } } } }, "responses": { "200": { "description": "Cart add-on quantity updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartResponse" } } } } }, "tags": [ "Cart" ], "security": [ { "bearer": [] } ] }, "delete": { "operationId": "cart_removeAddOn", "summary": "Remove a cart add-on item", "parameters": [ { "name": "cartAddOnItemId", "required": true, "in": "path", "description": "Cart add-on item ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cart add-on removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartResponse" } } } } }, "tags": [ "Cart" ], "security": [ { "bearer": [] } ] } }, "/storefront/cart/checkout/start": { "post": { "operationId": "checkout_start", "summary": "Start checkout for cart (create payment, validate items)", "parameters": [ { "name": "X-Cart-Id", "required": true, "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartCheckout" } } } }, "responses": { "201": { "description": "Checkout started with provider info and client secret (if any).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutStartResponse" } } } } }, "tags": [ "Checkout" ], "security": [ { "bearer": [] } ] } }, "/storefront/cart/checkout/submit": { "post": { "operationId": "checkout_submit", "summary": "Submit checkout (capture payment, create order, auto-authenticate customer)", "description": "Creates order and returns auth tokens for automatic customer authentication", "parameters": [ { "name": "X-Cart-Id", "required": true, "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitCheckout" } } } }, "responses": { "200": { "description": "Order created with optional auth tokens for customer auto-authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutResponse" } } } } }, "tags": [ "Checkout" ], "security": [ { "bearer": [] } ] } }, "/storefront/cart/checkout/questions/{language}": { "get": { "operationId": "checkout_getCartQuestions", "summary": "Get all checkout questions for current cart", "parameters": [ { "name": "X-Cart-Id", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "language", "required": true, "in": "path", "description": "Language code for translations", "schema": { "example": "en" } } ], "responses": { "200": { "description": "Checkout questions for all cart items", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CartCheckoutQuestionResponse" } } } } } }, "tags": [ "Checkout" ], "security": [ { "bearer": [] } ] } }, "/storefront/cart/checkout/save-customer": { "post": { "operationId": "checkout_saveCustomer", "summary": "Save customer information to cart and appointments", "parameters": [ { "name": "X-Cart-Id", "required": true, "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutCustomer" } } } }, "responses": { "200": { "description": "Customer saved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveCustomerResponse" } } } } }, "tags": [ "Checkout" ], "security": [ { "bearer": [] } ] } }, "/storefront/cart/checkout/save-answers": { "post": { "operationId": "checkout_saveAnswers", "summary": "Save checkout question answers to appointments", "parameters": [ { "name": "X-Cart-Id", "required": true, "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutQuestionAnswers" } } } }, "responses": { "200": { "description": "Answers saved successfully" } }, "tags": [ "Checkout" ], "security": [ { "bearer": [] } ] } }, "/storefront/cart/discount-code": { "post": { "operationId": "cartDiscount_applyCode", "summary": "Apply a discount/promo code to the cart", "parameters": [ { "name": "X-Cart-Id", "required": true, "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyCode" } } } }, "responses": { "200": { "description": "Cart with discount applied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartResponse" } } } }, "400": { "description": "The code could not be applied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscountCodeErrorResponse" } } } } }, "tags": [ "Cart" ], "security": [ { "bearer": [] } ] }, "delete": { "operationId": "cartDiscount_removeCode", "summary": "Remove the applied discount/promo code from the cart", "parameters": [ { "name": "X-Cart-Id", "required": true, "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cart with discount removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartResponse" } } } } }, "tags": [ "Cart" ], "security": [ { "bearer": [] } ] } }, "/storefront/stores/public-settings": { "get": { "operationId": "store_getStorePublicSettings", "summary": "Get store public settings", "parameters": [], "responses": { "200": { "description": "Public settings retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePublicSettings" } } } } }, "tags": [ "Store" ] } }, "/storefront/products/slug/{slug}": { "get": { "operationId": "product_getBySlug", "summary": "Get product by slug", "description": "Retrieve a product by its URL-friendly slug for the current store", "parameters": [ { "name": "slug", "required": true, "in": "path", "description": "Product slug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Product retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductSlugResponse" } } } } }, "tags": [ "Products" ] } }, "/storefront/products/{productId}": { "get": { "operationId": "product_get", "summary": "Get product by ID", "description": "Retrieve a product by its internal ID for the current store", "parameters": [ { "name": "productId", "required": true, "in": "path", "description": "Product ID", "schema": { "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "Product retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDetailResponse" } } } } }, "tags": [ "Products" ] } }, "/storefront/products/by-external-id/{productExternalId}": { "get": { "operationId": "product_getByExternalId", "summary": "Get products by external ID", "description": "Retrieve products by their external platform ID (e.g., Shopify product ID) for the current store", "parameters": [ { "name": "productExternalId", "required": true, "in": "path", "description": "External ID (e.g., Shopify product ID)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Products retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProductExternalIdResponse" } } } } } }, "tags": [ "Products" ] } }, "/storefront/products/by-external-variant-id/{productExternalVariantId}": { "get": { "operationId": "product_getByExternalVariantId", "summary": "Get a product by external variant ID", "description": "Retrieve a product by its external variant ID (e.g., Shopify variant ID) for the current store", "parameters": [ { "name": "productExternalVariantId", "required": true, "in": "path", "description": "External variant ID (e.g., Shopify variant ID)", "schema": { "example": "9876543210", "type": "string" } } ], "responses": { "200": { "description": "Product retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductExternalVariantResponse" } } } }, "404": { "description": "Product not found" } }, "tags": [ "Products" ] } }, "/storefront/products": { "get": { "operationId": "product_list", "summary": "List store products", "description": "Retrieve a paginated list of active products for the current store, for the current store", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "Page number for pagination (1-indexed)", "schema": { "minimum": 1, "default": 1, "example": 1, "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Number of items to return per page. Maximum allowed value is 100.", "schema": { "minimum": 1, "maximum": 100, "default": 50, "example": 50, "type": "number" } }, { "name": "q", "required": false, "in": "query", "description": "Search query to filter products by name or description", "schema": { "example": "haircut", "type": "string" } }, { "name": "locationId", "required": false, "in": "query", "description": "Filter products by location", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "Filter products by status", "schema": { "example": [ "active" ], "type": "array", "items": { "type": "string", "enum": [ "active", "inactive" ] } } }, { "name": "orderBy", "required": false, "in": "query", "description": "Field to order results by", "schema": { "example": "title", "type": "string" } }, { "name": "order", "required": false, "in": "query", "description": "Sort direction", "schema": { "default": "ASC", "enum": [ "ASC", "DESC" ], "type": "string" } } ], "responses": { "200": { "description": "List of products for the current store", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductListItemResponse" } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" } } } } } } }, "tags": [ "Products" ] } }, "/storefront/products/{productId}/nearest-availability": { "get": { "operationId": "product_getNearestAvailability", "summary": "Get the nearest available slot for a product", "description": "Find the nearest upcoming availability slot for a product. Returns null/204 if no slot exists within the advance schedule window.", "parameters": [ { "name": "productId", "required": true, "in": "path", "description": "ID of the product", "schema": { "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } }, { "name": "locationId", "required": false, "in": "query", "description": "Filter by location ID", "schema": { "type": "string" } }, { "name": "staffMemberId", "required": false, "in": "query", "description": "Filter by staff member ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Nearest available slot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailabilitySlot" } } } }, "204": { "description": "No availability found within the advance schedule window" } }, "tags": [ "Products" ] } }, "/storefront/products/{productId}/current-availabilities": { "get": { "operationId": "product_getCurrentAvailabilities", "summary": "Get current availabilities for a product", "description": "Retrieve individual bookable time slots for a product on a given date.", "parameters": [ { "name": "productId", "required": true, "in": "path", "description": "ID of the product", "schema": { "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } }, { "name": "date", "required": true, "in": "query", "description": "Date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "locationId", "required": false, "in": "query", "description": "Filter by location ID", "schema": { "type": "string" } }, { "name": "staffMemberId", "required": false, "in": "query", "description": "Filter by staff member ID", "schema": { "type": "string" } }, { "name": "timezone", "required": false, "in": "query", "description": "Timezone for date/time calculations", "schema": { "type": "string" } }, { "name": "duration", "required": false, "in": "query", "description": "Booking duration in seconds; defaults to the product base duration", "schema": { "type": "string" } }, { "name": "excludeAppointmentId", "required": false, "in": "query", "description": "Appointment to exclude from the busy overlay. Pass the appointment being moved when rescheduling so its own slot is not treated as taken.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Availabilities", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CurrentAvailabilitySlot" } } } } } }, "tags": [ "Products" ] } }, "/storefront/products/{productId}/current-availability-ranges": { "get": { "operationId": "product_getCurrentAvailabilitiesMerged", "summary": "Get merged availability ranges for a product", "description": "Retrieve merged availability ranges (broad time windows) for a product. Useful for calendar date highlighting.", "parameters": [ { "name": "productId", "required": true, "in": "path", "description": "ID of the product", "schema": { "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } }, { "name": "locationId", "required": false, "in": "query", "description": "Filter by location ID", "schema": { "type": "string" } }, { "name": "staffMemberId", "required": false, "in": "query", "description": "Filter by staff member ID", "schema": { "type": "string" } }, { "name": "date", "required": false, "in": "query", "description": "Date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "timezone", "required": false, "in": "query", "description": "Timezone for date/time calculations", "schema": { "type": "string" } }, { "name": "duration", "required": false, "in": "query", "description": "Booking duration in seconds; defaults to the product base duration. Ranges too short for the requested duration are omitted.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Availability ranges", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CurrentAvailabilitySlot" } } } } } }, "tags": [ "Products" ] } }, "/storefront/products/{productId}/add-ons": { "get": { "operationId": "product_listAddOns", "summary": "List available add-ons for a product", "description": "Returns active add-ons available for the given product, filtered by location and staff member assignments.", "parameters": [ { "name": "productId", "required": true, "in": "path", "description": "Product ID", "schema": { "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } }, { "name": "locationId", "required": false, "in": "query", "description": "Filter by location", "schema": { "type": "string" } }, { "name": "staffMemberId", "required": false, "in": "query", "description": "Filter by staff member", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Add-ons returned", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AddOnListItemResponse" } } } } } }, "tags": [ "Products" ] } }, "/storefront/products/slug/{slug}/add-ons": { "get": { "operationId": "product_listAddOnsBySlug", "summary": "List available add-ons for a product by slug", "description": "Returns active add-ons available for the given product slug, filtered by location and staff member assignments.", "parameters": [ { "name": "slug", "required": true, "in": "path", "description": "Product slug", "schema": { "type": "string" } }, { "name": "locationId", "required": false, "in": "query", "description": "Filter by location", "schema": { "type": "string" } }, { "name": "staffMemberId", "required": false, "in": "query", "description": "Filter by staff member", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Add-ons returned", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AddOnListItemResponse" } } } } } }, "tags": [ "Products" ] } }, "/storefront/locations/slug/{slug}": { "get": { "operationId": "location_getBySlug", "summary": "Get location by slug", "description": "Retrieve a location by its URL-friendly slug for current store", "parameters": [ { "name": "slug", "required": true, "in": "path", "description": "Location slug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Location retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationDetailResponse" } } } } }, "tags": [ "Locations" ] } }, "/storefront/locations/{locationId}": { "get": { "operationId": "location_get", "summary": "Get location by ID", "description": "Retrieve a location by its internal ID for current store", "parameters": [ { "name": "locationId", "required": true, "in": "path", "description": "Location ID", "schema": { "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "Location retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationDetailResponse" } } } } }, "tags": [ "Locations" ] } }, "/storefront/locations": { "get": { "operationId": "location_list", "summary": "List store locations", "description": "Retrieve a paginated list of locations for the current store", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "Page number for pagination (1-indexed)", "schema": { "minimum": 1, "default": 1, "example": 1, "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Number of items to return per page. Maximum allowed value is 100.", "schema": { "minimum": 1, "maximum": 100, "default": 50, "example": 50, "type": "number" } }, { "name": "q", "required": false, "in": "query", "description": "Search query to filter locations by title or description", "schema": { "example": "Main Office", "type": "string" } }, { "name": "orderBy", "required": false, "in": "query", "description": "Field to order results by", "schema": { "example": "createdAt", "enum": [ "id", "title", "createdAt", "type" ], "type": "string" } }, { "name": "order", "required": false, "in": "query", "description": "Order direction", "schema": { "default": "ASC", "example": "DESC", "enum": [ "ASC", "DESC" ], "type": "string" } } ], "responses": { "200": { "description": "List of locations for the current store", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LocationDetailResponse" } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" } } } } } } }, "tags": [ "Locations" ] } }, "/storefront/product-collections/slug/{slug}": { "get": { "operationId": "productCollections_getBySlug", "summary": "Get product collection by slug", "description": "Retrieve a product collection by its URL-friendly slug for the current store", "parameters": [ { "name": "slug", "required": true, "in": "path", "description": "Product collection slug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Product collection retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCollectionResponse" } } } } }, "tags": [ "Product Collections" ] } }, "/storefront/product-collections": { "get": { "operationId": "productCollections_list", "summary": "List store product collections", "description": "Retrieve a paginated list of product collections for the current store", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "Page number for pagination (1-indexed)", "schema": { "minimum": 1, "default": 1, "example": 1, "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Number of items to return per page. Maximum allowed value is 100.", "schema": { "minimum": 1, "maximum": 100, "default": 50, "example": 50, "type": "number" } }, { "name": "q", "required": false, "in": "query", "description": "Search query to filter collections by title or description", "schema": { "example": "wellness", "type": "string" } }, { "name": "isVisible", "required": false, "in": "query", "description": "Filter collections by active status", "schema": { "example": true, "type": "boolean" } }, { "name": "orderBy", "required": false, "in": "query", "description": "Field to order results by", "schema": { "example": "title", "enum": [ "title", "createdAt", "updatedAt" ], "type": "string" } }, { "name": "order", "required": false, "in": "query", "description": "Sort direction", "schema": { "default": "ASC", "enum": [ "ASC", "DESC" ], "type": "string" } } ], "responses": { "200": { "description": "List of product collections for the current store", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductCollectionResponse" } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" } } } } } } }, "tags": [ "Product Collections" ] } }, "/storefront/staff-members/slug/{slug}": { "get": { "operationId": "staffMember_getBySlug", "summary": "Get staff member by slug", "description": "Retrieve a staff member by their URL-friendly slug for current store", "parameters": [ { "name": "slug", "required": true, "in": "path", "description": "Staff member slug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Staff member retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffMemberDetailResponse" } } } } }, "tags": [ "Staff Members" ] } }, "/storefront/staff-members": { "get": { "operationId": "staffMember_list", "summary": "List store staff members", "description": "Retrieve a paginated list of staff members for the current store", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "Page number for pagination (1-indexed)", "schema": { "minimum": 1, "default": 1, "example": 1, "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Number of items to return per page. Maximum allowed value is 100.", "schema": { "minimum": 1, "maximum": 100, "default": 50, "example": 50, "type": "number" } }, { "name": "q", "required": false, "in": "query", "description": "Search query to filter staff members by name or email", "schema": { "example": "john", "type": "string" } }, { "name": "orderBy", "required": false, "in": "query", "description": "Field to order results by", "schema": { "example": "createdAt", "type": "string" } }, { "name": "order", "required": false, "in": "query", "description": "Order direction", "schema": { "default": "ASC", "enum": [ "ASC", "DESC" ], "type": "string" } } ], "responses": { "200": { "description": "List of staff members for the current store", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StaffMemberListItemResponse" } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" } } } } } } }, "tags": [ "Staff Members" ] } }, "/storefront/add-ons": { "get": { "operationId": "addOn_list", "summary": "List add-ons for the current store", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "Page number for pagination (1-indexed)", "schema": { "minimum": 1, "default": 1, "example": 1, "type": "number" } }, { "name": "take", "required": false, "in": "query", "description": "Number of items to return per page. Maximum allowed value is 100.", "schema": { "minimum": 1, "maximum": 100, "default": 50, "example": 50, "type": "number" } }, { "name": "q", "required": false, "in": "query", "description": "Search query to filter add-ons by title or slug", "schema": { "example": "child seat", "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "Filter add-ons by status (accepts one or more statuses)", "schema": { "example": [ "active" ], "type": "array", "items": { "type": "string", "enum": [ "active", "inactive" ] } } }, { "name": "productId", "required": false, "in": "query", "description": "Filter add-ons by product ID (only return add-ons attached to this product)", "schema": { "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } }, { "name": "locationId", "required": false, "in": "query", "description": "Filter add-ons by location ID (only return add-ons available at this location)", "schema": { "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } }, { "name": "staffMemberId", "required": false, "in": "query", "description": "Filter add-ons by staff member ID (only return add-ons available with this staff member)", "schema": { "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "List of add-ons for the current store", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AddOnListItemResponse" } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" } } } } } } }, "tags": [ "Add-ons" ] } }, "/storefront/add-ons/{addOnId}": { "get": { "operationId": "addOn_get", "summary": "Get an add-on by ID", "parameters": [ { "name": "addOnId", "required": true, "in": "path", "description": "Add-on ID", "schema": { "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "Add-on returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddOnDetailResponse" } } } } }, "tags": [ "Add-ons" ] } }, "/storefront/add-ons/slug/{slug}": { "get": { "operationId": "addOn_getBySlug", "summary": "Get an add-on by slug", "parameters": [ { "name": "slug", "required": true, "in": "path", "description": "Add-on slug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Add-on returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddOnDetailResponse" } } } } }, "tags": [ "Add-ons" ] } }, "/storefront/payment/providers": { "get": { "operationId": "payment_getAvailableProviders", "summary": "Get available payment providers for checkout", "description": "Returns the active, eligible payment providers configured for this store. When the cart is identified (X-Cart-Id header or cart_id cookie) the list is amount-aware: only providers that can charge the current total are returned, and when nothing is collectible (fully discounted, or below every method’s minimum) a single \"no_payment_required\" provider is returned.", "parameters": [ { "name": "X-Cart-Id", "required": true, "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of available payment providers", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerProviderCatalogItem" } } } } } }, "tags": [ "Payment" ] } }, "/storefront/payment/settings": { "get": { "operationId": "payment_getSettings", "summary": "Get public payment settings", "description": "Returns public payment configuration like currency and capture method.", "parameters": [], "responses": { "200": { "description": "Public payment settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentSettingResponse" } } } } }, "tags": [ "Payment" ] } }, "/storefront/orders/{orderId}/invoices": { "get": { "operationId": "invoice_list", "summary": "List invoices issued for the authenticated customer order", "parameters": [ { "name": "orderId", "required": true, "in": "path", "description": "Unique identifier of the order", "schema": { "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceResponse" } } } } } }, "tags": [ "Invoices" ], "security": [ { "bearer": [] } ] } }, "/storefront/feedback-questions/{productId}/translations/{language}": { "get": { "operationId": "feedbackQuestion_listTranslations", "summary": "List feedback questions translations", "parameters": [ { "name": "productId", "required": true, "in": "path", "description": "ID of the product", "schema": { "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } }, { "name": "language", "required": true, "in": "path", "description": "Language code", "schema": { "$ref": "#/components/schemas/LanguageCode" } } ], "responses": { "200": { "description": "Feedback questions with translations", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FeedbackQuestionResponse" } } } } } }, "tags": [ "Feedback Questions" ] } }, "/storefront/checkout-questions/{productId}/translations/{language}": { "get": { "operationId": "checkoutQuestion_listTranslations", "summary": "List checkout questions translations for a product", "parameters": [ { "name": "productId", "required": true, "in": "path", "description": "ID of the product", "schema": { "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } }, { "name": "language", "required": true, "in": "path", "description": "Language code", "schema": { "$ref": "#/components/schemas/LanguageCode" } } ], "responses": { "200": { "description": "Checkout questions with translations", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutQuestionResponse" } } } } } }, "tags": [ "Checkout Questions" ] } }, "/storefront/uploads/presign": { "post": { "operationId": "customerUpload_presign", "summary": "Generate a presigned S3 URL for a customer file upload", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateUploadUrl" } } } }, "responses": { "200": { "description": "Presigned upload URL + file id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateUploadUrlResponse" } } } } }, "tags": [ "Customer Uploads" ] } }, "/storefront/images/{imageId}": { "get": { "operationId": "image_get", "summary": "Get image by ID", "parameters": [ { "name": "imageId", "required": true, "in": "path", "description": "Image unique identifier", "schema": { "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "Image", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageResponse" } } } } }, "tags": [ "Images" ] } } }, "info": { "title": "Opencals API", "description": "# Opencals Storefront API\n\nBuild custom booking storefronts with the Opencals Storefront API. Browse services, check real-time availability, manage carts, process payments, and complete bookings — all programmatically.\n\n---\n\n## Getting Started\n\n### 1. Create an Account\n\nSign up at [app.opencals.com](https://app.opencals.com) and set up your store with services, staff members, locations, and schedules.\n\n### 2. Generate a Storefront API Key\n\nNavigate to **Settings > API Keys** in your dashboard. Create a new **Storefront API Key**. Each key is scoped to your store and starts with `sfk_`.\n\n### 3. Make Your First Request\n\n```bash\ncurl -H \"X-Api-Key: sfk_your_key_here\" \\\n https://api.opencals.com/customer/products\n```\n\nThis returns a paginated list of your store's active services.\n\n---\n\n## Authentication\n\n### Storefront API Key\n\nAll requests require a **Storefront API Key** in the `X-Api-Key` header:\n\n```\nX-Api-Key: sfk_your_key_here\n```\n\nThis key identifies your store. It should be kept server-side (e.g., in environment variables) and never exposed to the browser.\n\n### Customer Authentication\n\nSome endpoints require a logged-in customer (viewing appointments, managing profile). Customers authenticate via credentials and receive JWT tokens:\n\n```http\nPOST /auth/customer/sign-in\nX-Api-Key: sfk_your_key_here\nContent-Type: application/json\n\n{\n \"email\": \"customer@example.com\",\n \"password\": \"securepassword\"\n}\n```\n\n**Response:**\n```json\n{\n \"accessToken\": \"eyJhbGciOi...\",\n \"refreshToken\": \"eyJhbGciOi...\"\n}\n```\n\nInclude the customer token alongside the API key for authenticated requests:\n```\nAuthorization: Bearer \nX-Api-Key: sfk_your_key_here\n```\n\n### Customer Auth Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `POST` | `/auth/customer/sign-up` | Register a new customer (sends verification email) |\n| `POST` | `/auth/customer/sign-in` | Sign in with email + password |\n| `POST` | `/auth/customer/oauth` | Sign in/register via OAuth provider (e.g., Google) |\n| `POST` | `/auth/customer/verify-email` | Verify email with token from verification email |\n| `POST` | `/auth/customer/request-email-verification` | Resend verification email |\n| `POST` | `/auth/customer/request-password-reset` | Send password reset email |\n| `POST` | `/auth/customer/reset-password` | Reset password with token |\n| `GET` | `/auth/customer/refresh` | Refresh tokens (pass refresh token as Bearer) |\n\n---\n\n## Booking Flows\n\nThe booking flow depends on your product configuration. Below are the common patterns.\n\n### Standard Booking (Single Time Slot)\n\nThe most common flow — customer picks a service, selects a date/time, and books.\n\n```\n1. GET /customer/products → Browse services\n2. GET /customer/products/:id/current-availabilities → Get available time slots for a date\n ?date=2026-06-15&timezone=America/New_York\n3. POST /customer/appointments → Create appointment with chosen slot\n { slot: { productId, fromDate, fromTime, toDate, toTime }, numberOfAttendees: 1 }\n4. POST /customer/cart → Create or get cart\n5. POST /customer/cart/items → Add appointment to cart\n { appointmentId: \"...\" }\n6. POST /customer/cart/checkout/start → Start checkout with payment provider\n { provider: \"stripe\" }\n7. POST /customer/cart/checkout/save-customer → Save customer info\n { customer: { email, firstName, lastName } }\n8. POST /customer/cart/checkout/submit → Complete booking & capture payment\n```\n\n### Custom Duration / Date Range Booking\n\nWhen a product has **custom duration** enabled (e.g., car rentals, venue bookings), customers select a date range instead of a single time slot.\n\n**How to detect:** The product's `isCustomDuration` field is `true`.\n\n```\n1. GET /customer/products/:id/current-availability-ranges → Get available date ranges\n ?timezone=America/New_York\n2. UI shows a date range picker instead of individual slots\n3. POST /customer/appointments\n { slot: { productId, fromDate: \"2026-06-15\", fromTime: \"09:00:00\",\n toDate: \"2026-06-18\", toTime: \"17:00:00\" } }\n4. Continue with cart → checkout flow as above\n```\n\n### Group Appointments\n\nWhen a product supports multiple attendees (`maxAttendees > 1`), display an attendees selector.\n\n```\nPOST /customer/appointments\n{\n \"slot\": { ... },\n \"numberOfAttendees\": 4\n}\n```\n\n### Location-First Flow\n\nWhen a store has multiple locations, let the customer pick a location first, then filter services and availability by location.\n\n```\n1. GET /customer/locations → List all locations\n2. User selects a location\n3. GET /customer/products?locationId= → Products at that location\n4. GET /customer/products/:id/current-availabilities\n ?date=2026-06-15&locationId= → Slots at that location\n5. POST /customer/appointments\n { slot: { ..., locationId: \"\" } }\n```\n\n### Staff-First Flow\n\nWhen staff member selection is important (e.g., hair salons), let customers choose their preferred staff member.\n\n```\n1. GET /customer/staff-members → List staff members\n2. User selects a staff member\n3. GET /customer/products/:id/current-availabilities\n ?date=2026-06-15&staffMemberId= → Slots with that staff member\n4. POST /customer/appointments\n { slot: { ..., staffMemberId: \"\" } }\n```\n\n### Combined Flow (Location + Staff + Service)\n\nAll filters can be combined:\n\n```\nGET /customer/products/:id/current-availabilities\n ?date=2026-06-15\n &locationId=\n &staffMemberId=\n &timezone=America/New_York\n```\n\n---\n\n## Product Configuration Flags\n\nProducts have configuration fields that determine which UI elements to display. Check these fields when rendering your booking interface:\n\n| Field | Type | UI Behavior |\n|-------|------|-------------|\n| `isCustomDuration` | `boolean` | `true` → show date range picker; `false` → show single time slot picker |\n| `maxAttendees` | `number` | `> 1` → show attendees selector; `1` → hide it |\n| `skipCheckout` | `boolean` | `true` → skip payment step, book directly; `false` → normal checkout |\n| `fixedStartTimes` / `fixedEndTimes` | `string[]` | If present, only these specific times are bookable |\n| `locations` | `Location[]` | If populated, show location selector |\n| `staffMembers` | `StaffMember[]` | If populated, show staff member selector |\n| `price` | `number` | Service price; `0` = free |\n| `minPrice` / `maxPrice` | `number` | Price range for variable-priced services |\n| `duration` | `number` | Service duration in seconds |\n| `minDuration` / `maxDuration` | `number` | Duration range for custom duration services |\n| `images` | `Image[]` | Product images for gallery display |\n| `description` | `string` | Product description (may contain markdown) |\n\n---\n\n## Endpoint Reference\n\n### Products\n\n| Method | Endpoint | Auth | Description |\n|--------|----------|------|-------------|\n| `GET` | `/customer/products` | API key | List all active products (paginated) |\n| `GET` | `/customer/products/:id` | API key | Get product by ID |\n| `GET` | `/customer/products/slug/:slug` | API key | Get product by URL slug |\n| `GET` | `/customer/products/:id/current-availabilities` | API key | Get bookable time slots for a date |\n| `GET` | `/customer/products/:id/current-availability-ranges` | API key | Get available date ranges (for custom duration) |\n| `GET` | `/customer/products/:id/nearest-availability` | API key | Find next available slot |\n\n**Availability query parameters:**\n\n| Parameter | Required | Description |\n|-----------|----------|-------------|\n| `date` | Yes (for current-availabilities) | Date in `YYYY-MM-DD` format |\n| `locationId` | No | Filter by location |\n| `staffMemberId` | No | Filter by staff member |\n| `timezone` | No | Timezone for date/time calculations (e.g., `America/New_York`) |\n\n### Product Collections\n\n| Method | Endpoint | Auth | Description |\n|--------|----------|------|-------------|\n| `GET` | `/customer/product-collections` | API key | List all collections (paginated) |\n| `GET` | `/customer/product-collections/slug/:slug` | API key | Get collection by slug |\n\n### Locations\n\n| Method | Endpoint | Auth | Description |\n|--------|----------|------|-------------|\n| `GET` | `/customer/locations` | API key | List all locations (paginated) |\n| `GET` | `/customer/locations/:id` | API key | Get location by ID |\n| `GET` | `/customer/locations/slug/:slug` | API key | Get location by slug |\n\n### Staff Members\n\n| Method | Endpoint | Auth | Description |\n|--------|----------|------|-------------|\n| `GET` | `/customer/staff-members` | API key | List all staff members (paginated) |\n| `GET` | `/customer/staff-members/slug/:slug` | API key | Get staff member by slug |\n\n### Cart\n\nAll cart endpoints use the `X-Cart-Id` header to identify the cart.\n\n| Method | Endpoint | Auth | Description |\n|--------|----------|------|-------------|\n| `POST` | `/customer/cart` | API key | Create or retrieve a cart |\n| `GET` | `/customer/cart` | API key | Get current cart |\n| `POST` | `/customer/cart/items` | API key | Add an appointment to the cart |\n| `DELETE` | `/customer/cart/items/:itemId` | API key | Remove item from cart |\n| `POST` | `/customer/cart/extend` | API key | Extend cart expiration (5 min) |\n\n**Adding items to cart:**\n```json\nPOST /customer/cart/items\nX-Cart-Id: \n\n{ \"appointmentId\": \"appointment-uuid-here\" }\n```\n\n### Add-Ons\n\nAdd-ons are optional extras customers can attach to a cart item at checkout (equipment rentals, upgrades, accessories, etc.). Add-ons are scoped to products — only add-ons assigned to the booked service appear.\n\n**Storefront (listing):**\n\n| Method | Endpoint | Auth | Description |\n|--------|----------|------|-------------|\n| `GET` | `/storefront/add-ons` | API key | List add-ons (filter by `productId`) |\n| `GET` | `/storefront/add-ons/:id` | API key | Get add-on by ID |\n| `GET` | `/storefront/add-ons/slug/:slug` | API key | Get add-on by slug |\n| `GET` | `/storefront/products/:id/add-ons` | API key | List add-ons for a specific product |\n\n**Cart (selection):**\n\nAll cart add-on endpoints require the `X-Cart-Id` header.\n\n| Method | Endpoint | Auth | Description |\n|--------|----------|------|-------------|\n| `POST` | `/storefront/cart/add-ons` | API key | Add an add-on to a cart item |\n| `PATCH` | `/storefront/cart/add-ons/:id` | API key | Update add-on quantity |\n| `DELETE` | `/storefront/cart/add-ons/:id` | API key | Remove add-on from cart |\n\n**Adding an add-on to a cart item:**\n```json\nPOST /storefront/cart/add-ons\nX-Cart-Id: \n\n{\n \"cartItemId\": \"uuid-of-cart-item\",\n \"addOnId\": \"uuid-of-add-on\",\n \"quantity\": 1\n}\n```\n\nThe system validates that the add-on is assigned to the cart item's product and that `quantity` does not exceed `maxQuantity` (if set). For duration-multiplied add-ons, quantity is auto-set to match the service duration units — send any value and it will be overridden.\n\n**Add-on object (storefront response):**\n```json\n{\n \"id\": \"addon-uuid\",\n \"slug\": \"deep-conditioning\",\n \"title\": \"Deep Conditioning Treatment\",\n \"description\": \"Intensive moisture treatment added to any color or cut service.\",\n \"price\": 20.00,\n \"taxable\": true,\n \"durationMultiplied\": false,\n \"maxQuantity\": 1,\n \"status\": \"active\",\n \"imageId\": \"img-uuid-or-null\"\n}\n```\n\n**Pricing notes:**\n- `price` — unit price. For duration-multiplied add-ons, multiply by duration units to get the total.\n- `durationMultiplied: true` — quantity is auto-set to the number of base-duration units booked (useful for per-day or per-hour charges).\n- Prices are snapshotted at cart/order creation. Later catalog price changes do not affect existing orders.\n\n**In the order response**, add-ons appear as `addOnLineItems` on each line item:\n```json\n{\n \"lineItems\": [\n {\n \"id\": \"...\",\n \"appointmentId\": \"...\",\n \"addOnLineItems\": [\n {\n \"id\": \"...\",\n \"addOnId\": \"...\",\n \"title\": \"Deep Conditioning Treatment\",\n \"quantity\": 1,\n \"originalUnitPrice\": 20.00,\n \"unitTaxAmount\": 3.33,\n \"totalPrice\": 20.00\n }\n ]\n }\n ]\n}\n```\n\n### Checkout\n\nAll checkout endpoints require the `X-Cart-Id` header.\n\n| Method | Endpoint | Auth | Description |\n|--------|----------|------|-------------|\n| `POST` | `/customer/cart/checkout/start` | API key | Start checkout (initialize payment) |\n| `POST` | `/customer/cart/checkout/save-customer` | API key | Save customer info to cart |\n| `GET` | `/customer/cart/checkout/questions/:language` | API key | Get checkout questions |\n| `POST` | `/customer/cart/checkout/save-answers` | API key | Save checkout question answers |\n| `POST` | `/customer/cart/checkout/submit` | API key | Submit checkout (capture payment, create order) |\n\n**Start checkout:**\n```json\nPOST /customer/cart/checkout/start\nX-Cart-Id: \n\n{\n \"provider\": \"stripe\",\n \"customer\": {\n \"email\": \"john@example.com\",\n \"firstName\": \"John\",\n \"lastName\": \"Smith\"\n }\n}\n```\n\nThe `provider` field accepts: `stripe`, `cash`, or other configured payment providers.\n\n**Submit checkout response** includes order details and optionally auto-generated customer auth tokens:\n```json\n{\n \"order\": { \"id\": \"...\", \"name\": \"#1001\", ... },\n \"tokens\": {\n \"accessToken\": \"eyJ...\",\n \"refreshToken\": \"eyJ...\"\n }\n}\n```\n\n### Appointments (Customer Authenticated)\n\n| Method | Endpoint | Auth | Description |\n|--------|----------|------|-------------|\n| `POST` | `/customer/appointments` | API key (+ optional customer token) | Create appointment |\n| `GET` | `/customer/appointments` | Customer token | List customer appointments (paginated) |\n| `GET` | `/customer/appointments/:id` | Customer token | Get appointment details |\n| `PUT` | `/customer/appointments/:id/reschedule` | Customer token | Reschedule appointment |\n| `PUT` | `/customer/appointments/:id/cancel` | Customer token | Cancel appointment |\n| `POST` | `/customer/appointments/:id/feedback` | Customer token | Submit feedback |\n| `GET` | `/customer/appointments/preferences/booking-history` | Customer token | Get booking preferences |\n\n### Orders (Customer Authenticated)\n\n| Method | Endpoint | Auth | Description |\n|--------|----------|------|-------------|\n| `GET` | `/customer/orders` | Customer token | List customer orders (paginated) |\n| `GET` | `/customer/orders/:id` | Customer token | Get order details |\n\n### Customer Profile (Customer Authenticated)\n\n| Method | Endpoint | Auth | Description |\n|--------|----------|------|-------------|\n| `GET` | `/customer/profile` | Customer token | Get customer profile |\n| `PUT` | `/customer/profile` | Customer token | Update customer profile |\n| `PUT` | `/customer/password` | Customer token | Change password |\n\n### Store\n\n| Method | Endpoint | Auth | Description |\n|--------|----------|------|-------------|\n| `GET` | `/customer/stores/public-settings` | API key | Get store public settings |\n\n**Public settings response includes:**\n- `name` — store display name\n- `domain` — store domain\n- `currency` — store currency code (e.g., `USD`)\n- `settings` — general store settings (timezone, locale, etc.)\n- `storefrontSettings` — presentation config (logo, colors, banners, etc.)\n- `contactInfo` — store contact information\n- `features` — enabled plan features\n\n### Payment\n\n| Method | Endpoint | Auth | Description |\n|--------|----------|------|-------------|\n| `GET` | `/customer/payment/providers` | API key | List available payment providers |\n| `GET` | `/customer/payment/settings` | API key | Get public payment settings |\n\n### Images\n\n| Method | Endpoint | Auth | Description |\n|--------|----------|------|-------------|\n| `GET` | `/customer/images/:id` | API key | Get image metadata by ID |\n\n### Checkout Questions\n\n| Method | Endpoint | Auth | Description |\n|--------|----------|------|-------------|\n| `GET` | `/customer/checkout-questions/:productId/translations/:language` | API key | Get checkout questions for a product |\n\n### Feedback Questions\n\n| Method | Endpoint | Auth | Description |\n|--------|----------|------|-------------|\n| `GET` | `/customer/feedback-questions/:productId/translations/:language` | Customer token | Get feedback questions for a product |\n\n---\n\n## Checkout Flow Detail\n\n### Step 1: Create Appointment\n\nBefore adding to a cart, create the appointment with the selected time slot:\n\n```json\nPOST /customer/appointments\n{\n \"slot\": {\n \"productId\": \"product-uuid\",\n \"fromDate\": \"2026-06-15\",\n \"fromTime\": \"09:00:00\",\n \"toDate\": \"2026-06-15\",\n \"toTime\": \"10:00:00\",\n \"locationId\": \"location-uuid-or-null\",\n \"staffMemberId\": \"staff-uuid-or-null\"\n },\n \"numberOfAttendees\": 1\n}\n```\n\nAll date/time values are in **UTC**. Convert from the user's timezone before sending.\n\n### Step 2: Create Cart & Add Items\n\n```json\nPOST /customer/cart\n→ Returns { \"id\": \"cart-uuid\", ... }\n\nPOST /customer/cart/items\nX-Cart-Id: cart-uuid\n{ \"appointmentId\": \"appointment-uuid\" }\n```\n\nCarts expire automatically. Use `POST /customer/cart/extend` to add 5 minutes.\n\n### Step 3: Start Checkout\n\n```json\nPOST /customer/cart/checkout/start\nX-Cart-Id: cart-uuid\n{\n \"provider\": \"stripe\",\n \"customer\": { \"email\": \"john@example.com\", \"firstName\": \"John\", \"lastName\": \"Smith\" }\n}\n```\n\nResponse includes payment provider details (e.g., Stripe `clientSecret` for Elements).\n\n### Step 4: Save Customer Info\n\nIf not provided in start, save customer details separately:\n\n```json\nPOST /customer/cart/checkout/save-customer\nX-Cart-Id: cart-uuid\n{\n \"customer\": { \"email\": \"john@example.com\", \"firstName\": \"John\", \"lastName\": \"Smith\" }\n}\n```\n\nFor logged-in customers, pass `{ \"customer\": { \"customerId\": \"existing-customer-uuid\" } }`.\n\n### Step 5: Checkout Questions (Optional)\n\nIf the store has checkout questions configured:\n\n```\nGET /customer/cart/checkout/questions/en\nX-Cart-Id: cart-uuid\n→ Returns array of questions with types (text, select, checkbox, etc.)\n\nPOST /customer/cart/checkout/save-answers\nX-Cart-Id: cart-uuid\n{ \"answers\": [{ \"questionId\": \"...\", \"value\": \"...\" }] }\n```\n\n### Step 6: Submit Checkout\n\n```json\nPOST /customer/cart/checkout/submit\nX-Cart-Id: cart-uuid\n{}\n```\n\nResponse includes the created order and optionally customer auth tokens for auto-login.\n\n---\n\n## Payment Integration\n\n### Available Providers\n\nFetch configured payment providers for your store:\n\n```\nGET /customer/payment/providers\n→ [{ \"name\": \"stripe\", \"displayName\": \"Credit Card\", ... }]\n```\n\n### Stripe Integration\n\n1. Get Stripe publishable key from `GET /customer/payment/settings`\n2. Start checkout with `provider: \"stripe\"` — response includes `clientSecret`\n3. Use Stripe Elements / Payment Element with the `clientSecret`\n4. After Stripe confirms payment client-side, call `POST /checkout/submit`\n\n### Cash / Pay at Venue\n\nStart checkout with `provider: \"cash\"`. No payment processing needed — submit directly.\n\n### Redirect-Based Payments\n\nSome providers redirect the customer to an external page. The start response includes a `redirectUrl`. After payment, the customer is redirected back to your `thankYouUrl`.\n\n---\n\n## Store Settings\n\nUse `GET /customer/stores/public-settings` to retrieve store configuration for your template:\n\n- **Store name** → display in header/navbar\n- **Logo** → from `storefrontSettings`\n- **Currency** → format prices correctly (e.g., `USD`, `EUR`)\n- **Timezone** → convert availability times to/from the store's timezone\n- **Contact info** → display in footer or contact page\n- **Features** → check which features are enabled (e.g., customer portal)\n\n---\n\n## Rate Limiting\n\nRequests are rate-limited per API key:\n\n| Category | Limit |\n|----------|-------|\n| General | 100 requests / 60 seconds |\n| Authentication | 20 requests / 10 seconds |\n| Password reset | 5 requests / hour |\n| Registration | 10 requests / minute |\n\nWhen rate-limited, you'll receive a `429 Too Many Requests` response.\n\n---\n\n## Response Format\n\nAll responses use **camelCase** property names:\n\n```json\n{\n \"id\": \"abc-123\",\n \"title\": \"Haircut\",\n \"maxAttendees\": 1,\n \"duration\": 3600,\n \"staffMembers\": [\n { \"id\": \"staff-1\", \"firstName\": \"John\", \"lastName\": \"Doe\" }\n ]\n}\n```\n\n### Pagination\n\nList endpoints return paginated collections:\n\n```json\n{\n \"data\": [ ... ],\n \"meta\": {\n \"total\": 42,\n \"page\": 1,\n \"limit\": 10,\n \"totalPages\": 5\n }\n}\n```\n\nUse `?page=2&limit=20` query parameters to paginate.\n\n---\n\n## Error Responses\n\n```json\n{\n \"statusCode\": 400,\n \"message\": \"Validation failed\",\n \"errors\": [\n { \"property\": \"email\", \"messages\": [\"Email is required\"] }\n ]\n}\n```\n\n| Status | Meaning |\n|--------|---------|\n| 400 | Validation error |\n| 401 | Invalid or missing API key / customer token |\n| 404 | Resource not found |\n| 429 | Rate limit exceeded |\n\n---\n\n## Timezone Handling\n\n- All date/time values in API requests and responses are in **UTC**\n- Pass the `timezone` query parameter to availability endpoints to get slots converted to a specific timezone\n- Use the store's timezone from public settings as the default display timezone\n- Convert user-selected times to UTC before creating appointments\n\n---\n\n## Webhooks (Coming Soon)\n\nWebhook support for real-time notifications is planned. Events will include:\n\n- `product.created`, `product.updated`, `product.deleted`\n- `staff_member.created`, `staff_member.updated`, `staff_member.deleted`\n- `location.created`, `location.updated`, `location.deleted`\n- `store.settings_updated`\n- `collection.updated`\n\nUse webhooks to invalidate cached data in your deployed storefronts.\n", "version": "1.0", "contact": {} }, "tags": [], "servers": [ { "url": "https://api.opencals.com" } ], "components": { "securitySchemes": { "Storefront API key": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Storefront API key (sfk_...)", "x-default": "sfk_your_api_key" }, "customer-token": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http", "description": "Customer access token" } }, "schemas": { "CollectionMeta": { "type": "object", "properties": { "page": { "type": "number", "description": "Current page number", "example": 1, "minimum": 1 }, "take": { "type": "number", "description": "Number of items per page", "example": 50, "minimum": 1 }, "itemCount": { "type": "number", "description": "Total number of items across all pages", "example": 125, "minimum": 0 }, "pageCount": { "type": "number", "description": "Total number of pages available", "example": 3, "minimum": 0 }, "hasPreviousPage": { "type": "boolean", "description": "Whether there is a previous page available", "example": false }, "hasNextPage": { "type": "boolean", "description": "Whether there is a next page available", "example": true } }, "required": [ "page", "take", "itemCount", "pageCount", "hasPreviousPage", "hasNextPage" ] }, "LanguageCode": { "type": "string", "description": "Language code for this translation", "enum": [ "af", "ak", "am", "ar", "as", "az", "be", "bg", "bm", "bn", "bo", "br", "bs", "ca", "ce", "cs", "cu", "cy", "da", "de", "dz", "ee", "el", "en", "eo", "es", "et", "eu", "fa", "ff", "fi", "fo", "fr", "fy", "ga", "gd", "gl", "gu", "gv", "ha", "he", "hi", "hr", "hu", "hy", "ia", "id", "ig", "ii", "is", "it", "ja", "jv", "ka", "ki", "kk", "kl", "km", "kn", "ko", "ks", "ku", "kw", "ky", "lb", "lg", "ln", "lo", "lt", "lu", "lv", "mg", "mi", "mk", "ml", "mn", "mr", "ms", "mt", "my", "nb", "nd", "ne", "nl", "nn", "no", "om", "or", "os", "pa", "pl", "ps", "pt", "pt_br", "pt_pt", "qu", "rm", "rn", "ro", "ru", "rw", "sd", "se", "sg", "si", "sk", "sl", "sn", "so", "sq", "sr", "su", "sv", "sw", "ta", "te", "tg", "th", "ti", "tk", "to", "tr", "tt", "ug", "uk", "ur", "uz", "vi", "vo", "wo", "xh", "yi", "yo", "zh", "zh_cn", "zh_tw", "zu" ] }, "AppointmentStatusType": { "type": "string", "description": "Current status of the appointment", "default": "pending", "enum": [ "pending", "scheduled", "completed", "canceled" ] }, "AppointmentCreatedByEnum": { "type": "string", "description": "Indicates who created the appointment (customer or merchant)", "default": "customer", "enum": [ "customer", "merchant" ] }, "CustomerAddress": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the address" }, "storeId": { "type": "string", "description": "ID of the store that owns this address" }, "customerId": { "type": "string", "description": "ID of the customer this address belongs to" }, "firstName": { "type": "string", "description": "First name of the bill-to party", "nullable": true }, "lastName": { "type": "string", "description": "Last name of the bill-to party", "nullable": true }, "companyName": { "type": "string", "description": "Company name", "nullable": true }, "taxRegistrationId": { "type": "string", "description": "Tax registration identifier (VAT / GST / ABN / EIN / …) of the party at this address", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of the address", "nullable": true }, "addressLine2": { "type": "string", "description": "Second line of the address", "nullable": true }, "city": { "type": "string", "description": "City", "nullable": true }, "state": { "type": "string", "description": "State/province", "nullable": true }, "postalCode": { "type": "string", "description": "Postal/zip code", "nullable": true }, "country": { "type": "string", "description": "Country", "nullable": true }, "email": { "type": "string", "description": "Contact email for this address", "nullable": true }, "phone": { "type": "string", "description": "Contact phone number for this address", "nullable": true }, "isDefault": { "type": "boolean", "description": "Whether this is the default address for the customer", "default": false }, "createdAt": { "format": "date-time", "type": "string", "description": "When the address was created" }, "updatedAt": { "format": "date-time", "type": "string", "description": "When the address was last updated", "nullable": true }, "formattedAddress": { "type": "string", "description": "Address street lines formatted as a single line", "example": "123 Main Street, Suite 456, New York, NY, 10001, USA" } }, "required": [ "id", "storeId", "customerId", "isDefault", "createdAt", "updatedAt", "formattedAddress" ] }, "OrderLogLevel": { "type": "string", "description": "Severity level of the log entry", "enum": [ "info", "error" ] }, "CheckoutFieldRequirement": { "type": "string", "description": "Requirement level for the customer billing address (street fields) at checkout. When required, address line 1, city, postal code and country are mandatory.", "default": "hidden", "enum": [ "hidden", "optional", "required" ] }, "MarketingOptInDisplay": { "type": "string", "description": "Where the WhatsApp marketing opt-in checkbox is shown", "default": "dont_show", "enum": [ "dont_show", "checkout_only", "checkout_and_account" ] }, "MarketingConsentState": { "type": "string", "description": "WhatsApp marketing consent state", "default": "not_subscribed", "enum": [ "not_subscribed", "subscribed", "unsubscribed" ] }, "AppointmentDateRangeSlot": { "type": "object", "properties": { "fromDate": { "type": "string", "description": "Start date for the appointment in YYYY-MM-DD format (UTC timezone)", "example": "2023-06-15", "pattern": "/^(\\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$/" }, "fromTime": { "type": "string", "description": "Start time for the appointment in HH:MM:SS format (UTC timezone)", "example": "09:00:00", "pattern": "/^(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d$/" }, "toDate": { "type": "string", "description": "End date for the appointment in YYYY-MM-DD format (UTC timezone)", "example": "2023-06-15", "pattern": "/^(\\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$/" }, "toTime": { "type": "string", "description": "End time for the appointment in HH:MM:SS format (UTC timezone)", "example": "10:00:00", "pattern": "/^(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d$/" }, "productId": { "type": "string", "description": "ID of the service/product for this appointment", "example": "123e4567-e89b-12d3-a456-426614174001" }, "locationId": { "type": "string", "description": "ID of the location where the appointment will take place (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "staffMemberId": { "type": "string", "description": "ID of the staff member assigned to this appointment (if any)", "example": "123e4567-e89b-12d3-a456-426614174003", "nullable": true } }, "required": [ "fromDate", "fromTime", "toDate", "toTime", "productId" ] }, "ExistingAppointmentCustomer": { "type": "object", "properties": { "customerId": { "type": "string", "description": "ID of an existing customer to book the appointment for", "example": "123e4567-e89b-12d3-a456-426614174004" } }, "required": [ "customerId" ] }, "NewAppointmentCustomer": { "type": "object", "properties": { "externalId": { "type": "string", "description": "External identifier for the new customer", "example": "1234567890" }, "email": { "type": "string", "description": "Email address of the new customer", "example": "john.smith@example.com" }, "firstName": { "type": "string", "description": "First name of the new customer", "example": "John", "nullable": true }, "lastName": { "type": "string", "description": "Last name of the new customer", "example": "Smith", "nullable": true } }, "required": [ "externalId", "email" ] }, "QuestionAnswer": { "type": "object", "properties": { "questionId": { "type": "string", "description": "ID of the feedback question", "example": "123e4567-e89b-12d3-a456-426614174000" }, "question": { "type": "string", "description": "The feedback question text presented to the customer", "example": "How would you rate the quality of service provided?" }, "answer": { "type": "string", "description": "Customer's answer to the feedback question", "example": "The service was excellent, very professional and timely.", "nullable": true }, "fileIds": { "description": "IDs of previously-uploaded files to attach to this answer (file-upload questions only)", "type": "array", "items": { "type": "string" } } }, "required": [ "questionId", "question" ] }, "CheckoutAuthTokens": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "Access token for customer authentication", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "refreshToken": { "type": "string", "description": "Refresh token for customer authentication", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } }, "required": [ "accessToken", "refreshToken" ] }, "CheckoutCustomerInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "Customer ID", "example": "customer-uuid" }, "email": { "type": "string", "description": "Customer email", "example": "customer@example.com" }, "firstName": { "type": "string", "description": "Customer first name", "example": "John" }, "lastName": { "type": "string", "description": "Customer last name", "example": "Doe" }, "hasPassword": { "type": "boolean", "description": "Whether customer has a password set", "example": false }, "emailVerified": { "type": "boolean", "description": "Whether customer email is verified", "example": true } }, "required": [ "id", "hasPassword", "emailVerified" ] }, "ExistingOrderCustomer": { "type": "object", "properties": { "customerId": { "type": "string", "description": "ID of an existing customer to book the appointment for", "example": "123e4567-e89b-12d3-a456-426614174004" }, "firstName": { "type": "string", "description": "Updated first name for the existing customer, captured at checkout", "nullable": true }, "lastName": { "type": "string", "description": "Updated last name for the existing customer, captured at checkout", "nullable": true }, "phone": { "type": "string", "description": "Updated phone number for the existing customer, captured at checkout", "nullable": true }, "billingAddress": { "description": "Billing address for this checkout (carries company + VAT). Saved to the address book.", "allOf": [ { "$ref": "#/components/schemas/BillingAddress" } ] }, "marketingConsent": { "description": "Per-channel marketing opt-in captured at checkout, recorded against the customer address.", "allOf": [ { "$ref": "#/components/schemas/MarketingConsentInput" } ] }, "deliveryAddress": { "description": "Delivery/shipping address for DELIVERY-type services. One per order, applied to every delivery appointment and mapped to the Shopify order shipping address.", "allOf": [ { "$ref": "#/components/schemas/Address" } ] } }, "required": [ "customerId" ] }, "NewOrderCustomer": { "type": "object", "properties": { "externalId": { "type": "string", "description": "External identifier for the new customer", "example": "1234567890" }, "email": { "type": "string", "description": "Email address of the new customer", "example": "john.smith@example.com" }, "firstName": { "type": "string", "description": "First name of the new customer", "example": "John", "nullable": true }, "lastName": { "type": "string", "description": "Last name of the new customer", "example": "Smith", "nullable": true }, "phone": { "type": "string", "description": "Phone number of the new customer", "example": "+12135550123", "nullable": true }, "billingAddress": { "description": "Billing address for this checkout (carries company + VAT). Saved to the address book.", "allOf": [ { "$ref": "#/components/schemas/BillingAddress" } ] }, "marketingConsent": { "description": "Per-channel marketing opt-in captured at checkout, recorded against the customer address.", "allOf": [ { "$ref": "#/components/schemas/MarketingConsentInput" } ] }, "deliveryAddress": { "description": "Delivery/shipping address for services with delivery location selected. One per order, applied to every delivery appointment.", "allOf": [ { "$ref": "#/components/schemas/Address" } ] } }, "required": [ "externalId", "email" ] }, "DeliveryAddress": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the address" }, "storeId": { "type": "string", "description": "ID of the store that owns this address" }, "customerId": { "type": "string", "description": "ID of the customer this address belongs to" }, "firstName": { "type": "string", "description": "First name of the party", "nullable": true }, "lastName": { "type": "string", "description": "Last name of the party", "nullable": true }, "companyName": { "type": "string", "description": "Company name", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of the address", "nullable": true }, "addressLine2": { "type": "string", "description": "Second line of the address", "nullable": true }, "city": { "type": "string", "description": "City", "nullable": true }, "state": { "type": "string", "description": "State/province", "nullable": true }, "postalCode": { "type": "string", "description": "Postal/zip code", "nullable": true }, "country": { "type": "string", "description": "Country", "nullable": true }, "email": { "type": "string", "description": "Contact email for this address", "nullable": true }, "phone": { "type": "string", "description": "Contact phone number for this address", "nullable": true }, "isDefault": { "type": "boolean", "description": "Whether this is the default address for the customer", "default": false }, "createdAt": { "format": "date-time", "type": "string", "description": "When the address was created" }, "updatedAt": { "format": "date-time", "type": "string", "description": "When the address was last updated", "nullable": true }, "formattedAddress": { "type": "string", "description": "Address street lines formatted as a single line", "example": "123 Main Street, Suite 456, New York, NY, 10001, USA" } }, "required": [ "id", "storeId", "customerId", "isDefault", "createdAt", "updatedAt", "formattedAddress" ] }, "CartItemAppliedDiscount": { "type": "object", "properties": { "discountId": { "type": "string", "description": "Discount ID" }, "title": { "type": "string", "description": "Discount title" }, "amountPerUnit": { "type": "number", "description": "Discount amount per unit" }, "valueType": { "type": "string", "description": "Value type of the discount", "enum": [ "percentage", "fixed_amount", "time" ] }, "value": { "type": "number", "description": "Configured discount value (percentage or fixed amount)" }, "targetType": { "type": "string", "description": "Whether this row targets the base item or an add-on", "enum": [ "base", "add_on" ] } }, "required": [ "discountId", "title", "amountPerUnit", "valueType", "value", "targetType" ] }, "AppliedDiscount": { "type": "object", "properties": { "id": { "type": "string", "description": "Discount ID" }, "title": { "type": "string", "description": "Discount title" }, "totalAmount": { "type": "number", "description": "Total discount amount across all affected items" }, "code": { "type": "string", "description": "Promo code used (only present for code-kind discounts)", "nullable": true } }, "required": [ "id", "title", "totalAmount" ] }, "RequestEmailVerification": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address to resend the verification email to" } }, "required": [ "email" ] }, "VerifyEmail": { "type": "object", "properties": { "token": { "type": "string", "description": "Email verification token from email link" } }, "required": [ "token" ] }, "AuthenticateCustomerCredentials": { "type": "object", "properties": { "tokenName": { "type": "string", "description": "Unique key identifier for this authentication session (e.g., frontend identifier)", "example": "web_app", "default": "default" }, "storeId": { "type": "string", "description": "Preferred store ID to scope the JWT to", "example": "store-uuid" }, "storeDomain": { "type": "string", "description": "Preferred store domain to resolve store and scope the JWT to", "example": "my-store.myshopify.com" }, "email": { "type": "string", "description": "Customer email" }, "password": { "type": "string", "description": "Customer password (min 8 chars)" } }, "required": [ "email", "password" ] }, "TokensResponse": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "JWT access token for authenticating API requests", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "refreshToken": { "type": "string", "description": "JWT refresh token for obtaining new access tokens", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } }, "required": [ "accessToken", "refreshToken" ] }, "AuthenticateCustomerOauth": { "type": "object", "properties": { "tokenName": { "type": "string", "description": "Unique key identifier for this authentication session (e.g., frontend identifier)", "example": "web_app", "default": "storefront" } } }, "RegisterCustomer": { "type": "object", "properties": { "email": { "type": "string", "description": "Customer email" }, "password": { "type": "string", "description": "Customer password (min 8 chars)" }, "firstName": { "type": "string", "description": "First name" }, "lastName": { "type": "string", "description": "Last name" } }, "required": [ "email", "password" ] }, "RequestPasswordReset": { "type": "object", "properties": { "email": { "type": "string", "example": "customer@example.com", "description": "Customer email address" } }, "required": [ "email" ] }, "CustomerResetPassword": { "type": "object", "properties": { "token": { "type": "string", "example": "abc123xyz...", "description": "Password reset token" }, "newPassword": { "type": "string", "example": "NewSecurePassword123!", "description": "New password" } }, "required": [ "token", "newPassword" ] }, "ResolveLinkResponse": { "type": "object", "properties": { "purpose": { "type": "string", "description": "Purpose of the magic link" }, "redirectPath": { "type": "string", "description": "Path to redirect the customer to" }, "accessToken": { "type": "string", "description": "Access token for authentication" }, "refreshToken": { "type": "string", "description": "Refresh token for authentication" }, "metadata": { "type": "object", "description": "Additional metadata" }, "requiresAction": { "type": "string", "description": "Action required from the customer" } }, "required": [ "purpose", "redirectPath" ] }, "RequestLoginCode": { "type": "object", "properties": { "email": { "type": "string", "description": "Customer email address", "example": "customer@example.com" } }, "required": [ "email" ] }, "VerifyLoginCode": { "type": "object", "properties": { "email": { "type": "string", "description": "Customer email address", "example": "customer@example.com" }, "code": { "type": "string", "description": "6-digit verification code", "example": "123456" } }, "required": [ "email", "code" ] }, "SelfServiceProfileResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the customer", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External customer identifier from integrated system", "example": "1234567890" }, "firstName": { "type": "string", "description": "Customer first name", "example": "John", "nullable": true }, "lastName": { "type": "string", "description": "Customer last name", "example": "Smith", "nullable": true }, "email": { "type": "string", "description": "Customer email address", "example": "john.smith@example.com", "nullable": true }, "phone": { "type": "string", "description": "Customer phone number", "example": "+12135550123", "nullable": true }, "password": { "type": "string", "description": "Hashed password of the customer", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this customer record", "example": "store-uuid" }, "language": { "example": "en", "$ref": "#/components/schemas/LanguageCode" }, "refreshToken": { "type": "string", "description": "Customer refresh token for authentication", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "nullable": true, "writeOnly": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Date when the customer record was created", "example": "2023-01-15T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date when the customer record was last updated", "example": "2023-02-20T14:15:00Z", "nullable": true }, "emailVerifiedAt": { "format": "date-time", "type": "string", "description": "Date and time when the customer verified email", "example": "2023-01-02T00:00:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "isEmailVerified": { "type": "boolean", "description": "Indicates whether customer email is verified" }, "isPasswordSet": { "type": "boolean", "description": "Indicates whether customer password is set" } }, "required": [ "id", "externalId", "firstName", "lastName", "email", "phone", "password", "storeId", "language", "refreshToken", "createdAt", "updatedAt", "emailVerifiedAt", "deletedAt", "isEmailVerified", "isPasswordSet" ] }, "UpdateCustomerProfile": { "type": "object", "properties": { "firstName": { "type": "string", "example": "John", "description": "Customer first name" }, "lastName": { "type": "string", "example": "Doe", "description": "Customer last name" }, "phone": { "type": "string", "description": "Phone number of the customer", "example": "+12135550123" } } }, "MarketingConsentResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the marketing consent row" }, "storeId": { "type": "string", "description": "ID of the store that owns this consent" }, "customerId": { "type": "string", "description": "ID of the customer this consent belongs to" }, "customerAddressId": { "type": "string", "description": "ID of the customer address this consent is attached to" }, "emailState": { "$ref": "#/components/schemas/MarketingConsentState" }, "emailUpdatedAt": { "format": "date-time", "type": "string", "description": "When the email consent state last changed", "nullable": true }, "smsState": { "$ref": "#/components/schemas/MarketingConsentState" }, "smsUpdatedAt": { "format": "date-time", "type": "string", "description": "When the SMS consent state last changed", "nullable": true }, "whatsappState": { "$ref": "#/components/schemas/MarketingConsentState" }, "whatsappUpdatedAt": { "format": "date-time", "type": "string", "description": "When the WhatsApp consent state last changed", "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "When the consent row was created" }, "updatedAt": { "format": "date-time", "type": "string", "description": "When the consent row was last updated", "nullable": true } }, "required": [ "id", "storeId", "customerId", "customerAddressId", "emailState", "emailUpdatedAt", "smsState", "smsUpdatedAt", "whatsappState", "whatsappUpdatedAt", "createdAt", "updatedAt" ] }, "MarketingConsentInput": { "type": "object", "properties": { "email": { "type": "boolean", "description": "Whether the customer is subscribed to email marketing" }, "sms": { "type": "boolean", "description": "Whether the customer is subscribed to SMS marketing" }, "whatsapp": { "type": "boolean", "description": "Whether the customer is subscribed to WhatsApp marketing" } } }, "UpdateCustomerPassword": { "type": "object", "properties": { "currentPassword": { "type": "string", "description": "Current password (required if user already has a password)" }, "newPassword": { "type": "string", "description": "New password" } }, "required": [ "newPassword" ] }, "BillingAddress": { "type": "object", "properties": { "firstName": { "type": "string", "description": "First name of the party", "example": "John", "maxLength": 255 }, "lastName": { "type": "string", "description": "Last name of the party", "example": "Smith", "maxLength": 255 }, "companyName": { "type": "string", "description": "Company name", "example": "Acme Inc.", "maxLength": 255 }, "addressLine1": { "type": "string", "description": "First line of the address", "example": "123 Main Street", "maxLength": 255 }, "addressLine2": { "type": "string", "description": "Second line of the address", "example": "Suite 456", "maxLength": 255 }, "city": { "type": "string", "description": "City", "example": "New York", "maxLength": 255 }, "state": { "type": "string", "description": "State/province", "example": "NY", "maxLength": 255 }, "postalCode": { "type": "string", "description": "Postal/zip code", "example": "10001", "maxLength": 255 }, "country": { "type": "string", "description": "2-letter ISO 3166-1 alpha-2 country code (uppercase)", "example": "US", "pattern": "^[A-Z]{2}$" }, "email": { "type": "string", "description": "Contact email for this address", "example": "john.smith@example.com", "maxLength": 255 }, "phone": { "type": "string", "description": "Contact phone number for this address", "example": "+12135550123", "maxLength": 255 }, "taxRegistrationId": { "type": "string", "description": "The bill-to party's tax registration identifier (VAT / GST / ABN / EIN / …).", "example": "GB123456789", "maxLength": 255 } } }, "Address": { "type": "object", "properties": { "firstName": { "type": "string", "description": "First name of the party", "example": "John", "maxLength": 255 }, "lastName": { "type": "string", "description": "Last name of the party", "example": "Smith", "maxLength": 255 }, "companyName": { "type": "string", "description": "Company name", "example": "Acme Inc.", "maxLength": 255 }, "addressLine1": { "type": "string", "description": "First line of the address", "example": "123 Main Street", "maxLength": 255 }, "addressLine2": { "type": "string", "description": "Second line of the address", "example": "Suite 456", "maxLength": 255 }, "city": { "type": "string", "description": "City", "example": "New York", "maxLength": 255 }, "state": { "type": "string", "description": "State/province", "example": "NY", "maxLength": 255 }, "postalCode": { "type": "string", "description": "Postal/zip code", "example": "10001", "maxLength": 255 }, "country": { "type": "string", "description": "2-letter ISO 3166-1 alpha-2 country code (uppercase)", "example": "US", "pattern": "^[A-Z]{2}$" }, "email": { "type": "string", "description": "Contact email for this address", "example": "john.smith@example.com", "maxLength": 255 }, "phone": { "type": "string", "description": "Contact phone number for this address", "example": "+12135550123", "maxLength": 255 } } }, "CheckoutQuestionAnswer": { "type": "object", "properties": { "questionId": { "type": "string", "description": "ID of the checkout question", "example": "123e4567-e89b-12d3-a456-426614174000" }, "question": { "type": "string", "description": "The question text (for historical record)", "example": "Do you have any allergies?" }, "answer": { "type": "string", "description": "The customer answer", "example": "No allergies" }, "fileIds": { "description": "IDs of previously-uploaded files to attach to this answer (file-upload questions only)", "type": "array", "items": { "type": "string" } } }, "required": [ "questionId", "question", "answer" ] }, "CreateAppointmentAddOn": { "type": "object", "properties": { "addOnId": { "type": "string", "description": "ID of the add-on to attach to the appointment", "example": "123e4567-e89b-12d3-a456-426614174006" }, "quantity": { "type": "number", "description": "Quantity of this add-on (for fixed add-ons). Ignored for duration-multiplied add-ons.", "example": 1, "default": 1 } }, "required": [ "addOnId" ] }, "AppointmentGuest": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address of the guest invited to the appointment", "example": "guest@example.com" } }, "required": [ "email" ] }, "CreateAppointment": { "type": "object", "properties": { "slot": { "description": "Appointment slot information — date/time range with product, location, and staff", "allOf": [ { "$ref": "#/components/schemas/AppointmentDateRangeSlot" } ] }, "customer": { "description": "Customer information - either an existing customer ID or details for a new customer", "oneOf": [ { "$ref": "#/components/schemas/ExistingAppointmentCustomer" }, { "$ref": "#/components/schemas/NewAppointmentCustomer" } ] }, "internalNote": { "type": "string", "description": "Internal notes about the appointment (not visible to customers)", "example": "Customer requested extra attention for specific needs" }, "address": { "description": "Customer delivery/service address for a DELIVERY-location appointment (Shopify MailingAddress shape: name/company/contact + street). Linked to the appointment as a reusable customer address; ignored for PHYSICAL/ONLINE locations, which derive their address from the location. A global delivery address supplied later at checkout (save-customer/start/submit) overrides this.", "allOf": [ { "$ref": "#/components/schemas/Address" } ] }, "checkoutQuestionAnswers": { "description": "Answers to checkout questions provided during booking", "type": "array", "items": { "$ref": "#/components/schemas/CheckoutQuestionAnswer" } }, "numberOfAttendees": { "type": "number", "description": "Number of people attending the appointment", "example": 1, "default": 1 }, "cartId": { "type": "string", "description": "ID of the cart associated with this appointment", "example": "123e4567-e89b-12d3-a456-426614174005" }, "addOns": { "description": "Add-ons to attach to this appointment at creation time", "type": "array", "items": { "$ref": "#/components/schemas/CreateAppointmentAddOn" } }, "guests": { "description": "Guests to invite to the appointment. They are copied on appointment notifications.", "type": "array", "items": { "$ref": "#/components/schemas/AppointmentGuest" } }, "customAttributes": { "type": "object", "description": "Custom key-value attributes to attach to the appointment (string keys and values). Max 250 entries.", "additionalProperties": { "type": "string" }, "example": { "source": "widget", "party_size": "4" } } }, "required": [ "slot" ] }, "RescheduleAppointment": { "type": "object", "properties": { "slot": { "description": "Appointment slot information — date/time range with product, location, and staff", "allOf": [ { "$ref": "#/components/schemas/AppointmentDateRangeSlot" } ] }, "notifyCustomer": { "type": "boolean", "description": "Whether to send rescheduling notification to the customer", "default": true, "example": true }, "address": { "description": "Customer delivery/service address for a DELIVERY-location appointment. Linked to the appointment as a reusable customer address (copy-on-write). Ignored for PHYSICAL/ONLINE locations.", "allOf": [ { "$ref": "#/components/schemas/Address" } ] } }, "required": [ "slot" ] }, "CancelAppointment": { "type": "object", "properties": { "notifyCustomer": { "type": "boolean", "description": "Whether to send a notification to the customer about the cancellation", "default": true, "example": true } } }, "AddGuest": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address of the guest to invite to the appointment", "example": "guest@example.com" }, "notify": { "type": "boolean", "description": "Whether to send the guest an invitation email. Defaults to true.", "example": true, "default": true } }, "required": [ "email" ] }, "Image": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External identifier for the image (e.g., from storage provider)", "example": "img_123456", "nullable": true }, "url": { "type": "string", "description": "URL where the image can be accessed", "example": "https://storage.example.com/images/product-image.jpg" }, "filename": { "type": "string", "description": "Original filename of the uploaded image", "example": "product-image.jpg", "nullable": true }, "mime": { "type": "string", "description": "MIME type of the image", "example": "image/jpeg", "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Creation timestamp", "example": "2023-01-01T12:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Last update timestamp", "example": "2023-01-02T12:00:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Soft deletion timestamp", "example": "2023-01-03T12:00:00Z", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this image", "example": "store-uuid", "nullable": true } }, "required": [ "id", "externalId", "url", "filename", "mime", "createdAt", "updatedAt", "deletedAt", "storeId" ] }, "AppointmentCreatedProduct": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "productId": { "type": "string", "description": "ID of the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID)", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID)", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this product", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the product (unique per store)", "example": "haircut-basic" }, "scheduleId": { "type": "string", "description": "ID of the schedule associated with this product" }, "productPoolId": { "type": "string", "description": "ID of the product pool this product belongs to (controls overlap prevention)", "nullable": true }, "title": { "type": "string", "description": "Title of the product", "example": "Haircut Service" }, "variantTitle": { "type": "string", "description": "Title of the specific product variant", "example": "Short Hair" }, "description": { "type": "string", "description": "Detailed description of the product" }, "imageId": { "type": "string", "description": "ID of the product image" }, "color": { "type": "string", "description": "Color code for displaying the product", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "BLUE", "default": "slate" }, "price": { "type": "number", "description": "Price of the product", "example": 250 }, "taxable": { "type": "boolean", "description": "Whether the product is taxable", "default": false }, "duration": { "type": "number", "description": "Duration of the service in seconds", "example": 3600 }, "allowCustomDuration": { "type": "boolean", "description": "Whether customers can customize the duration by selecting multiples of the base service duration (e.g., if base duration is 1 day, customers can book 1, 2, 3+ days)", "default": false }, "maxDuration": { "type": "number", "description": "When allow_custom_duration=true, maximum duration allowed for multi-duration bookings in seconds (-1 for unlimited)", "default": -1 }, "maxAttendees": { "type": "number", "description": "Maximum number of attendees allowed", "default": 1 }, "maxGuests": { "type": "number", "description": "Maximum number of guests allowed per appointment. Null means unlimited.", "nullable": true }, "allowGuests": { "type": "boolean", "description": "Whether customers can invite guests to the appointment", "default": false }, "allowCustomerReschedule": { "type": "boolean", "description": "Whether customers can reschedule their bookings", "default": false }, "allowCustomerCancel": { "type": "boolean", "description": "Whether customers can cancel their bookings", "default": false }, "rescheduleGap": { "type": "number", "description": "Time in seconds before appointment when rescheduling is no longer allowed" }, "cancelGap": { "type": "number", "description": "Time in seconds before appointment when cancellation is no longer allowed" }, "beforeGap": { "type": "number", "description": "Buffer time in seconds required before this service" }, "afterGap": { "type": "number", "description": "Buffer time in seconds required after this service" }, "fixedTimes": { "type": "boolean", "description": "When allow_custom_duration=true, whether appointments must start and end at fixed times (like fixed check-in/check-out times for multi-duration bookings)", "default": false }, "fixedStartTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must start (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "09:00:00" }, "fixedEndTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must end (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "17:00:00" }, "advanceScheduleThreshold": { "type": "number", "description": "How many days in advance bookings can be made", "default": 0 }, "sendConfirmationEmail": { "type": "boolean", "description": "Whether to send confirmation emails for bookings", "default": true }, "sendReminderEmail": { "type": "boolean", "description": "Whether to send reminder emails before appointments", "default": false }, "sendFeedbackEmail": { "type": "boolean", "description": "Whether to send feedback request emails after appointments", "default": false }, "skipCheckout": { "type": "boolean", "description": "Whether to skip the checkout process for this product (Shopify merchants only)", "default": false }, "status": { "type": "string", "description": "Current status of the product", "enum": [ "active", "inactive" ], "example": "ACTIVE", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the product was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the product was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the product was deleted (for soft deletes)" }, "image": { "description": "Primary image of the product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "productId", "externalId", "externalVariantId", "storeId", "slug", "scheduleId", "productPoolId", "title", "variantTitle", "description", "imageId", "color", "price", "taxable", "duration", "allowCustomDuration", "maxDuration", "maxAttendees", "maxGuests", "allowGuests", "allowCustomerReschedule", "allowCustomerCancel", "rescheduleGap", "cancelGap", "beforeGap", "afterGap", "fixedTimes", "fixedStartTime", "fixedEndTime", "advanceScheduleThreshold", "sendConfirmationEmail", "sendReminderEmail", "sendFeedbackEmail", "skipCheckout", "status", "createdAt", "updatedAt", "deletedAt" ] }, "AppointmentCreatedStaffMember": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this staff member record", "example": "123e4567-e89b-12d3-a456-426614174111" }, "userId": { "type": "string", "description": "User ID of the staff member login identity (nullable until linked)", "example": "user-uuid" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this staff member, defines their availability", "example": "123e4567-e89b-12d3-a456-426614174000" }, "imageId": { "type": "string", "description": "ID of the image associated with this staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "firstName": { "type": "string", "description": "First name of the staff member", "example": "John" }, "lastName": { "type": "string", "description": "Last name of the staff member", "example": "Doe" }, "email": { "type": "string", "description": "Email address of the staff member, used for notifications and calendar integration", "example": "john.doe@example.com" }, "slug": { "type": "string", "description": "URL-friendly slug for the staff member (unique per store)", "example": "mike" }, "refreshToken": { "type": "string", "description": "Refresh token for integrations like Google Calendar", "example": "abc123xyz456" }, "createdAt": { "type": "string", "description": "Date and time when the staff member was created", "example": "2025-05-01T12:00:00Z" }, "updatedAt": { "type": "string", "description": "Date and time when the staff member was last updated", "example": "2025-05-15T14:30:00Z" }, "deletedAt": { "type": "string", "description": "Date and time when the staff member was soft deleted", "example": "2025-06-01T09:15:00Z" }, "image": { "description": "Profile image of the staff member", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "storeId", "userId", "scheduleId", "imageId", "firstName", "lastName", "email", "slug", "refreshToken", "createdAt", "updatedAt", "deletedAt" ] }, "AppointmentCreatedLocation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the location", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this location", "example": "123e4567-e89b-12d3-a456-426614174001" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this location (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "title": { "type": "string", "description": "Name of the location", "example": "Main Office", "nullable": true }, "description": { "type": "string", "description": "Description of the location", "example": "Our main downtown office location with 3 treatment rooms", "nullable": true }, "slug": { "type": "string", "description": "URL-friendly slug for the location (unique per store)", "example": "new-york" }, "type": { "type": "string", "description": "Type of location", "enum": [ "physical", "online", "delivery" ], "example": "physical" }, "link": { "type": "string", "description": "URL link for online locations", "example": "https://zoom.us/j/123456789", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of address for physical locations", "example": "123 Main Street", "nullable": true }, "addressLine2": { "type": "string", "description": "Second line of address for physical locations", "example": "Suite 200", "nullable": true }, "city": { "type": "string", "description": "City for physical locations", "example": "San Francisco", "nullable": true }, "state": { "type": "string", "description": "State/province for physical locations", "example": "CA", "nullable": true }, "postalCode": { "type": "string", "description": "Postal code for physical locations", "example": "94105", "nullable": true }, "country": { "type": "string", "description": "Country for physical locations", "example": "United States", "nullable": true }, "displayAddress": { "type": "string", "description": "Merchant-defined display address that overrides the auto-formatted address (emails, booking page). Null falls back to the concatenated address fields.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressPlaceId": { "type": "string", "description": "Google Place ID for the physical address", "example": "ChIJIQBpAG2ahYAR_6128GcTUEo", "nullable": true }, "latitude": { "type": "number", "description": "Latitude in WGS84", "example": 37.4224764, "nullable": true }, "longitude": { "type": "number", "description": "Longitude in WGS84", "example": -122.0842499, "nullable": true }, "createdAt": { "type": "string", "description": "Date when the location was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the location was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "type": "string", "description": "Date when the location was deleted (for soft deletes)", "example": "2023-03-10T11:45:00Z", "nullable": true }, "address": { "type": "string", "description": "The formatted address string", "nullable": true } }, "required": [ "id", "storeId", "scheduleId", "title", "description", "slug", "type", "link", "addressLine1", "addressLine2", "city", "state", "postalCode", "country", "addressPlaceId", "latitude", "longitude", "createdAt", "updatedAt", "deletedAt", "address" ] }, "AppointmentCreatedAddOnItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the add-on", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID) for synced add-ons", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID) for synced add-ons", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this add-on", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the add-on (unique per store)", "example": "child-seat" }, "title": { "type": "string", "description": "Title of the add-on", "example": "Child Seat" }, "description": { "type": "string", "description": "Detailed description of the add-on" }, "imageId": { "type": "string", "description": "ID of the primary image for the add-on" }, "color": { "type": "string", "description": "Color code used when displaying the add-on", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "slate", "default": "slate" }, "price": { "type": "number", "description": "Unit price of the add-on", "example": 15 }, "taxable": { "type": "boolean", "description": "Whether the add-on is taxable", "default": true }, "durationMultiplied": { "type": "boolean", "description": "When true, the add-on is charged per base-duration unit of the parent appointment. Quantity on the cart/order line item mirrors the parent CartItem.quantity (i.e., the booked duration units). Only meaningful for attached products with allowCustomDuration=true.", "default": false }, "maxQuantity": { "type": "number", "description": "Maximum quantity a customer can pick for this add-on. Only applies to fixed add-ons (durationMultiplied=false). Null means unlimited.", "example": 4, "minimum": 1, "nullable": true }, "status": { "type": "string", "description": "Current status of the add-on", "enum": [ "active", "inactive" ], "example": "active", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the add-on was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the add-on was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the add-on was soft-deleted" }, "image": { "description": "Primary image of the add-on", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "externalId", "externalVariantId", "storeId", "slug", "title", "description", "imageId", "color", "price", "taxable", "durationMultiplied", "maxQuantity", "status", "createdAt", "updatedAt", "deletedAt" ] }, "AppointmentCreatedAddOn": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier" }, "appointmentId": { "type": "string", "description": "Appointment ID" }, "addOnId": { "type": "string", "description": "Add-on ID" }, "quantity": { "type": "number", "description": "Quantity of this add-on for the appointment", "default": 1 }, "createdAt": { "format": "date-time", "type": "string", "description": "Created at timestamp" }, "addOn": { "description": "The add-on details", "allOf": [ { "$ref": "#/components/schemas/AppointmentCreatedAddOnItem" } ] } }, "required": [ "id", "appointmentId", "addOnId", "quantity", "createdAt", "addOn" ] }, "AppointmentCreatedGuest": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier" }, "appointmentId": { "type": "string", "description": "Appointment ID" }, "email": { "type": "string", "description": "Guest email address" }, "createdAt": { "format": "date-time", "type": "string", "description": "Created at timestamp" } }, "required": [ "id", "appointmentId", "email", "createdAt" ] }, "AppointmentCreatedCustomer": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the customer", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External customer identifier from integrated system", "example": "1234567890" }, "firstName": { "type": "string", "description": "Customer first name", "example": "John", "nullable": true }, "lastName": { "type": "string", "description": "Customer last name", "example": "Smith", "nullable": true }, "email": { "type": "string", "description": "Customer email address", "example": "john.smith@example.com", "nullable": true }, "phone": { "type": "string", "description": "Customer phone number", "example": "+12135550123", "nullable": true }, "password": { "type": "string", "description": "Hashed password of the customer", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this customer record", "example": "store-uuid" }, "language": { "example": "en", "$ref": "#/components/schemas/LanguageCode" }, "refreshToken": { "type": "string", "description": "Customer refresh token for authentication", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "nullable": true, "writeOnly": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Date when the customer record was created", "example": "2023-01-15T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date when the customer record was last updated", "example": "2023-02-20T14:15:00Z", "nullable": true }, "emailVerifiedAt": { "format": "date-time", "type": "string", "description": "Date and time when the customer verified email", "example": "2023-01-02T00:00:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "isEmailVerified": { "type": "boolean", "description": "Indicates whether customer email is verified" }, "isPasswordSet": { "type": "boolean", "description": "Indicates whether customer password is set" } }, "required": [ "id", "externalId", "firstName", "lastName", "email", "phone", "password", "storeId", "language", "refreshToken", "createdAt", "updatedAt", "emailVerifiedAt", "deletedAt", "isEmailVerified", "isPasswordSet" ] }, "AppointmentCreatedResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the appointment", "example": "123e4567-e89b-12d3-a456-426614174000" }, "name": { "type": "string", "description": "Generated appointment name for the user (starts at 1001 and increments)", "example": "1001" }, "productId": { "type": "string", "description": "ID of the service/product for this appointment", "example": "123e4567-e89b-12d3-a456-426614174001" }, "staffMemberId": { "type": "string", "description": "ID of the staff member assigned to this appointment (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "locationId": { "type": "string", "description": "ID of the location where the appointment will take place (if any)", "example": "123e4567-e89b-12d3-a456-426614174003", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this appointment", "example": "123e4567-e89b-12d3-a456-426614174004" }, "customerId": { "type": "string", "description": "ID of the customer who booked the appointment", "example": "123e4567-e89b-12d3-a456-426614174005", "nullable": true }, "externalOrderId": { "type": "string", "description": "External order ID from user's platform (if any)", "example": "12345678", "nullable": true }, "externalOrderName": { "type": "string", "description": "External order name/reference from user's platform", "example": "#1001", "nullable": true }, "from": { "format": "date-time", "type": "string", "description": "Start date and time of the appointment (UTC timezone)", "example": "2023-06-15T09:00:00Z" }, "to": { "format": "date-time", "type": "string", "description": "End date and time of the appointment (UTC timezone)", "example": "2023-06-15T10:00:00Z" }, "displayAddress": { "type": "string", "description": "Merchant-defined display address from the location; overrides the concatenated address fields in notifications. Null falls back to the structured address.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressId": { "type": "string", "description": "ID of the linked service/delivery address", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of the appointment address", "nullable": true, "deprecated": true }, "addressLine2": { "type": "string", "description": "Second line of the appointment address", "nullable": true, "deprecated": true }, "city": { "type": "string", "description": "City of the appointment location", "nullable": true, "deprecated": true }, "state": { "type": "string", "description": "State/province of the appointment location", "nullable": true, "deprecated": true }, "postalCode": { "type": "string", "description": "Postal/zip code of the appointment location", "nullable": true, "deprecated": true }, "country": { "type": "string", "description": "Country of the appointment location", "nullable": true, "deprecated": true }, "status": { "example": "scheduled", "$ref": "#/components/schemas/AppointmentStatusType" }, "internalNote": { "type": "string", "description": "Internal notes about the appointment (not visible to customers)", "example": "Customer requested extra attention for specific needs", "nullable": true }, "createdBy": { "example": "customer", "$ref": "#/components/schemas/AppointmentCreatedByEnum" }, "reminderSentAt": { "format": "date-time", "type": "string", "description": "Date and time when reminder was sent to the customer", "example": "2023-06-14T09:00:00Z", "nullable": true }, "numberOfAttendees": { "type": "number", "description": "Number of people attending the appointment", "example": 1, "default": 1 }, "customAttributes": { "type": "object", "description": "Custom key-value attributes (strings) attached to the appointment. Max 250 entries.", "additionalProperties": { "type": "string" }, "nullable": true, "example": { "source": "widget", "party_size": "4" } }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "deliveryAddress": { "description": "Linked service/delivery address (DELIVERY locations)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DeliveryAddress" } ] }, "product": { "description": "Service/product details for this appointment", "allOf": [ { "$ref": "#/components/schemas/AppointmentCreatedProduct" } ] }, "staffMember": { "description": "Staff member assigned to this appointment", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/AppointmentCreatedStaffMember" } ] }, "location": { "description": "Location where the appointment will take place", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/AppointmentCreatedLocation" } ] }, "addOns": { "description": "Add-ons attached to this appointment", "type": "array", "items": { "$ref": "#/components/schemas/AppointmentCreatedAddOn" } }, "guests": { "description": "Guests invited to this appointment (copied on notifications)", "type": "array", "items": { "$ref": "#/components/schemas/AppointmentCreatedGuest" } }, "customer": { "description": "Customer the appointment was booked for", "allOf": [ { "$ref": "#/components/schemas/AppointmentCreatedCustomer" } ] } }, "required": [ "id", "name", "productId", "staffMemberId", "locationId", "storeId", "customerId", "externalOrderId", "externalOrderName", "from", "to", "displayAddress", "status", "internalNote", "createdBy", "reminderSentAt", "numberOfAttendees", "createdAt", "updatedAt", "deletedAt", "product", "staffMember", "location", "addOns", "guests", "customer" ] }, "AppointmentListItemProduct": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "productId": { "type": "string", "description": "ID of the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID)", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID)", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this product", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the product (unique per store)", "example": "haircut-basic" }, "scheduleId": { "type": "string", "description": "ID of the schedule associated with this product" }, "productPoolId": { "type": "string", "description": "ID of the product pool this product belongs to (controls overlap prevention)", "nullable": true }, "title": { "type": "string", "description": "Title of the product", "example": "Haircut Service" }, "variantTitle": { "type": "string", "description": "Title of the specific product variant", "example": "Short Hair" }, "description": { "type": "string", "description": "Detailed description of the product" }, "imageId": { "type": "string", "description": "ID of the product image" }, "color": { "type": "string", "description": "Color code for displaying the product", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "BLUE", "default": "slate" }, "price": { "type": "number", "description": "Price of the product", "example": 250 }, "taxable": { "type": "boolean", "description": "Whether the product is taxable", "default": false }, "duration": { "type": "number", "description": "Duration of the service in seconds", "example": 3600 }, "allowCustomDuration": { "type": "boolean", "description": "Whether customers can customize the duration by selecting multiples of the base service duration (e.g., if base duration is 1 day, customers can book 1, 2, 3+ days)", "default": false }, "maxDuration": { "type": "number", "description": "When allow_custom_duration=true, maximum duration allowed for multi-duration bookings in seconds (-1 for unlimited)", "default": -1 }, "maxAttendees": { "type": "number", "description": "Maximum number of attendees allowed", "default": 1 }, "maxGuests": { "type": "number", "description": "Maximum number of guests allowed per appointment. Null means unlimited.", "nullable": true }, "allowGuests": { "type": "boolean", "description": "Whether customers can invite guests to the appointment", "default": false }, "allowCustomerReschedule": { "type": "boolean", "description": "Whether customers can reschedule their bookings", "default": false }, "allowCustomerCancel": { "type": "boolean", "description": "Whether customers can cancel their bookings", "default": false }, "rescheduleGap": { "type": "number", "description": "Time in seconds before appointment when rescheduling is no longer allowed" }, "cancelGap": { "type": "number", "description": "Time in seconds before appointment when cancellation is no longer allowed" }, "beforeGap": { "type": "number", "description": "Buffer time in seconds required before this service" }, "afterGap": { "type": "number", "description": "Buffer time in seconds required after this service" }, "fixedTimes": { "type": "boolean", "description": "When allow_custom_duration=true, whether appointments must start and end at fixed times (like fixed check-in/check-out times for multi-duration bookings)", "default": false }, "fixedStartTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must start (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "09:00:00" }, "fixedEndTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must end (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "17:00:00" }, "advanceScheduleThreshold": { "type": "number", "description": "How many days in advance bookings can be made", "default": 0 }, "sendConfirmationEmail": { "type": "boolean", "description": "Whether to send confirmation emails for bookings", "default": true }, "sendReminderEmail": { "type": "boolean", "description": "Whether to send reminder emails before appointments", "default": false }, "sendFeedbackEmail": { "type": "boolean", "description": "Whether to send feedback request emails after appointments", "default": false }, "skipCheckout": { "type": "boolean", "description": "Whether to skip the checkout process for this product (Shopify merchants only)", "default": false }, "status": { "type": "string", "description": "Current status of the product", "enum": [ "active", "inactive" ], "example": "ACTIVE", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the product was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the product was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the product was deleted (for soft deletes)" }, "image": { "description": "Primary image of the product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "productId", "externalId", "externalVariantId", "storeId", "slug", "scheduleId", "productPoolId", "title", "variantTitle", "description", "imageId", "color", "price", "taxable", "duration", "allowCustomDuration", "maxDuration", "maxAttendees", "maxGuests", "allowGuests", "allowCustomerReschedule", "allowCustomerCancel", "rescheduleGap", "cancelGap", "beforeGap", "afterGap", "fixedTimes", "fixedStartTime", "fixedEndTime", "advanceScheduleThreshold", "sendConfirmationEmail", "sendReminderEmail", "sendFeedbackEmail", "skipCheckout", "status", "createdAt", "updatedAt", "deletedAt" ] }, "AppointmentListItemStaffMember": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this staff member record", "example": "123e4567-e89b-12d3-a456-426614174111" }, "userId": { "type": "string", "description": "User ID of the staff member login identity (nullable until linked)", "example": "user-uuid" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this staff member, defines their availability", "example": "123e4567-e89b-12d3-a456-426614174000" }, "imageId": { "type": "string", "description": "ID of the image associated with this staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "firstName": { "type": "string", "description": "First name of the staff member", "example": "John" }, "lastName": { "type": "string", "description": "Last name of the staff member", "example": "Doe" }, "email": { "type": "string", "description": "Email address of the staff member, used for notifications and calendar integration", "example": "john.doe@example.com" }, "slug": { "type": "string", "description": "URL-friendly slug for the staff member (unique per store)", "example": "mike" }, "refreshToken": { "type": "string", "description": "Refresh token for integrations like Google Calendar", "example": "abc123xyz456" }, "createdAt": { "type": "string", "description": "Date and time when the staff member was created", "example": "2025-05-01T12:00:00Z" }, "updatedAt": { "type": "string", "description": "Date and time when the staff member was last updated", "example": "2025-05-15T14:30:00Z" }, "deletedAt": { "type": "string", "description": "Date and time when the staff member was soft deleted", "example": "2025-06-01T09:15:00Z" }, "image": { "description": "Profile image of the staff member", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "storeId", "userId", "scheduleId", "imageId", "firstName", "lastName", "email", "slug", "refreshToken", "createdAt", "updatedAt", "deletedAt" ] }, "AppointmentListItemLocation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the location", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this location", "example": "123e4567-e89b-12d3-a456-426614174001" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this location (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "title": { "type": "string", "description": "Name of the location", "example": "Main Office", "nullable": true }, "description": { "type": "string", "description": "Description of the location", "example": "Our main downtown office location with 3 treatment rooms", "nullable": true }, "slug": { "type": "string", "description": "URL-friendly slug for the location (unique per store)", "example": "new-york" }, "type": { "type": "string", "description": "Type of location", "enum": [ "physical", "online", "delivery" ], "example": "physical" }, "link": { "type": "string", "description": "URL link for online locations", "example": "https://zoom.us/j/123456789", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of address for physical locations", "example": "123 Main Street", "nullable": true }, "addressLine2": { "type": "string", "description": "Second line of address for physical locations", "example": "Suite 200", "nullable": true }, "city": { "type": "string", "description": "City for physical locations", "example": "San Francisco", "nullable": true }, "state": { "type": "string", "description": "State/province for physical locations", "example": "CA", "nullable": true }, "postalCode": { "type": "string", "description": "Postal code for physical locations", "example": "94105", "nullable": true }, "country": { "type": "string", "description": "Country for physical locations", "example": "United States", "nullable": true }, "displayAddress": { "type": "string", "description": "Merchant-defined display address that overrides the auto-formatted address (emails, booking page). Null falls back to the concatenated address fields.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressPlaceId": { "type": "string", "description": "Google Place ID for the physical address", "example": "ChIJIQBpAG2ahYAR_6128GcTUEo", "nullable": true }, "latitude": { "type": "number", "description": "Latitude in WGS84", "example": 37.4224764, "nullable": true }, "longitude": { "type": "number", "description": "Longitude in WGS84", "example": -122.0842499, "nullable": true }, "createdAt": { "type": "string", "description": "Date when the location was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the location was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "type": "string", "description": "Date when the location was deleted (for soft deletes)", "example": "2023-03-10T11:45:00Z", "nullable": true }, "address": { "type": "string", "description": "The formatted address string", "nullable": true } }, "required": [ "id", "storeId", "scheduleId", "title", "description", "slug", "type", "link", "addressLine1", "addressLine2", "city", "state", "postalCode", "country", "addressPlaceId", "latitude", "longitude", "createdAt", "updatedAt", "deletedAt", "address" ] }, "AppointmentListItemCustomer": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the customer", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External customer identifier from integrated system", "example": "1234567890" }, "firstName": { "type": "string", "description": "Customer first name", "example": "John", "nullable": true }, "lastName": { "type": "string", "description": "Customer last name", "example": "Smith", "nullable": true }, "email": { "type": "string", "description": "Customer email address", "example": "john.smith@example.com", "nullable": true }, "phone": { "type": "string", "description": "Customer phone number", "example": "+12135550123", "nullable": true }, "password": { "type": "string", "description": "Hashed password of the customer", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this customer record", "example": "store-uuid" }, "language": { "example": "en", "$ref": "#/components/schemas/LanguageCode" }, "refreshToken": { "type": "string", "description": "Customer refresh token for authentication", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "nullable": true, "writeOnly": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Date when the customer record was created", "example": "2023-01-15T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date when the customer record was last updated", "example": "2023-02-20T14:15:00Z", "nullable": true }, "emailVerifiedAt": { "format": "date-time", "type": "string", "description": "Date and time when the customer verified email", "example": "2023-01-02T00:00:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "isEmailVerified": { "type": "boolean", "description": "Indicates whether customer email is verified" }, "isPasswordSet": { "type": "boolean", "description": "Indicates whether customer password is set" } }, "required": [ "id", "externalId", "firstName", "lastName", "email", "phone", "password", "storeId", "language", "refreshToken", "createdAt", "updatedAt", "emailVerifiedAt", "deletedAt", "isEmailVerified", "isPasswordSet" ] }, "AppointmentListItemOrderLineItem": { "type": "object", "properties": { "orderId": { "type": "string", "description": "ID of the order", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "appointmentId": { "type": "string", "description": "ID of the appointment associated with line item", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "externalId": { "type": "string", "description": "External order line item ID from user's platform (if any)", "example": "12345678", "nullable": true }, "originalUnitPrice": { "type": "number", "description": "Original price of the item", "example": 249.99 }, "discountedUnitPrice": { "type": "number", "description": "Discounted price per unit (approximate — use the line totals for exact amounts)", "example": 249.99 }, "unitTaxAmount": { "type": "number", "description": "Tax amount per unit (approximate — use the line totals for exact amounts)", "example": 0 }, "quantity": { "type": "number", "description": "Quantity of the item ordered", "example": 1 }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "addOnSubtotal": { "type": "number", "description": "Discounted subtotal of the add-ons attached to this line item, before tax" }, "addOnTotalTax": { "type": "number", "description": "Total tax of the add-ons attached to this line item (approximate)" }, "originalSubtotal": { "type": "number", "description": "Original subtotal of the base line across all quantities, before discount", "example": 249.99 }, "totalDiscount": { "type": "number", "description": "Exact total discount applied to the base line, across all quantities", "example": 0 }, "discountedSubtotal": { "type": "number", "description": "Discounted subtotal of the base line (original subtotal − total discount), before tax", "example": 249.99 }, "discountedTotal": { "type": "number", "description": "Discounted total of the base line, including tax when not already in the price", "example": 249.99 }, "totalTax": { "type": "number", "description": "Total tax of the base line across all quantities (approximate)", "example": 0 }, "refundedQuantity": { "type": "number", "description": "The quantity of the line item that has been refunded", "example": 249.99 }, "refundableQuantity": { "type": "number", "description": "The quantity of the line item that can be refunded", "example": 249.99 } }, "required": [ "orderId", "appointmentId", "externalId", "originalUnitPrice", "discountedUnitPrice", "unitTaxAmount", "quantity", "createdAt", "updatedAt", "deletedAt", "addOnSubtotal", "addOnTotalTax", "originalSubtotal", "totalDiscount", "discountedSubtotal", "discountedTotal", "totalTax", "refundedQuantity", "refundableQuantity" ] }, "AppointmentListItemResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the appointment", "example": "123e4567-e89b-12d3-a456-426614174000" }, "name": { "type": "string", "description": "Generated appointment name for the user (starts at 1001 and increments)", "example": "1001" }, "productId": { "type": "string", "description": "ID of the service/product for this appointment", "example": "123e4567-e89b-12d3-a456-426614174001" }, "staffMemberId": { "type": "string", "description": "ID of the staff member assigned to this appointment (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "locationId": { "type": "string", "description": "ID of the location where the appointment will take place (if any)", "example": "123e4567-e89b-12d3-a456-426614174003", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this appointment", "example": "123e4567-e89b-12d3-a456-426614174004" }, "customerId": { "type": "string", "description": "ID of the customer who booked the appointment", "example": "123e4567-e89b-12d3-a456-426614174005", "nullable": true }, "externalOrderId": { "type": "string", "description": "External order ID from user's platform (if any)", "example": "12345678", "nullable": true }, "externalOrderName": { "type": "string", "description": "External order name/reference from user's platform", "example": "#1001", "nullable": true }, "from": { "format": "date-time", "type": "string", "description": "Start date and time of the appointment (UTC timezone)", "example": "2023-06-15T09:00:00Z" }, "to": { "format": "date-time", "type": "string", "description": "End date and time of the appointment (UTC timezone)", "example": "2023-06-15T10:00:00Z" }, "displayAddress": { "type": "string", "description": "Merchant-defined display address from the location; overrides the concatenated address fields in notifications. Null falls back to the structured address.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressId": { "type": "string", "description": "ID of the linked service/delivery address", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of the appointment address", "nullable": true, "deprecated": true }, "addressLine2": { "type": "string", "description": "Second line of the appointment address", "nullable": true, "deprecated": true }, "city": { "type": "string", "description": "City of the appointment location", "nullable": true, "deprecated": true }, "state": { "type": "string", "description": "State/province of the appointment location", "nullable": true, "deprecated": true }, "postalCode": { "type": "string", "description": "Postal/zip code of the appointment location", "nullable": true, "deprecated": true }, "country": { "type": "string", "description": "Country of the appointment location", "nullable": true, "deprecated": true }, "status": { "example": "scheduled", "$ref": "#/components/schemas/AppointmentStatusType" }, "internalNote": { "type": "string", "description": "Internal notes about the appointment (not visible to customers)", "example": "Customer requested extra attention for specific needs", "nullable": true }, "createdBy": { "example": "customer", "$ref": "#/components/schemas/AppointmentCreatedByEnum" }, "reminderSentAt": { "format": "date-time", "type": "string", "description": "Date and time when reminder was sent to the customer", "example": "2023-06-14T09:00:00Z", "nullable": true }, "numberOfAttendees": { "type": "number", "description": "Number of people attending the appointment", "example": 1, "default": 1 }, "customAttributes": { "type": "object", "description": "Custom key-value attributes (strings) attached to the appointment. Max 250 entries.", "additionalProperties": { "type": "string" }, "nullable": true, "example": { "source": "widget", "party_size": "4" } }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "deliveryAddress": { "description": "Linked service/delivery address (DELIVERY locations)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DeliveryAddress" } ] }, "product": { "description": "Service/product details for this appointment", "allOf": [ { "$ref": "#/components/schemas/AppointmentListItemProduct" } ] }, "staffMember": { "description": "Staff member assigned to this appointment", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/AppointmentListItemStaffMember" } ] }, "location": { "description": "Location where the appointment will take place", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/AppointmentListItemLocation" } ] }, "customer": { "description": "Customer who booked the appointment", "allOf": [ { "$ref": "#/components/schemas/AppointmentListItemCustomer" } ] }, "orderLineItem": { "description": "The order line item linking this appointment to its order", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/AppointmentListItemOrderLineItem" } ] } }, "required": [ "id", "name", "productId", "staffMemberId", "locationId", "storeId", "customerId", "externalOrderId", "externalOrderName", "from", "to", "displayAddress", "status", "internalNote", "createdBy", "reminderSentAt", "numberOfAttendees", "createdAt", "updatedAt", "deletedAt", "product", "staffMember", "location", "customer", "orderLineItem" ] }, "AppointmentDetailProduct": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "productId": { "type": "string", "description": "ID of the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID)", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID)", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this product", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the product (unique per store)", "example": "haircut-basic" }, "scheduleId": { "type": "string", "description": "ID of the schedule associated with this product" }, "productPoolId": { "type": "string", "description": "ID of the product pool this product belongs to (controls overlap prevention)", "nullable": true }, "title": { "type": "string", "description": "Title of the product", "example": "Haircut Service" }, "variantTitle": { "type": "string", "description": "Title of the specific product variant", "example": "Short Hair" }, "description": { "type": "string", "description": "Detailed description of the product" }, "imageId": { "type": "string", "description": "ID of the product image" }, "color": { "type": "string", "description": "Color code for displaying the product", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "BLUE", "default": "slate" }, "price": { "type": "number", "description": "Price of the product", "example": 250 }, "taxable": { "type": "boolean", "description": "Whether the product is taxable", "default": false }, "duration": { "type": "number", "description": "Duration of the service in seconds", "example": 3600 }, "allowCustomDuration": { "type": "boolean", "description": "Whether customers can customize the duration by selecting multiples of the base service duration (e.g., if base duration is 1 day, customers can book 1, 2, 3+ days)", "default": false }, "maxDuration": { "type": "number", "description": "When allow_custom_duration=true, maximum duration allowed for multi-duration bookings in seconds (-1 for unlimited)", "default": -1 }, "maxAttendees": { "type": "number", "description": "Maximum number of attendees allowed", "default": 1 }, "maxGuests": { "type": "number", "description": "Maximum number of guests allowed per appointment. Null means unlimited.", "nullable": true }, "allowGuests": { "type": "boolean", "description": "Whether customers can invite guests to the appointment", "default": false }, "allowCustomerReschedule": { "type": "boolean", "description": "Whether customers can reschedule their bookings", "default": false }, "allowCustomerCancel": { "type": "boolean", "description": "Whether customers can cancel their bookings", "default": false }, "rescheduleGap": { "type": "number", "description": "Time in seconds before appointment when rescheduling is no longer allowed" }, "cancelGap": { "type": "number", "description": "Time in seconds before appointment when cancellation is no longer allowed" }, "beforeGap": { "type": "number", "description": "Buffer time in seconds required before this service" }, "afterGap": { "type": "number", "description": "Buffer time in seconds required after this service" }, "fixedTimes": { "type": "boolean", "description": "When allow_custom_duration=true, whether appointments must start and end at fixed times (like fixed check-in/check-out times for multi-duration bookings)", "default": false }, "fixedStartTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must start (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "09:00:00" }, "fixedEndTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must end (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "17:00:00" }, "advanceScheduleThreshold": { "type": "number", "description": "How many days in advance bookings can be made", "default": 0 }, "sendConfirmationEmail": { "type": "boolean", "description": "Whether to send confirmation emails for bookings", "default": true }, "sendReminderEmail": { "type": "boolean", "description": "Whether to send reminder emails before appointments", "default": false }, "sendFeedbackEmail": { "type": "boolean", "description": "Whether to send feedback request emails after appointments", "default": false }, "skipCheckout": { "type": "boolean", "description": "Whether to skip the checkout process for this product (Shopify merchants only)", "default": false }, "status": { "type": "string", "description": "Current status of the product", "enum": [ "active", "inactive" ], "example": "ACTIVE", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the product was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the product was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the product was deleted (for soft deletes)" }, "image": { "description": "Primary image of the product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "productId", "externalId", "externalVariantId", "storeId", "slug", "scheduleId", "productPoolId", "title", "variantTitle", "description", "imageId", "color", "price", "taxable", "duration", "allowCustomDuration", "maxDuration", "maxAttendees", "maxGuests", "allowGuests", "allowCustomerReschedule", "allowCustomerCancel", "rescheduleGap", "cancelGap", "beforeGap", "afterGap", "fixedTimes", "fixedStartTime", "fixedEndTime", "advanceScheduleThreshold", "sendConfirmationEmail", "sendReminderEmail", "sendFeedbackEmail", "skipCheckout", "status", "createdAt", "updatedAt", "deletedAt" ] }, "AppointmentDetailStaffMember": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this staff member record", "example": "123e4567-e89b-12d3-a456-426614174111" }, "userId": { "type": "string", "description": "User ID of the staff member login identity (nullable until linked)", "example": "user-uuid" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this staff member, defines their availability", "example": "123e4567-e89b-12d3-a456-426614174000" }, "imageId": { "type": "string", "description": "ID of the image associated with this staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "firstName": { "type": "string", "description": "First name of the staff member", "example": "John" }, "lastName": { "type": "string", "description": "Last name of the staff member", "example": "Doe" }, "email": { "type": "string", "description": "Email address of the staff member, used for notifications and calendar integration", "example": "john.doe@example.com" }, "slug": { "type": "string", "description": "URL-friendly slug for the staff member (unique per store)", "example": "mike" }, "refreshToken": { "type": "string", "description": "Refresh token for integrations like Google Calendar", "example": "abc123xyz456" }, "createdAt": { "type": "string", "description": "Date and time when the staff member was created", "example": "2025-05-01T12:00:00Z" }, "updatedAt": { "type": "string", "description": "Date and time when the staff member was last updated", "example": "2025-05-15T14:30:00Z" }, "deletedAt": { "type": "string", "description": "Date and time when the staff member was soft deleted", "example": "2025-06-01T09:15:00Z" }, "image": { "description": "Profile image of the staff member", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "storeId", "userId", "scheduleId", "imageId", "firstName", "lastName", "email", "slug", "refreshToken", "createdAt", "updatedAt", "deletedAt" ] }, "AppointmentDetailLocation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the location", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this location", "example": "123e4567-e89b-12d3-a456-426614174001" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this location (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "title": { "type": "string", "description": "Name of the location", "example": "Main Office", "nullable": true }, "description": { "type": "string", "description": "Description of the location", "example": "Our main downtown office location with 3 treatment rooms", "nullable": true }, "slug": { "type": "string", "description": "URL-friendly slug for the location (unique per store)", "example": "new-york" }, "type": { "type": "string", "description": "Type of location", "enum": [ "physical", "online", "delivery" ], "example": "physical" }, "link": { "type": "string", "description": "URL link for online locations", "example": "https://zoom.us/j/123456789", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of address for physical locations", "example": "123 Main Street", "nullable": true }, "addressLine2": { "type": "string", "description": "Second line of address for physical locations", "example": "Suite 200", "nullable": true }, "city": { "type": "string", "description": "City for physical locations", "example": "San Francisco", "nullable": true }, "state": { "type": "string", "description": "State/province for physical locations", "example": "CA", "nullable": true }, "postalCode": { "type": "string", "description": "Postal code for physical locations", "example": "94105", "nullable": true }, "country": { "type": "string", "description": "Country for physical locations", "example": "United States", "nullable": true }, "displayAddress": { "type": "string", "description": "Merchant-defined display address that overrides the auto-formatted address (emails, booking page). Null falls back to the concatenated address fields.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressPlaceId": { "type": "string", "description": "Google Place ID for the physical address", "example": "ChIJIQBpAG2ahYAR_6128GcTUEo", "nullable": true }, "latitude": { "type": "number", "description": "Latitude in WGS84", "example": 37.4224764, "nullable": true }, "longitude": { "type": "number", "description": "Longitude in WGS84", "example": -122.0842499, "nullable": true }, "createdAt": { "type": "string", "description": "Date when the location was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the location was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "type": "string", "description": "Date when the location was deleted (for soft deletes)", "example": "2023-03-10T11:45:00Z", "nullable": true }, "address": { "type": "string", "description": "The formatted address string", "nullable": true } }, "required": [ "id", "storeId", "scheduleId", "title", "description", "slug", "type", "link", "addressLine1", "addressLine2", "city", "state", "postalCode", "country", "addressPlaceId", "latitude", "longitude", "createdAt", "updatedAt", "deletedAt", "address" ] }, "AppointmentDetailCustomer": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the customer", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External customer identifier from integrated system", "example": "1234567890" }, "firstName": { "type": "string", "description": "Customer first name", "example": "John", "nullable": true }, "lastName": { "type": "string", "description": "Customer last name", "example": "Smith", "nullable": true }, "email": { "type": "string", "description": "Customer email address", "example": "john.smith@example.com", "nullable": true }, "phone": { "type": "string", "description": "Customer phone number", "example": "+12135550123", "nullable": true }, "password": { "type": "string", "description": "Hashed password of the customer", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this customer record", "example": "store-uuid" }, "language": { "example": "en", "$ref": "#/components/schemas/LanguageCode" }, "refreshToken": { "type": "string", "description": "Customer refresh token for authentication", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "nullable": true, "writeOnly": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Date when the customer record was created", "example": "2023-01-15T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date when the customer record was last updated", "example": "2023-02-20T14:15:00Z", "nullable": true }, "emailVerifiedAt": { "format": "date-time", "type": "string", "description": "Date and time when the customer verified email", "example": "2023-01-02T00:00:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "isEmailVerified": { "type": "boolean", "description": "Indicates whether customer email is verified" }, "isPasswordSet": { "type": "boolean", "description": "Indicates whether customer password is set" } }, "required": [ "id", "externalId", "firstName", "lastName", "email", "phone", "password", "storeId", "language", "refreshToken", "createdAt", "updatedAt", "emailVerifiedAt", "deletedAt", "isEmailVerified", "isPasswordSet" ] }, "AppointmentDetailAddOnItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the add-on", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID) for synced add-ons", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID) for synced add-ons", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this add-on", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the add-on (unique per store)", "example": "child-seat" }, "title": { "type": "string", "description": "Title of the add-on", "example": "Child Seat" }, "description": { "type": "string", "description": "Detailed description of the add-on" }, "imageId": { "type": "string", "description": "ID of the primary image for the add-on" }, "color": { "type": "string", "description": "Color code used when displaying the add-on", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "slate", "default": "slate" }, "price": { "type": "number", "description": "Unit price of the add-on", "example": 15 }, "taxable": { "type": "boolean", "description": "Whether the add-on is taxable", "default": true }, "durationMultiplied": { "type": "boolean", "description": "When true, the add-on is charged per base-duration unit of the parent appointment. Quantity on the cart/order line item mirrors the parent CartItem.quantity (i.e., the booked duration units). Only meaningful for attached products with allowCustomDuration=true.", "default": false }, "maxQuantity": { "type": "number", "description": "Maximum quantity a customer can pick for this add-on. Only applies to fixed add-ons (durationMultiplied=false). Null means unlimited.", "example": 4, "minimum": 1, "nullable": true }, "status": { "type": "string", "description": "Current status of the add-on", "enum": [ "active", "inactive" ], "example": "active", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the add-on was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the add-on was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the add-on was soft-deleted" }, "image": { "description": "Primary image of the add-on", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "externalId", "externalVariantId", "storeId", "slug", "title", "description", "imageId", "color", "price", "taxable", "durationMultiplied", "maxQuantity", "status", "createdAt", "updatedAt", "deletedAt" ] }, "AppointmentDetailAddOn": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier" }, "appointmentId": { "type": "string", "description": "Appointment ID" }, "addOnId": { "type": "string", "description": "Add-on ID" }, "quantity": { "type": "number", "description": "Quantity of this add-on for the appointment", "default": 1 }, "createdAt": { "format": "date-time", "type": "string", "description": "Created at timestamp" }, "addOn": { "description": "The add-on details", "allOf": [ { "$ref": "#/components/schemas/AppointmentDetailAddOnItem" } ] } }, "required": [ "id", "appointmentId", "addOnId", "quantity", "createdAt", "addOn" ] }, "AppointmentDetailGuest": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier" }, "appointmentId": { "type": "string", "description": "Appointment ID" }, "email": { "type": "string", "description": "Guest email address" }, "createdAt": { "format": "date-time", "type": "string", "description": "Created at timestamp" } }, "required": [ "id", "appointmentId", "email", "createdAt" ] }, "AppointmentDetailFeedbackAnswerFile": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "S3 object key", "example": "customer-uploads/store-id/uuid-logo.png", "nullable": true }, "url": { "type": "string", "description": "Stored URL (informational; re-signed on read)", "nullable": true }, "filename": { "type": "string", "description": "Original filename", "example": "logo.png", "nullable": true }, "mime": { "type": "string", "description": "MIME type", "example": "image/png", "nullable": true }, "size": { "type": "number", "description": "File size in bytes", "example": 20480, "nullable": true }, "answerId": { "type": "string", "description": "ID of the feedback-question answer this file belongs to", "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Creation timestamp", "example": "2023-01-01T12:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Last update timestamp", "example": "2023-01-02T12:00:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Soft deletion timestamp", "example": "2023-01-03T12:00:00Z", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this file", "example": "store-uuid", "nullable": true } }, "required": [ "id", "externalId", "url", "filename", "mime", "size", "createdAt", "updatedAt", "deletedAt", "storeId" ] }, "AppointmentDetailFeedbackAnswer": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the feedback question answer", "example": "123e4567-e89b-12d3-a456-426614174000" }, "appointmentId": { "type": "string", "description": "ID of the appointment this feedback relates to", "example": "123e4567-e89b-12d3-a456-426614174001" }, "questionId": { "type": "string", "description": "ID of the feedback question (set to null if question is deleted)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "question": { "type": "string", "description": "The feedback question text presented to the customer", "example": "How would you rate the quality of service provided?" }, "answer": { "type": "string", "description": "Customer's answer to the feedback question", "example": "The service was excellent, very professional and timely.", "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when this feedback was recorded", "example": "2023-06-15T14:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when this feedback was last updated", "example": "2023-06-15T15:45:00Z", "nullable": true }, "files": { "description": "Files the customer uploaded for this answer (file-upload questions only)", "type": "array", "items": { "$ref": "#/components/schemas/AppointmentDetailFeedbackAnswerFile" } } }, "required": [ "id", "appointmentId", "questionId", "question", "answer", "createdAt", "updatedAt", "files" ] }, "AppointmentDetailCheckoutAnswerFile": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "S3 object key", "example": "customer-uploads/store-id/uuid-logo.png", "nullable": true }, "url": { "type": "string", "description": "Stored URL (informational; re-signed on read)", "nullable": true }, "filename": { "type": "string", "description": "Original filename", "example": "logo.png", "nullable": true }, "mime": { "type": "string", "description": "MIME type", "example": "image/png", "nullable": true }, "size": { "type": "number", "description": "File size in bytes", "example": 20480, "nullable": true }, "answerId": { "type": "string", "description": "ID of the checkout-question answer this file belongs to", "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Creation timestamp", "example": "2023-01-01T12:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Last update timestamp", "example": "2023-01-02T12:00:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Soft deletion timestamp", "example": "2023-01-03T12:00:00Z", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this file", "example": "store-uuid", "nullable": true } }, "required": [ "id", "externalId", "url", "filename", "mime", "size", "createdAt", "updatedAt", "deletedAt", "storeId" ] }, "AppointmentDetailCheckoutAnswer": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the checkout question answer", "example": "123e4567-e89b-12d3-a456-426614174000" }, "appointmentId": { "type": "string", "description": "ID of the appointment this question answer relates to", "example": "123e4567-e89b-12d3-a456-426614174001" }, "questionId": { "type": "string", "description": "ID of the checkout question (set to null if question is deleted)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "question": { "type": "string", "description": "The checkout question text presented to the customer", "example": "Do you have any allergies or medical conditions we should know about?" }, "answer": { "type": "string", "description": "Customer's answer to the checkout question", "example": "I have a mild allergy to latex, please use vinyl gloves.", "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when this answer was recorded", "example": "2023-06-10T14:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when this answer was last updated", "example": "2023-06-10T15:45:00Z", "nullable": true }, "files": { "description": "Files the customer uploaded for this answer (file-upload questions only)", "type": "array", "items": { "$ref": "#/components/schemas/AppointmentDetailCheckoutAnswerFile" } } }, "required": [ "id", "appointmentId", "questionId", "question", "answer", "createdAt", "updatedAt", "files" ] }, "AppointmentDetailOrderTransaction": { "type": "object", "properties": { "orderId": { "type": "string", "description": "ID of the order", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "externalId": { "type": "string", "description": "External order transaction ID from user's platform (if any)", "example": "12345678", "nullable": true }, "parentId": { "type": "string", "description": "The parent transaction ID", "example": "12345678", "nullable": true }, "refundId": { "type": "string", "description": "The refund ID this transaction belongs to (if any)", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "type": { "type": "string", "description": "The type of transaction", "example": "sale", "enum": [ "authorization", "capture", "void", "sale", "refund" ] }, "amount": { "type": "number", "description": "Amount of the transaction", "example": 249.99 }, "currencyCode": { "type": "string", "description": "The currency code", "example": "USD" }, "gateway": { "type": "string", "description": "The payment gateway", "example": "shopify", "enum": [ "shopify", "cash", "bank_transfer", "stripe" ], "deprecated": true }, "provider": { "type": "string", "description": "The payment provider (replaces gateway)", "example": "stripe", "enum": [ "stripe", "cash", "bank_transfer", "shopify", "no_payment_required" ] }, "status": { "type": "string", "description": "The status of the transaction", "example": "success", "enum": [ "pending", "success", "failed" ] }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "refundableAmount": { "type": "number", "description": "The refundable amount for this transaction", "example": 249.99 }, "refundedAmount": { "type": "number", "description": "The refunded amount for this transaction", "example": 249.99 }, "isRefundable": { "type": "boolean", "description": "Whether this transaction is refundable", "example": true } }, "required": [ "orderId", "externalId", "parentId", "refundId", "type", "amount", "currencyCode", "gateway", "provider", "status", "createdAt", "updatedAt", "deletedAt", "refundableAmount", "refundedAmount", "isRefundable" ] }, "AppointmentDetailOrderItemProduct": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "productId": { "type": "string", "description": "ID of the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID)", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID)", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this product", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the product (unique per store)", "example": "haircut-basic" }, "scheduleId": { "type": "string", "description": "ID of the schedule associated with this product" }, "productPoolId": { "type": "string", "description": "ID of the product pool this product belongs to (controls overlap prevention)", "nullable": true }, "title": { "type": "string", "description": "Title of the product", "example": "Haircut Service" }, "variantTitle": { "type": "string", "description": "Title of the specific product variant", "example": "Short Hair" }, "description": { "type": "string", "description": "Detailed description of the product" }, "imageId": { "type": "string", "description": "ID of the product image" }, "color": { "type": "string", "description": "Color code for displaying the product", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "BLUE", "default": "slate" }, "price": { "type": "number", "description": "Price of the product", "example": 250 }, "taxable": { "type": "boolean", "description": "Whether the product is taxable", "default": false }, "duration": { "type": "number", "description": "Duration of the service in seconds", "example": 3600 }, "allowCustomDuration": { "type": "boolean", "description": "Whether customers can customize the duration by selecting multiples of the base service duration (e.g., if base duration is 1 day, customers can book 1, 2, 3+ days)", "default": false }, "maxDuration": { "type": "number", "description": "When allow_custom_duration=true, maximum duration allowed for multi-duration bookings in seconds (-1 for unlimited)", "default": -1 }, "maxAttendees": { "type": "number", "description": "Maximum number of attendees allowed", "default": 1 }, "maxGuests": { "type": "number", "description": "Maximum number of guests allowed per appointment. Null means unlimited.", "nullable": true }, "allowGuests": { "type": "boolean", "description": "Whether customers can invite guests to the appointment", "default": false }, "allowCustomerReschedule": { "type": "boolean", "description": "Whether customers can reschedule their bookings", "default": false }, "allowCustomerCancel": { "type": "boolean", "description": "Whether customers can cancel their bookings", "default": false }, "rescheduleGap": { "type": "number", "description": "Time in seconds before appointment when rescheduling is no longer allowed" }, "cancelGap": { "type": "number", "description": "Time in seconds before appointment when cancellation is no longer allowed" }, "beforeGap": { "type": "number", "description": "Buffer time in seconds required before this service" }, "afterGap": { "type": "number", "description": "Buffer time in seconds required after this service" }, "fixedTimes": { "type": "boolean", "description": "When allow_custom_duration=true, whether appointments must start and end at fixed times (like fixed check-in/check-out times for multi-duration bookings)", "default": false }, "fixedStartTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must start (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "09:00:00" }, "fixedEndTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must end (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "17:00:00" }, "advanceScheduleThreshold": { "type": "number", "description": "How many days in advance bookings can be made", "default": 0 }, "sendConfirmationEmail": { "type": "boolean", "description": "Whether to send confirmation emails for bookings", "default": true }, "sendReminderEmail": { "type": "boolean", "description": "Whether to send reminder emails before appointments", "default": false }, "sendFeedbackEmail": { "type": "boolean", "description": "Whether to send feedback request emails after appointments", "default": false }, "skipCheckout": { "type": "boolean", "description": "Whether to skip the checkout process for this product (Shopify merchants only)", "default": false }, "status": { "type": "string", "description": "Current status of the product", "enum": [ "active", "inactive" ], "example": "ACTIVE", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the product was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the product was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the product was deleted (for soft deletes)" }, "image": { "description": "Primary image of the product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "productId", "externalId", "externalVariantId", "storeId", "slug", "scheduleId", "productPoolId", "title", "variantTitle", "description", "imageId", "color", "price", "taxable", "duration", "allowCustomDuration", "maxDuration", "maxAttendees", "maxGuests", "allowGuests", "allowCustomerReschedule", "allowCustomerCancel", "rescheduleGap", "cancelGap", "beforeGap", "afterGap", "fixedTimes", "fixedStartTime", "fixedEndTime", "advanceScheduleThreshold", "sendConfirmationEmail", "sendReminderEmail", "sendFeedbackEmail", "skipCheckout", "status", "createdAt", "updatedAt", "deletedAt" ] }, "AppointmentDetailOrderItemStaffMember": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this staff member record", "example": "123e4567-e89b-12d3-a456-426614174111" }, "userId": { "type": "string", "description": "User ID of the staff member login identity (nullable until linked)", "example": "user-uuid" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this staff member, defines their availability", "example": "123e4567-e89b-12d3-a456-426614174000" }, "imageId": { "type": "string", "description": "ID of the image associated with this staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "firstName": { "type": "string", "description": "First name of the staff member", "example": "John" }, "lastName": { "type": "string", "description": "Last name of the staff member", "example": "Doe" }, "email": { "type": "string", "description": "Email address of the staff member, used for notifications and calendar integration", "example": "john.doe@example.com" }, "slug": { "type": "string", "description": "URL-friendly slug for the staff member (unique per store)", "example": "mike" }, "refreshToken": { "type": "string", "description": "Refresh token for integrations like Google Calendar", "example": "abc123xyz456" }, "createdAt": { "type": "string", "description": "Date and time when the staff member was created", "example": "2025-05-01T12:00:00Z" }, "updatedAt": { "type": "string", "description": "Date and time when the staff member was last updated", "example": "2025-05-15T14:30:00Z" }, "deletedAt": { "type": "string", "description": "Date and time when the staff member was soft deleted", "example": "2025-06-01T09:15:00Z" }, "image": { "description": "Profile image of the staff member", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "storeId", "userId", "scheduleId", "imageId", "firstName", "lastName", "email", "slug", "refreshToken", "createdAt", "updatedAt", "deletedAt" ] }, "AppointmentDetailOrderItemLocation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the location", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this location", "example": "123e4567-e89b-12d3-a456-426614174001" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this location (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "title": { "type": "string", "description": "Name of the location", "example": "Main Office", "nullable": true }, "description": { "type": "string", "description": "Description of the location", "example": "Our main downtown office location with 3 treatment rooms", "nullable": true }, "slug": { "type": "string", "description": "URL-friendly slug for the location (unique per store)", "example": "new-york" }, "type": { "type": "string", "description": "Type of location", "enum": [ "physical", "online", "delivery" ], "example": "physical" }, "link": { "type": "string", "description": "URL link for online locations", "example": "https://zoom.us/j/123456789", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of address for physical locations", "example": "123 Main Street", "nullable": true }, "addressLine2": { "type": "string", "description": "Second line of address for physical locations", "example": "Suite 200", "nullable": true }, "city": { "type": "string", "description": "City for physical locations", "example": "San Francisco", "nullable": true }, "state": { "type": "string", "description": "State/province for physical locations", "example": "CA", "nullable": true }, "postalCode": { "type": "string", "description": "Postal code for physical locations", "example": "94105", "nullable": true }, "country": { "type": "string", "description": "Country for physical locations", "example": "United States", "nullable": true }, "displayAddress": { "type": "string", "description": "Merchant-defined display address that overrides the auto-formatted address (emails, booking page). Null falls back to the concatenated address fields.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressPlaceId": { "type": "string", "description": "Google Place ID for the physical address", "example": "ChIJIQBpAG2ahYAR_6128GcTUEo", "nullable": true }, "latitude": { "type": "number", "description": "Latitude in WGS84", "example": 37.4224764, "nullable": true }, "longitude": { "type": "number", "description": "Longitude in WGS84", "example": -122.0842499, "nullable": true }, "createdAt": { "type": "string", "description": "Date when the location was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the location was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "type": "string", "description": "Date when the location was deleted (for soft deletes)", "example": "2023-03-10T11:45:00Z", "nullable": true }, "address": { "type": "string", "description": "The formatted address string", "nullable": true } }, "required": [ "id", "storeId", "scheduleId", "title", "description", "slug", "type", "link", "addressLine1", "addressLine2", "city", "state", "postalCode", "country", "addressPlaceId", "latitude", "longitude", "createdAt", "updatedAt", "deletedAt", "address" ] }, "AppointmentDetailOrderItemAppointment": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the appointment", "example": "123e4567-e89b-12d3-a456-426614174000" }, "name": { "type": "string", "description": "Generated appointment name for the user (starts at 1001 and increments)", "example": "1001" }, "productId": { "type": "string", "description": "ID of the service/product for this appointment", "example": "123e4567-e89b-12d3-a456-426614174001" }, "staffMemberId": { "type": "string", "description": "ID of the staff member assigned to this appointment (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "locationId": { "type": "string", "description": "ID of the location where the appointment will take place (if any)", "example": "123e4567-e89b-12d3-a456-426614174003", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this appointment", "example": "123e4567-e89b-12d3-a456-426614174004" }, "customerId": { "type": "string", "description": "ID of the customer who booked the appointment", "example": "123e4567-e89b-12d3-a456-426614174005", "nullable": true }, "externalOrderId": { "type": "string", "description": "External order ID from user's platform (if any)", "example": "12345678", "nullable": true }, "externalOrderName": { "type": "string", "description": "External order name/reference from user's platform", "example": "#1001", "nullable": true }, "from": { "format": "date-time", "type": "string", "description": "Start date and time of the appointment (UTC timezone)", "example": "2023-06-15T09:00:00Z" }, "to": { "format": "date-time", "type": "string", "description": "End date and time of the appointment (UTC timezone)", "example": "2023-06-15T10:00:00Z" }, "displayAddress": { "type": "string", "description": "Merchant-defined display address from the location; overrides the concatenated address fields in notifications. Null falls back to the structured address.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressId": { "type": "string", "description": "ID of the linked service/delivery address", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of the appointment address", "nullable": true, "deprecated": true }, "addressLine2": { "type": "string", "description": "Second line of the appointment address", "nullable": true, "deprecated": true }, "city": { "type": "string", "description": "City of the appointment location", "nullable": true, "deprecated": true }, "state": { "type": "string", "description": "State/province of the appointment location", "nullable": true, "deprecated": true }, "postalCode": { "type": "string", "description": "Postal/zip code of the appointment location", "nullable": true, "deprecated": true }, "country": { "type": "string", "description": "Country of the appointment location", "nullable": true, "deprecated": true }, "status": { "example": "scheduled", "$ref": "#/components/schemas/AppointmentStatusType" }, "internalNote": { "type": "string", "description": "Internal notes about the appointment (not visible to customers)", "example": "Customer requested extra attention for specific needs", "nullable": true }, "createdBy": { "example": "customer", "$ref": "#/components/schemas/AppointmentCreatedByEnum" }, "reminderSentAt": { "format": "date-time", "type": "string", "description": "Date and time when reminder was sent to the customer", "example": "2023-06-14T09:00:00Z", "nullable": true }, "numberOfAttendees": { "type": "number", "description": "Number of people attending the appointment", "example": 1, "default": 1 }, "customAttributes": { "type": "object", "description": "Custom key-value attributes (strings) attached to the appointment. Max 250 entries.", "additionalProperties": { "type": "string" }, "nullable": true, "example": { "source": "widget", "party_size": "4" } }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "deliveryAddress": { "description": "Linked service/delivery address (DELIVERY locations)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DeliveryAddress" } ] }, "product": { "description": "Service/product for this line item", "allOf": [ { "$ref": "#/components/schemas/AppointmentDetailOrderItemProduct" } ] }, "staffMember": { "description": "Staff member for this line item", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/AppointmentDetailOrderItemStaffMember" } ] }, "location": { "description": "Location for this line item", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/AppointmentDetailOrderItemLocation" } ] } }, "required": [ "id", "name", "productId", "staffMemberId", "locationId", "storeId", "customerId", "externalOrderId", "externalOrderName", "from", "to", "displayAddress", "status", "internalNote", "createdBy", "reminderSentAt", "numberOfAttendees", "createdAt", "updatedAt", "deletedAt", "product", "staffMember", "location" ] }, "AppointmentDetailOrderItemAddOnItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the add-on", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID) for synced add-ons", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID) for synced add-ons", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this add-on", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the add-on (unique per store)", "example": "child-seat" }, "title": { "type": "string", "description": "Title of the add-on", "example": "Child Seat" }, "description": { "type": "string", "description": "Detailed description of the add-on" }, "imageId": { "type": "string", "description": "ID of the primary image for the add-on" }, "color": { "type": "string", "description": "Color code used when displaying the add-on", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "slate", "default": "slate" }, "price": { "type": "number", "description": "Unit price of the add-on", "example": 15 }, "taxable": { "type": "boolean", "description": "Whether the add-on is taxable", "default": true }, "durationMultiplied": { "type": "boolean", "description": "When true, the add-on is charged per base-duration unit of the parent appointment. Quantity on the cart/order line item mirrors the parent CartItem.quantity (i.e., the booked duration units). Only meaningful for attached products with allowCustomDuration=true.", "default": false }, "maxQuantity": { "type": "number", "description": "Maximum quantity a customer can pick for this add-on. Only applies to fixed add-ons (durationMultiplied=false). Null means unlimited.", "example": 4, "minimum": 1, "nullable": true }, "status": { "type": "string", "description": "Current status of the add-on", "enum": [ "active", "inactive" ], "example": "active", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the add-on was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the add-on was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the add-on was soft-deleted" }, "image": { "description": "Primary image of the add-on", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "externalId", "externalVariantId", "storeId", "slug", "title", "description", "imageId", "color", "price", "taxable", "durationMultiplied", "maxQuantity", "status", "createdAt", "updatedAt", "deletedAt" ] }, "AppointmentDetailOrderItemAddOn": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the order add-on line item" }, "orderId": { "type": "string", "description": "ID of the order" }, "lineItemId": { "type": "string", "description": "ID of the parent order line item (the appointment) this add-on belongs to" }, "addOnId": { "type": "string", "description": "ID of the add-on" }, "externalId": { "type": "string", "description": "External line item ID from the platform (e.g., Shopify) for this add-on", "nullable": true }, "originalUnitPrice": { "type": "number", "description": "Original unit price" }, "discountedUnitPrice": { "type": "number", "description": "Discounted price per unit (approximate — use the line totals for exact amounts)" }, "unitTaxAmount": { "type": "number", "description": "Tax amount per unit (approximate — use the line totals for exact amounts)" }, "quantity": { "type": "number", "description": "Quantity. For fixed add-ons this is the customer-picked count; for duration-multiplied add-ons it is the number of base-duration units of the parent appointment, snapshotted at cart → order conversion." }, "createdAt": { "format": "date-time", "type": "string", "description": "Created at" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Updated at", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Deleted at", "nullable": true }, "originalSubtotal": { "type": "number", "description": "Original subtotal of this add-on across all quantities, before discount" }, "totalDiscount": { "type": "number", "description": "Total discount applied to this add-on, across all quantities (approximate)" }, "discountedSubtotal": { "type": "number", "description": "Discounted subtotal of this add-on (original subtotal − total discount), before tax" }, "discountedTotal": { "type": "number", "description": "Discounted total of this add-on line item, including tax when not already in the price" }, "totalTax": { "type": "number", "description": "Total tax for this add-on line item (approximate)" }, "refundedQuantity": { "type": "number", "description": "Quantity already refunded" }, "refundableQuantity": { "type": "number", "description": "Remaining refundable quantity" }, "addOn": { "description": "The add-on", "allOf": [ { "$ref": "#/components/schemas/AppointmentDetailOrderItemAddOnItem" } ] } }, "required": [ "id", "orderId", "lineItemId", "addOnId", "externalId", "originalUnitPrice", "discountedUnitPrice", "unitTaxAmount", "quantity", "createdAt", "updatedAt", "deletedAt", "originalSubtotal", "totalDiscount", "discountedSubtotal", "discountedTotal", "totalTax", "refundedQuantity", "refundableQuantity", "addOn" ] }, "AppointmentDetailOrderItem": { "type": "object", "properties": { "orderId": { "type": "string", "description": "ID of the order", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "appointmentId": { "type": "string", "description": "ID of the appointment associated with line item", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "externalId": { "type": "string", "description": "External order line item ID from user's platform (if any)", "example": "12345678", "nullable": true }, "originalUnitPrice": { "type": "number", "description": "Original price of the item", "example": 249.99 }, "discountedUnitPrice": { "type": "number", "description": "Discounted price per unit (approximate — use the line totals for exact amounts)", "example": 249.99 }, "unitTaxAmount": { "type": "number", "description": "Tax amount per unit (approximate — use the line totals for exact amounts)", "example": 0 }, "quantity": { "type": "number", "description": "Quantity of the item ordered", "example": 1 }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "addOnSubtotal": { "type": "number", "description": "Discounted subtotal of the add-ons attached to this line item, before tax" }, "addOnTotalTax": { "type": "number", "description": "Total tax of the add-ons attached to this line item (approximate)" }, "originalSubtotal": { "type": "number", "description": "Original subtotal of the base line across all quantities, before discount", "example": 249.99 }, "totalDiscount": { "type": "number", "description": "Exact total discount applied to the base line, across all quantities", "example": 0 }, "discountedSubtotal": { "type": "number", "description": "Discounted subtotal of the base line (original subtotal − total discount), before tax", "example": 249.99 }, "discountedTotal": { "type": "number", "description": "Discounted total of the base line, including tax when not already in the price", "example": 249.99 }, "totalTax": { "type": "number", "description": "Total tax of the base line across all quantities (approximate)", "example": 0 }, "refundedQuantity": { "type": "number", "description": "The quantity of the line item that has been refunded", "example": 249.99 }, "refundableQuantity": { "type": "number", "description": "The quantity of the line item that can be refunded", "example": 249.99 }, "appointment": { "description": "The appointment this line item is for", "allOf": [ { "$ref": "#/components/schemas/AppointmentDetailOrderItemAppointment" } ] }, "addOnLineItems": { "description": "Add-on line items attached to this line item", "type": "array", "items": { "$ref": "#/components/schemas/AppointmentDetailOrderItemAddOn" } } }, "required": [ "orderId", "appointmentId", "externalId", "originalUnitPrice", "discountedUnitPrice", "unitTaxAmount", "quantity", "createdAt", "updatedAt", "deletedAt", "addOnSubtotal", "addOnTotalTax", "originalSubtotal", "totalDiscount", "discountedSubtotal", "discountedTotal", "totalTax", "refundedQuantity", "refundableQuantity", "appointment", "addOnLineItems" ] }, "AppointmentDetailOrder": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the order" }, "paymentCurrencyCode": { "type": "string", "description": "The currency used by the customer when placing the order.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "taxesIncluded": { "type": "boolean", "description": "Whether the taxes are included in the order subtotal.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External order ID from user's platform (if any)", "example": "shop123_order_456", "nullable": true }, "externalName": { "type": "string", "description": "External order name/reference from user's platform", "example": "#1001", "nullable": true }, "name": { "type": "string", "description": "Generated order name for the user (starts at 1001 and increments)", "example": "1001" }, "customerId": { "type": "string", "description": "ID of the customer who placed the order", "example": "123e4567-e89b-12d3-a456-426614174000", "nullable": true }, "customerFirstName": { "type": "string", "description": "Snapshot of the customer first name captured when the order was placed", "nullable": true }, "customerLastName": { "type": "string", "description": "Snapshot of the customer last name captured when the order was placed", "nullable": true }, "customerEmail": { "type": "string", "description": "Snapshot of the customer email captured when the order was placed", "nullable": true }, "customerPhone": { "type": "string", "description": "Snapshot of the customer phone captured when the order was placed", "nullable": true }, "billingAddressId": { "type": "string", "description": "ID of the linked billing address", "nullable": true }, "deliveryAddressId": { "type": "string", "description": "ID of the linked order-level delivery address", "nullable": true }, "billingFirstName": { "type": "string", "description": "Billing bill-to first name", "nullable": true, "deprecated": true }, "billingLastName": { "type": "string", "description": "Billing bill-to last name", "nullable": true, "deprecated": true }, "billingCompanyName": { "type": "string", "description": "Billing company name", "nullable": true, "deprecated": true }, "billingTaxRegistrationId": { "type": "string", "description": "Billing tax registration id (VAT / GST / …)", "nullable": true, "deprecated": true }, "billingAddressLine1": { "type": "string", "description": "Billing address line 1", "nullable": true, "deprecated": true }, "billingAddressLine2": { "type": "string", "description": "Billing address line 2", "nullable": true, "deprecated": true }, "billingCity": { "type": "string", "description": "Billing city", "nullable": true, "deprecated": true }, "billingState": { "type": "string", "description": "Billing state/province", "nullable": true, "deprecated": true }, "billingPostalCode": { "type": "string", "description": "Billing postal/zip code", "nullable": true, "deprecated": true }, "billingCountry": { "type": "string", "description": "Billing country", "nullable": true, "deprecated": true }, "storeId": { "type": "string", "description": "ID of the store that owns the order", "example": "store-uuid", "nullable": true }, "cartId": { "type": "string", "description": "ID of the cart from which the order was created", "example": "123e4567-e89b-12d3-a456-426614174000", "nullable": true }, "gclid": { "type": "string", "description": "Google Ads click ID captured at the time of booking", "example": "EAIaIQobChMI...", "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "billingAddress": { "description": "Linked billing address", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CustomerAddress" } ] }, "deliveryAddress": { "description": "Linked order-level delivery address", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DeliveryAddress" } ] }, "subtotal": { "type": "number", "description": "Subtotal amount of the order, excluding canceled appointments", "example": 249.99 }, "total": { "type": "number", "description": "Total amount of the order, including canceled appointments and taxes", "example": 249.99 }, "totalTax": { "type": "number", "description": "Total tax amount of the order, excluding canceled appointments", "example": 249.99 }, "dueToPay": { "type": "number", "description": "Total amount still due to be paid for the order. Derived from the current total (which excludes canceled appointments and reflects current add-ons and discounts) minus the net amount already held (paid minus refunded). Never negative — when the customer has overpaid the current total, the surplus surfaces via dueToRefund instead.", "example": 249.99 }, "paidTotal": { "type": "number", "description": "Total amount paid for the order", "example": 249.99 }, "refundedTotal": { "type": "number", "description": "Total amount refunded for the order", "example": 249.99 }, "balance": { "type": "number", "description": "Balance of the order; based on paid and refunded amounts", "example": 249.99 }, "dueToRefund": { "type": "number", "description": "Total amount owed back to the customer. Derived from the net amount held (paid minus refunded) minus the current total. Any change that lowers the current total below what the customer has already paid — a canceled appointment, a removed or reduced add-on, or a discount that is restored on reevaluation — surfaces the surplus here. Never negative.", "example": 249.99 }, "isFullyPaid": { "type": "boolean", "description": "Whether the order is fully paid", "example": false }, "isFullyRefunded": { "type": "boolean", "description": "Whether everything the customer paid has been refunded (paid something, nothing held).", "example": false }, "paymentStatus": { "type": "string", "description": "Payment status of the order", "example": "paid", "enum": [ "unpaid", "paid", "partially-paid" ] }, "refundStatus": { "type": "string", "description": "Refund status of the order", "example": "partially-refunded", "enum": [ "refund-owed", "partially-refunded", "fully-refunded", "unrefunded" ] }, "fulfillmentStatus": { "type": "string", "description": "Fulfillment status of the order", "example": "partially-fulfilled", "enum": [ "partially-fulfilled", "fulfilled", "unfulfilled" ] }, "transactions": { "description": "Transactions associated with this order", "type": "array", "items": { "$ref": "#/components/schemas/AppointmentDetailOrderTransaction" } }, "lineItems": { "description": "Line items in the order", "type": "array", "items": { "$ref": "#/components/schemas/AppointmentDetailOrderItem" } } }, "required": [ "id", "paymentCurrencyCode", "taxesIncluded", "externalId", "externalName", "name", "customerId", "storeId", "cartId", "createdAt", "updatedAt", "deletedAt", "subtotal", "total", "totalTax", "dueToPay", "paidTotal", "refundedTotal", "balance", "dueToRefund", "isFullyPaid", "isFullyRefunded", "paymentStatus", "refundStatus", "fulfillmentStatus", "transactions", "lineItems" ] }, "AppointmentDetailOrderLineItem": { "type": "object", "properties": { "orderId": { "type": "string", "description": "ID of the order", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "appointmentId": { "type": "string", "description": "ID of the appointment associated with line item", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "externalId": { "type": "string", "description": "External order line item ID from user's platform (if any)", "example": "12345678", "nullable": true }, "originalUnitPrice": { "type": "number", "description": "Original price of the item", "example": 249.99 }, "discountedUnitPrice": { "type": "number", "description": "Discounted price per unit (approximate — use the line totals for exact amounts)", "example": 249.99 }, "unitTaxAmount": { "type": "number", "description": "Tax amount per unit (approximate — use the line totals for exact amounts)", "example": 0 }, "quantity": { "type": "number", "description": "Quantity of the item ordered", "example": 1 }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "addOnSubtotal": { "type": "number", "description": "Discounted subtotal of the add-ons attached to this line item, before tax" }, "addOnTotalTax": { "type": "number", "description": "Total tax of the add-ons attached to this line item (approximate)" }, "originalSubtotal": { "type": "number", "description": "Original subtotal of the base line across all quantities, before discount", "example": 249.99 }, "totalDiscount": { "type": "number", "description": "Exact total discount applied to the base line, across all quantities", "example": 0 }, "discountedSubtotal": { "type": "number", "description": "Discounted subtotal of the base line (original subtotal − total discount), before tax", "example": 249.99 }, "discountedTotal": { "type": "number", "description": "Discounted total of the base line, including tax when not already in the price", "example": 249.99 }, "totalTax": { "type": "number", "description": "Total tax of the base line across all quantities (approximate)", "example": 0 }, "refundedQuantity": { "type": "number", "description": "The quantity of the line item that has been refunded", "example": 249.99 }, "refundableQuantity": { "type": "number", "description": "The quantity of the line item that can be refunded", "example": 249.99 }, "order": { "description": "The order this line item belongs to", "allOf": [ { "$ref": "#/components/schemas/AppointmentDetailOrder" } ] } }, "required": [ "orderId", "appointmentId", "externalId", "originalUnitPrice", "discountedUnitPrice", "unitTaxAmount", "quantity", "createdAt", "updatedAt", "deletedAt", "addOnSubtotal", "addOnTotalTax", "originalSubtotal", "totalDiscount", "discountedSubtotal", "discountedTotal", "totalTax", "refundedQuantity", "refundableQuantity", "order" ] }, "AppointmentDetailResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the appointment", "example": "123e4567-e89b-12d3-a456-426614174000" }, "name": { "type": "string", "description": "Generated appointment name for the user (starts at 1001 and increments)", "example": "1001" }, "productId": { "type": "string", "description": "ID of the service/product for this appointment", "example": "123e4567-e89b-12d3-a456-426614174001" }, "staffMemberId": { "type": "string", "description": "ID of the staff member assigned to this appointment (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "locationId": { "type": "string", "description": "ID of the location where the appointment will take place (if any)", "example": "123e4567-e89b-12d3-a456-426614174003", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this appointment", "example": "123e4567-e89b-12d3-a456-426614174004" }, "customerId": { "type": "string", "description": "ID of the customer who booked the appointment", "example": "123e4567-e89b-12d3-a456-426614174005", "nullable": true }, "externalOrderId": { "type": "string", "description": "External order ID from user's platform (if any)", "example": "12345678", "nullable": true }, "externalOrderName": { "type": "string", "description": "External order name/reference from user's platform", "example": "#1001", "nullable": true }, "from": { "format": "date-time", "type": "string", "description": "Start date and time of the appointment (UTC timezone)", "example": "2023-06-15T09:00:00Z" }, "to": { "format": "date-time", "type": "string", "description": "End date and time of the appointment (UTC timezone)", "example": "2023-06-15T10:00:00Z" }, "displayAddress": { "type": "string", "description": "Merchant-defined display address from the location; overrides the concatenated address fields in notifications. Null falls back to the structured address.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressId": { "type": "string", "description": "ID of the linked service/delivery address", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of the appointment address", "nullable": true, "deprecated": true }, "addressLine2": { "type": "string", "description": "Second line of the appointment address", "nullable": true, "deprecated": true }, "city": { "type": "string", "description": "City of the appointment location", "nullable": true, "deprecated": true }, "state": { "type": "string", "description": "State/province of the appointment location", "nullable": true, "deprecated": true }, "postalCode": { "type": "string", "description": "Postal/zip code of the appointment location", "nullable": true, "deprecated": true }, "country": { "type": "string", "description": "Country of the appointment location", "nullable": true, "deprecated": true }, "status": { "example": "scheduled", "$ref": "#/components/schemas/AppointmentStatusType" }, "internalNote": { "type": "string", "description": "Internal notes about the appointment (not visible to customers)", "example": "Customer requested extra attention for specific needs", "nullable": true }, "createdBy": { "example": "customer", "$ref": "#/components/schemas/AppointmentCreatedByEnum" }, "reminderSentAt": { "format": "date-time", "type": "string", "description": "Date and time when reminder was sent to the customer", "example": "2023-06-14T09:00:00Z", "nullable": true }, "numberOfAttendees": { "type": "number", "description": "Number of people attending the appointment", "example": 1, "default": 1 }, "customAttributes": { "type": "object", "description": "Custom key-value attributes (strings) attached to the appointment. Max 250 entries.", "additionalProperties": { "type": "string" }, "nullable": true, "example": { "source": "widget", "party_size": "4" } }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "deliveryAddress": { "description": "Linked service/delivery address (DELIVERY locations)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DeliveryAddress" } ] }, "product": { "description": "Service/product details for this appointment", "allOf": [ { "$ref": "#/components/schemas/AppointmentDetailProduct" } ] }, "staffMember": { "description": "Staff member assigned to this appointment", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/AppointmentDetailStaffMember" } ] }, "location": { "description": "Location where the appointment will take place", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/AppointmentDetailLocation" } ] }, "customer": { "description": "Customer who booked the appointment", "allOf": [ { "$ref": "#/components/schemas/AppointmentDetailCustomer" } ] }, "addOns": { "description": "Add-ons attached to this appointment", "type": "array", "items": { "$ref": "#/components/schemas/AppointmentDetailAddOn" } }, "guests": { "description": "Guests invited to this appointment (copied on notifications)", "type": "array", "items": { "$ref": "#/components/schemas/AppointmentDetailGuest" } }, "feedbackQuestionAnswers": { "description": "Answers to feedback questions provided after the appointment", "type": "array", "items": { "$ref": "#/components/schemas/AppointmentDetailFeedbackAnswer" } }, "checkoutQuestionAnswers": { "description": "Answers to checkout questions provided when booking", "type": "array", "items": { "$ref": "#/components/schemas/AppointmentDetailCheckoutAnswer" } }, "orderLineItem": { "description": "The order line item linking this appointment to its order", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/AppointmentDetailOrderLineItem" } ] }, "order": { "description": "The order associated with this appointment (via the order line item)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/AppointmentDetailOrder" } ] } }, "required": [ "id", "name", "productId", "staffMemberId", "locationId", "storeId", "customerId", "externalOrderId", "externalOrderName", "from", "to", "displayAddress", "status", "internalNote", "createdBy", "reminderSentAt", "numberOfAttendees", "createdAt", "updatedAt", "deletedAt", "product", "staffMember", "location", "customer", "addOns", "guests", "feedbackQuestionAnswers", "checkoutQuestionAnswers", "orderLineItem", "order" ] }, "AppointmentProduct": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "productId": { "type": "string", "description": "ID of the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID)", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID)", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this product", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the product (unique per store)", "example": "haircut-basic" }, "scheduleId": { "type": "string", "description": "ID of the schedule associated with this product" }, "productPoolId": { "type": "string", "description": "ID of the product pool this product belongs to (controls overlap prevention)", "nullable": true }, "title": { "type": "string", "description": "Title of the product", "example": "Haircut Service" }, "variantTitle": { "type": "string", "description": "Title of the specific product variant", "example": "Short Hair" }, "description": { "type": "string", "description": "Detailed description of the product" }, "imageId": { "type": "string", "description": "ID of the product image" }, "color": { "type": "string", "description": "Color code for displaying the product", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "BLUE", "default": "slate" }, "price": { "type": "number", "description": "Price of the product", "example": 250 }, "taxable": { "type": "boolean", "description": "Whether the product is taxable", "default": false }, "duration": { "type": "number", "description": "Duration of the service in seconds", "example": 3600 }, "allowCustomDuration": { "type": "boolean", "description": "Whether customers can customize the duration by selecting multiples of the base service duration (e.g., if base duration is 1 day, customers can book 1, 2, 3+ days)", "default": false }, "maxDuration": { "type": "number", "description": "When allow_custom_duration=true, maximum duration allowed for multi-duration bookings in seconds (-1 for unlimited)", "default": -1 }, "maxAttendees": { "type": "number", "description": "Maximum number of attendees allowed", "default": 1 }, "maxGuests": { "type": "number", "description": "Maximum number of guests allowed per appointment. Null means unlimited.", "nullable": true }, "allowGuests": { "type": "boolean", "description": "Whether customers can invite guests to the appointment", "default": false }, "allowCustomerReschedule": { "type": "boolean", "description": "Whether customers can reschedule their bookings", "default": false }, "allowCustomerCancel": { "type": "boolean", "description": "Whether customers can cancel their bookings", "default": false }, "rescheduleGap": { "type": "number", "description": "Time in seconds before appointment when rescheduling is no longer allowed" }, "cancelGap": { "type": "number", "description": "Time in seconds before appointment when cancellation is no longer allowed" }, "beforeGap": { "type": "number", "description": "Buffer time in seconds required before this service" }, "afterGap": { "type": "number", "description": "Buffer time in seconds required after this service" }, "fixedTimes": { "type": "boolean", "description": "When allow_custom_duration=true, whether appointments must start and end at fixed times (like fixed check-in/check-out times for multi-duration bookings)", "default": false }, "fixedStartTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must start (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "09:00:00" }, "fixedEndTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must end (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "17:00:00" }, "advanceScheduleThreshold": { "type": "number", "description": "How many days in advance bookings can be made", "default": 0 }, "sendConfirmationEmail": { "type": "boolean", "description": "Whether to send confirmation emails for bookings", "default": true }, "sendReminderEmail": { "type": "boolean", "description": "Whether to send reminder emails before appointments", "default": false }, "sendFeedbackEmail": { "type": "boolean", "description": "Whether to send feedback request emails after appointments", "default": false }, "skipCheckout": { "type": "boolean", "description": "Whether to skip the checkout process for this product (Shopify merchants only)", "default": false }, "status": { "type": "string", "description": "Current status of the product", "enum": [ "active", "inactive" ], "example": "ACTIVE", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the product was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the product was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the product was deleted (for soft deletes)" }, "image": { "description": "Primary image of the product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "productId", "externalId", "externalVariantId", "storeId", "slug", "scheduleId", "productPoolId", "title", "variantTitle", "description", "imageId", "color", "price", "taxable", "duration", "allowCustomDuration", "maxDuration", "maxAttendees", "maxGuests", "allowGuests", "allowCustomerReschedule", "allowCustomerCancel", "rescheduleGap", "cancelGap", "beforeGap", "afterGap", "fixedTimes", "fixedStartTime", "fixedEndTime", "advanceScheduleThreshold", "sendConfirmationEmail", "sendReminderEmail", "sendFeedbackEmail", "skipCheckout", "status", "createdAt", "updatedAt", "deletedAt" ] }, "AppointmentStaffMember": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this staff member record", "example": "123e4567-e89b-12d3-a456-426614174111" }, "userId": { "type": "string", "description": "User ID of the staff member login identity (nullable until linked)", "example": "user-uuid" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this staff member, defines their availability", "example": "123e4567-e89b-12d3-a456-426614174000" }, "imageId": { "type": "string", "description": "ID of the image associated with this staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "firstName": { "type": "string", "description": "First name of the staff member", "example": "John" }, "lastName": { "type": "string", "description": "Last name of the staff member", "example": "Doe" }, "email": { "type": "string", "description": "Email address of the staff member, used for notifications and calendar integration", "example": "john.doe@example.com" }, "slug": { "type": "string", "description": "URL-friendly slug for the staff member (unique per store)", "example": "mike" }, "refreshToken": { "type": "string", "description": "Refresh token for integrations like Google Calendar", "example": "abc123xyz456" }, "createdAt": { "type": "string", "description": "Date and time when the staff member was created", "example": "2025-05-01T12:00:00Z" }, "updatedAt": { "type": "string", "description": "Date and time when the staff member was last updated", "example": "2025-05-15T14:30:00Z" }, "deletedAt": { "type": "string", "description": "Date and time when the staff member was soft deleted", "example": "2025-06-01T09:15:00Z" }, "image": { "description": "Profile image of the staff member", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "storeId", "userId", "scheduleId", "imageId", "firstName", "lastName", "email", "slug", "refreshToken", "createdAt", "updatedAt", "deletedAt" ] }, "AppointmentLocation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the location", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this location", "example": "123e4567-e89b-12d3-a456-426614174001" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this location (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "title": { "type": "string", "description": "Name of the location", "example": "Main Office", "nullable": true }, "description": { "type": "string", "description": "Description of the location", "example": "Our main downtown office location with 3 treatment rooms", "nullable": true }, "slug": { "type": "string", "description": "URL-friendly slug for the location (unique per store)", "example": "new-york" }, "type": { "type": "string", "description": "Type of location", "enum": [ "physical", "online", "delivery" ], "example": "physical" }, "link": { "type": "string", "description": "URL link for online locations", "example": "https://zoom.us/j/123456789", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of address for physical locations", "example": "123 Main Street", "nullable": true }, "addressLine2": { "type": "string", "description": "Second line of address for physical locations", "example": "Suite 200", "nullable": true }, "city": { "type": "string", "description": "City for physical locations", "example": "San Francisco", "nullable": true }, "state": { "type": "string", "description": "State/province for physical locations", "example": "CA", "nullable": true }, "postalCode": { "type": "string", "description": "Postal code for physical locations", "example": "94105", "nullable": true }, "country": { "type": "string", "description": "Country for physical locations", "example": "United States", "nullable": true }, "displayAddress": { "type": "string", "description": "Merchant-defined display address that overrides the auto-formatted address (emails, booking page). Null falls back to the concatenated address fields.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressPlaceId": { "type": "string", "description": "Google Place ID for the physical address", "example": "ChIJIQBpAG2ahYAR_6128GcTUEo", "nullable": true }, "latitude": { "type": "number", "description": "Latitude in WGS84", "example": 37.4224764, "nullable": true }, "longitude": { "type": "number", "description": "Longitude in WGS84", "example": -122.0842499, "nullable": true }, "createdAt": { "type": "string", "description": "Date when the location was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the location was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "type": "string", "description": "Date when the location was deleted (for soft deletes)", "example": "2023-03-10T11:45:00Z", "nullable": true }, "address": { "type": "string", "description": "The formatted address string", "nullable": true } }, "required": [ "id", "storeId", "scheduleId", "title", "description", "slug", "type", "link", "addressLine1", "addressLine2", "city", "state", "postalCode", "country", "addressPlaceId", "latitude", "longitude", "createdAt", "updatedAt", "deletedAt", "address" ] }, "AppointmentAddOnItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the add-on", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID) for synced add-ons", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID) for synced add-ons", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this add-on", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the add-on (unique per store)", "example": "child-seat" }, "title": { "type": "string", "description": "Title of the add-on", "example": "Child Seat" }, "description": { "type": "string", "description": "Detailed description of the add-on" }, "imageId": { "type": "string", "description": "ID of the primary image for the add-on" }, "color": { "type": "string", "description": "Color code used when displaying the add-on", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "slate", "default": "slate" }, "price": { "type": "number", "description": "Unit price of the add-on", "example": 15 }, "taxable": { "type": "boolean", "description": "Whether the add-on is taxable", "default": true }, "durationMultiplied": { "type": "boolean", "description": "When true, the add-on is charged per base-duration unit of the parent appointment. Quantity on the cart/order line item mirrors the parent CartItem.quantity (i.e., the booked duration units). Only meaningful for attached products with allowCustomDuration=true.", "default": false }, "maxQuantity": { "type": "number", "description": "Maximum quantity a customer can pick for this add-on. Only applies to fixed add-ons (durationMultiplied=false). Null means unlimited.", "example": 4, "minimum": 1, "nullable": true }, "status": { "type": "string", "description": "Current status of the add-on", "enum": [ "active", "inactive" ], "example": "active", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the add-on was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the add-on was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the add-on was soft-deleted" }, "image": { "description": "Primary image of the add-on", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "externalId", "externalVariantId", "storeId", "slug", "title", "description", "imageId", "color", "price", "taxable", "durationMultiplied", "maxQuantity", "status", "createdAt", "updatedAt", "deletedAt" ] }, "AppointmentAddOn": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier" }, "appointmentId": { "type": "string", "description": "Appointment ID" }, "addOnId": { "type": "string", "description": "Add-on ID" }, "quantity": { "type": "number", "description": "Quantity of this add-on for the appointment", "default": 1 }, "createdAt": { "format": "date-time", "type": "string", "description": "Created at timestamp" }, "addOn": { "description": "The add-on details", "allOf": [ { "$ref": "#/components/schemas/AppointmentAddOnItem" } ] } }, "required": [ "id", "appointmentId", "addOnId", "quantity", "createdAt", "addOn" ] }, "AppointmentResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the appointment", "example": "123e4567-e89b-12d3-a456-426614174000" }, "name": { "type": "string", "description": "Generated appointment name for the user (starts at 1001 and increments)", "example": "1001" }, "productId": { "type": "string", "description": "ID of the service/product for this appointment", "example": "123e4567-e89b-12d3-a456-426614174001" }, "staffMemberId": { "type": "string", "description": "ID of the staff member assigned to this appointment (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "locationId": { "type": "string", "description": "ID of the location where the appointment will take place (if any)", "example": "123e4567-e89b-12d3-a456-426614174003", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this appointment", "example": "123e4567-e89b-12d3-a456-426614174004" }, "customerId": { "type": "string", "description": "ID of the customer who booked the appointment", "example": "123e4567-e89b-12d3-a456-426614174005", "nullable": true }, "externalOrderId": { "type": "string", "description": "External order ID from user's platform (if any)", "example": "12345678", "nullable": true }, "externalOrderName": { "type": "string", "description": "External order name/reference from user's platform", "example": "#1001", "nullable": true }, "from": { "format": "date-time", "type": "string", "description": "Start date and time of the appointment (UTC timezone)", "example": "2023-06-15T09:00:00Z" }, "to": { "format": "date-time", "type": "string", "description": "End date and time of the appointment (UTC timezone)", "example": "2023-06-15T10:00:00Z" }, "displayAddress": { "type": "string", "description": "Merchant-defined display address from the location; overrides the concatenated address fields in notifications. Null falls back to the structured address.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressId": { "type": "string", "description": "ID of the linked service/delivery address", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of the appointment address", "nullable": true, "deprecated": true }, "addressLine2": { "type": "string", "description": "Second line of the appointment address", "nullable": true, "deprecated": true }, "city": { "type": "string", "description": "City of the appointment location", "nullable": true, "deprecated": true }, "state": { "type": "string", "description": "State/province of the appointment location", "nullable": true, "deprecated": true }, "postalCode": { "type": "string", "description": "Postal/zip code of the appointment location", "nullable": true, "deprecated": true }, "country": { "type": "string", "description": "Country of the appointment location", "nullable": true, "deprecated": true }, "status": { "example": "scheduled", "$ref": "#/components/schemas/AppointmentStatusType" }, "internalNote": { "type": "string", "description": "Internal notes about the appointment (not visible to customers)", "example": "Customer requested extra attention for specific needs", "nullable": true }, "createdBy": { "example": "customer", "$ref": "#/components/schemas/AppointmentCreatedByEnum" }, "reminderSentAt": { "format": "date-time", "type": "string", "description": "Date and time when reminder was sent to the customer", "example": "2023-06-14T09:00:00Z", "nullable": true }, "numberOfAttendees": { "type": "number", "description": "Number of people attending the appointment", "example": 1, "default": 1 }, "customAttributes": { "type": "object", "description": "Custom key-value attributes (strings) attached to the appointment. Max 250 entries.", "additionalProperties": { "type": "string" }, "nullable": true, "example": { "source": "widget", "party_size": "4" } }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "deliveryAddress": { "description": "Linked service/delivery address (DELIVERY locations)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DeliveryAddress" } ] }, "product": { "description": "Service/product details for this appointment", "allOf": [ { "$ref": "#/components/schemas/AppointmentProduct" } ] }, "staffMember": { "description": "Staff member assigned to this appointment", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/AppointmentStaffMember" } ] }, "location": { "description": "Location where the appointment will take place", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/AppointmentLocation" } ] }, "addOns": { "description": "Add-ons attached to this appointment", "type": "array", "items": { "$ref": "#/components/schemas/AppointmentAddOn" } }, "guests": { "description": "Guests invited to this appointment (copied on notifications)", "type": "array", "items": { "$ref": "#/components/schemas/AppointmentGuest" } } }, "required": [ "id", "name", "productId", "staffMemberId", "locationId", "storeId", "customerId", "externalOrderId", "externalOrderName", "from", "to", "displayAddress", "status", "internalNote", "createdBy", "reminderSentAt", "numberOfAttendees", "createdAt", "updatedAt", "deletedAt", "product", "staffMember", "location", "addOns", "guests" ] }, "FeedbackQuestionAnswers": { "type": "object", "properties": { "answers": { "description": "Array of feedback questions and answers for the appointment", "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/QuestionAnswer" } } }, "required": [ "answers" ] }, "FeedbackQuestionAnswerResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the feedback question answer", "example": "123e4567-e89b-12d3-a456-426614174000" }, "appointmentId": { "type": "string", "description": "ID of the appointment this feedback relates to", "example": "123e4567-e89b-12d3-a456-426614174001" }, "questionId": { "type": "string", "description": "ID of the feedback question (set to null if question is deleted)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "question": { "type": "string", "description": "The feedback question text presented to the customer", "example": "How would you rate the quality of service provided?" }, "answer": { "type": "string", "description": "Customer's answer to the feedback question", "example": "The service was excellent, very professional and timely.", "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when this feedback was recorded", "example": "2023-06-15T14:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when this feedback was last updated", "example": "2023-06-15T15:45:00Z", "nullable": true } }, "required": [ "id", "appointmentId", "questionId", "question", "answer", "createdAt", "updatedAt" ] }, "AppointmentGuestResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier" }, "appointmentId": { "type": "string", "description": "Appointment ID" }, "email": { "type": "string", "description": "Guest email address" }, "createdAt": { "format": "date-time", "type": "string", "description": "Created at timestamp" } }, "required": [ "id", "appointmentId", "email", "createdAt" ] }, "Product": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "productId": { "type": "string", "description": "ID of the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID)", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID)", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this product", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the product (unique per store)", "example": "haircut-basic" }, "scheduleId": { "type": "string", "description": "ID of the schedule associated with this product" }, "productPoolId": { "type": "string", "description": "ID of the product pool this product belongs to (controls overlap prevention)", "nullable": true }, "title": { "type": "string", "description": "Title of the product", "example": "Haircut Service" }, "variantTitle": { "type": "string", "description": "Title of the specific product variant", "example": "Short Hair" }, "description": { "type": "string", "description": "Detailed description of the product" }, "imageId": { "type": "string", "description": "ID of the product image" }, "color": { "type": "string", "description": "Color code for displaying the product", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "BLUE", "default": "slate" }, "price": { "type": "number", "description": "Price of the product", "example": 250 }, "taxable": { "type": "boolean", "description": "Whether the product is taxable", "default": false }, "duration": { "type": "number", "description": "Duration of the service in seconds", "example": 3600 }, "allowCustomDuration": { "type": "boolean", "description": "Whether customers can customize the duration by selecting multiples of the base service duration (e.g., if base duration is 1 day, customers can book 1, 2, 3+ days)", "default": false }, "maxDuration": { "type": "number", "description": "When allow_custom_duration=true, maximum duration allowed for multi-duration bookings in seconds (-1 for unlimited)", "default": -1 }, "maxAttendees": { "type": "number", "description": "Maximum number of attendees allowed", "default": 1 }, "maxGuests": { "type": "number", "description": "Maximum number of guests allowed per appointment. Null means unlimited.", "nullable": true }, "allowGuests": { "type": "boolean", "description": "Whether customers can invite guests to the appointment", "default": false }, "allowCustomerReschedule": { "type": "boolean", "description": "Whether customers can reschedule their bookings", "default": false }, "allowCustomerCancel": { "type": "boolean", "description": "Whether customers can cancel their bookings", "default": false }, "rescheduleGap": { "type": "number", "description": "Time in seconds before appointment when rescheduling is no longer allowed" }, "cancelGap": { "type": "number", "description": "Time in seconds before appointment when cancellation is no longer allowed" }, "beforeGap": { "type": "number", "description": "Buffer time in seconds required before this service" }, "afterGap": { "type": "number", "description": "Buffer time in seconds required after this service" }, "fixedTimes": { "type": "boolean", "description": "When allow_custom_duration=true, whether appointments must start and end at fixed times (like fixed check-in/check-out times for multi-duration bookings)", "default": false }, "fixedStartTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must start (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "09:00:00" }, "fixedEndTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must end (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "17:00:00" }, "advanceScheduleThreshold": { "type": "number", "description": "How many days in advance bookings can be made", "default": 0 }, "sendConfirmationEmail": { "type": "boolean", "description": "Whether to send confirmation emails for bookings", "default": true }, "sendReminderEmail": { "type": "boolean", "description": "Whether to send reminder emails before appointments", "default": false }, "sendFeedbackEmail": { "type": "boolean", "description": "Whether to send feedback request emails after appointments", "default": false }, "skipCheckout": { "type": "boolean", "description": "Whether to skip the checkout process for this product (Shopify merchants only)", "default": false }, "status": { "type": "string", "description": "Current status of the product", "enum": [ "active", "inactive" ], "example": "ACTIVE", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the product was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the product was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the product was deleted (for soft deletes)" }, "image": { "description": "Primary image of the product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "productId", "externalId", "externalVariantId", "storeId", "slug", "scheduleId", "productPoolId", "title", "variantTitle", "description", "imageId", "color", "price", "taxable", "duration", "allowCustomDuration", "maxDuration", "maxAttendees", "maxGuests", "allowGuests", "allowCustomerReschedule", "allowCustomerCancel", "rescheduleGap", "cancelGap", "beforeGap", "afterGap", "fixedTimes", "fixedStartTime", "fixedEndTime", "advanceScheduleThreshold", "sendConfirmationEmail", "sendReminderEmail", "sendFeedbackEmail", "skipCheckout", "status", "createdAt", "updatedAt", "deletedAt" ] }, "StaffMember": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this staff member record", "example": "123e4567-e89b-12d3-a456-426614174111" }, "userId": { "type": "string", "description": "User ID of the staff member login identity (nullable until linked)", "example": "user-uuid" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this staff member, defines their availability", "example": "123e4567-e89b-12d3-a456-426614174000" }, "imageId": { "type": "string", "description": "ID of the image associated with this staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "firstName": { "type": "string", "description": "First name of the staff member", "example": "John" }, "lastName": { "type": "string", "description": "Last name of the staff member", "example": "Doe" }, "email": { "type": "string", "description": "Email address of the staff member, used for notifications and calendar integration", "example": "john.doe@example.com" }, "slug": { "type": "string", "description": "URL-friendly slug for the staff member (unique per store)", "example": "mike" }, "refreshToken": { "type": "string", "description": "Refresh token for integrations like Google Calendar", "example": "abc123xyz456" }, "createdAt": { "type": "string", "description": "Date and time when the staff member was created", "example": "2025-05-01T12:00:00Z" }, "updatedAt": { "type": "string", "description": "Date and time when the staff member was last updated", "example": "2025-05-15T14:30:00Z" }, "deletedAt": { "type": "string", "description": "Date and time when the staff member was soft deleted", "example": "2025-06-01T09:15:00Z" }, "image": { "description": "Profile image of the staff member", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "storeId", "userId", "scheduleId", "imageId", "firstName", "lastName", "email", "slug", "refreshToken", "createdAt", "updatedAt", "deletedAt" ] }, "Location": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the location", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this location", "example": "123e4567-e89b-12d3-a456-426614174001" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this location (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "title": { "type": "string", "description": "Name of the location", "example": "Main Office", "nullable": true }, "description": { "type": "string", "description": "Description of the location", "example": "Our main downtown office location with 3 treatment rooms", "nullable": true }, "slug": { "type": "string", "description": "URL-friendly slug for the location (unique per store)", "example": "new-york" }, "type": { "type": "string", "description": "Type of location", "enum": [ "physical", "online", "delivery" ], "example": "physical" }, "link": { "type": "string", "description": "URL link for online locations", "example": "https://zoom.us/j/123456789", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of address for physical locations", "example": "123 Main Street", "nullable": true }, "addressLine2": { "type": "string", "description": "Second line of address for physical locations", "example": "Suite 200", "nullable": true }, "city": { "type": "string", "description": "City for physical locations", "example": "San Francisco", "nullable": true }, "state": { "type": "string", "description": "State/province for physical locations", "example": "CA", "nullable": true }, "postalCode": { "type": "string", "description": "Postal code for physical locations", "example": "94105", "nullable": true }, "country": { "type": "string", "description": "Country for physical locations", "example": "United States", "nullable": true }, "displayAddress": { "type": "string", "description": "Merchant-defined display address that overrides the auto-formatted address (emails, booking page). Null falls back to the concatenated address fields.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressPlaceId": { "type": "string", "description": "Google Place ID for the physical address", "example": "ChIJIQBpAG2ahYAR_6128GcTUEo", "nullable": true }, "latitude": { "type": "number", "description": "Latitude in WGS84", "example": 37.4224764, "nullable": true }, "longitude": { "type": "number", "description": "Longitude in WGS84", "example": -122.0842499, "nullable": true }, "createdAt": { "type": "string", "description": "Date when the location was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the location was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "type": "string", "description": "Date when the location was deleted (for soft deletes)", "example": "2023-03-10T11:45:00Z", "nullable": true }, "address": { "type": "string", "description": "The formatted address string", "nullable": true } }, "required": [ "id", "storeId", "scheduleId", "title", "description", "slug", "type", "link", "addressLine1", "addressLine2", "city", "state", "postalCode", "country", "addressPlaceId", "latitude", "longitude", "createdAt", "updatedAt", "deletedAt", "address" ] }, "ServicePreference": { "type": "object", "properties": { "product": { "description": "The product/service", "allOf": [ { "$ref": "#/components/schemas/Product" } ] }, "staffMember": { "description": "Preferred staff member for this service", "allOf": [ { "$ref": "#/components/schemas/StaffMember" } ] }, "location": { "description": "Preferred location for this service", "allOf": [ { "$ref": "#/components/schemas/Location" } ] }, "bookingCount": { "type": "number", "description": "Number of times booked", "example": 5 }, "lastBookedAt": { "format": "date-time", "type": "string", "description": "Last time this service was booked", "example": "2024-10-15T14:30:00Z" } }, "required": [ "product", "bookingCount", "lastBookedAt" ] }, "LocationPreference": { "type": "object", "properties": { "location": { "description": "The location", "allOf": [ { "$ref": "#/components/schemas/Location" } ] }, "bookingCount": { "type": "number", "description": "Number of bookings at this location", "example": 10 }, "lastBookedAt": { "format": "date-time", "type": "string", "description": "Last time this location was used", "example": "2024-10-15T14:30:00Z" } }, "required": [ "location", "bookingCount", "lastBookedAt" ] }, "StaffMemberPreference": { "type": "object", "properties": { "staffMember": { "description": "The staff member", "allOf": [ { "$ref": "#/components/schemas/StaffMember" } ] }, "bookingCount": { "type": "number", "description": "Number of bookings with this staff member", "example": 7 }, "lastBookedAt": { "format": "date-time", "type": "string", "description": "Last time this staff member was booked", "example": "2024-10-15T14:30:00Z" } }, "required": [ "staffMember", "bookingCount", "lastBookedAt" ] }, "CustomerBookingPreferencesResponse": { "type": "object", "properties": { "services": { "description": "Most frequently booked services", "type": "array", "items": { "$ref": "#/components/schemas/ServicePreference" } }, "locations": { "description": "Most frequently used locations", "type": "array", "items": { "$ref": "#/components/schemas/LocationPreference" } }, "staffMembers": { "description": "Most frequently booked staff members", "type": "array", "items": { "$ref": "#/components/schemas/StaffMemberPreference" } } }, "required": [ "services", "locations", "staffMembers" ] }, "CreateOrderAppointmentsSettings": { "type": "object", "properties": { "markAsScheduled": { "type": "boolean", "description": "Whether the order should be marked as scheduled", "example": true, "nullable": true }, "notifyCustomer": { "type": "boolean", "description": "Whether to send an appointment confirmation email to the customer. This is only applicable when mark_as_scheduled is set to true.", "example": true, "nullable": true } } }, "OrderListCustomer": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the customer", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External customer identifier from integrated system", "example": "1234567890" }, "firstName": { "type": "string", "description": "Customer first name", "example": "John", "nullable": true }, "lastName": { "type": "string", "description": "Customer last name", "example": "Smith", "nullable": true }, "email": { "type": "string", "description": "Customer email address", "example": "john.smith@example.com", "nullable": true }, "phone": { "type": "string", "description": "Customer phone number", "example": "+12135550123", "nullable": true }, "password": { "type": "string", "description": "Hashed password of the customer", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this customer record", "example": "store-uuid" }, "language": { "example": "en", "$ref": "#/components/schemas/LanguageCode" }, "refreshToken": { "type": "string", "description": "Customer refresh token for authentication", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "nullable": true, "writeOnly": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Date when the customer record was created", "example": "2023-01-15T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date when the customer record was last updated", "example": "2023-02-20T14:15:00Z", "nullable": true }, "emailVerifiedAt": { "format": "date-time", "type": "string", "description": "Date and time when the customer verified email", "example": "2023-01-02T00:00:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "isEmailVerified": { "type": "boolean", "description": "Indicates whether customer email is verified" }, "isPasswordSet": { "type": "boolean", "description": "Indicates whether customer password is set" } }, "required": [ "id", "externalId", "firstName", "lastName", "email", "phone", "password", "storeId", "language", "refreshToken", "createdAt", "updatedAt", "emailVerifiedAt", "deletedAt", "isEmailVerified", "isPasswordSet" ] }, "OrderListAppointmentProduct": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "productId": { "type": "string", "description": "ID of the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID)", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID)", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this product", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the product (unique per store)", "example": "haircut-basic" }, "scheduleId": { "type": "string", "description": "ID of the schedule associated with this product" }, "productPoolId": { "type": "string", "description": "ID of the product pool this product belongs to (controls overlap prevention)", "nullable": true }, "title": { "type": "string", "description": "Title of the product", "example": "Haircut Service" }, "variantTitle": { "type": "string", "description": "Title of the specific product variant", "example": "Short Hair" }, "description": { "type": "string", "description": "Detailed description of the product" }, "imageId": { "type": "string", "description": "ID of the product image" }, "color": { "type": "string", "description": "Color code for displaying the product", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "BLUE", "default": "slate" }, "price": { "type": "number", "description": "Price of the product", "example": 250 }, "taxable": { "type": "boolean", "description": "Whether the product is taxable", "default": false }, "duration": { "type": "number", "description": "Duration of the service in seconds", "example": 3600 }, "allowCustomDuration": { "type": "boolean", "description": "Whether customers can customize the duration by selecting multiples of the base service duration (e.g., if base duration is 1 day, customers can book 1, 2, 3+ days)", "default": false }, "maxDuration": { "type": "number", "description": "When allow_custom_duration=true, maximum duration allowed for multi-duration bookings in seconds (-1 for unlimited)", "default": -1 }, "maxAttendees": { "type": "number", "description": "Maximum number of attendees allowed", "default": 1 }, "maxGuests": { "type": "number", "description": "Maximum number of guests allowed per appointment. Null means unlimited.", "nullable": true }, "allowGuests": { "type": "boolean", "description": "Whether customers can invite guests to the appointment", "default": false }, "allowCustomerReschedule": { "type": "boolean", "description": "Whether customers can reschedule their bookings", "default": false }, "allowCustomerCancel": { "type": "boolean", "description": "Whether customers can cancel their bookings", "default": false }, "rescheduleGap": { "type": "number", "description": "Time in seconds before appointment when rescheduling is no longer allowed" }, "cancelGap": { "type": "number", "description": "Time in seconds before appointment when cancellation is no longer allowed" }, "beforeGap": { "type": "number", "description": "Buffer time in seconds required before this service" }, "afterGap": { "type": "number", "description": "Buffer time in seconds required after this service" }, "fixedTimes": { "type": "boolean", "description": "When allow_custom_duration=true, whether appointments must start and end at fixed times (like fixed check-in/check-out times for multi-duration bookings)", "default": false }, "fixedStartTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must start (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "09:00:00" }, "fixedEndTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must end (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "17:00:00" }, "advanceScheduleThreshold": { "type": "number", "description": "How many days in advance bookings can be made", "default": 0 }, "sendConfirmationEmail": { "type": "boolean", "description": "Whether to send confirmation emails for bookings", "default": true }, "sendReminderEmail": { "type": "boolean", "description": "Whether to send reminder emails before appointments", "default": false }, "sendFeedbackEmail": { "type": "boolean", "description": "Whether to send feedback request emails after appointments", "default": false }, "skipCheckout": { "type": "boolean", "description": "Whether to skip the checkout process for this product (Shopify merchants only)", "default": false }, "status": { "type": "string", "description": "Current status of the product", "enum": [ "active", "inactive" ], "example": "ACTIVE", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the product was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the product was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the product was deleted (for soft deletes)" }, "image": { "description": "Primary image of the product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "productId", "externalId", "externalVariantId", "storeId", "slug", "scheduleId", "productPoolId", "title", "variantTitle", "description", "imageId", "color", "price", "taxable", "duration", "allowCustomDuration", "maxDuration", "maxAttendees", "maxGuests", "allowGuests", "allowCustomerReschedule", "allowCustomerCancel", "rescheduleGap", "cancelGap", "beforeGap", "afterGap", "fixedTimes", "fixedStartTime", "fixedEndTime", "advanceScheduleThreshold", "sendConfirmationEmail", "sendReminderEmail", "sendFeedbackEmail", "skipCheckout", "status", "createdAt", "updatedAt", "deletedAt" ] }, "OrderListAppointmentStaffMember": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this staff member record", "example": "123e4567-e89b-12d3-a456-426614174111" }, "userId": { "type": "string", "description": "User ID of the staff member login identity (nullable until linked)", "example": "user-uuid" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this staff member, defines their availability", "example": "123e4567-e89b-12d3-a456-426614174000" }, "imageId": { "type": "string", "description": "ID of the image associated with this staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "firstName": { "type": "string", "description": "First name of the staff member", "example": "John" }, "lastName": { "type": "string", "description": "Last name of the staff member", "example": "Doe" }, "email": { "type": "string", "description": "Email address of the staff member, used for notifications and calendar integration", "example": "john.doe@example.com" }, "slug": { "type": "string", "description": "URL-friendly slug for the staff member (unique per store)", "example": "mike" }, "refreshToken": { "type": "string", "description": "Refresh token for integrations like Google Calendar", "example": "abc123xyz456" }, "createdAt": { "type": "string", "description": "Date and time when the staff member was created", "example": "2025-05-01T12:00:00Z" }, "updatedAt": { "type": "string", "description": "Date and time when the staff member was last updated", "example": "2025-05-15T14:30:00Z" }, "deletedAt": { "type": "string", "description": "Date and time when the staff member was soft deleted", "example": "2025-06-01T09:15:00Z" }, "image": { "description": "Profile image of the staff member", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "storeId", "userId", "scheduleId", "imageId", "firstName", "lastName", "email", "slug", "refreshToken", "createdAt", "updatedAt", "deletedAt" ] }, "OrderListAppointmentLocation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the location", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this location", "example": "123e4567-e89b-12d3-a456-426614174001" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this location (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "title": { "type": "string", "description": "Name of the location", "example": "Main Office", "nullable": true }, "description": { "type": "string", "description": "Description of the location", "example": "Our main downtown office location with 3 treatment rooms", "nullable": true }, "slug": { "type": "string", "description": "URL-friendly slug for the location (unique per store)", "example": "new-york" }, "type": { "type": "string", "description": "Type of location", "enum": [ "physical", "online", "delivery" ], "example": "physical" }, "link": { "type": "string", "description": "URL link for online locations", "example": "https://zoom.us/j/123456789", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of address for physical locations", "example": "123 Main Street", "nullable": true }, "addressLine2": { "type": "string", "description": "Second line of address for physical locations", "example": "Suite 200", "nullable": true }, "city": { "type": "string", "description": "City for physical locations", "example": "San Francisco", "nullable": true }, "state": { "type": "string", "description": "State/province for physical locations", "example": "CA", "nullable": true }, "postalCode": { "type": "string", "description": "Postal code for physical locations", "example": "94105", "nullable": true }, "country": { "type": "string", "description": "Country for physical locations", "example": "United States", "nullable": true }, "displayAddress": { "type": "string", "description": "Merchant-defined display address that overrides the auto-formatted address (emails, booking page). Null falls back to the concatenated address fields.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressPlaceId": { "type": "string", "description": "Google Place ID for the physical address", "example": "ChIJIQBpAG2ahYAR_6128GcTUEo", "nullable": true }, "latitude": { "type": "number", "description": "Latitude in WGS84", "example": 37.4224764, "nullable": true }, "longitude": { "type": "number", "description": "Longitude in WGS84", "example": -122.0842499, "nullable": true }, "createdAt": { "type": "string", "description": "Date when the location was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the location was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "type": "string", "description": "Date when the location was deleted (for soft deletes)", "example": "2023-03-10T11:45:00Z", "nullable": true }, "address": { "type": "string", "description": "The formatted address string", "nullable": true } }, "required": [ "id", "storeId", "scheduleId", "title", "description", "slug", "type", "link", "addressLine1", "addressLine2", "city", "state", "postalCode", "country", "addressPlaceId", "latitude", "longitude", "createdAt", "updatedAt", "deletedAt", "address" ] }, "OrderListAppointment": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the appointment", "example": "123e4567-e89b-12d3-a456-426614174000" }, "name": { "type": "string", "description": "Generated appointment name for the user (starts at 1001 and increments)", "example": "1001" }, "productId": { "type": "string", "description": "ID of the service/product for this appointment", "example": "123e4567-e89b-12d3-a456-426614174001" }, "staffMemberId": { "type": "string", "description": "ID of the staff member assigned to this appointment (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "locationId": { "type": "string", "description": "ID of the location where the appointment will take place (if any)", "example": "123e4567-e89b-12d3-a456-426614174003", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this appointment", "example": "123e4567-e89b-12d3-a456-426614174004" }, "customerId": { "type": "string", "description": "ID of the customer who booked the appointment", "example": "123e4567-e89b-12d3-a456-426614174005", "nullable": true }, "externalOrderId": { "type": "string", "description": "External order ID from user's platform (if any)", "example": "12345678", "nullable": true }, "externalOrderName": { "type": "string", "description": "External order name/reference from user's platform", "example": "#1001", "nullable": true }, "from": { "format": "date-time", "type": "string", "description": "Start date and time of the appointment (UTC timezone)", "example": "2023-06-15T09:00:00Z" }, "to": { "format": "date-time", "type": "string", "description": "End date and time of the appointment (UTC timezone)", "example": "2023-06-15T10:00:00Z" }, "displayAddress": { "type": "string", "description": "Merchant-defined display address from the location; overrides the concatenated address fields in notifications. Null falls back to the structured address.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressId": { "type": "string", "description": "ID of the linked service/delivery address", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of the appointment address", "nullable": true, "deprecated": true }, "addressLine2": { "type": "string", "description": "Second line of the appointment address", "nullable": true, "deprecated": true }, "city": { "type": "string", "description": "City of the appointment location", "nullable": true, "deprecated": true }, "state": { "type": "string", "description": "State/province of the appointment location", "nullable": true, "deprecated": true }, "postalCode": { "type": "string", "description": "Postal/zip code of the appointment location", "nullable": true, "deprecated": true }, "country": { "type": "string", "description": "Country of the appointment location", "nullable": true, "deprecated": true }, "status": { "example": "scheduled", "$ref": "#/components/schemas/AppointmentStatusType" }, "internalNote": { "type": "string", "description": "Internal notes about the appointment (not visible to customers)", "example": "Customer requested extra attention for specific needs", "nullable": true }, "createdBy": { "example": "customer", "$ref": "#/components/schemas/AppointmentCreatedByEnum" }, "reminderSentAt": { "format": "date-time", "type": "string", "description": "Date and time when reminder was sent to the customer", "example": "2023-06-14T09:00:00Z", "nullable": true }, "numberOfAttendees": { "type": "number", "description": "Number of people attending the appointment", "example": 1, "default": 1 }, "customAttributes": { "type": "object", "description": "Custom key-value attributes (strings) attached to the appointment. Max 250 entries.", "additionalProperties": { "type": "string" }, "nullable": true, "example": { "source": "widget", "party_size": "4" } }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "deliveryAddress": { "description": "Linked service/delivery address (DELIVERY locations)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DeliveryAddress" } ] }, "product": { "description": "Service/product details for this appointment", "allOf": [ { "$ref": "#/components/schemas/OrderListAppointmentProduct" } ] }, "staffMember": { "description": "Staff member assigned to this appointment", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/OrderListAppointmentStaffMember" } ] }, "location": { "description": "Location where the appointment will take place", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/OrderListAppointmentLocation" } ] } }, "required": [ "id", "name", "productId", "staffMemberId", "locationId", "storeId", "customerId", "externalOrderId", "externalOrderName", "from", "to", "displayAddress", "status", "internalNote", "createdBy", "reminderSentAt", "numberOfAttendees", "createdAt", "updatedAt", "deletedAt", "product", "staffMember", "location" ] }, "OrderListAddOnLineItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the order add-on line item" }, "orderId": { "type": "string", "description": "ID of the order" }, "lineItemId": { "type": "string", "description": "ID of the parent order line item (the appointment) this add-on belongs to" }, "addOnId": { "type": "string", "description": "ID of the add-on" }, "externalId": { "type": "string", "description": "External line item ID from the platform (e.g., Shopify) for this add-on", "nullable": true }, "originalUnitPrice": { "type": "number", "description": "Original unit price" }, "discountedUnitPrice": { "type": "number", "description": "Discounted price per unit (approximate — use the line totals for exact amounts)" }, "unitTaxAmount": { "type": "number", "description": "Tax amount per unit (approximate — use the line totals for exact amounts)" }, "quantity": { "type": "number", "description": "Quantity. For fixed add-ons this is the customer-picked count; for duration-multiplied add-ons it is the number of base-duration units of the parent appointment, snapshotted at cart → order conversion." }, "createdAt": { "format": "date-time", "type": "string", "description": "Created at" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Updated at", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Deleted at", "nullable": true }, "originalSubtotal": { "type": "number", "description": "Original subtotal of this add-on across all quantities, before discount" }, "totalDiscount": { "type": "number", "description": "Total discount applied to this add-on, across all quantities (approximate)" }, "discountedSubtotal": { "type": "number", "description": "Discounted subtotal of this add-on (original subtotal − total discount), before tax" }, "discountedTotal": { "type": "number", "description": "Discounted total of this add-on line item, including tax when not already in the price" }, "totalTax": { "type": "number", "description": "Total tax for this add-on line item (approximate)" }, "refundedQuantity": { "type": "number", "description": "Quantity already refunded" }, "refundableQuantity": { "type": "number", "description": "Remaining refundable quantity" } }, "required": [ "id", "orderId", "lineItemId", "addOnId", "externalId", "originalUnitPrice", "discountedUnitPrice", "unitTaxAmount", "quantity", "createdAt", "updatedAt", "deletedAt", "originalSubtotal", "totalDiscount", "discountedSubtotal", "discountedTotal", "totalTax", "refundedQuantity", "refundableQuantity" ] }, "OrderListLineItem": { "type": "object", "properties": { "orderId": { "type": "string", "description": "ID of the order", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "appointmentId": { "type": "string", "description": "ID of the appointment associated with line item", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "externalId": { "type": "string", "description": "External order line item ID from user's platform (if any)", "example": "12345678", "nullable": true }, "originalUnitPrice": { "type": "number", "description": "Original price of the item", "example": 249.99 }, "discountedUnitPrice": { "type": "number", "description": "Discounted price per unit (approximate — use the line totals for exact amounts)", "example": 249.99 }, "unitTaxAmount": { "type": "number", "description": "Tax amount per unit (approximate — use the line totals for exact amounts)", "example": 0 }, "quantity": { "type": "number", "description": "Quantity of the item ordered", "example": 1 }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "addOnSubtotal": { "type": "number", "description": "Discounted subtotal of the add-ons attached to this line item, before tax" }, "addOnTotalTax": { "type": "number", "description": "Total tax of the add-ons attached to this line item (approximate)" }, "originalSubtotal": { "type": "number", "description": "Original subtotal of the base line across all quantities, before discount", "example": 249.99 }, "totalDiscount": { "type": "number", "description": "Exact total discount applied to the base line, across all quantities", "example": 0 }, "discountedSubtotal": { "type": "number", "description": "Discounted subtotal of the base line (original subtotal − total discount), before tax", "example": 249.99 }, "discountedTotal": { "type": "number", "description": "Discounted total of the base line, including tax when not already in the price", "example": 249.99 }, "totalTax": { "type": "number", "description": "Total tax of the base line across all quantities (approximate)", "example": 0 }, "refundedQuantity": { "type": "number", "description": "The quantity of the line item that has been refunded", "example": 249.99 }, "refundableQuantity": { "type": "number", "description": "The quantity of the line item that can be refunded", "example": 249.99 }, "appointment": { "description": "The appointment this line item is for", "allOf": [ { "$ref": "#/components/schemas/OrderListAppointment" } ] }, "addOnLineItems": { "description": "Add-on line items attached to this line item", "type": "array", "items": { "$ref": "#/components/schemas/OrderListAddOnLineItem" } } }, "required": [ "orderId", "appointmentId", "externalId", "originalUnitPrice", "discountedUnitPrice", "unitTaxAmount", "quantity", "createdAt", "updatedAt", "deletedAt", "addOnSubtotal", "addOnTotalTax", "originalSubtotal", "totalDiscount", "discountedSubtotal", "discountedTotal", "totalTax", "refundedQuantity", "refundableQuantity", "appointment", "addOnLineItems" ] }, "OrderListTransaction": { "type": "object", "properties": { "orderId": { "type": "string", "description": "ID of the order", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "externalId": { "type": "string", "description": "External order transaction ID from user's platform (if any)", "example": "12345678", "nullable": true }, "parentId": { "type": "string", "description": "The parent transaction ID", "example": "12345678", "nullable": true }, "refundId": { "type": "string", "description": "The refund ID this transaction belongs to (if any)", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "type": { "type": "string", "description": "The type of transaction", "example": "sale", "enum": [ "authorization", "capture", "void", "sale", "refund" ] }, "amount": { "type": "number", "description": "Amount of the transaction", "example": 249.99 }, "currencyCode": { "type": "string", "description": "The currency code", "example": "USD" }, "gateway": { "type": "string", "description": "The payment gateway", "example": "shopify", "enum": [ "shopify", "cash", "bank_transfer", "stripe" ], "deprecated": true }, "provider": { "type": "string", "description": "The payment provider (replaces gateway)", "example": "stripe", "enum": [ "stripe", "cash", "bank_transfer", "shopify", "no_payment_required" ] }, "status": { "type": "string", "description": "The status of the transaction", "example": "success", "enum": [ "pending", "success", "failed" ] }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "refundableAmount": { "type": "number", "description": "The refundable amount for this transaction", "example": 249.99 }, "refundedAmount": { "type": "number", "description": "The refunded amount for this transaction", "example": 249.99 }, "isRefundable": { "type": "boolean", "description": "Whether this transaction is refundable", "example": true } }, "required": [ "orderId", "externalId", "parentId", "refundId", "type", "amount", "currencyCode", "gateway", "provider", "status", "createdAt", "updatedAt", "deletedAt", "refundableAmount", "refundedAmount", "isRefundable" ] }, "OrderListItemResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the order" }, "paymentCurrencyCode": { "type": "string", "description": "The currency used by the customer when placing the order.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "taxesIncluded": { "type": "boolean", "description": "Whether the taxes are included in the order subtotal.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External order ID from user's platform (if any)", "example": "shop123_order_456", "nullable": true }, "externalName": { "type": "string", "description": "External order name/reference from user's platform", "example": "#1001", "nullable": true }, "name": { "type": "string", "description": "Generated order name for the user (starts at 1001 and increments)", "example": "1001" }, "customerId": { "type": "string", "description": "ID of the customer who placed the order", "example": "123e4567-e89b-12d3-a456-426614174000", "nullable": true }, "customerFirstName": { "type": "string", "description": "Snapshot of the customer first name captured when the order was placed", "nullable": true }, "customerLastName": { "type": "string", "description": "Snapshot of the customer last name captured when the order was placed", "nullable": true }, "customerEmail": { "type": "string", "description": "Snapshot of the customer email captured when the order was placed", "nullable": true }, "customerPhone": { "type": "string", "description": "Snapshot of the customer phone captured when the order was placed", "nullable": true }, "billingAddressId": { "type": "string", "description": "ID of the linked billing address", "nullable": true }, "deliveryAddressId": { "type": "string", "description": "ID of the linked order-level delivery address", "nullable": true }, "billingFirstName": { "type": "string", "description": "Billing bill-to first name", "nullable": true, "deprecated": true }, "billingLastName": { "type": "string", "description": "Billing bill-to last name", "nullable": true, "deprecated": true }, "billingCompanyName": { "type": "string", "description": "Billing company name", "nullable": true, "deprecated": true }, "billingTaxRegistrationId": { "type": "string", "description": "Billing tax registration id (VAT / GST / …)", "nullable": true, "deprecated": true }, "billingAddressLine1": { "type": "string", "description": "Billing address line 1", "nullable": true, "deprecated": true }, "billingAddressLine2": { "type": "string", "description": "Billing address line 2", "nullable": true, "deprecated": true }, "billingCity": { "type": "string", "description": "Billing city", "nullable": true, "deprecated": true }, "billingState": { "type": "string", "description": "Billing state/province", "nullable": true, "deprecated": true }, "billingPostalCode": { "type": "string", "description": "Billing postal/zip code", "nullable": true, "deprecated": true }, "billingCountry": { "type": "string", "description": "Billing country", "nullable": true, "deprecated": true }, "storeId": { "type": "string", "description": "ID of the store that owns the order", "example": "store-uuid", "nullable": true }, "cartId": { "type": "string", "description": "ID of the cart from which the order was created", "example": "123e4567-e89b-12d3-a456-426614174000", "nullable": true }, "gclid": { "type": "string", "description": "Google Ads click ID captured at the time of booking", "example": "EAIaIQobChMI...", "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "billingAddress": { "description": "Linked billing address", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CustomerAddress" } ] }, "deliveryAddress": { "description": "Linked order-level delivery address", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DeliveryAddress" } ] }, "subtotal": { "type": "number", "description": "Subtotal amount of the order, excluding canceled appointments", "example": 249.99 }, "total": { "type": "number", "description": "Total amount of the order, including canceled appointments and taxes", "example": 249.99 }, "totalTax": { "type": "number", "description": "Total tax amount of the order, excluding canceled appointments", "example": 249.99 }, "dueToPay": { "type": "number", "description": "Total amount still due to be paid for the order. Derived from the current total (which excludes canceled appointments and reflects current add-ons and discounts) minus the net amount already held (paid minus refunded). Never negative — when the customer has overpaid the current total, the surplus surfaces via dueToRefund instead.", "example": 249.99 }, "paidTotal": { "type": "number", "description": "Total amount paid for the order", "example": 249.99 }, "refundedTotal": { "type": "number", "description": "Total amount refunded for the order", "example": 249.99 }, "balance": { "type": "number", "description": "Balance of the order; based on paid and refunded amounts", "example": 249.99 }, "dueToRefund": { "type": "number", "description": "Total amount owed back to the customer. Derived from the net amount held (paid minus refunded) minus the current total. Any change that lowers the current total below what the customer has already paid — a canceled appointment, a removed or reduced add-on, or a discount that is restored on reevaluation — surfaces the surplus here. Never negative.", "example": 249.99 }, "isFullyPaid": { "type": "boolean", "description": "Whether the order is fully paid", "example": false }, "isFullyRefunded": { "type": "boolean", "description": "Whether everything the customer paid has been refunded (paid something, nothing held).", "example": false }, "paymentStatus": { "type": "string", "description": "Payment status of the order", "example": "paid", "enum": [ "unpaid", "paid", "partially-paid" ] }, "refundStatus": { "type": "string", "description": "Refund status of the order", "example": "partially-refunded", "enum": [ "refund-owed", "partially-refunded", "fully-refunded", "unrefunded" ] }, "fulfillmentStatus": { "type": "string", "description": "Fulfillment status of the order", "example": "partially-fulfilled", "enum": [ "partially-fulfilled", "fulfilled", "unfulfilled" ] }, "customer": { "description": "Customer who placed the order", "allOf": [ { "$ref": "#/components/schemas/OrderListCustomer" } ] }, "lineItems": { "description": "Line items in the order", "type": "array", "items": { "$ref": "#/components/schemas/OrderListLineItem" } }, "transactions": { "description": "Transactions associated with this order", "type": "array", "items": { "$ref": "#/components/schemas/OrderListTransaction" } } }, "required": [ "id", "paymentCurrencyCode", "taxesIncluded", "externalId", "externalName", "name", "customerId", "storeId", "cartId", "createdAt", "updatedAt", "deletedAt", "subtotal", "total", "totalTax", "dueToPay", "paidTotal", "refundedTotal", "balance", "dueToRefund", "isFullyPaid", "isFullyRefunded", "paymentStatus", "refundStatus", "fulfillmentStatus", "customer", "lineItems", "transactions" ] }, "OrderDetailCustomer": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the customer", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External customer identifier from integrated system", "example": "1234567890" }, "firstName": { "type": "string", "description": "Customer first name", "example": "John", "nullable": true }, "lastName": { "type": "string", "description": "Customer last name", "example": "Smith", "nullable": true }, "email": { "type": "string", "description": "Customer email address", "example": "john.smith@example.com", "nullable": true }, "phone": { "type": "string", "description": "Customer phone number", "example": "+12135550123", "nullable": true }, "password": { "type": "string", "description": "Hashed password of the customer", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this customer record", "example": "store-uuid" }, "language": { "example": "en", "$ref": "#/components/schemas/LanguageCode" }, "refreshToken": { "type": "string", "description": "Customer refresh token for authentication", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "nullable": true, "writeOnly": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Date when the customer record was created", "example": "2023-01-15T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date when the customer record was last updated", "example": "2023-02-20T14:15:00Z", "nullable": true }, "emailVerifiedAt": { "format": "date-time", "type": "string", "description": "Date and time when the customer verified email", "example": "2023-01-02T00:00:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "isEmailVerified": { "type": "boolean", "description": "Indicates whether customer email is verified" }, "isPasswordSet": { "type": "boolean", "description": "Indicates whether customer password is set" } }, "required": [ "id", "externalId", "firstName", "lastName", "email", "phone", "password", "storeId", "language", "refreshToken", "createdAt", "updatedAt", "emailVerifiedAt", "deletedAt", "isEmailVerified", "isPasswordSet" ] }, "OrderDetailAppointmentProduct": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "productId": { "type": "string", "description": "ID of the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID)", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID)", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this product", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the product (unique per store)", "example": "haircut-basic" }, "scheduleId": { "type": "string", "description": "ID of the schedule associated with this product" }, "productPoolId": { "type": "string", "description": "ID of the product pool this product belongs to (controls overlap prevention)", "nullable": true }, "title": { "type": "string", "description": "Title of the product", "example": "Haircut Service" }, "variantTitle": { "type": "string", "description": "Title of the specific product variant", "example": "Short Hair" }, "description": { "type": "string", "description": "Detailed description of the product" }, "imageId": { "type": "string", "description": "ID of the product image" }, "color": { "type": "string", "description": "Color code for displaying the product", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "BLUE", "default": "slate" }, "price": { "type": "number", "description": "Price of the product", "example": 250 }, "taxable": { "type": "boolean", "description": "Whether the product is taxable", "default": false }, "duration": { "type": "number", "description": "Duration of the service in seconds", "example": 3600 }, "allowCustomDuration": { "type": "boolean", "description": "Whether customers can customize the duration by selecting multiples of the base service duration (e.g., if base duration is 1 day, customers can book 1, 2, 3+ days)", "default": false }, "maxDuration": { "type": "number", "description": "When allow_custom_duration=true, maximum duration allowed for multi-duration bookings in seconds (-1 for unlimited)", "default": -1 }, "maxAttendees": { "type": "number", "description": "Maximum number of attendees allowed", "default": 1 }, "maxGuests": { "type": "number", "description": "Maximum number of guests allowed per appointment. Null means unlimited.", "nullable": true }, "allowGuests": { "type": "boolean", "description": "Whether customers can invite guests to the appointment", "default": false }, "allowCustomerReschedule": { "type": "boolean", "description": "Whether customers can reschedule their bookings", "default": false }, "allowCustomerCancel": { "type": "boolean", "description": "Whether customers can cancel their bookings", "default": false }, "rescheduleGap": { "type": "number", "description": "Time in seconds before appointment when rescheduling is no longer allowed" }, "cancelGap": { "type": "number", "description": "Time in seconds before appointment when cancellation is no longer allowed" }, "beforeGap": { "type": "number", "description": "Buffer time in seconds required before this service" }, "afterGap": { "type": "number", "description": "Buffer time in seconds required after this service" }, "fixedTimes": { "type": "boolean", "description": "When allow_custom_duration=true, whether appointments must start and end at fixed times (like fixed check-in/check-out times for multi-duration bookings)", "default": false }, "fixedStartTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must start (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "09:00:00" }, "fixedEndTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must end (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "17:00:00" }, "advanceScheduleThreshold": { "type": "number", "description": "How many days in advance bookings can be made", "default": 0 }, "sendConfirmationEmail": { "type": "boolean", "description": "Whether to send confirmation emails for bookings", "default": true }, "sendReminderEmail": { "type": "boolean", "description": "Whether to send reminder emails before appointments", "default": false }, "sendFeedbackEmail": { "type": "boolean", "description": "Whether to send feedback request emails after appointments", "default": false }, "skipCheckout": { "type": "boolean", "description": "Whether to skip the checkout process for this product (Shopify merchants only)", "default": false }, "status": { "type": "string", "description": "Current status of the product", "enum": [ "active", "inactive" ], "example": "ACTIVE", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the product was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the product was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the product was deleted (for soft deletes)" }, "image": { "description": "Primary image of the product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "productId", "externalId", "externalVariantId", "storeId", "slug", "scheduleId", "productPoolId", "title", "variantTitle", "description", "imageId", "color", "price", "taxable", "duration", "allowCustomDuration", "maxDuration", "maxAttendees", "maxGuests", "allowGuests", "allowCustomerReschedule", "allowCustomerCancel", "rescheduleGap", "cancelGap", "beforeGap", "afterGap", "fixedTimes", "fixedStartTime", "fixedEndTime", "advanceScheduleThreshold", "sendConfirmationEmail", "sendReminderEmail", "sendFeedbackEmail", "skipCheckout", "status", "createdAt", "updatedAt", "deletedAt" ] }, "OrderDetailAppointmentStaffMember": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this staff member record", "example": "123e4567-e89b-12d3-a456-426614174111" }, "userId": { "type": "string", "description": "User ID of the staff member login identity (nullable until linked)", "example": "user-uuid" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this staff member, defines their availability", "example": "123e4567-e89b-12d3-a456-426614174000" }, "imageId": { "type": "string", "description": "ID of the image associated with this staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "firstName": { "type": "string", "description": "First name of the staff member", "example": "John" }, "lastName": { "type": "string", "description": "Last name of the staff member", "example": "Doe" }, "email": { "type": "string", "description": "Email address of the staff member, used for notifications and calendar integration", "example": "john.doe@example.com" }, "slug": { "type": "string", "description": "URL-friendly slug for the staff member (unique per store)", "example": "mike" }, "refreshToken": { "type": "string", "description": "Refresh token for integrations like Google Calendar", "example": "abc123xyz456" }, "createdAt": { "type": "string", "description": "Date and time when the staff member was created", "example": "2025-05-01T12:00:00Z" }, "updatedAt": { "type": "string", "description": "Date and time when the staff member was last updated", "example": "2025-05-15T14:30:00Z" }, "deletedAt": { "type": "string", "description": "Date and time when the staff member was soft deleted", "example": "2025-06-01T09:15:00Z" }, "image": { "description": "Profile image of the staff member", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "storeId", "userId", "scheduleId", "imageId", "firstName", "lastName", "email", "slug", "refreshToken", "createdAt", "updatedAt", "deletedAt" ] }, "OrderDetailAppointmentLocation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the location", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this location", "example": "123e4567-e89b-12d3-a456-426614174001" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this location (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "title": { "type": "string", "description": "Name of the location", "example": "Main Office", "nullable": true }, "description": { "type": "string", "description": "Description of the location", "example": "Our main downtown office location with 3 treatment rooms", "nullable": true }, "slug": { "type": "string", "description": "URL-friendly slug for the location (unique per store)", "example": "new-york" }, "type": { "type": "string", "description": "Type of location", "enum": [ "physical", "online", "delivery" ], "example": "physical" }, "link": { "type": "string", "description": "URL link for online locations", "example": "https://zoom.us/j/123456789", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of address for physical locations", "example": "123 Main Street", "nullable": true }, "addressLine2": { "type": "string", "description": "Second line of address for physical locations", "example": "Suite 200", "nullable": true }, "city": { "type": "string", "description": "City for physical locations", "example": "San Francisco", "nullable": true }, "state": { "type": "string", "description": "State/province for physical locations", "example": "CA", "nullable": true }, "postalCode": { "type": "string", "description": "Postal code for physical locations", "example": "94105", "nullable": true }, "country": { "type": "string", "description": "Country for physical locations", "example": "United States", "nullable": true }, "displayAddress": { "type": "string", "description": "Merchant-defined display address that overrides the auto-formatted address (emails, booking page). Null falls back to the concatenated address fields.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressPlaceId": { "type": "string", "description": "Google Place ID for the physical address", "example": "ChIJIQBpAG2ahYAR_6128GcTUEo", "nullable": true }, "latitude": { "type": "number", "description": "Latitude in WGS84", "example": 37.4224764, "nullable": true }, "longitude": { "type": "number", "description": "Longitude in WGS84", "example": -122.0842499, "nullable": true }, "createdAt": { "type": "string", "description": "Date when the location was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the location was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "type": "string", "description": "Date when the location was deleted (for soft deletes)", "example": "2023-03-10T11:45:00Z", "nullable": true }, "address": { "type": "string", "description": "The formatted address string", "nullable": true } }, "required": [ "id", "storeId", "scheduleId", "title", "description", "slug", "type", "link", "addressLine1", "addressLine2", "city", "state", "postalCode", "country", "addressPlaceId", "latitude", "longitude", "createdAt", "updatedAt", "deletedAt", "address" ] }, "OrderDetailAppointment": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the appointment", "example": "123e4567-e89b-12d3-a456-426614174000" }, "name": { "type": "string", "description": "Generated appointment name for the user (starts at 1001 and increments)", "example": "1001" }, "productId": { "type": "string", "description": "ID of the service/product for this appointment", "example": "123e4567-e89b-12d3-a456-426614174001" }, "staffMemberId": { "type": "string", "description": "ID of the staff member assigned to this appointment (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "locationId": { "type": "string", "description": "ID of the location where the appointment will take place (if any)", "example": "123e4567-e89b-12d3-a456-426614174003", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this appointment", "example": "123e4567-e89b-12d3-a456-426614174004" }, "customerId": { "type": "string", "description": "ID of the customer who booked the appointment", "example": "123e4567-e89b-12d3-a456-426614174005", "nullable": true }, "externalOrderId": { "type": "string", "description": "External order ID from user's platform (if any)", "example": "12345678", "nullable": true }, "externalOrderName": { "type": "string", "description": "External order name/reference from user's platform", "example": "#1001", "nullable": true }, "from": { "format": "date-time", "type": "string", "description": "Start date and time of the appointment (UTC timezone)", "example": "2023-06-15T09:00:00Z" }, "to": { "format": "date-time", "type": "string", "description": "End date and time of the appointment (UTC timezone)", "example": "2023-06-15T10:00:00Z" }, "displayAddress": { "type": "string", "description": "Merchant-defined display address from the location; overrides the concatenated address fields in notifications. Null falls back to the structured address.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressId": { "type": "string", "description": "ID of the linked service/delivery address", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of the appointment address", "nullable": true, "deprecated": true }, "addressLine2": { "type": "string", "description": "Second line of the appointment address", "nullable": true, "deprecated": true }, "city": { "type": "string", "description": "City of the appointment location", "nullable": true, "deprecated": true }, "state": { "type": "string", "description": "State/province of the appointment location", "nullable": true, "deprecated": true }, "postalCode": { "type": "string", "description": "Postal/zip code of the appointment location", "nullable": true, "deprecated": true }, "country": { "type": "string", "description": "Country of the appointment location", "nullable": true, "deprecated": true }, "status": { "example": "scheduled", "$ref": "#/components/schemas/AppointmentStatusType" }, "internalNote": { "type": "string", "description": "Internal notes about the appointment (not visible to customers)", "example": "Customer requested extra attention for specific needs", "nullable": true }, "createdBy": { "example": "customer", "$ref": "#/components/schemas/AppointmentCreatedByEnum" }, "reminderSentAt": { "format": "date-time", "type": "string", "description": "Date and time when reminder was sent to the customer", "example": "2023-06-14T09:00:00Z", "nullable": true }, "numberOfAttendees": { "type": "number", "description": "Number of people attending the appointment", "example": 1, "default": 1 }, "customAttributes": { "type": "object", "description": "Custom key-value attributes (strings) attached to the appointment. Max 250 entries.", "additionalProperties": { "type": "string" }, "nullable": true, "example": { "source": "widget", "party_size": "4" } }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "deliveryAddress": { "description": "Linked service/delivery address (DELIVERY locations)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DeliveryAddress" } ] }, "product": { "description": "Service/product details for this appointment", "allOf": [ { "$ref": "#/components/schemas/OrderDetailAppointmentProduct" } ] }, "staffMember": { "description": "Staff member assigned to this appointment", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/OrderDetailAppointmentStaffMember" } ] }, "location": { "description": "Location where the appointment will take place", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/OrderDetailAppointmentLocation" } ] } }, "required": [ "id", "name", "productId", "staffMemberId", "locationId", "storeId", "customerId", "externalOrderId", "externalOrderName", "from", "to", "displayAddress", "status", "internalNote", "createdBy", "reminderSentAt", "numberOfAttendees", "createdAt", "updatedAt", "deletedAt", "product", "staffMember", "location" ] }, "OrderDetailAddOn": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the add-on", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID) for synced add-ons", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID) for synced add-ons", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this add-on", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the add-on (unique per store)", "example": "child-seat" }, "title": { "type": "string", "description": "Title of the add-on", "example": "Child Seat" }, "description": { "type": "string", "description": "Detailed description of the add-on" }, "imageId": { "type": "string", "description": "ID of the primary image for the add-on" }, "color": { "type": "string", "description": "Color code used when displaying the add-on", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "slate", "default": "slate" }, "price": { "type": "number", "description": "Unit price of the add-on", "example": 15 }, "taxable": { "type": "boolean", "description": "Whether the add-on is taxable", "default": true }, "durationMultiplied": { "type": "boolean", "description": "When true, the add-on is charged per base-duration unit of the parent appointment. Quantity on the cart/order line item mirrors the parent CartItem.quantity (i.e., the booked duration units). Only meaningful for attached products with allowCustomDuration=true.", "default": false }, "maxQuantity": { "type": "number", "description": "Maximum quantity a customer can pick for this add-on. Only applies to fixed add-ons (durationMultiplied=false). Null means unlimited.", "example": 4, "minimum": 1, "nullable": true }, "status": { "type": "string", "description": "Current status of the add-on", "enum": [ "active", "inactive" ], "example": "active", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the add-on was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the add-on was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the add-on was soft-deleted" }, "image": { "description": "Primary image of the add-on", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "externalId", "externalVariantId", "storeId", "slug", "title", "description", "imageId", "color", "price", "taxable", "durationMultiplied", "maxQuantity", "status", "createdAt", "updatedAt", "deletedAt" ] }, "OrderDetailAddOnRefundLineItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the refund add-on line item" }, "refundId": { "type": "string", "description": "ID of the refund this line item belongs to" }, "externalId": { "type": "string", "description": "External refund line item ID from the platform (e.g., Shopify)", "nullable": true }, "addOnLineItemId": { "type": "string", "description": "ID of the original order add-on line item being refunded" }, "quantity": { "type": "number", "description": "Quantity of the add-on line item being refunded", "minimum": 1 }, "createdAt": { "format": "date-time", "type": "string", "description": "Created at" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Updated at", "nullable": true } }, "required": [ "id", "refundId", "externalId", "addOnLineItemId", "quantity", "createdAt", "updatedAt" ] }, "OrderDetailAddOnLineItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the order add-on line item" }, "orderId": { "type": "string", "description": "ID of the order" }, "lineItemId": { "type": "string", "description": "ID of the parent order line item (the appointment) this add-on belongs to" }, "addOnId": { "type": "string", "description": "ID of the add-on" }, "externalId": { "type": "string", "description": "External line item ID from the platform (e.g., Shopify) for this add-on", "nullable": true }, "originalUnitPrice": { "type": "number", "description": "Original unit price" }, "discountedUnitPrice": { "type": "number", "description": "Discounted price per unit (approximate — use the line totals for exact amounts)" }, "unitTaxAmount": { "type": "number", "description": "Tax amount per unit (approximate — use the line totals for exact amounts)" }, "quantity": { "type": "number", "description": "Quantity. For fixed add-ons this is the customer-picked count; for duration-multiplied add-ons it is the number of base-duration units of the parent appointment, snapshotted at cart → order conversion." }, "createdAt": { "format": "date-time", "type": "string", "description": "Created at" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Updated at", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Deleted at", "nullable": true }, "originalSubtotal": { "type": "number", "description": "Original subtotal of this add-on across all quantities, before discount" }, "totalDiscount": { "type": "number", "description": "Total discount applied to this add-on, across all quantities (approximate)" }, "discountedSubtotal": { "type": "number", "description": "Discounted subtotal of this add-on (original subtotal − total discount), before tax" }, "discountedTotal": { "type": "number", "description": "Discounted total of this add-on line item, including tax when not already in the price" }, "totalTax": { "type": "number", "description": "Total tax for this add-on line item (approximate)" }, "refundedQuantity": { "type": "number", "description": "Quantity already refunded" }, "refundableQuantity": { "type": "number", "description": "Remaining refundable quantity" }, "addOn": { "description": "The add-on details", "allOf": [ { "$ref": "#/components/schemas/OrderDetailAddOn" } ] }, "refundLineItems": { "description": "Refund line items for this add-on", "type": "array", "items": { "$ref": "#/components/schemas/OrderDetailAddOnRefundLineItem" } } }, "required": [ "id", "orderId", "lineItemId", "addOnId", "externalId", "originalUnitPrice", "discountedUnitPrice", "unitTaxAmount", "quantity", "createdAt", "updatedAt", "deletedAt", "originalSubtotal", "totalDiscount", "discountedSubtotal", "discountedTotal", "totalTax", "refundedQuantity", "refundableQuantity", "addOn", "refundLineItems" ] }, "OrderDetailLineItemRefundLineItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the refund line item", "example": "550e8400-e29b-41d4-a716-446655440000" }, "refundId": { "type": "string", "description": "ID of the refund this line item belongs to", "example": "550e8400-e29b-41d4-a716-446655440000" }, "externalId": { "type": "string", "description": "External refund line item ID from the platform (e.g., Shopify)", "example": "123456789", "nullable": true }, "lineItemId": { "type": "string", "description": "ID of the original order line item being refunded", "example": "550e8400-e29b-41d4-a716-446655440000" }, "quantity": { "type": "number", "description": "Quantity of the line item being refunded", "example": 2, "minimum": 1 }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the refund line item was created", "example": "2023-06-10T15:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the refund line item was last updated", "example": "2023-06-10T16:15:00Z", "nullable": true } }, "required": [ "id", "refundId", "externalId", "lineItemId", "quantity", "createdAt", "updatedAt" ] }, "OrderDetailLineItem": { "type": "object", "properties": { "orderId": { "type": "string", "description": "ID of the order", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "appointmentId": { "type": "string", "description": "ID of the appointment associated with line item", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "externalId": { "type": "string", "description": "External order line item ID from user's platform (if any)", "example": "12345678", "nullable": true }, "originalUnitPrice": { "type": "number", "description": "Original price of the item", "example": 249.99 }, "discountedUnitPrice": { "type": "number", "description": "Discounted price per unit (approximate — use the line totals for exact amounts)", "example": 249.99 }, "unitTaxAmount": { "type": "number", "description": "Tax amount per unit (approximate — use the line totals for exact amounts)", "example": 0 }, "quantity": { "type": "number", "description": "Quantity of the item ordered", "example": 1 }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "addOnSubtotal": { "type": "number", "description": "Discounted subtotal of the add-ons attached to this line item, before tax" }, "addOnTotalTax": { "type": "number", "description": "Total tax of the add-ons attached to this line item (approximate)" }, "originalSubtotal": { "type": "number", "description": "Original subtotal of the base line across all quantities, before discount", "example": 249.99 }, "totalDiscount": { "type": "number", "description": "Exact total discount applied to the base line, across all quantities", "example": 0 }, "discountedSubtotal": { "type": "number", "description": "Discounted subtotal of the base line (original subtotal − total discount), before tax", "example": 249.99 }, "discountedTotal": { "type": "number", "description": "Discounted total of the base line, including tax when not already in the price", "example": 249.99 }, "totalTax": { "type": "number", "description": "Total tax of the base line across all quantities (approximate)", "example": 0 }, "refundedQuantity": { "type": "number", "description": "The quantity of the line item that has been refunded", "example": 249.99 }, "refundableQuantity": { "type": "number", "description": "The quantity of the line item that can be refunded", "example": 249.99 }, "appointment": { "description": "The appointment this line item is for", "allOf": [ { "$ref": "#/components/schemas/OrderDetailAppointment" } ] }, "addOnLineItems": { "description": "Add-on line items attached to this line item", "type": "array", "items": { "$ref": "#/components/schemas/OrderDetailAddOnLineItem" } }, "refundLineItems": { "description": "Refund line items associated with this line item", "type": "array", "items": { "$ref": "#/components/schemas/OrderDetailLineItemRefundLineItem" } } }, "required": [ "orderId", "appointmentId", "externalId", "originalUnitPrice", "discountedUnitPrice", "unitTaxAmount", "quantity", "createdAt", "updatedAt", "deletedAt", "addOnSubtotal", "addOnTotalTax", "originalSubtotal", "totalDiscount", "discountedSubtotal", "discountedTotal", "totalTax", "refundedQuantity", "refundableQuantity", "appointment", "addOnLineItems", "refundLineItems" ] }, "OrderDetailParentTransaction": { "type": "object", "properties": { "orderId": { "type": "string", "description": "ID of the order", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "externalId": { "type": "string", "description": "External order transaction ID from user's platform (if any)", "example": "12345678", "nullable": true }, "parentId": { "type": "string", "description": "The parent transaction ID", "example": "12345678", "nullable": true }, "refundId": { "type": "string", "description": "The refund ID this transaction belongs to (if any)", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "type": { "type": "string", "description": "The type of transaction", "example": "sale", "enum": [ "authorization", "capture", "void", "sale", "refund" ] }, "amount": { "type": "number", "description": "Amount of the transaction", "example": 249.99 }, "currencyCode": { "type": "string", "description": "The currency code", "example": "USD" }, "gateway": { "type": "string", "description": "The payment gateway", "example": "shopify", "enum": [ "shopify", "cash", "bank_transfer", "stripe" ], "deprecated": true }, "provider": { "type": "string", "description": "The payment provider (replaces gateway)", "example": "stripe", "enum": [ "stripe", "cash", "bank_transfer", "shopify", "no_payment_required" ] }, "status": { "type": "string", "description": "The status of the transaction", "example": "success", "enum": [ "pending", "success", "failed" ] }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "refundableAmount": { "type": "number", "description": "The refundable amount for this transaction", "example": 249.99 }, "refundedAmount": { "type": "number", "description": "The refunded amount for this transaction", "example": 249.99 }, "isRefundable": { "type": "boolean", "description": "Whether this transaction is refundable", "example": true } }, "required": [ "orderId", "externalId", "parentId", "refundId", "type", "amount", "currencyCode", "gateway", "provider", "status", "createdAt", "updatedAt", "deletedAt", "refundableAmount", "refundedAmount", "isRefundable" ] }, "OrderDetailChildTransaction": { "type": "object", "properties": { "orderId": { "type": "string", "description": "ID of the order", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "externalId": { "type": "string", "description": "External order transaction ID from user's platform (if any)", "example": "12345678", "nullable": true }, "parentId": { "type": "string", "description": "The parent transaction ID", "example": "12345678", "nullable": true }, "refundId": { "type": "string", "description": "The refund ID this transaction belongs to (if any)", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "type": { "type": "string", "description": "The type of transaction", "example": "sale", "enum": [ "authorization", "capture", "void", "sale", "refund" ] }, "amount": { "type": "number", "description": "Amount of the transaction", "example": 249.99 }, "currencyCode": { "type": "string", "description": "The currency code", "example": "USD" }, "gateway": { "type": "string", "description": "The payment gateway", "example": "shopify", "enum": [ "shopify", "cash", "bank_transfer", "stripe" ], "deprecated": true }, "provider": { "type": "string", "description": "The payment provider (replaces gateway)", "example": "stripe", "enum": [ "stripe", "cash", "bank_transfer", "shopify", "no_payment_required" ] }, "status": { "type": "string", "description": "The status of the transaction", "example": "success", "enum": [ "pending", "success", "failed" ] }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "refundableAmount": { "type": "number", "description": "The refundable amount for this transaction", "example": 249.99 }, "refundedAmount": { "type": "number", "description": "The refunded amount for this transaction", "example": 249.99 }, "isRefundable": { "type": "boolean", "description": "Whether this transaction is refundable", "example": true } }, "required": [ "orderId", "externalId", "parentId", "refundId", "type", "amount", "currencyCode", "gateway", "provider", "status", "createdAt", "updatedAt", "deletedAt", "refundableAmount", "refundedAmount", "isRefundable" ] }, "OrderDetailTransactionRefundTransaction": { "type": "object", "properties": { "orderId": { "type": "string", "description": "ID of the order", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "externalId": { "type": "string", "description": "External order transaction ID from user's platform (if any)", "example": "12345678", "nullable": true }, "parentId": { "type": "string", "description": "The parent transaction ID", "example": "12345678", "nullable": true }, "refundId": { "type": "string", "description": "The refund ID this transaction belongs to (if any)", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "type": { "type": "string", "description": "The type of transaction", "example": "sale", "enum": [ "authorization", "capture", "void", "sale", "refund" ] }, "amount": { "type": "number", "description": "Amount of the transaction", "example": 249.99 }, "currencyCode": { "type": "string", "description": "The currency code", "example": "USD" }, "gateway": { "type": "string", "description": "The payment gateway", "example": "shopify", "enum": [ "shopify", "cash", "bank_transfer", "stripe" ], "deprecated": true }, "provider": { "type": "string", "description": "The payment provider (replaces gateway)", "example": "stripe", "enum": [ "stripe", "cash", "bank_transfer", "shopify", "no_payment_required" ] }, "status": { "type": "string", "description": "The status of the transaction", "example": "success", "enum": [ "pending", "success", "failed" ] }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "refundableAmount": { "type": "number", "description": "The refundable amount for this transaction", "example": 249.99 }, "refundedAmount": { "type": "number", "description": "The refunded amount for this transaction", "example": 249.99 }, "isRefundable": { "type": "boolean", "description": "Whether this transaction is refundable", "example": true } }, "required": [ "orderId", "externalId", "parentId", "refundId", "type", "amount", "currencyCode", "gateway", "provider", "status", "createdAt", "updatedAt", "deletedAt", "refundableAmount", "refundedAmount", "isRefundable" ] }, "OrderDetailTransactionRefund": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the order refund", "example": "550e8400-e29b-41d4-a716-446655440000" }, "orderId": { "type": "string", "description": "ID of the order being refunded", "example": "550e8400-e29b-41d4-a716-446655440000" }, "externalId": { "type": "string", "description": "External refund ID from the platform (e.g., Shopify)", "example": "123456789", "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the refund was created", "example": "2023-06-10T15:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the refund was last updated", "example": "2023-06-10T16:15:00Z", "nullable": true }, "total": { "type": "number", "description": "The total amount of the refund", "example": 100 }, "transactions": { "description": "Transactions associated with this refund", "type": "array", "items": { "$ref": "#/components/schemas/OrderDetailTransactionRefundTransaction" } } }, "required": [ "id", "orderId", "externalId", "createdAt", "updatedAt", "total", "transactions" ] }, "OrderDetailTransaction": { "type": "object", "properties": { "orderId": { "type": "string", "description": "ID of the order", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "externalId": { "type": "string", "description": "External order transaction ID from user's platform (if any)", "example": "12345678", "nullable": true }, "parentId": { "type": "string", "description": "The parent transaction ID", "example": "12345678", "nullable": true }, "refundId": { "type": "string", "description": "The refund ID this transaction belongs to (if any)", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "type": { "type": "string", "description": "The type of transaction", "example": "sale", "enum": [ "authorization", "capture", "void", "sale", "refund" ] }, "amount": { "type": "number", "description": "Amount of the transaction", "example": 249.99 }, "currencyCode": { "type": "string", "description": "The currency code", "example": "USD" }, "gateway": { "type": "string", "description": "The payment gateway", "example": "shopify", "enum": [ "shopify", "cash", "bank_transfer", "stripe" ], "deprecated": true }, "provider": { "type": "string", "description": "The payment provider (replaces gateway)", "example": "stripe", "enum": [ "stripe", "cash", "bank_transfer", "shopify", "no_payment_required" ] }, "status": { "type": "string", "description": "The status of the transaction", "example": "success", "enum": [ "pending", "success", "failed" ] }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "refundableAmount": { "type": "number", "description": "The refundable amount for this transaction", "example": 249.99 }, "refundedAmount": { "type": "number", "description": "The refunded amount for this transaction", "example": 249.99 }, "isRefundable": { "type": "boolean", "description": "Whether this transaction is refundable", "example": true }, "parentTransaction": { "description": "The parent transaction", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/OrderDetailParentTransaction" } ] }, "childTransactions": { "description": "The child transactions", "type": "array", "items": { "$ref": "#/components/schemas/OrderDetailChildTransaction" } }, "refund": { "description": "The refund this transaction belongs to", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/OrderDetailTransactionRefund" } ] } }, "required": [ "orderId", "externalId", "parentId", "refundId", "type", "amount", "currencyCode", "gateway", "provider", "status", "createdAt", "updatedAt", "deletedAt", "refundableAmount", "refundedAmount", "isRefundable", "parentTransaction", "childTransactions", "refund" ] }, "OrderDetailRefundLineItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the refund line item", "example": "550e8400-e29b-41d4-a716-446655440000" }, "refundId": { "type": "string", "description": "ID of the refund this line item belongs to", "example": "550e8400-e29b-41d4-a716-446655440000" }, "externalId": { "type": "string", "description": "External refund line item ID from the platform (e.g., Shopify)", "example": "123456789", "nullable": true }, "lineItemId": { "type": "string", "description": "ID of the original order line item being refunded", "example": "550e8400-e29b-41d4-a716-446655440000" }, "quantity": { "type": "number", "description": "Quantity of the line item being refunded", "example": 2, "minimum": 1 }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the refund line item was created", "example": "2023-06-10T15:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the refund line item was last updated", "example": "2023-06-10T16:15:00Z", "nullable": true } }, "required": [ "id", "refundId", "externalId", "lineItemId", "quantity", "createdAt", "updatedAt" ] }, "OrderDetailRefundTransaction": { "type": "object", "properties": { "orderId": { "type": "string", "description": "ID of the order", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "externalId": { "type": "string", "description": "External order transaction ID from user's platform (if any)", "example": "12345678", "nullable": true }, "parentId": { "type": "string", "description": "The parent transaction ID", "example": "12345678", "nullable": true }, "refundId": { "type": "string", "description": "The refund ID this transaction belongs to (if any)", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "type": { "type": "string", "description": "The type of transaction", "example": "sale", "enum": [ "authorization", "capture", "void", "sale", "refund" ] }, "amount": { "type": "number", "description": "Amount of the transaction", "example": 249.99 }, "currencyCode": { "type": "string", "description": "The currency code", "example": "USD" }, "gateway": { "type": "string", "description": "The payment gateway", "example": "shopify", "enum": [ "shopify", "cash", "bank_transfer", "stripe" ], "deprecated": true }, "provider": { "type": "string", "description": "The payment provider (replaces gateway)", "example": "stripe", "enum": [ "stripe", "cash", "bank_transfer", "shopify", "no_payment_required" ] }, "status": { "type": "string", "description": "The status of the transaction", "example": "success", "enum": [ "pending", "success", "failed" ] }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "refundableAmount": { "type": "number", "description": "The refundable amount for this transaction", "example": 249.99 }, "refundedAmount": { "type": "number", "description": "The refunded amount for this transaction", "example": 249.99 }, "isRefundable": { "type": "boolean", "description": "Whether this transaction is refundable", "example": true } }, "required": [ "orderId", "externalId", "parentId", "refundId", "type", "amount", "currencyCode", "gateway", "provider", "status", "createdAt", "updatedAt", "deletedAt", "refundableAmount", "refundedAmount", "isRefundable" ] }, "OrderDetailRefund": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the order refund", "example": "550e8400-e29b-41d4-a716-446655440000" }, "orderId": { "type": "string", "description": "ID of the order being refunded", "example": "550e8400-e29b-41d4-a716-446655440000" }, "externalId": { "type": "string", "description": "External refund ID from the platform (e.g., Shopify)", "example": "123456789", "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the refund was created", "example": "2023-06-10T15:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the refund was last updated", "example": "2023-06-10T16:15:00Z", "nullable": true }, "total": { "type": "number", "description": "The total amount of the refund", "example": 100 }, "lineItems": { "description": "Line items included in this refund", "type": "array", "items": { "$ref": "#/components/schemas/OrderDetailRefundLineItem" } }, "transactions": { "description": "Transactions associated with this refund", "type": "array", "items": { "$ref": "#/components/schemas/OrderDetailRefundTransaction" } } }, "required": [ "id", "orderId", "externalId", "createdAt", "updatedAt", "total", "lineItems", "transactions" ] }, "OrderDetailLog": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the order log entry", "example": "123e4567-e89b-12d3-a456-426614174000" }, "orderId": { "type": "string", "description": "ID of the order this log entry relates to", "example": "123e4567-e89b-12d3-a456-426614174001" }, "title": { "type": "string", "description": "Title or summary of the log entry", "example": "Order rescheduled" }, "description": { "type": "string", "description": "Detailed description or additional information about the log entry", "example": "Customer requested to reschedule from June 15 to June 20", "nullable": true }, "level": { "example": "info", "$ref": "#/components/schemas/OrderLogLevel" }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when this log entry was created", "example": "2023-06-10T15:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when this log entry was last updated", "example": "2023-06-10T16:15:00Z", "nullable": true } }, "required": [ "id", "orderId", "title", "description", "level", "createdAt", "updatedAt" ] }, "OrderDetailResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the order" }, "paymentCurrencyCode": { "type": "string", "description": "The currency used by the customer when placing the order.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "taxesIncluded": { "type": "boolean", "description": "Whether the taxes are included in the order subtotal.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External order ID from user's platform (if any)", "example": "shop123_order_456", "nullable": true }, "externalName": { "type": "string", "description": "External order name/reference from user's platform", "example": "#1001", "nullable": true }, "name": { "type": "string", "description": "Generated order name for the user (starts at 1001 and increments)", "example": "1001" }, "customerId": { "type": "string", "description": "ID of the customer who placed the order", "example": "123e4567-e89b-12d3-a456-426614174000", "nullable": true }, "customerFirstName": { "type": "string", "description": "Snapshot of the customer first name captured when the order was placed", "nullable": true }, "customerLastName": { "type": "string", "description": "Snapshot of the customer last name captured when the order was placed", "nullable": true }, "customerEmail": { "type": "string", "description": "Snapshot of the customer email captured when the order was placed", "nullable": true }, "customerPhone": { "type": "string", "description": "Snapshot of the customer phone captured when the order was placed", "nullable": true }, "billingAddressId": { "type": "string", "description": "ID of the linked billing address", "nullable": true }, "deliveryAddressId": { "type": "string", "description": "ID of the linked order-level delivery address", "nullable": true }, "billingFirstName": { "type": "string", "description": "Billing bill-to first name", "nullable": true, "deprecated": true }, "billingLastName": { "type": "string", "description": "Billing bill-to last name", "nullable": true, "deprecated": true }, "billingCompanyName": { "type": "string", "description": "Billing company name", "nullable": true, "deprecated": true }, "billingTaxRegistrationId": { "type": "string", "description": "Billing tax registration id (VAT / GST / …)", "nullable": true, "deprecated": true }, "billingAddressLine1": { "type": "string", "description": "Billing address line 1", "nullable": true, "deprecated": true }, "billingAddressLine2": { "type": "string", "description": "Billing address line 2", "nullable": true, "deprecated": true }, "billingCity": { "type": "string", "description": "Billing city", "nullable": true, "deprecated": true }, "billingState": { "type": "string", "description": "Billing state/province", "nullable": true, "deprecated": true }, "billingPostalCode": { "type": "string", "description": "Billing postal/zip code", "nullable": true, "deprecated": true }, "billingCountry": { "type": "string", "description": "Billing country", "nullable": true, "deprecated": true }, "storeId": { "type": "string", "description": "ID of the store that owns the order", "example": "store-uuid", "nullable": true }, "cartId": { "type": "string", "description": "ID of the cart from which the order was created", "example": "123e4567-e89b-12d3-a456-426614174000", "nullable": true }, "gclid": { "type": "string", "description": "Google Ads click ID captured at the time of booking", "example": "EAIaIQobChMI...", "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "billingAddress": { "description": "Linked billing address", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CustomerAddress" } ] }, "deliveryAddress": { "description": "Linked order-level delivery address", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DeliveryAddress" } ] }, "subtotal": { "type": "number", "description": "Subtotal amount of the order, excluding canceled appointments", "example": 249.99 }, "total": { "type": "number", "description": "Total amount of the order, including canceled appointments and taxes", "example": 249.99 }, "totalTax": { "type": "number", "description": "Total tax amount of the order, excluding canceled appointments", "example": 249.99 }, "dueToPay": { "type": "number", "description": "Total amount still due to be paid for the order. Derived from the current total (which excludes canceled appointments and reflects current add-ons and discounts) minus the net amount already held (paid minus refunded). Never negative — when the customer has overpaid the current total, the surplus surfaces via dueToRefund instead.", "example": 249.99 }, "paidTotal": { "type": "number", "description": "Total amount paid for the order", "example": 249.99 }, "refundedTotal": { "type": "number", "description": "Total amount refunded for the order", "example": 249.99 }, "balance": { "type": "number", "description": "Balance of the order; based on paid and refunded amounts", "example": 249.99 }, "dueToRefund": { "type": "number", "description": "Total amount owed back to the customer. Derived from the net amount held (paid minus refunded) minus the current total. Any change that lowers the current total below what the customer has already paid — a canceled appointment, a removed or reduced add-on, or a discount that is restored on reevaluation — surfaces the surplus here. Never negative.", "example": 249.99 }, "isFullyPaid": { "type": "boolean", "description": "Whether the order is fully paid", "example": false }, "isFullyRefunded": { "type": "boolean", "description": "Whether everything the customer paid has been refunded (paid something, nothing held).", "example": false }, "paymentStatus": { "type": "string", "description": "Payment status of the order", "example": "paid", "enum": [ "unpaid", "paid", "partially-paid" ] }, "refundStatus": { "type": "string", "description": "Refund status of the order", "example": "partially-refunded", "enum": [ "refund-owed", "partially-refunded", "fully-refunded", "unrefunded" ] }, "fulfillmentStatus": { "type": "string", "description": "Fulfillment status of the order", "example": "partially-fulfilled", "enum": [ "partially-fulfilled", "fulfilled", "unfulfilled" ] }, "customer": { "description": "Customer who placed the order", "allOf": [ { "$ref": "#/components/schemas/OrderDetailCustomer" } ] }, "lineItems": { "description": "Line items in the order", "type": "array", "items": { "$ref": "#/components/schemas/OrderDetailLineItem" } }, "transactions": { "description": "Transactions associated with this order", "type": "array", "items": { "$ref": "#/components/schemas/OrderDetailTransaction" } }, "refunds": { "description": "Refunds associated with this order", "type": "array", "items": { "$ref": "#/components/schemas/OrderDetailRefund" } }, "logs": { "description": "Order activity logs", "type": "array", "items": { "$ref": "#/components/schemas/OrderDetailLog" } } }, "required": [ "id", "paymentCurrencyCode", "taxesIncluded", "externalId", "externalName", "name", "customerId", "storeId", "cartId", "createdAt", "updatedAt", "deletedAt", "subtotal", "total", "totalTax", "dueToPay", "paidTotal", "refundedTotal", "balance", "dueToRefund", "isFullyPaid", "isFullyRefunded", "paymentStatus", "refundStatus", "fulfillmentStatus", "customer", "lineItems", "transactions", "refunds", "logs" ] }, "CartCustomer": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the customer", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External customer identifier from integrated system", "example": "1234567890" }, "firstName": { "type": "string", "description": "Customer first name", "example": "John", "nullable": true }, "lastName": { "type": "string", "description": "Customer last name", "example": "Smith", "nullable": true }, "email": { "type": "string", "description": "Customer email address", "example": "john.smith@example.com", "nullable": true }, "phone": { "type": "string", "description": "Customer phone number", "example": "+12135550123", "nullable": true }, "password": { "type": "string", "description": "Hashed password of the customer", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this customer record", "example": "store-uuid" }, "language": { "example": "en", "$ref": "#/components/schemas/LanguageCode" }, "refreshToken": { "type": "string", "description": "Customer refresh token for authentication", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "nullable": true, "writeOnly": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Date when the customer record was created", "example": "2023-01-15T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date when the customer record was last updated", "example": "2023-02-20T14:15:00Z", "nullable": true }, "emailVerifiedAt": { "format": "date-time", "type": "string", "description": "Date and time when the customer verified email", "example": "2023-01-02T00:00:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "isEmailVerified": { "type": "boolean", "description": "Indicates whether customer email is verified" }, "isPasswordSet": { "type": "boolean", "description": "Indicates whether customer password is set" } }, "required": [ "id", "externalId", "firstName", "lastName", "email", "phone", "password", "storeId", "language", "refreshToken", "createdAt", "updatedAt", "emailVerifiedAt", "deletedAt", "isEmailVerified", "isPasswordSet" ] }, "Schedule": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the schedule", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this schedule", "example": "123e4567-e89b-12d3-a456-426614174001" }, "name": { "type": "string", "description": "Name of the schedule", "example": "Standard Business Hours", "nullable": true }, "timezone": { "type": "string", "description": "Timezone for the schedule", "example": "UTC", "default": "UTC" }, "scheduleGap": { "type": "string", "description": "Time slot frequency for the schedule", "enum": [ "every-10-minutes", "every-15-minutes", "every-20-minutes", "every-30-minutes", "every-60-minutes" ], "example": "every-15-minutes", "default": "every-15-minutes" }, "appointmentsGap": { "type": "number", "description": "Buffer time between appointments in seconds", "example": 900 }, "advanceScheduleDays": { "type": "number", "description": "Number of days customers can book in advance (-1 for unlimited)", "example": 60, "default": -1 }, "availabilityType": { "type": "string", "description": "Type of availability pattern for this schedule", "enum": [ "continuous", "recurring", "non-recurring" ], "example": "recurring", "default": "continuous" }, "status": { "type": "string", "description": "Status of the schedule", "enum": [ "active", "inactive" ], "example": "active", "default": "inactive" }, "createdAt": { "type": "string", "description": "Date when the schedule was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the schedule was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date when the schedule was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true } }, "required": [ "id", "storeId", "name", "timezone", "scheduleGap", "appointmentsGap", "advanceScheduleDays", "availabilityType", "status", "createdAt", "updatedAt", "deletedAt" ] }, "CartItemProduct": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "productId": { "type": "string", "description": "ID of the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID)", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID)", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this product", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the product (unique per store)", "example": "haircut-basic" }, "scheduleId": { "type": "string", "description": "ID of the schedule associated with this product" }, "productPoolId": { "type": "string", "description": "ID of the product pool this product belongs to (controls overlap prevention)", "nullable": true }, "title": { "type": "string", "description": "Title of the product", "example": "Haircut Service" }, "variantTitle": { "type": "string", "description": "Title of the specific product variant", "example": "Short Hair" }, "description": { "type": "string", "description": "Detailed description of the product" }, "imageId": { "type": "string", "description": "ID of the product image" }, "color": { "type": "string", "description": "Color code for displaying the product", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "BLUE", "default": "slate" }, "price": { "type": "number", "description": "Price of the product", "example": 250 }, "taxable": { "type": "boolean", "description": "Whether the product is taxable", "default": false }, "duration": { "type": "number", "description": "Duration of the service in seconds", "example": 3600 }, "allowCustomDuration": { "type": "boolean", "description": "Whether customers can customize the duration by selecting multiples of the base service duration (e.g., if base duration is 1 day, customers can book 1, 2, 3+ days)", "default": false }, "maxDuration": { "type": "number", "description": "When allow_custom_duration=true, maximum duration allowed for multi-duration bookings in seconds (-1 for unlimited)", "default": -1 }, "maxAttendees": { "type": "number", "description": "Maximum number of attendees allowed", "default": 1 }, "maxGuests": { "type": "number", "description": "Maximum number of guests allowed per appointment. Null means unlimited.", "nullable": true }, "allowGuests": { "type": "boolean", "description": "Whether customers can invite guests to the appointment", "default": false }, "allowCustomerReschedule": { "type": "boolean", "description": "Whether customers can reschedule their bookings", "default": false }, "allowCustomerCancel": { "type": "boolean", "description": "Whether customers can cancel their bookings", "default": false }, "rescheduleGap": { "type": "number", "description": "Time in seconds before appointment when rescheduling is no longer allowed" }, "cancelGap": { "type": "number", "description": "Time in seconds before appointment when cancellation is no longer allowed" }, "beforeGap": { "type": "number", "description": "Buffer time in seconds required before this service" }, "afterGap": { "type": "number", "description": "Buffer time in seconds required after this service" }, "fixedTimes": { "type": "boolean", "description": "When allow_custom_duration=true, whether appointments must start and end at fixed times (like fixed check-in/check-out times for multi-duration bookings)", "default": false }, "fixedStartTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must start (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "09:00:00" }, "fixedEndTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must end (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "17:00:00" }, "advanceScheduleThreshold": { "type": "number", "description": "How many days in advance bookings can be made", "default": 0 }, "sendConfirmationEmail": { "type": "boolean", "description": "Whether to send confirmation emails for bookings", "default": true }, "sendReminderEmail": { "type": "boolean", "description": "Whether to send reminder emails before appointments", "default": false }, "sendFeedbackEmail": { "type": "boolean", "description": "Whether to send feedback request emails after appointments", "default": false }, "skipCheckout": { "type": "boolean", "description": "Whether to skip the checkout process for this product (Shopify merchants only)", "default": false }, "status": { "type": "string", "description": "Current status of the product", "enum": [ "active", "inactive" ], "example": "ACTIVE", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the product was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the product was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the product was deleted (for soft deletes)" }, "image": { "description": "Primary image of the product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] }, "schedule": { "description": "Availability schedule for the product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Schedule" } ] } }, "required": [ "id", "productId", "externalId", "externalVariantId", "storeId", "slug", "scheduleId", "productPoolId", "title", "variantTitle", "description", "imageId", "color", "price", "taxable", "duration", "allowCustomDuration", "maxDuration", "maxAttendees", "maxGuests", "allowGuests", "allowCustomerReschedule", "allowCustomerCancel", "rescheduleGap", "cancelGap", "beforeGap", "afterGap", "fixedTimes", "fixedStartTime", "fixedEndTime", "advanceScheduleThreshold", "sendConfirmationEmail", "sendReminderEmail", "sendFeedbackEmail", "skipCheckout", "status", "createdAt", "updatedAt", "deletedAt", "schedule" ] }, "CartItemStaffMember": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this staff member record", "example": "123e4567-e89b-12d3-a456-426614174111" }, "userId": { "type": "string", "description": "User ID of the staff member login identity (nullable until linked)", "example": "user-uuid" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this staff member, defines their availability", "example": "123e4567-e89b-12d3-a456-426614174000" }, "imageId": { "type": "string", "description": "ID of the image associated with this staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "firstName": { "type": "string", "description": "First name of the staff member", "example": "John" }, "lastName": { "type": "string", "description": "Last name of the staff member", "example": "Doe" }, "email": { "type": "string", "description": "Email address of the staff member, used for notifications and calendar integration", "example": "john.doe@example.com" }, "slug": { "type": "string", "description": "URL-friendly slug for the staff member (unique per store)", "example": "mike" }, "refreshToken": { "type": "string", "description": "Refresh token for integrations like Google Calendar", "example": "abc123xyz456" }, "createdAt": { "type": "string", "description": "Date and time when the staff member was created", "example": "2025-05-01T12:00:00Z" }, "updatedAt": { "type": "string", "description": "Date and time when the staff member was last updated", "example": "2025-05-15T14:30:00Z" }, "deletedAt": { "type": "string", "description": "Date and time when the staff member was soft deleted", "example": "2025-06-01T09:15:00Z" }, "image": { "description": "Profile image of the staff member", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] }, "schedule": { "description": "Availability schedule for the staff member", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Schedule" } ] } }, "required": [ "id", "storeId", "userId", "scheduleId", "imageId", "firstName", "lastName", "email", "slug", "refreshToken", "createdAt", "updatedAt", "deletedAt", "schedule" ] }, "CartItemLocation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the location", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this location", "example": "123e4567-e89b-12d3-a456-426614174001" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this location (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "title": { "type": "string", "description": "Name of the location", "example": "Main Office", "nullable": true }, "description": { "type": "string", "description": "Description of the location", "example": "Our main downtown office location with 3 treatment rooms", "nullable": true }, "slug": { "type": "string", "description": "URL-friendly slug for the location (unique per store)", "example": "new-york" }, "type": { "type": "string", "description": "Type of location", "enum": [ "physical", "online", "delivery" ], "example": "physical" }, "link": { "type": "string", "description": "URL link for online locations", "example": "https://zoom.us/j/123456789", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of address for physical locations", "example": "123 Main Street", "nullable": true }, "addressLine2": { "type": "string", "description": "Second line of address for physical locations", "example": "Suite 200", "nullable": true }, "city": { "type": "string", "description": "City for physical locations", "example": "San Francisco", "nullable": true }, "state": { "type": "string", "description": "State/province for physical locations", "example": "CA", "nullable": true }, "postalCode": { "type": "string", "description": "Postal code for physical locations", "example": "94105", "nullable": true }, "country": { "type": "string", "description": "Country for physical locations", "example": "United States", "nullable": true }, "displayAddress": { "type": "string", "description": "Merchant-defined display address that overrides the auto-formatted address (emails, booking page). Null falls back to the concatenated address fields.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressPlaceId": { "type": "string", "description": "Google Place ID for the physical address", "example": "ChIJIQBpAG2ahYAR_6128GcTUEo", "nullable": true }, "latitude": { "type": "number", "description": "Latitude in WGS84", "example": 37.4224764, "nullable": true }, "longitude": { "type": "number", "description": "Longitude in WGS84", "example": -122.0842499, "nullable": true }, "createdAt": { "type": "string", "description": "Date when the location was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the location was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "type": "string", "description": "Date when the location was deleted (for soft deletes)", "example": "2023-03-10T11:45:00Z", "nullable": true }, "address": { "type": "string", "description": "The formatted address string", "nullable": true }, "schedule": { "description": "Availability schedule for the location", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Schedule" } ] } }, "required": [ "id", "storeId", "scheduleId", "title", "description", "slug", "type", "link", "addressLine1", "addressLine2", "city", "state", "postalCode", "country", "addressPlaceId", "latitude", "longitude", "createdAt", "updatedAt", "deletedAt", "address", "schedule" ] }, "CartItemAppointment": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the appointment", "example": "123e4567-e89b-12d3-a456-426614174000" }, "name": { "type": "string", "description": "Generated appointment name for the user (starts at 1001 and increments)", "example": "1001" }, "productId": { "type": "string", "description": "ID of the service/product for this appointment", "example": "123e4567-e89b-12d3-a456-426614174001" }, "staffMemberId": { "type": "string", "description": "ID of the staff member assigned to this appointment (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "locationId": { "type": "string", "description": "ID of the location where the appointment will take place (if any)", "example": "123e4567-e89b-12d3-a456-426614174003", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this appointment", "example": "123e4567-e89b-12d3-a456-426614174004" }, "customerId": { "type": "string", "description": "ID of the customer who booked the appointment", "example": "123e4567-e89b-12d3-a456-426614174005", "nullable": true }, "externalOrderId": { "type": "string", "description": "External order ID from user's platform (if any)", "example": "12345678", "nullable": true }, "externalOrderName": { "type": "string", "description": "External order name/reference from user's platform", "example": "#1001", "nullable": true }, "from": { "format": "date-time", "type": "string", "description": "Start date and time of the appointment (UTC timezone)", "example": "2023-06-15T09:00:00Z" }, "to": { "format": "date-time", "type": "string", "description": "End date and time of the appointment (UTC timezone)", "example": "2023-06-15T10:00:00Z" }, "displayAddress": { "type": "string", "description": "Merchant-defined display address from the location; overrides the concatenated address fields in notifications. Null falls back to the structured address.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressId": { "type": "string", "description": "ID of the linked service/delivery address", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of the appointment address", "nullable": true, "deprecated": true }, "addressLine2": { "type": "string", "description": "Second line of the appointment address", "nullable": true, "deprecated": true }, "city": { "type": "string", "description": "City of the appointment location", "nullable": true, "deprecated": true }, "state": { "type": "string", "description": "State/province of the appointment location", "nullable": true, "deprecated": true }, "postalCode": { "type": "string", "description": "Postal/zip code of the appointment location", "nullable": true, "deprecated": true }, "country": { "type": "string", "description": "Country of the appointment location", "nullable": true, "deprecated": true }, "status": { "example": "scheduled", "$ref": "#/components/schemas/AppointmentStatusType" }, "internalNote": { "type": "string", "description": "Internal notes about the appointment (not visible to customers)", "example": "Customer requested extra attention for specific needs", "nullable": true }, "createdBy": { "example": "customer", "$ref": "#/components/schemas/AppointmentCreatedByEnum" }, "reminderSentAt": { "format": "date-time", "type": "string", "description": "Date and time when reminder was sent to the customer", "example": "2023-06-14T09:00:00Z", "nullable": true }, "numberOfAttendees": { "type": "number", "description": "Number of people attending the appointment", "example": 1, "default": 1 }, "customAttributes": { "type": "object", "description": "Custom key-value attributes (strings) attached to the appointment. Max 250 entries.", "additionalProperties": { "type": "string" }, "nullable": true, "example": { "source": "widget", "party_size": "4" } }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "deliveryAddress": { "description": "Linked service/delivery address (DELIVERY locations)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DeliveryAddress" } ] }, "product": { "description": "Service/product details for this appointment", "allOf": [ { "$ref": "#/components/schemas/CartItemProduct" } ] }, "staffMember": { "description": "Staff member assigned to this appointment", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CartItemStaffMember" } ] }, "location": { "description": "Location where the appointment will take place", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CartItemLocation" } ] } }, "required": [ "id", "name", "productId", "staffMemberId", "locationId", "storeId", "customerId", "externalOrderId", "externalOrderName", "from", "to", "displayAddress", "status", "internalNote", "createdBy", "reminderSentAt", "numberOfAttendees", "createdAt", "updatedAt", "deletedAt", "product", "staffMember", "location" ] }, "CartAddOnItemAddOn": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the add-on", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID) for synced add-ons", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID) for synced add-ons", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this add-on", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the add-on (unique per store)", "example": "child-seat" }, "title": { "type": "string", "description": "Title of the add-on", "example": "Child Seat" }, "description": { "type": "string", "description": "Detailed description of the add-on" }, "imageId": { "type": "string", "description": "ID of the primary image for the add-on" }, "color": { "type": "string", "description": "Color code used when displaying the add-on", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "slate", "default": "slate" }, "price": { "type": "number", "description": "Unit price of the add-on", "example": 15 }, "taxable": { "type": "boolean", "description": "Whether the add-on is taxable", "default": true }, "durationMultiplied": { "type": "boolean", "description": "When true, the add-on is charged per base-duration unit of the parent appointment. Quantity on the cart/order line item mirrors the parent CartItem.quantity (i.e., the booked duration units). Only meaningful for attached products with allowCustomDuration=true.", "default": false }, "maxQuantity": { "type": "number", "description": "Maximum quantity a customer can pick for this add-on. Only applies to fixed add-ons (durationMultiplied=false). Null means unlimited.", "example": 4, "minimum": 1, "nullable": true }, "status": { "type": "string", "description": "Current status of the add-on", "enum": [ "active", "inactive" ], "example": "active", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the add-on was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the add-on was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the add-on was soft-deleted" }, "image": { "description": "Primary image of the add-on", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "externalId", "externalVariantId", "storeId", "slug", "title", "description", "imageId", "color", "price", "taxable", "durationMultiplied", "maxQuantity", "status", "createdAt", "updatedAt", "deletedAt" ] }, "CartAddOnItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the cart add-on item" }, "cartId": { "type": "string", "description": "Cart ID" }, "cartItemId": { "type": "string", "description": "Parent cart item ID (the appointment this add-on is attached to)" }, "addOnId": { "type": "string", "description": "Add-on ID" }, "originalUnitPrice": { "type": "number", "description": "Original unit price" }, "discountedUnitPrice": { "type": "number", "description": "Discounted price per unit (approximate — use the line totals for exact amounts)" }, "unitTaxAmount": { "type": "number", "description": "Tax amount per unit (approximate — use the line totals for exact amounts)" }, "quantity": { "type": "number", "description": "Quantity. For fixed add-ons, this is the customer-picked count (bounded by AddOn.maxQuantity). For duration-multiplied add-ons, this mirrors the parent CartItem.quantity (number of base-duration units booked) and is kept in sync by the cart service whenever the appointment duration changes.", "example": 1 }, "createdAt": { "format": "date-time", "type": "string", "description": "Created at timestamp" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Updated at timestamp", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Deleted at timestamp", "nullable": true }, "discounts": { "description": "Applied discounts on this add-on item", "type": "array", "items": { "$ref": "#/components/schemas/CartItemAppliedDiscount" } }, "originalSubtotal": { "type": "number", "description": "Original subtotal of this add-on across all quantities, before discount" }, "totalDiscount": { "type": "number", "description": "Total discount applied to this add-on, across all quantities (approximate)" }, "discountedSubtotal": { "type": "number", "description": "Discounted subtotal of this add-on (subtotal − total discount), before tax" }, "totalTax": { "type": "number", "description": "Total tax for this add-on line item (approximate)" }, "discountedTotal": { "type": "number", "description": "Discounted total of this add-on line item, including tax when not already in the price" }, "addOn": { "description": "The add-on details", "allOf": [ { "$ref": "#/components/schemas/CartAddOnItemAddOn" } ] } }, "required": [ "id", "cartId", "cartItemId", "addOnId", "originalUnitPrice", "discountedUnitPrice", "unitTaxAmount", "quantity", "createdAt", "updatedAt", "deletedAt", "discounts", "originalSubtotal", "totalDiscount", "discountedSubtotal", "totalTax", "discountedTotal", "addOn" ] }, "CartItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the cart item" }, "cartId": { "type": "string", "description": "Cart ID" }, "appointmentId": { "type": "string", "description": "Appointment ID" }, "originalUnitPrice": { "type": "number", "description": "Original unit price" }, "discountedUnitPrice": { "type": "number", "description": "Discounted price per unit (approximate — use the line totals for exact amounts)" }, "unitTaxAmount": { "type": "number", "description": "Tax amount per unit (approximate — use the line totals for exact amounts)" }, "quantity": { "type": "number", "description": "Quantity", "example": 1 }, "createdAt": { "format": "date-time", "type": "string", "description": "Created at timestamp" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Updated at timestamp", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Deleted at timestamp", "nullable": true }, "discounts": { "description": "Applied discounts on this cart item (base line only)", "type": "array", "items": { "$ref": "#/components/schemas/CartItemAppliedDiscount" } }, "originalSubtotal": { "type": "number", "description": "Original subtotal of the base line across all quantities, before discount", "example": 225 }, "totalDiscount": { "type": "number", "description": "Exact total discount applied to the base line, across all quantities", "example": 100 }, "discountedSubtotal": { "type": "number", "description": "Discounted subtotal of the base line (subtotal − total discount), before tax", "example": 125 }, "totalTax": { "type": "number", "description": "Total tax of the base line across all quantities (approximate)", "example": 0 }, "discountedTotal": { "type": "number", "description": "Discounted total of the base line, including tax when not already in the price", "example": 125 }, "addOnSubtotal": { "type": "number", "description": "Discounted subtotal of this line’s add-ons, before tax", "example": 0 }, "addOnTotalTax": { "type": "number", "description": "Total tax of this line’s add-ons (approximate)", "example": 0 }, "appointment": { "description": "Appointment for this cart item", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CartItemAppointment" } ] }, "addOnItems": { "description": "Add-on items attached to this cart item", "type": "array", "items": { "$ref": "#/components/schemas/CartAddOnItem" } } }, "required": [ "id", "cartId", "appointmentId", "originalUnitPrice", "discountedUnitPrice", "unitTaxAmount", "quantity", "createdAt", "updatedAt", "deletedAt", "discounts", "originalSubtotal", "totalDiscount", "discountedSubtotal", "totalTax", "discountedTotal", "addOnSubtotal", "addOnTotalTax", "appointment", "addOnItems" ] }, "CartPayment": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the cart payment" }, "cartId": { "type": "string", "description": "Cart ID" }, "orderId": { "type": "string", "description": "Order ID created from the cart payment", "nullable": true }, "provider": { "type": "object", "description": "Payment provider identifier (e.g., stripe, cash, shopify)" }, "providerReference": { "type": "string", "description": "Provider reference (PaymentIntent/Session/charge id)", "nullable": true }, "status": { "type": "string", "description": "Payment status", "enum": [ "created", "authorized", "captured", "failed", "voided", "refunded" ] }, "amount": { "type": "number", "description": "Payment amount" }, "currency": { "type": "string", "description": "Payment currency code" }, "capturedAmount": { "type": "number", "description": "Captured amount" }, "authorizedUntil": { "format": "date-time", "type": "string", "description": "Authorization expiration timestamp", "nullable": true }, "clientSecret": { "type": "string", "description": "Client secret for Payment Element flow", "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Created at timestamp" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Updated at timestamp", "nullable": true } }, "required": [ "id", "cartId", "orderId", "provider", "providerReference", "status", "amount", "currency", "capturedAmount", "authorizedUntil", "clientSecret", "createdAt", "updatedAt" ] }, "CartResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the cart" }, "storeId": { "type": "string", "description": "ID of the store that owns the cart" }, "customerId": { "type": "string", "description": "ID of the customer who owns the cart", "nullable": true }, "customerFirstName": { "type": "string", "description": "Snapshot of the customer first name captured at checkout", "nullable": true }, "customerLastName": { "type": "string", "description": "Snapshot of the customer last name captured at checkout", "nullable": true }, "customerEmail": { "type": "string", "description": "Snapshot of the customer email captured at checkout", "nullable": true }, "customerPhone": { "type": "string", "description": "Snapshot of the customer phone captured at checkout", "nullable": true }, "billingAddressId": { "type": "string", "description": "ID of the linked billing address", "nullable": true }, "deliveryAddressId": { "type": "string", "description": "ID of the linked order-level delivery address", "nullable": true }, "billingFirstName": { "type": "string", "description": "Billing bill-to first name", "nullable": true, "deprecated": true }, "billingLastName": { "type": "string", "description": "Billing bill-to last name", "nullable": true, "deprecated": true }, "billingCompanyName": { "type": "string", "description": "Billing company name", "nullable": true, "deprecated": true }, "billingTaxRegistrationId": { "type": "string", "description": "Billing tax registration id (VAT / GST / …)", "nullable": true, "deprecated": true }, "billingAddressLine1": { "type": "string", "description": "Billing address line 1", "nullable": true, "deprecated": true }, "billingAddressLine2": { "type": "string", "description": "Billing address line 2", "nullable": true, "deprecated": true }, "billingCity": { "type": "string", "description": "Billing city", "nullable": true, "deprecated": true }, "billingState": { "type": "string", "description": "Billing state/province", "nullable": true, "deprecated": true }, "billingPostalCode": { "type": "string", "description": "Billing postal/zip code", "nullable": true, "deprecated": true }, "billingCountry": { "type": "string", "description": "Billing country", "nullable": true, "deprecated": true }, "status": { "type": "string", "description": "Cart status", "enum": [ "active", "converted", "abandoned" ] }, "paymentCurrencyCode": { "type": "string", "description": "Payment currency code for the cart totals" }, "taxesIncluded": { "type": "boolean", "description": "Whether taxes are included in prices" }, "expiresAt": { "format": "date-time", "type": "string", "description": "When cart should expire", "nullable": true }, "extensionsCount": { "type": "number", "description": "Number of times the cart expiration has been extended" }, "appliedDiscountCode": { "type": "string", "description": "Applied promo/discount code for this cart", "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Created at timestamp" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Updated at timestamp", "nullable": true }, "billingAddress": { "description": "Linked billing address", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CustomerAddress" } ] }, "deliveryAddress": { "description": "Linked order-level delivery address", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DeliveryAddress" } ] }, "subtotal": { "type": "number", "description": "Subtotal amount of the cart", "example": 100 }, "totalTax": { "type": "number", "description": "Total tax amount of the cart", "example": 20 }, "total": { "type": "number", "description": "Grand total of the cart", "example": 120 }, "appliedDiscounts": { "description": "Applied discounts aggregated across all cart items", "type": "array", "items": { "$ref": "#/components/schemas/AppliedDiscount" } }, "creditCovered": { "type": "number", "description": "Amount of credit consumed by this cart (minutes or currency; null if no credit applied)", "nullable": true }, "creditRemaining": { "type": "number", "description": "Credit balance remaining after this booking (minutes or currency; null if none)", "nullable": true }, "creditValueType": { "type": "string", "description": "Value type of the applied credit ('time' or 'fixed_amount'); null if none", "nullable": true }, "customer": { "description": "Customer who owns the cart", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CartCustomer" } ] }, "items": { "description": "Items in the cart", "type": "array", "items": { "$ref": "#/components/schemas/CartItem" } }, "payments": { "description": "Payment records associated with the cart", "type": "array", "items": { "$ref": "#/components/schemas/CartPayment" } } }, "required": [ "id", "storeId", "customerId", "status", "paymentCurrencyCode", "taxesIncluded", "expiresAt", "extensionsCount", "appliedDiscountCode", "createdAt", "updatedAt", "subtotal", "totalTax", "total", "appliedDiscounts", "customer", "items", "payments" ] }, "CreateCartItem": { "type": "object", "properties": { "appointmentId": { "type": "string", "description": "Appointment ID to add to the cart", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" } }, "required": [ "appointmentId" ] }, "AddCartAddOn": { "type": "object", "properties": { "addOnId": { "type": "string", "description": "Add-on ID to attach to the cart item" }, "quantity": { "type": "number", "description": "Quantity to add. Only used for fixed (non-duration-multiplied) add-ons; bounded by AddOn.maxQuantity. Ignored for duration-multiplied add-ons (quantity is taken from the parent CartItem).", "example": 1, "minimum": 1 } }, "required": [ "addOnId" ] }, "UpdateCartAddOn": { "type": "object", "properties": { "quantity": { "type": "number", "description": "New quantity for this fixed cart add-on item", "minimum": 1 } }, "required": [ "quantity" ] }, "StartCheckout": { "type": "object", "properties": { "provider": { "type": "string", "description": "Payment provider to use for this checkout", "enum": [ "stripe", "cash", "bank_transfer", "shopify", "no_payment_required" ], "example": "stripe" }, "customer": { "description": "Customer information to attach to the cart and appointments", "oneOf": [ { "$ref": "#/components/schemas/ExistingOrderCustomer" }, { "$ref": "#/components/schemas/NewOrderCustomer" } ] } }, "required": [ "provider" ] }, "CheckoutStartCartCustomer": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the customer", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External customer identifier from integrated system", "example": "1234567890" }, "firstName": { "type": "string", "description": "Customer first name", "example": "John", "nullable": true }, "lastName": { "type": "string", "description": "Customer last name", "example": "Smith", "nullable": true }, "email": { "type": "string", "description": "Customer email address", "example": "john.smith@example.com", "nullable": true }, "phone": { "type": "string", "description": "Customer phone number", "example": "+12135550123", "nullable": true }, "password": { "type": "string", "description": "Hashed password of the customer", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this customer record", "example": "store-uuid" }, "language": { "example": "en", "$ref": "#/components/schemas/LanguageCode" }, "refreshToken": { "type": "string", "description": "Customer refresh token for authentication", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "nullable": true, "writeOnly": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Date when the customer record was created", "example": "2023-01-15T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date when the customer record was last updated", "example": "2023-02-20T14:15:00Z", "nullable": true }, "emailVerifiedAt": { "format": "date-time", "type": "string", "description": "Date and time when the customer verified email", "example": "2023-01-02T00:00:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "isEmailVerified": { "type": "boolean", "description": "Indicates whether customer email is verified" }, "isPasswordSet": { "type": "boolean", "description": "Indicates whether customer password is set" } }, "required": [ "id", "externalId", "firstName", "lastName", "email", "phone", "password", "storeId", "language", "refreshToken", "createdAt", "updatedAt", "emailVerifiedAt", "deletedAt", "isEmailVerified", "isPasswordSet" ] }, "CheckoutStartCartItemProduct": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "productId": { "type": "string", "description": "ID of the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID)", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID)", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this product", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the product (unique per store)", "example": "haircut-basic" }, "scheduleId": { "type": "string", "description": "ID of the schedule associated with this product" }, "productPoolId": { "type": "string", "description": "ID of the product pool this product belongs to (controls overlap prevention)", "nullable": true }, "title": { "type": "string", "description": "Title of the product", "example": "Haircut Service" }, "variantTitle": { "type": "string", "description": "Title of the specific product variant", "example": "Short Hair" }, "description": { "type": "string", "description": "Detailed description of the product" }, "imageId": { "type": "string", "description": "ID of the product image" }, "color": { "type": "string", "description": "Color code for displaying the product", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "BLUE", "default": "slate" }, "price": { "type": "number", "description": "Price of the product", "example": 250 }, "taxable": { "type": "boolean", "description": "Whether the product is taxable", "default": false }, "duration": { "type": "number", "description": "Duration of the service in seconds", "example": 3600 }, "allowCustomDuration": { "type": "boolean", "description": "Whether customers can customize the duration by selecting multiples of the base service duration (e.g., if base duration is 1 day, customers can book 1, 2, 3+ days)", "default": false }, "maxDuration": { "type": "number", "description": "When allow_custom_duration=true, maximum duration allowed for multi-duration bookings in seconds (-1 for unlimited)", "default": -1 }, "maxAttendees": { "type": "number", "description": "Maximum number of attendees allowed", "default": 1 }, "maxGuests": { "type": "number", "description": "Maximum number of guests allowed per appointment. Null means unlimited.", "nullable": true }, "allowGuests": { "type": "boolean", "description": "Whether customers can invite guests to the appointment", "default": false }, "allowCustomerReschedule": { "type": "boolean", "description": "Whether customers can reschedule their bookings", "default": false }, "allowCustomerCancel": { "type": "boolean", "description": "Whether customers can cancel their bookings", "default": false }, "rescheduleGap": { "type": "number", "description": "Time in seconds before appointment when rescheduling is no longer allowed" }, "cancelGap": { "type": "number", "description": "Time in seconds before appointment when cancellation is no longer allowed" }, "beforeGap": { "type": "number", "description": "Buffer time in seconds required before this service" }, "afterGap": { "type": "number", "description": "Buffer time in seconds required after this service" }, "fixedTimes": { "type": "boolean", "description": "When allow_custom_duration=true, whether appointments must start and end at fixed times (like fixed check-in/check-out times for multi-duration bookings)", "default": false }, "fixedStartTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must start (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "09:00:00" }, "fixedEndTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must end (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "17:00:00" }, "advanceScheduleThreshold": { "type": "number", "description": "How many days in advance bookings can be made", "default": 0 }, "sendConfirmationEmail": { "type": "boolean", "description": "Whether to send confirmation emails for bookings", "default": true }, "sendReminderEmail": { "type": "boolean", "description": "Whether to send reminder emails before appointments", "default": false }, "sendFeedbackEmail": { "type": "boolean", "description": "Whether to send feedback request emails after appointments", "default": false }, "skipCheckout": { "type": "boolean", "description": "Whether to skip the checkout process for this product (Shopify merchants only)", "default": false }, "status": { "type": "string", "description": "Current status of the product", "enum": [ "active", "inactive" ], "example": "ACTIVE", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the product was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the product was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the product was deleted (for soft deletes)" }, "image": { "description": "Primary image of the product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] }, "schedule": { "description": "Availability schedule for the product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Schedule" } ] } }, "required": [ "id", "productId", "externalId", "externalVariantId", "storeId", "slug", "scheduleId", "productPoolId", "title", "variantTitle", "description", "imageId", "color", "price", "taxable", "duration", "allowCustomDuration", "maxDuration", "maxAttendees", "maxGuests", "allowGuests", "allowCustomerReschedule", "allowCustomerCancel", "rescheduleGap", "cancelGap", "beforeGap", "afterGap", "fixedTimes", "fixedStartTime", "fixedEndTime", "advanceScheduleThreshold", "sendConfirmationEmail", "sendReminderEmail", "sendFeedbackEmail", "skipCheckout", "status", "createdAt", "updatedAt", "deletedAt" ] }, "CheckoutStartCartItemStaffMember": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this staff member record", "example": "123e4567-e89b-12d3-a456-426614174111" }, "userId": { "type": "string", "description": "User ID of the staff member login identity (nullable until linked)", "example": "user-uuid" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this staff member, defines their availability", "example": "123e4567-e89b-12d3-a456-426614174000" }, "imageId": { "type": "string", "description": "ID of the image associated with this staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "firstName": { "type": "string", "description": "First name of the staff member", "example": "John" }, "lastName": { "type": "string", "description": "Last name of the staff member", "example": "Doe" }, "email": { "type": "string", "description": "Email address of the staff member, used for notifications and calendar integration", "example": "john.doe@example.com" }, "slug": { "type": "string", "description": "URL-friendly slug for the staff member (unique per store)", "example": "mike" }, "refreshToken": { "type": "string", "description": "Refresh token for integrations like Google Calendar", "example": "abc123xyz456" }, "createdAt": { "type": "string", "description": "Date and time when the staff member was created", "example": "2025-05-01T12:00:00Z" }, "updatedAt": { "type": "string", "description": "Date and time when the staff member was last updated", "example": "2025-05-15T14:30:00Z" }, "deletedAt": { "type": "string", "description": "Date and time when the staff member was soft deleted", "example": "2025-06-01T09:15:00Z" }, "image": { "description": "Profile image of the staff member", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] }, "schedule": { "description": "Availability schedule for the staff member", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Schedule" } ] } }, "required": [ "id", "storeId", "userId", "scheduleId", "imageId", "firstName", "lastName", "email", "slug", "refreshToken", "createdAt", "updatedAt", "deletedAt" ] }, "CheckoutStartCartItemLocation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the location", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this location", "example": "123e4567-e89b-12d3-a456-426614174001" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this location (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "title": { "type": "string", "description": "Name of the location", "example": "Main Office", "nullable": true }, "description": { "type": "string", "description": "Description of the location", "example": "Our main downtown office location with 3 treatment rooms", "nullable": true }, "slug": { "type": "string", "description": "URL-friendly slug for the location (unique per store)", "example": "new-york" }, "type": { "type": "string", "description": "Type of location", "enum": [ "physical", "online", "delivery" ], "example": "physical" }, "link": { "type": "string", "description": "URL link for online locations", "example": "https://zoom.us/j/123456789", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of address for physical locations", "example": "123 Main Street", "nullable": true }, "addressLine2": { "type": "string", "description": "Second line of address for physical locations", "example": "Suite 200", "nullable": true }, "city": { "type": "string", "description": "City for physical locations", "example": "San Francisco", "nullable": true }, "state": { "type": "string", "description": "State/province for physical locations", "example": "CA", "nullable": true }, "postalCode": { "type": "string", "description": "Postal code for physical locations", "example": "94105", "nullable": true }, "country": { "type": "string", "description": "Country for physical locations", "example": "United States", "nullable": true }, "displayAddress": { "type": "string", "description": "Merchant-defined display address that overrides the auto-formatted address (emails, booking page). Null falls back to the concatenated address fields.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressPlaceId": { "type": "string", "description": "Google Place ID for the physical address", "example": "ChIJIQBpAG2ahYAR_6128GcTUEo", "nullable": true }, "latitude": { "type": "number", "description": "Latitude in WGS84", "example": 37.4224764, "nullable": true }, "longitude": { "type": "number", "description": "Longitude in WGS84", "example": -122.0842499, "nullable": true }, "createdAt": { "type": "string", "description": "Date when the location was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the location was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "type": "string", "description": "Date when the location was deleted (for soft deletes)", "example": "2023-03-10T11:45:00Z", "nullable": true }, "address": { "type": "string", "description": "The formatted address string", "nullable": true }, "schedule": { "description": "Availability schedule for the location", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Schedule" } ] } }, "required": [ "id", "storeId", "scheduleId", "title", "description", "slug", "type", "link", "addressLine1", "addressLine2", "city", "state", "postalCode", "country", "addressPlaceId", "latitude", "longitude", "createdAt", "updatedAt", "deletedAt", "address" ] }, "CheckoutStartCartItemAppointment": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the appointment", "example": "123e4567-e89b-12d3-a456-426614174000" }, "name": { "type": "string", "description": "Generated appointment name for the user (starts at 1001 and increments)", "example": "1001" }, "productId": { "type": "string", "description": "ID of the service/product for this appointment", "example": "123e4567-e89b-12d3-a456-426614174001" }, "staffMemberId": { "type": "string", "description": "ID of the staff member assigned to this appointment (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "locationId": { "type": "string", "description": "ID of the location where the appointment will take place (if any)", "example": "123e4567-e89b-12d3-a456-426614174003", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this appointment", "example": "123e4567-e89b-12d3-a456-426614174004" }, "customerId": { "type": "string", "description": "ID of the customer who booked the appointment", "example": "123e4567-e89b-12d3-a456-426614174005", "nullable": true }, "externalOrderId": { "type": "string", "description": "External order ID from user's platform (if any)", "example": "12345678", "nullable": true }, "externalOrderName": { "type": "string", "description": "External order name/reference from user's platform", "example": "#1001", "nullable": true }, "from": { "format": "date-time", "type": "string", "description": "Start date and time of the appointment (UTC timezone)", "example": "2023-06-15T09:00:00Z" }, "to": { "format": "date-time", "type": "string", "description": "End date and time of the appointment (UTC timezone)", "example": "2023-06-15T10:00:00Z" }, "displayAddress": { "type": "string", "description": "Merchant-defined display address from the location; overrides the concatenated address fields in notifications. Null falls back to the structured address.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressId": { "type": "string", "description": "ID of the linked service/delivery address", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of the appointment address", "nullable": true, "deprecated": true }, "addressLine2": { "type": "string", "description": "Second line of the appointment address", "nullable": true, "deprecated": true }, "city": { "type": "string", "description": "City of the appointment location", "nullable": true, "deprecated": true }, "state": { "type": "string", "description": "State/province of the appointment location", "nullable": true, "deprecated": true }, "postalCode": { "type": "string", "description": "Postal/zip code of the appointment location", "nullable": true, "deprecated": true }, "country": { "type": "string", "description": "Country of the appointment location", "nullable": true, "deprecated": true }, "status": { "example": "scheduled", "$ref": "#/components/schemas/AppointmentStatusType" }, "internalNote": { "type": "string", "description": "Internal notes about the appointment (not visible to customers)", "example": "Customer requested extra attention for specific needs", "nullable": true }, "createdBy": { "example": "customer", "$ref": "#/components/schemas/AppointmentCreatedByEnum" }, "reminderSentAt": { "format": "date-time", "type": "string", "description": "Date and time when reminder was sent to the customer", "example": "2023-06-14T09:00:00Z", "nullable": true }, "numberOfAttendees": { "type": "number", "description": "Number of people attending the appointment", "example": 1, "default": 1 }, "customAttributes": { "type": "object", "description": "Custom key-value attributes (strings) attached to the appointment. Max 250 entries.", "additionalProperties": { "type": "string" }, "nullable": true, "example": { "source": "widget", "party_size": "4" } }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "deliveryAddress": { "description": "Linked service/delivery address (DELIVERY locations)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DeliveryAddress" } ] }, "product": { "description": "Service/product details for this appointment", "allOf": [ { "$ref": "#/components/schemas/CheckoutStartCartItemProduct" } ] }, "staffMember": { "description": "Staff member assigned to this appointment", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CheckoutStartCartItemStaffMember" } ] }, "location": { "description": "Location where the appointment will take place", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CheckoutStartCartItemLocation" } ] } }, "required": [ "id", "name", "productId", "staffMemberId", "locationId", "storeId", "customerId", "externalOrderId", "externalOrderName", "from", "to", "displayAddress", "status", "internalNote", "createdBy", "reminderSentAt", "numberOfAttendees", "createdAt", "updatedAt", "deletedAt" ] }, "CheckoutStartCartAddOnItemAddOn": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the add-on", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID) for synced add-ons", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID) for synced add-ons", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this add-on", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the add-on (unique per store)", "example": "child-seat" }, "title": { "type": "string", "description": "Title of the add-on", "example": "Child Seat" }, "description": { "type": "string", "description": "Detailed description of the add-on" }, "imageId": { "type": "string", "description": "ID of the primary image for the add-on" }, "color": { "type": "string", "description": "Color code used when displaying the add-on", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "slate", "default": "slate" }, "price": { "type": "number", "description": "Unit price of the add-on", "example": 15 }, "taxable": { "type": "boolean", "description": "Whether the add-on is taxable", "default": true }, "durationMultiplied": { "type": "boolean", "description": "When true, the add-on is charged per base-duration unit of the parent appointment. Quantity on the cart/order line item mirrors the parent CartItem.quantity (i.e., the booked duration units). Only meaningful for attached products with allowCustomDuration=true.", "default": false }, "maxQuantity": { "type": "number", "description": "Maximum quantity a customer can pick for this add-on. Only applies to fixed add-ons (durationMultiplied=false). Null means unlimited.", "example": 4, "minimum": 1, "nullable": true }, "status": { "type": "string", "description": "Current status of the add-on", "enum": [ "active", "inactive" ], "example": "active", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the add-on was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the add-on was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the add-on was soft-deleted" }, "image": { "description": "Primary image of the add-on", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "externalId", "externalVariantId", "storeId", "slug", "title", "description", "imageId", "color", "price", "taxable", "durationMultiplied", "maxQuantity", "status", "createdAt", "updatedAt", "deletedAt" ] }, "CheckoutStartCartAddOnItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the cart add-on item" }, "cartId": { "type": "string", "description": "Cart ID" }, "cartItemId": { "type": "string", "description": "Parent cart item ID (the appointment this add-on is attached to)" }, "addOnId": { "type": "string", "description": "Add-on ID" }, "originalUnitPrice": { "type": "number", "description": "Original unit price" }, "discountedUnitPrice": { "type": "number", "description": "Discounted price per unit (approximate — use the line totals for exact amounts)" }, "unitTaxAmount": { "type": "number", "description": "Tax amount per unit (approximate — use the line totals for exact amounts)" }, "quantity": { "type": "number", "description": "Quantity. For fixed add-ons, this is the customer-picked count (bounded by AddOn.maxQuantity). For duration-multiplied add-ons, this mirrors the parent CartItem.quantity (number of base-duration units booked) and is kept in sync by the cart service whenever the appointment duration changes.", "example": 1 }, "createdAt": { "format": "date-time", "type": "string", "description": "Created at timestamp" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Updated at timestamp", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Deleted at timestamp", "nullable": true }, "discounts": { "description": "Applied discounts on this add-on item", "type": "array", "items": { "$ref": "#/components/schemas/CartItemAppliedDiscount" } }, "originalSubtotal": { "type": "number", "description": "Original subtotal of this add-on across all quantities, before discount" }, "totalDiscount": { "type": "number", "description": "Total discount applied to this add-on, across all quantities (approximate)" }, "discountedSubtotal": { "type": "number", "description": "Discounted subtotal of this add-on (subtotal − total discount), before tax" }, "totalTax": { "type": "number", "description": "Total tax for this add-on line item (approximate)" }, "discountedTotal": { "type": "number", "description": "Discounted total of this add-on line item, including tax when not already in the price" }, "addOn": { "description": "The add-on details", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CheckoutStartCartAddOnItemAddOn" } ] } }, "required": [ "id", "cartId", "cartItemId", "addOnId", "originalUnitPrice", "discountedUnitPrice", "unitTaxAmount", "quantity", "createdAt", "updatedAt", "deletedAt", "discounts", "originalSubtotal", "totalDiscount", "discountedSubtotal", "totalTax", "discountedTotal" ] }, "CheckoutStartCartItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the cart item" }, "cartId": { "type": "string", "description": "Cart ID" }, "appointmentId": { "type": "string", "description": "Appointment ID" }, "originalUnitPrice": { "type": "number", "description": "Original unit price" }, "discountedUnitPrice": { "type": "number", "description": "Discounted price per unit (approximate — use the line totals for exact amounts)" }, "unitTaxAmount": { "type": "number", "description": "Tax amount per unit (approximate — use the line totals for exact amounts)" }, "quantity": { "type": "number", "description": "Quantity", "example": 1 }, "createdAt": { "format": "date-time", "type": "string", "description": "Created at timestamp" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Updated at timestamp", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Deleted at timestamp", "nullable": true }, "discounts": { "description": "Applied discounts on this cart item (base line only)", "type": "array", "items": { "$ref": "#/components/schemas/CartItemAppliedDiscount" } }, "originalSubtotal": { "type": "number", "description": "Original subtotal of the base line across all quantities, before discount", "example": 225 }, "totalDiscount": { "type": "number", "description": "Exact total discount applied to the base line, across all quantities", "example": 100 }, "discountedSubtotal": { "type": "number", "description": "Discounted subtotal of the base line (subtotal − total discount), before tax", "example": 125 }, "totalTax": { "type": "number", "description": "Total tax of the base line across all quantities (approximate)", "example": 0 }, "discountedTotal": { "type": "number", "description": "Discounted total of the base line, including tax when not already in the price", "example": 125 }, "addOnSubtotal": { "type": "number", "description": "Discounted subtotal of this line’s add-ons, before tax", "example": 0 }, "addOnTotalTax": { "type": "number", "description": "Total tax of this line’s add-ons (approximate)", "example": 0 }, "appointment": { "description": "Appointment for this cart item", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CheckoutStartCartItemAppointment" } ] }, "addOnItems": { "description": "Add-on items attached to this cart item", "type": "array", "items": { "$ref": "#/components/schemas/CheckoutStartCartAddOnItem" } } }, "required": [ "id", "cartId", "appointmentId", "originalUnitPrice", "discountedUnitPrice", "unitTaxAmount", "quantity", "createdAt", "updatedAt", "deletedAt", "discounts", "originalSubtotal", "totalDiscount", "discountedSubtotal", "totalTax", "discountedTotal", "addOnSubtotal", "addOnTotalTax" ] }, "CheckoutStartCartPayment": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the cart payment" }, "cartId": { "type": "string", "description": "Cart ID" }, "orderId": { "type": "string", "description": "Order ID created from the cart payment", "nullable": true }, "provider": { "type": "object", "description": "Payment provider identifier (e.g., stripe, cash, shopify)" }, "providerReference": { "type": "string", "description": "Provider reference (PaymentIntent/Session/charge id)", "nullable": true }, "status": { "type": "string", "description": "Payment status", "enum": [ "created", "authorized", "captured", "failed", "voided", "refunded" ] }, "amount": { "type": "number", "description": "Payment amount" }, "currency": { "type": "string", "description": "Payment currency code" }, "capturedAmount": { "type": "number", "description": "Captured amount" }, "authorizedUntil": { "format": "date-time", "type": "string", "description": "Authorization expiration timestamp", "nullable": true }, "clientSecret": { "type": "string", "description": "Client secret for Payment Element flow", "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Created at timestamp" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Updated at timestamp", "nullable": true } }, "required": [ "id", "cartId", "orderId", "provider", "providerReference", "status", "amount", "currency", "capturedAmount", "authorizedUntil", "clientSecret", "createdAt", "updatedAt" ] }, "CheckoutStartCart": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the cart" }, "storeId": { "type": "string", "description": "ID of the store that owns the cart" }, "customerId": { "type": "string", "description": "ID of the customer who owns the cart", "nullable": true }, "customerFirstName": { "type": "string", "description": "Snapshot of the customer first name captured at checkout", "nullable": true }, "customerLastName": { "type": "string", "description": "Snapshot of the customer last name captured at checkout", "nullable": true }, "customerEmail": { "type": "string", "description": "Snapshot of the customer email captured at checkout", "nullable": true }, "customerPhone": { "type": "string", "description": "Snapshot of the customer phone captured at checkout", "nullable": true }, "billingAddressId": { "type": "string", "description": "ID of the linked billing address", "nullable": true }, "deliveryAddressId": { "type": "string", "description": "ID of the linked order-level delivery address", "nullable": true }, "billingFirstName": { "type": "string", "description": "Billing bill-to first name", "nullable": true, "deprecated": true }, "billingLastName": { "type": "string", "description": "Billing bill-to last name", "nullable": true, "deprecated": true }, "billingCompanyName": { "type": "string", "description": "Billing company name", "nullable": true, "deprecated": true }, "billingTaxRegistrationId": { "type": "string", "description": "Billing tax registration id (VAT / GST / …)", "nullable": true, "deprecated": true }, "billingAddressLine1": { "type": "string", "description": "Billing address line 1", "nullable": true, "deprecated": true }, "billingAddressLine2": { "type": "string", "description": "Billing address line 2", "nullable": true, "deprecated": true }, "billingCity": { "type": "string", "description": "Billing city", "nullable": true, "deprecated": true }, "billingState": { "type": "string", "description": "Billing state/province", "nullable": true, "deprecated": true }, "billingPostalCode": { "type": "string", "description": "Billing postal/zip code", "nullable": true, "deprecated": true }, "billingCountry": { "type": "string", "description": "Billing country", "nullable": true, "deprecated": true }, "status": { "type": "string", "description": "Cart status", "enum": [ "active", "converted", "abandoned" ] }, "paymentCurrencyCode": { "type": "string", "description": "Payment currency code for the cart totals" }, "taxesIncluded": { "type": "boolean", "description": "Whether taxes are included in prices" }, "expiresAt": { "format": "date-time", "type": "string", "description": "When cart should expire", "nullable": true }, "extensionsCount": { "type": "number", "description": "Number of times the cart expiration has been extended" }, "appliedDiscountCode": { "type": "string", "description": "Applied promo/discount code for this cart", "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Created at timestamp" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Updated at timestamp", "nullable": true }, "billingAddress": { "description": "Linked billing address", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CustomerAddress" } ] }, "deliveryAddress": { "description": "Linked order-level delivery address", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DeliveryAddress" } ] }, "subtotal": { "type": "number", "description": "Subtotal amount of the cart", "example": 100 }, "totalTax": { "type": "number", "description": "Total tax amount of the cart", "example": 20 }, "total": { "type": "number", "description": "Grand total of the cart", "example": 120 }, "appliedDiscounts": { "description": "Applied discounts aggregated across all cart items", "type": "array", "items": { "$ref": "#/components/schemas/AppliedDiscount" } }, "creditCovered": { "type": "number", "description": "Amount of credit consumed by this cart (minutes or currency; null if no credit applied)", "nullable": true }, "creditRemaining": { "type": "number", "description": "Credit balance remaining after this booking (minutes or currency; null if none)", "nullable": true }, "creditValueType": { "type": "string", "description": "Value type of the applied credit ('time' or 'fixed_amount'); null if none", "nullable": true }, "customer": { "description": "Customer who owns the cart", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CheckoutStartCartCustomer" } ] }, "items": { "description": "Items in the cart", "type": "array", "items": { "$ref": "#/components/schemas/CheckoutStartCartItem" } }, "payments": { "description": "Payment records associated with the cart", "type": "array", "items": { "$ref": "#/components/schemas/CheckoutStartCartPayment" } } }, "required": [ "id", "storeId", "customerId", "status", "paymentCurrencyCode", "taxesIncluded", "expiresAt", "extensionsCount", "appliedDiscountCode", "createdAt", "updatedAt", "subtotal", "totalTax", "total", "appliedDiscounts" ] }, "CheckoutStartResponse": { "type": "object", "properties": { "provider": { "type": "string", "description": "Payment provider used", "enum": [ "stripe", "cash", "bank_transfer", "shopify", "no_payment_required" ] }, "clientSecret": { "type": "string", "description": "Stripe client secret for payment confirmation", "nullable": true }, "redirectUrl": { "type": "string", "description": "Redirect URL for external payment providers", "nullable": true }, "stripeAccountId": { "type": "string", "description": "Stripe connected account ID", "nullable": true }, "publishableKey": { "type": "string", "description": "Stripe platform publishable key matching the connected account mode (test/live)", "nullable": true }, "paymentId": { "type": "string", "description": "Cart payment record ID" }, "cart": { "description": "Updated cart", "allOf": [ { "$ref": "#/components/schemas/CheckoutStartCart" } ] }, "invalidItemIds": { "description": "IDs of invalid cart items that were removed", "type": "array", "items": { "type": "string" } }, "revivedItemIds": { "description": "IDs of expired cart items that were revived", "type": "array", "items": { "type": "string" } }, "discountCodeCleared": { "type": "boolean", "description": "True when an applied discount code was cleared during revalidation", "nullable": true } }, "required": [ "provider", "paymentId", "cart", "invalidItemIds", "revivedItemIds" ] }, "CheckoutTrackingData": { "type": "object", "properties": { "gclid": { "type": "string", "description": "Google Ads click ID (gclid) captured from the landing URL" } } }, "SubmitCheckout": { "type": "object", "properties": { "stripePaymentIntentId": { "type": "string", "description": "Stripe PaymentIntent ID (if payment was confirmed on frontend)" }, "customer": { "description": "Customer info to create/order if not already set on cart", "oneOf": [ { "$ref": "#/components/schemas/ExistingOrderCustomer" }, { "$ref": "#/components/schemas/NewOrderCustomer" } ] }, "appointmentsSettings": { "description": "Appointment settings to apply on order (e.g., mark as scheduled)", "allOf": [ { "$ref": "#/components/schemas/CreateOrderAppointmentsSettings" } ] }, "trackingData": { "description": "Client-side tracking data (e.g. Google Ads gclid)", "allOf": [ { "$ref": "#/components/schemas/CheckoutTrackingData" } ] } } }, "CheckoutOrderCustomer": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the customer", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External customer identifier from integrated system", "example": "1234567890" }, "firstName": { "type": "string", "description": "Customer first name", "example": "John", "nullable": true }, "lastName": { "type": "string", "description": "Customer last name", "example": "Smith", "nullable": true }, "email": { "type": "string", "description": "Customer email address", "example": "john.smith@example.com", "nullable": true }, "phone": { "type": "string", "description": "Customer phone number", "example": "+12135550123", "nullable": true }, "password": { "type": "string", "description": "Hashed password of the customer", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this customer record", "example": "store-uuid" }, "language": { "example": "en", "$ref": "#/components/schemas/LanguageCode" }, "refreshToken": { "type": "string", "description": "Customer refresh token for authentication", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "nullable": true, "writeOnly": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Date when the customer record was created", "example": "2023-01-15T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date when the customer record was last updated", "example": "2023-02-20T14:15:00Z", "nullable": true }, "emailVerifiedAt": { "format": "date-time", "type": "string", "description": "Date and time when the customer verified email", "example": "2023-01-02T00:00:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "isEmailVerified": { "type": "boolean", "description": "Indicates whether customer email is verified" }, "isPasswordSet": { "type": "boolean", "description": "Indicates whether customer password is set" } }, "required": [ "id", "externalId", "firstName", "lastName", "email", "phone", "password", "storeId", "language", "refreshToken", "createdAt", "updatedAt", "emailVerifiedAt", "deletedAt", "isEmailVerified", "isPasswordSet" ] }, "CheckoutOrderAppointmentProduct": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "productId": { "type": "string", "description": "ID of the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID)", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID)", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this product", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the product (unique per store)", "example": "haircut-basic" }, "scheduleId": { "type": "string", "description": "ID of the schedule associated with this product" }, "productPoolId": { "type": "string", "description": "ID of the product pool this product belongs to (controls overlap prevention)", "nullable": true }, "title": { "type": "string", "description": "Title of the product", "example": "Haircut Service" }, "variantTitle": { "type": "string", "description": "Title of the specific product variant", "example": "Short Hair" }, "description": { "type": "string", "description": "Detailed description of the product" }, "imageId": { "type": "string", "description": "ID of the product image" }, "color": { "type": "string", "description": "Color code for displaying the product", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "BLUE", "default": "slate" }, "price": { "type": "number", "description": "Price of the product", "example": 250 }, "taxable": { "type": "boolean", "description": "Whether the product is taxable", "default": false }, "duration": { "type": "number", "description": "Duration of the service in seconds", "example": 3600 }, "allowCustomDuration": { "type": "boolean", "description": "Whether customers can customize the duration by selecting multiples of the base service duration (e.g., if base duration is 1 day, customers can book 1, 2, 3+ days)", "default": false }, "maxDuration": { "type": "number", "description": "When allow_custom_duration=true, maximum duration allowed for multi-duration bookings in seconds (-1 for unlimited)", "default": -1 }, "maxAttendees": { "type": "number", "description": "Maximum number of attendees allowed", "default": 1 }, "maxGuests": { "type": "number", "description": "Maximum number of guests allowed per appointment. Null means unlimited.", "nullable": true }, "allowGuests": { "type": "boolean", "description": "Whether customers can invite guests to the appointment", "default": false }, "allowCustomerReschedule": { "type": "boolean", "description": "Whether customers can reschedule their bookings", "default": false }, "allowCustomerCancel": { "type": "boolean", "description": "Whether customers can cancel their bookings", "default": false }, "rescheduleGap": { "type": "number", "description": "Time in seconds before appointment when rescheduling is no longer allowed" }, "cancelGap": { "type": "number", "description": "Time in seconds before appointment when cancellation is no longer allowed" }, "beforeGap": { "type": "number", "description": "Buffer time in seconds required before this service" }, "afterGap": { "type": "number", "description": "Buffer time in seconds required after this service" }, "fixedTimes": { "type": "boolean", "description": "When allow_custom_duration=true, whether appointments must start and end at fixed times (like fixed check-in/check-out times for multi-duration bookings)", "default": false }, "fixedStartTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must start (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "09:00:00" }, "fixedEndTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must end (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "17:00:00" }, "advanceScheduleThreshold": { "type": "number", "description": "How many days in advance bookings can be made", "default": 0 }, "sendConfirmationEmail": { "type": "boolean", "description": "Whether to send confirmation emails for bookings", "default": true }, "sendReminderEmail": { "type": "boolean", "description": "Whether to send reminder emails before appointments", "default": false }, "sendFeedbackEmail": { "type": "boolean", "description": "Whether to send feedback request emails after appointments", "default": false }, "skipCheckout": { "type": "boolean", "description": "Whether to skip the checkout process for this product (Shopify merchants only)", "default": false }, "status": { "type": "string", "description": "Current status of the product", "enum": [ "active", "inactive" ], "example": "ACTIVE", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the product was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the product was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the product was deleted (for soft deletes)" }, "image": { "description": "Primary image of the product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "productId", "externalId", "externalVariantId", "storeId", "slug", "scheduleId", "productPoolId", "title", "variantTitle", "description", "imageId", "color", "price", "taxable", "duration", "allowCustomDuration", "maxDuration", "maxAttendees", "maxGuests", "allowGuests", "allowCustomerReschedule", "allowCustomerCancel", "rescheduleGap", "cancelGap", "beforeGap", "afterGap", "fixedTimes", "fixedStartTime", "fixedEndTime", "advanceScheduleThreshold", "sendConfirmationEmail", "sendReminderEmail", "sendFeedbackEmail", "skipCheckout", "status", "createdAt", "updatedAt", "deletedAt" ] }, "CheckoutOrderAppointmentStaffMember": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this staff member record", "example": "123e4567-e89b-12d3-a456-426614174111" }, "userId": { "type": "string", "description": "User ID of the staff member login identity (nullable until linked)", "example": "user-uuid" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this staff member, defines their availability", "example": "123e4567-e89b-12d3-a456-426614174000" }, "imageId": { "type": "string", "description": "ID of the image associated with this staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "firstName": { "type": "string", "description": "First name of the staff member", "example": "John" }, "lastName": { "type": "string", "description": "Last name of the staff member", "example": "Doe" }, "email": { "type": "string", "description": "Email address of the staff member, used for notifications and calendar integration", "example": "john.doe@example.com" }, "slug": { "type": "string", "description": "URL-friendly slug for the staff member (unique per store)", "example": "mike" }, "refreshToken": { "type": "string", "description": "Refresh token for integrations like Google Calendar", "example": "abc123xyz456" }, "createdAt": { "type": "string", "description": "Date and time when the staff member was created", "example": "2025-05-01T12:00:00Z" }, "updatedAt": { "type": "string", "description": "Date and time when the staff member was last updated", "example": "2025-05-15T14:30:00Z" }, "deletedAt": { "type": "string", "description": "Date and time when the staff member was soft deleted", "example": "2025-06-01T09:15:00Z" }, "image": { "description": "Profile image of the staff member", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "storeId", "userId", "scheduleId", "imageId", "firstName", "lastName", "email", "slug", "refreshToken", "createdAt", "updatedAt", "deletedAt" ] }, "CheckoutOrderAppointmentLocation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the location", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this location", "example": "123e4567-e89b-12d3-a456-426614174001" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this location (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "title": { "type": "string", "description": "Name of the location", "example": "Main Office", "nullable": true }, "description": { "type": "string", "description": "Description of the location", "example": "Our main downtown office location with 3 treatment rooms", "nullable": true }, "slug": { "type": "string", "description": "URL-friendly slug for the location (unique per store)", "example": "new-york" }, "type": { "type": "string", "description": "Type of location", "enum": [ "physical", "online", "delivery" ], "example": "physical" }, "link": { "type": "string", "description": "URL link for online locations", "example": "https://zoom.us/j/123456789", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of address for physical locations", "example": "123 Main Street", "nullable": true }, "addressLine2": { "type": "string", "description": "Second line of address for physical locations", "example": "Suite 200", "nullable": true }, "city": { "type": "string", "description": "City for physical locations", "example": "San Francisco", "nullable": true }, "state": { "type": "string", "description": "State/province for physical locations", "example": "CA", "nullable": true }, "postalCode": { "type": "string", "description": "Postal code for physical locations", "example": "94105", "nullable": true }, "country": { "type": "string", "description": "Country for physical locations", "example": "United States", "nullable": true }, "displayAddress": { "type": "string", "description": "Merchant-defined display address that overrides the auto-formatted address (emails, booking page). Null falls back to the concatenated address fields.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressPlaceId": { "type": "string", "description": "Google Place ID for the physical address", "example": "ChIJIQBpAG2ahYAR_6128GcTUEo", "nullable": true }, "latitude": { "type": "number", "description": "Latitude in WGS84", "example": 37.4224764, "nullable": true }, "longitude": { "type": "number", "description": "Longitude in WGS84", "example": -122.0842499, "nullable": true }, "createdAt": { "type": "string", "description": "Date when the location was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the location was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "type": "string", "description": "Date when the location was deleted (for soft deletes)", "example": "2023-03-10T11:45:00Z", "nullable": true }, "address": { "type": "string", "description": "The formatted address string", "nullable": true } }, "required": [ "id", "storeId", "scheduleId", "title", "description", "slug", "type", "link", "addressLine1", "addressLine2", "city", "state", "postalCode", "country", "addressPlaceId", "latitude", "longitude", "createdAt", "updatedAt", "deletedAt", "address" ] }, "CheckoutOrderAppointmentAddOnItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the add-on", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID) for synced add-ons", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID) for synced add-ons", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this add-on", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the add-on (unique per store)", "example": "child-seat" }, "title": { "type": "string", "description": "Title of the add-on", "example": "Child Seat" }, "description": { "type": "string", "description": "Detailed description of the add-on" }, "imageId": { "type": "string", "description": "ID of the primary image for the add-on" }, "color": { "type": "string", "description": "Color code used when displaying the add-on", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "slate", "default": "slate" }, "price": { "type": "number", "description": "Unit price of the add-on", "example": 15 }, "taxable": { "type": "boolean", "description": "Whether the add-on is taxable", "default": true }, "durationMultiplied": { "type": "boolean", "description": "When true, the add-on is charged per base-duration unit of the parent appointment. Quantity on the cart/order line item mirrors the parent CartItem.quantity (i.e., the booked duration units). Only meaningful for attached products with allowCustomDuration=true.", "default": false }, "maxQuantity": { "type": "number", "description": "Maximum quantity a customer can pick for this add-on. Only applies to fixed add-ons (durationMultiplied=false). Null means unlimited.", "example": 4, "minimum": 1, "nullable": true }, "status": { "type": "string", "description": "Current status of the add-on", "enum": [ "active", "inactive" ], "example": "active", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the add-on was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the add-on was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the add-on was soft-deleted" }, "image": { "description": "Primary image of the add-on", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "externalId", "externalVariantId", "storeId", "slug", "title", "description", "imageId", "color", "price", "taxable", "durationMultiplied", "maxQuantity", "status", "createdAt", "updatedAt", "deletedAt" ] }, "CheckoutOrderAppointmentAddOn": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier" }, "appointmentId": { "type": "string", "description": "Appointment ID" }, "addOnId": { "type": "string", "description": "Add-on ID" }, "quantity": { "type": "number", "description": "Quantity of this add-on for the appointment", "default": 1 }, "createdAt": { "format": "date-time", "type": "string", "description": "Created at timestamp" }, "addOn": { "description": "The add-on details", "allOf": [ { "$ref": "#/components/schemas/CheckoutOrderAppointmentAddOnItem" } ] } }, "required": [ "id", "appointmentId", "addOnId", "quantity", "createdAt" ] }, "CheckoutOrderAppointment": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the appointment", "example": "123e4567-e89b-12d3-a456-426614174000" }, "name": { "type": "string", "description": "Generated appointment name for the user (starts at 1001 and increments)", "example": "1001" }, "productId": { "type": "string", "description": "ID of the service/product for this appointment", "example": "123e4567-e89b-12d3-a456-426614174001" }, "staffMemberId": { "type": "string", "description": "ID of the staff member assigned to this appointment (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "locationId": { "type": "string", "description": "ID of the location where the appointment will take place (if any)", "example": "123e4567-e89b-12d3-a456-426614174003", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this appointment", "example": "123e4567-e89b-12d3-a456-426614174004" }, "customerId": { "type": "string", "description": "ID of the customer who booked the appointment", "example": "123e4567-e89b-12d3-a456-426614174005", "nullable": true }, "externalOrderId": { "type": "string", "description": "External order ID from user's platform (if any)", "example": "12345678", "nullable": true }, "externalOrderName": { "type": "string", "description": "External order name/reference from user's platform", "example": "#1001", "nullable": true }, "from": { "format": "date-time", "type": "string", "description": "Start date and time of the appointment (UTC timezone)", "example": "2023-06-15T09:00:00Z" }, "to": { "format": "date-time", "type": "string", "description": "End date and time of the appointment (UTC timezone)", "example": "2023-06-15T10:00:00Z" }, "displayAddress": { "type": "string", "description": "Merchant-defined display address from the location; overrides the concatenated address fields in notifications. Null falls back to the structured address.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressId": { "type": "string", "description": "ID of the linked service/delivery address", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of the appointment address", "nullable": true, "deprecated": true }, "addressLine2": { "type": "string", "description": "Second line of the appointment address", "nullable": true, "deprecated": true }, "city": { "type": "string", "description": "City of the appointment location", "nullable": true, "deprecated": true }, "state": { "type": "string", "description": "State/province of the appointment location", "nullable": true, "deprecated": true }, "postalCode": { "type": "string", "description": "Postal/zip code of the appointment location", "nullable": true, "deprecated": true }, "country": { "type": "string", "description": "Country of the appointment location", "nullable": true, "deprecated": true }, "status": { "example": "scheduled", "$ref": "#/components/schemas/AppointmentStatusType" }, "internalNote": { "type": "string", "description": "Internal notes about the appointment (not visible to customers)", "example": "Customer requested extra attention for specific needs", "nullable": true }, "createdBy": { "example": "customer", "$ref": "#/components/schemas/AppointmentCreatedByEnum" }, "reminderSentAt": { "format": "date-time", "type": "string", "description": "Date and time when reminder was sent to the customer", "example": "2023-06-14T09:00:00Z", "nullable": true }, "numberOfAttendees": { "type": "number", "description": "Number of people attending the appointment", "example": 1, "default": 1 }, "customAttributes": { "type": "object", "description": "Custom key-value attributes (strings) attached to the appointment. Max 250 entries.", "additionalProperties": { "type": "string" }, "nullable": true, "example": { "source": "widget", "party_size": "4" } }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the appointment was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "deliveryAddress": { "description": "Linked service/delivery address (DELIVERY locations)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DeliveryAddress" } ] }, "product": { "description": "Service/product details for this appointment", "allOf": [ { "$ref": "#/components/schemas/CheckoutOrderAppointmentProduct" } ] }, "staffMember": { "description": "Staff member assigned to this appointment", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CheckoutOrderAppointmentStaffMember" } ] }, "location": { "description": "Location where the appointment will take place", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CheckoutOrderAppointmentLocation" } ] }, "addOns": { "description": "Add-ons attached to this appointment", "type": "array", "items": { "$ref": "#/components/schemas/CheckoutOrderAppointmentAddOn" } } }, "required": [ "id", "name", "productId", "staffMemberId", "locationId", "storeId", "customerId", "externalOrderId", "externalOrderName", "from", "to", "displayAddress", "status", "internalNote", "createdBy", "reminderSentAt", "numberOfAttendees", "createdAt", "updatedAt", "deletedAt" ] }, "CheckoutOrderAddOn": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the add-on", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID) for synced add-ons", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID) for synced add-ons", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this add-on", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the add-on (unique per store)", "example": "child-seat" }, "title": { "type": "string", "description": "Title of the add-on", "example": "Child Seat" }, "description": { "type": "string", "description": "Detailed description of the add-on" }, "imageId": { "type": "string", "description": "ID of the primary image for the add-on" }, "color": { "type": "string", "description": "Color code used when displaying the add-on", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "slate", "default": "slate" }, "price": { "type": "number", "description": "Unit price of the add-on", "example": 15 }, "taxable": { "type": "boolean", "description": "Whether the add-on is taxable", "default": true }, "durationMultiplied": { "type": "boolean", "description": "When true, the add-on is charged per base-duration unit of the parent appointment. Quantity on the cart/order line item mirrors the parent CartItem.quantity (i.e., the booked duration units). Only meaningful for attached products with allowCustomDuration=true.", "default": false }, "maxQuantity": { "type": "number", "description": "Maximum quantity a customer can pick for this add-on. Only applies to fixed add-ons (durationMultiplied=false). Null means unlimited.", "example": 4, "minimum": 1, "nullable": true }, "status": { "type": "string", "description": "Current status of the add-on", "enum": [ "active", "inactive" ], "example": "active", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the add-on was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the add-on was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the add-on was soft-deleted" }, "image": { "description": "Primary image of the add-on", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "externalId", "externalVariantId", "storeId", "slug", "title", "description", "imageId", "color", "price", "taxable", "durationMultiplied", "maxQuantity", "status", "createdAt", "updatedAt", "deletedAt" ] }, "CheckoutOrderAddOnRefundLineItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the refund add-on line item" }, "refundId": { "type": "string", "description": "ID of the refund this line item belongs to" }, "externalId": { "type": "string", "description": "External refund line item ID from the platform (e.g., Shopify)", "nullable": true }, "addOnLineItemId": { "type": "string", "description": "ID of the original order add-on line item being refunded" }, "quantity": { "type": "number", "description": "Quantity of the add-on line item being refunded", "minimum": 1 }, "createdAt": { "format": "date-time", "type": "string", "description": "Created at" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Updated at", "nullable": true } }, "required": [ "id", "refundId", "externalId", "addOnLineItemId", "quantity", "createdAt", "updatedAt" ] }, "CheckoutOrderAddOnLineItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the order add-on line item" }, "orderId": { "type": "string", "description": "ID of the order" }, "lineItemId": { "type": "string", "description": "ID of the parent order line item (the appointment) this add-on belongs to" }, "addOnId": { "type": "string", "description": "ID of the add-on" }, "externalId": { "type": "string", "description": "External line item ID from the platform (e.g., Shopify) for this add-on", "nullable": true }, "originalUnitPrice": { "type": "number", "description": "Original unit price" }, "discountedUnitPrice": { "type": "number", "description": "Discounted price per unit (approximate — use the line totals for exact amounts)" }, "unitTaxAmount": { "type": "number", "description": "Tax amount per unit (approximate — use the line totals for exact amounts)" }, "quantity": { "type": "number", "description": "Quantity. For fixed add-ons this is the customer-picked count; for duration-multiplied add-ons it is the number of base-duration units of the parent appointment, snapshotted at cart → order conversion." }, "createdAt": { "format": "date-time", "type": "string", "description": "Created at" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Updated at", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Deleted at", "nullable": true }, "originalSubtotal": { "type": "number", "description": "Original subtotal of this add-on across all quantities, before discount" }, "totalDiscount": { "type": "number", "description": "Total discount applied to this add-on, across all quantities (approximate)" }, "discountedSubtotal": { "type": "number", "description": "Discounted subtotal of this add-on (original subtotal − total discount), before tax" }, "discountedTotal": { "type": "number", "description": "Discounted total of this add-on line item, including tax when not already in the price" }, "totalTax": { "type": "number", "description": "Total tax for this add-on line item (approximate)" }, "refundedQuantity": { "type": "number", "description": "Quantity already refunded" }, "refundableQuantity": { "type": "number", "description": "Remaining refundable quantity" }, "addOn": { "description": "The add-on details", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CheckoutOrderAddOn" } ] }, "refundLineItems": { "description": "Refund line items for this add-on", "type": "array", "items": { "$ref": "#/components/schemas/CheckoutOrderAddOnRefundLineItem" } } }, "required": [ "id", "orderId", "lineItemId", "addOnId", "externalId", "originalUnitPrice", "discountedUnitPrice", "unitTaxAmount", "quantity", "createdAt", "updatedAt", "deletedAt", "originalSubtotal", "totalDiscount", "discountedSubtotal", "discountedTotal", "totalTax", "refundedQuantity", "refundableQuantity" ] }, "CheckoutOrderLineItemRefundLineItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the refund line item", "example": "550e8400-e29b-41d4-a716-446655440000" }, "refundId": { "type": "string", "description": "ID of the refund this line item belongs to", "example": "550e8400-e29b-41d4-a716-446655440000" }, "externalId": { "type": "string", "description": "External refund line item ID from the platform (e.g., Shopify)", "example": "123456789", "nullable": true }, "lineItemId": { "type": "string", "description": "ID of the original order line item being refunded", "example": "550e8400-e29b-41d4-a716-446655440000" }, "quantity": { "type": "number", "description": "Quantity of the line item being refunded", "example": 2, "minimum": 1 }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the refund line item was created", "example": "2023-06-10T15:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the refund line item was last updated", "example": "2023-06-10T16:15:00Z", "nullable": true } }, "required": [ "id", "refundId", "externalId", "lineItemId", "quantity", "createdAt", "updatedAt" ] }, "CheckoutOrderLineItem": { "type": "object", "properties": { "orderId": { "type": "string", "description": "ID of the order", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "appointmentId": { "type": "string", "description": "ID of the appointment associated with line item", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "externalId": { "type": "string", "description": "External order line item ID from user's platform (if any)", "example": "12345678", "nullable": true }, "originalUnitPrice": { "type": "number", "description": "Original price of the item", "example": 249.99 }, "discountedUnitPrice": { "type": "number", "description": "Discounted price per unit (approximate — use the line totals for exact amounts)", "example": 249.99 }, "unitTaxAmount": { "type": "number", "description": "Tax amount per unit (approximate — use the line totals for exact amounts)", "example": 0 }, "quantity": { "type": "number", "description": "Quantity of the item ordered", "example": 1 }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "addOnSubtotal": { "type": "number", "description": "Discounted subtotal of the add-ons attached to this line item, before tax" }, "addOnTotalTax": { "type": "number", "description": "Total tax of the add-ons attached to this line item (approximate)" }, "originalSubtotal": { "type": "number", "description": "Original subtotal of the base line across all quantities, before discount", "example": 249.99 }, "totalDiscount": { "type": "number", "description": "Exact total discount applied to the base line, across all quantities", "example": 0 }, "discountedSubtotal": { "type": "number", "description": "Discounted subtotal of the base line (original subtotal − total discount), before tax", "example": 249.99 }, "discountedTotal": { "type": "number", "description": "Discounted total of the base line, including tax when not already in the price", "example": 249.99 }, "totalTax": { "type": "number", "description": "Total tax of the base line across all quantities (approximate)", "example": 0 }, "refundedQuantity": { "type": "number", "description": "The quantity of the line item that has been refunded", "example": 249.99 }, "refundableQuantity": { "type": "number", "description": "The quantity of the line item that can be refunded", "example": 249.99 }, "appointment": { "description": "The appointment this line item is for", "allOf": [ { "$ref": "#/components/schemas/CheckoutOrderAppointment" } ] }, "addOnLineItems": { "description": "Add-on line items attached to this line item", "type": "array", "items": { "$ref": "#/components/schemas/CheckoutOrderAddOnLineItem" } }, "refundLineItems": { "description": "Refund line items associated with this line item", "type": "array", "items": { "$ref": "#/components/schemas/CheckoutOrderLineItemRefundLineItem" } } }, "required": [ "orderId", "appointmentId", "externalId", "originalUnitPrice", "discountedUnitPrice", "unitTaxAmount", "quantity", "createdAt", "updatedAt", "deletedAt", "addOnSubtotal", "addOnTotalTax", "originalSubtotal", "totalDiscount", "discountedSubtotal", "discountedTotal", "totalTax", "refundedQuantity", "refundableQuantity" ] }, "CheckoutOrderParentTransaction": { "type": "object", "properties": { "orderId": { "type": "string", "description": "ID of the order", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "externalId": { "type": "string", "description": "External order transaction ID from user's platform (if any)", "example": "12345678", "nullable": true }, "parentId": { "type": "string", "description": "The parent transaction ID", "example": "12345678", "nullable": true }, "refundId": { "type": "string", "description": "The refund ID this transaction belongs to (if any)", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "type": { "type": "string", "description": "The type of transaction", "example": "sale", "enum": [ "authorization", "capture", "void", "sale", "refund" ] }, "amount": { "type": "number", "description": "Amount of the transaction", "example": 249.99 }, "currencyCode": { "type": "string", "description": "The currency code", "example": "USD" }, "gateway": { "type": "string", "description": "The payment gateway", "example": "shopify", "enum": [ "shopify", "cash", "bank_transfer", "stripe" ], "deprecated": true }, "provider": { "type": "string", "description": "The payment provider (replaces gateway)", "example": "stripe", "enum": [ "stripe", "cash", "bank_transfer", "shopify", "no_payment_required" ] }, "status": { "type": "string", "description": "The status of the transaction", "example": "success", "enum": [ "pending", "success", "failed" ] }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "refundableAmount": { "type": "number", "description": "The refundable amount for this transaction", "example": 249.99 }, "refundedAmount": { "type": "number", "description": "The refunded amount for this transaction", "example": 249.99 }, "isRefundable": { "type": "boolean", "description": "Whether this transaction is refundable", "example": true } }, "required": [ "orderId", "externalId", "parentId", "refundId", "type", "amount", "currencyCode", "gateway", "provider", "status", "createdAt", "updatedAt", "deletedAt", "refundableAmount", "refundedAmount", "isRefundable" ] }, "CheckoutOrderChildTransaction": { "type": "object", "properties": { "orderId": { "type": "string", "description": "ID of the order", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "externalId": { "type": "string", "description": "External order transaction ID from user's platform (if any)", "example": "12345678", "nullable": true }, "parentId": { "type": "string", "description": "The parent transaction ID", "example": "12345678", "nullable": true }, "refundId": { "type": "string", "description": "The refund ID this transaction belongs to (if any)", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "type": { "type": "string", "description": "The type of transaction", "example": "sale", "enum": [ "authorization", "capture", "void", "sale", "refund" ] }, "amount": { "type": "number", "description": "Amount of the transaction", "example": 249.99 }, "currencyCode": { "type": "string", "description": "The currency code", "example": "USD" }, "gateway": { "type": "string", "description": "The payment gateway", "example": "shopify", "enum": [ "shopify", "cash", "bank_transfer", "stripe" ], "deprecated": true }, "provider": { "type": "string", "description": "The payment provider (replaces gateway)", "example": "stripe", "enum": [ "stripe", "cash", "bank_transfer", "shopify", "no_payment_required" ] }, "status": { "type": "string", "description": "The status of the transaction", "example": "success", "enum": [ "pending", "success", "failed" ] }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "refundableAmount": { "type": "number", "description": "The refundable amount for this transaction", "example": 249.99 }, "refundedAmount": { "type": "number", "description": "The refunded amount for this transaction", "example": 249.99 }, "isRefundable": { "type": "boolean", "description": "Whether this transaction is refundable", "example": true } }, "required": [ "orderId", "externalId", "parentId", "refundId", "type", "amount", "currencyCode", "gateway", "provider", "status", "createdAt", "updatedAt", "deletedAt", "refundableAmount", "refundedAmount", "isRefundable" ] }, "CheckoutOrderTransactionRefundTransaction": { "type": "object", "properties": { "orderId": { "type": "string", "description": "ID of the order", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "externalId": { "type": "string", "description": "External order transaction ID from user's platform (if any)", "example": "12345678", "nullable": true }, "parentId": { "type": "string", "description": "The parent transaction ID", "example": "12345678", "nullable": true }, "refundId": { "type": "string", "description": "The refund ID this transaction belongs to (if any)", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "type": { "type": "string", "description": "The type of transaction", "example": "sale", "enum": [ "authorization", "capture", "void", "sale", "refund" ] }, "amount": { "type": "number", "description": "Amount of the transaction", "example": 249.99 }, "currencyCode": { "type": "string", "description": "The currency code", "example": "USD" }, "gateway": { "type": "string", "description": "The payment gateway", "example": "shopify", "enum": [ "shopify", "cash", "bank_transfer", "stripe" ], "deprecated": true }, "provider": { "type": "string", "description": "The payment provider (replaces gateway)", "example": "stripe", "enum": [ "stripe", "cash", "bank_transfer", "shopify", "no_payment_required" ] }, "status": { "type": "string", "description": "The status of the transaction", "example": "success", "enum": [ "pending", "success", "failed" ] }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "refundableAmount": { "type": "number", "description": "The refundable amount for this transaction", "example": 249.99 }, "refundedAmount": { "type": "number", "description": "The refunded amount for this transaction", "example": 249.99 }, "isRefundable": { "type": "boolean", "description": "Whether this transaction is refundable", "example": true } }, "required": [ "orderId", "externalId", "parentId", "refundId", "type", "amount", "currencyCode", "gateway", "provider", "status", "createdAt", "updatedAt", "deletedAt", "refundableAmount", "refundedAmount", "isRefundable" ] }, "CheckoutOrderTransactionRefund": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the order refund", "example": "550e8400-e29b-41d4-a716-446655440000" }, "orderId": { "type": "string", "description": "ID of the order being refunded", "example": "550e8400-e29b-41d4-a716-446655440000" }, "externalId": { "type": "string", "description": "External refund ID from the platform (e.g., Shopify)", "example": "123456789", "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the refund was created", "example": "2023-06-10T15:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the refund was last updated", "example": "2023-06-10T16:15:00Z", "nullable": true }, "total": { "type": "number", "description": "The total amount of the refund", "example": 100 }, "transactions": { "description": "Transactions associated with this refund", "type": "array", "items": { "$ref": "#/components/schemas/CheckoutOrderTransactionRefundTransaction" } } }, "required": [ "id", "orderId", "externalId", "createdAt", "updatedAt", "total" ] }, "CheckoutOrderTransaction": { "type": "object", "properties": { "orderId": { "type": "string", "description": "ID of the order", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "externalId": { "type": "string", "description": "External order transaction ID from user's platform (if any)", "example": "12345678", "nullable": true }, "parentId": { "type": "string", "description": "The parent transaction ID", "example": "12345678", "nullable": true }, "refundId": { "type": "string", "description": "The refund ID this transaction belongs to (if any)", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "type": { "type": "string", "description": "The type of transaction", "example": "sale", "enum": [ "authorization", "capture", "void", "sale", "refund" ] }, "amount": { "type": "number", "description": "Amount of the transaction", "example": 249.99 }, "currencyCode": { "type": "string", "description": "The currency code", "example": "USD" }, "gateway": { "type": "string", "description": "The payment gateway", "example": "shopify", "enum": [ "shopify", "cash", "bank_transfer", "stripe" ], "deprecated": true }, "provider": { "type": "string", "description": "The payment provider (replaces gateway)", "example": "stripe", "enum": [ "stripe", "cash", "bank_transfer", "shopify", "no_payment_required" ] }, "status": { "type": "string", "description": "The status of the transaction", "example": "success", "enum": [ "pending", "success", "failed" ] }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the transaction was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "refundableAmount": { "type": "number", "description": "The refundable amount for this transaction", "example": 249.99 }, "refundedAmount": { "type": "number", "description": "The refunded amount for this transaction", "example": 249.99 }, "isRefundable": { "type": "boolean", "description": "Whether this transaction is refundable", "example": true }, "parentTransaction": { "description": "The parent transaction", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CheckoutOrderParentTransaction" } ] }, "childTransactions": { "description": "The child transactions", "type": "array", "items": { "$ref": "#/components/schemas/CheckoutOrderChildTransaction" } }, "refund": { "description": "The refund this transaction belongs to", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CheckoutOrderTransactionRefund" } ] } }, "required": [ "orderId", "externalId", "parentId", "refundId", "type", "amount", "currencyCode", "gateway", "provider", "status", "createdAt", "updatedAt", "deletedAt", "refundableAmount", "refundedAmount", "isRefundable" ] }, "CheckoutOrderLog": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the order log entry", "example": "123e4567-e89b-12d3-a456-426614174000" }, "orderId": { "type": "string", "description": "ID of the order this log entry relates to", "example": "123e4567-e89b-12d3-a456-426614174001" }, "title": { "type": "string", "description": "Title or summary of the log entry", "example": "Order rescheduled" }, "description": { "type": "string", "description": "Detailed description or additional information about the log entry", "example": "Customer requested to reschedule from June 15 to June 20", "nullable": true }, "level": { "example": "info", "$ref": "#/components/schemas/OrderLogLevel" }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when this log entry was created", "example": "2023-06-10T15:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when this log entry was last updated", "example": "2023-06-10T16:15:00Z", "nullable": true } }, "required": [ "id", "orderId", "title", "description", "level", "createdAt", "updatedAt" ] }, "CheckoutOrder": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the order" }, "paymentCurrencyCode": { "type": "string", "description": "The currency used by the customer when placing the order.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "taxesIncluded": { "type": "boolean", "description": "Whether the taxes are included in the order subtotal.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External order ID from user's platform (if any)", "example": "shop123_order_456", "nullable": true }, "externalName": { "type": "string", "description": "External order name/reference from user's platform", "example": "#1001", "nullable": true }, "name": { "type": "string", "description": "Generated order name for the user (starts at 1001 and increments)", "example": "1001" }, "customerId": { "type": "string", "description": "ID of the customer who placed the order", "example": "123e4567-e89b-12d3-a456-426614174000", "nullable": true }, "customerFirstName": { "type": "string", "description": "Snapshot of the customer first name captured when the order was placed", "nullable": true }, "customerLastName": { "type": "string", "description": "Snapshot of the customer last name captured when the order was placed", "nullable": true }, "customerEmail": { "type": "string", "description": "Snapshot of the customer email captured when the order was placed", "nullable": true }, "customerPhone": { "type": "string", "description": "Snapshot of the customer phone captured when the order was placed", "nullable": true }, "billingAddressId": { "type": "string", "description": "ID of the linked billing address", "nullable": true }, "deliveryAddressId": { "type": "string", "description": "ID of the linked order-level delivery address", "nullable": true }, "billingFirstName": { "type": "string", "description": "Billing bill-to first name", "nullable": true, "deprecated": true }, "billingLastName": { "type": "string", "description": "Billing bill-to last name", "nullable": true, "deprecated": true }, "billingCompanyName": { "type": "string", "description": "Billing company name", "nullable": true, "deprecated": true }, "billingTaxRegistrationId": { "type": "string", "description": "Billing tax registration id (VAT / GST / …)", "nullable": true, "deprecated": true }, "billingAddressLine1": { "type": "string", "description": "Billing address line 1", "nullable": true, "deprecated": true }, "billingAddressLine2": { "type": "string", "description": "Billing address line 2", "nullable": true, "deprecated": true }, "billingCity": { "type": "string", "description": "Billing city", "nullable": true, "deprecated": true }, "billingState": { "type": "string", "description": "Billing state/province", "nullable": true, "deprecated": true }, "billingPostalCode": { "type": "string", "description": "Billing postal/zip code", "nullable": true, "deprecated": true }, "billingCountry": { "type": "string", "description": "Billing country", "nullable": true, "deprecated": true }, "storeId": { "type": "string", "description": "ID of the store that owns the order", "example": "store-uuid", "nullable": true }, "cartId": { "type": "string", "description": "ID of the cart from which the order was created", "example": "123e4567-e89b-12d3-a456-426614174000", "nullable": true }, "gclid": { "type": "string", "description": "Google Ads click ID captured at the time of booking", "example": "EAIaIQobChMI...", "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was created", "example": "2023-06-01T10:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was last updated", "example": "2023-06-02T14:15:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the order was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "billingAddress": { "description": "Linked billing address", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CustomerAddress" } ] }, "deliveryAddress": { "description": "Linked order-level delivery address", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DeliveryAddress" } ] }, "subtotal": { "type": "number", "description": "Subtotal amount of the order, excluding canceled appointments", "example": 249.99 }, "total": { "type": "number", "description": "Total amount of the order, including canceled appointments and taxes", "example": 249.99 }, "totalTax": { "type": "number", "description": "Total tax amount of the order, excluding canceled appointments", "example": 249.99 }, "dueToPay": { "type": "number", "description": "Total amount still due to be paid for the order. Derived from the current total (which excludes canceled appointments and reflects current add-ons and discounts) minus the net amount already held (paid minus refunded). Never negative — when the customer has overpaid the current total, the surplus surfaces via dueToRefund instead.", "example": 249.99 }, "paidTotal": { "type": "number", "description": "Total amount paid for the order", "example": 249.99 }, "refundedTotal": { "type": "number", "description": "Total amount refunded for the order", "example": 249.99 }, "balance": { "type": "number", "description": "Balance of the order; based on paid and refunded amounts", "example": 249.99 }, "dueToRefund": { "type": "number", "description": "Total amount owed back to the customer. Derived from the net amount held (paid minus refunded) minus the current total. Any change that lowers the current total below what the customer has already paid — a canceled appointment, a removed or reduced add-on, or a discount that is restored on reevaluation — surfaces the surplus here. Never negative.", "example": 249.99 }, "isFullyPaid": { "type": "boolean", "description": "Whether the order is fully paid", "example": false }, "isFullyRefunded": { "type": "boolean", "description": "Whether everything the customer paid has been refunded (paid something, nothing held).", "example": false }, "paymentStatus": { "type": "string", "description": "Payment status of the order", "example": "paid", "enum": [ "unpaid", "paid", "partially-paid" ] }, "refundStatus": { "type": "string", "description": "Refund status of the order", "example": "partially-refunded", "enum": [ "refund-owed", "partially-refunded", "fully-refunded", "unrefunded" ] }, "fulfillmentStatus": { "type": "string", "description": "Fulfillment status of the order", "example": "partially-fulfilled", "enum": [ "partially-fulfilled", "fulfilled", "unfulfilled" ] }, "customer": { "description": "Customer who placed the order", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CheckoutOrderCustomer" } ] }, "lineItems": { "description": "Line items in the order", "type": "array", "items": { "$ref": "#/components/schemas/CheckoutOrderLineItem" } }, "transactions": { "description": "Transactions associated with this order", "type": "array", "items": { "$ref": "#/components/schemas/CheckoutOrderTransaction" } }, "logs": { "description": "Order activity logs", "type": "array", "items": { "$ref": "#/components/schemas/CheckoutOrderLog" } } }, "required": [ "id", "paymentCurrencyCode", "taxesIncluded", "externalId", "externalName", "name", "customerId", "storeId", "cartId", "createdAt", "updatedAt", "deletedAt", "subtotal", "total", "totalTax", "dueToPay", "paidTotal", "refundedTotal", "balance", "dueToRefund", "isFullyPaid", "isFullyRefunded", "paymentStatus", "refundStatus", "fulfillmentStatus" ] }, "CheckoutResponse": { "type": "object", "properties": { "order": { "description": "Created order", "allOf": [ { "$ref": "#/components/schemas/CheckoutOrder" } ] }, "auth": { "description": "Authentication tokens (included for new or passwordless customers)", "allOf": [ { "$ref": "#/components/schemas/CheckoutAuthTokens" } ] }, "customer": { "description": "Customer information", "allOf": [ { "$ref": "#/components/schemas/CheckoutCustomerInfo" } ] } }, "required": [ "order" ] }, "CartCheckoutQuestionTranslation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the translation", "example": "550e8400-e29b-41d4-a716-446655440000" }, "questionId": { "type": "string", "description": "ID of the checkout question this translation belongs to", "example": "550e8400-e29b-41d4-a716-446655440000" }, "title": { "type": "string", "description": "Translated title of the question shown to customers", "example": "Do you have any allergies?" }, "description": { "type": "string", "description": "Translated description or additional instructions for the question", "example": "Please let us know about any food allergies or dietary restrictions." }, "options": { "description": "Available options for dropdown or checkbox questions in this language", "example": [ "Nut allergy", "Gluten intolerance", "Lactose intolerance", "None" ], "nullable": true, "type": "array", "items": { "type": "string" } }, "languageCode": { "type": "string", "description": "Language code for this translation", "enum": [ "af", "ak", "am", "ar", "as", "az", "be", "bg", "bm", "bn", "bo", "br", "bs", "ca", "ce", "cs", "cu", "cy", "da", "de", "dz", "ee", "el", "en", "eo", "es", "et", "eu", "fa", "ff", "fi", "fo", "fr", "fy", "ga", "gd", "gl", "gu", "gv", "ha", "he", "hi", "hr", "hu", "hy", "ia", "id", "ig", "ii", "is", "it", "ja", "jv", "ka", "ki", "kk", "kl", "km", "kn", "ko", "ks", "ku", "kw", "ky", "lb", "lg", "ln", "lo", "lt", "lu", "lv", "mg", "mi", "mk", "ml", "mn", "mr", "ms", "mt", "my", "nb", "nd", "ne", "nl", "nn", "no", "om", "or", "os", "pa", "pl", "ps", "pt", "pt_br", "pt_pt", "qu", "rm", "rn", "ro", "ru", "rw", "sd", "se", "sg", "si", "sk", "sl", "sn", "so", "sq", "sr", "su", "sv", "sw", "ta", "te", "tg", "th", "ti", "tk", "to", "tr", "tt", "ug", "uk", "ur", "uz", "vi", "vo", "wo", "xh", "yi", "yo", "zh", "zh_cn", "zh_tw", "zu" ], "example": "en" }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the translation was created", "example": "2023-01-01T00:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the translation was last updated", "example": "2023-01-15T00:00:00Z", "nullable": true } }, "required": [ "id", "questionId", "title", "description", "options", "languageCode", "createdAt", "updatedAt" ] }, "CartCheckoutQuestionResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the checkout question", "example": "550e8400-e29b-41d4-a716-446655440000" }, "internalName": { "type": "string", "description": "Internal name for the question (not shown to customers)", "example": "Customer Allergies Question" }, "required": { "type": "boolean", "description": "Whether the question is required to be answered", "example": true }, "type": { "type": "string", "description": "Type of input for the question", "enum": [ "single-line-text-field", "multi-line-text-field", "dropdown", "rating", "checkbox", "file-upload" ], "example": "single-line-text-field" }, "order": { "type": "number", "description": "Display order of the question (lower numbers appear first)", "example": 1, "default": 0 }, "alwaysShow": { "type": "boolean", "description": "Whether this question is shown for all products in the store", "example": false, "default": false }, "fileConfig": { "type": "object", "description": "File-upload constraints (allowed categories, max size, max files). Only set when type is file-upload.", "example": { "categories": [ "images", "pdf" ], "maxSizeBytes": 26214400, "maxFiles": 5 }, "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the question was created", "example": "2023-01-01T00:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the question was last updated", "example": "2023-01-15T00:00:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date when the question was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this question", "example": "store-uuid" }, "translations": { "description": "Translations of this question (filtered to the requested language)", "type": "array", "items": { "$ref": "#/components/schemas/CartCheckoutQuestionTranslation" } }, "existingAnswer": { "type": "string", "description": "The customer's previously-saved answer to this question, if any" } }, "required": [ "id", "internalName", "required", "type", "order", "alwaysShow", "createdAt", "updatedAt", "deletedAt", "storeId", "translations" ] }, "CheckoutCustomer": { "type": "object", "properties": { "customer": { "description": "Customer information to save and attach to the cart", "oneOf": [ { "$ref": "#/components/schemas/ExistingOrderCustomer" }, { "$ref": "#/components/schemas/NewOrderCustomer" } ] } }, "required": [ "customer" ] }, "SaveCustomerResponse": { "type": "object", "properties": { "customerId": { "type": "string", "description": "Created or resolved customer ID" } }, "required": [ "customerId" ] }, "CheckoutQuestionAnswers": { "type": "object", "properties": { "answers": { "description": "Array of question answers to save", "type": "array", "items": { "$ref": "#/components/schemas/CheckoutQuestionAnswer" } } }, "required": [ "answers" ] }, "ApplyCode": { "type": "object", "properties": { "code": { "type": "string", "description": "Promo code to apply", "maxLength": 64 } }, "required": [ "code" ] }, "DiscountCodeErrorResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable reason the code could not be applied", "example": "Discount code has expired" }, "code": { "type": "string", "description": "Machine-readable reason code", "enum": [ "CODE_NOT_FOUND", "CODE_EXPIRED", "CODE_DISABLED", "CODE_LIMIT_REACHED", "CODE_CUSTOMER_INELIGIBLE", "CODE_NO_MATCHING_ITEMS", "CODE_NO_CREDIT", "minimum_requirement_not_met" ], "example": "CODE_EXPIRED" }, "statusCode": { "type": "number", "description": "HTTP status code", "example": 400 } }, "required": [ "message", "code", "statusCode" ] }, "Setting": { "type": "object", "properties": { "id": { "type": "string", "description": "Primary identifier of the settings row", "example": "550e8400-e29b-41d4-a716-446655440000" }, "storeId": { "type": "string", "description": "The unique identifier of the store that owns these settings", "example": "store-123" }, "isEnabled": { "type": "boolean", "description": "Whether the user account is enabled", "example": true, "default": true }, "timezone": { "type": "string", "description": "The timezone used for scheduling and displaying times", "example": "UTC", "default": "UTC" }, "timeFormat": { "type": "string", "description": "The format used for displaying times (12-hour or 24-hour)", "enum": [ "12H", "24H" ], "default": "24H", "example": "24H" }, "dateFormat": { "type": "string", "description": "The format used for displaying dates", "example": "YYYY-MM-DD", "default": "YYYY-MM-DD" }, "reservationGap": { "type": "number", "description": "Blocks bookings for the given number of seconds; after this period, pending appointments are canceled", "example": 900, "nullable": true }, "sendAppointmentConfirmationEmail": { "type": "boolean", "description": "Whether to send confirmation emails for appointments", "example": true, "default": true }, "sendAppointmentReminderEmail": { "type": "boolean", "description": "Whether to send reminder emails for appointments", "example": false, "default": false }, "sendAppointmentReminderEmailTimeBefore": { "type": "number", "description": "How many seconds before an appointment to send a reminder email", "example": 3600, "default": 3600 }, "sendAppointmentFeedbackEmail": { "type": "boolean", "description": "Whether to send feedback emails after appointments", "example": false, "default": false }, "customerCalendarUrl": { "type": "string", "description": "URL for the customer's calendar page", "example": "https://calendar.example.com/customer", "nullable": true }, "storefrontBaseUrl": { "type": "string", "description": "Base URL for the customer-facing storefront. Used to construct email links.", "example": "https://my-store.opencals.com", "nullable": true }, "emailFromAddress": { "type": "string", "description": "Email address to use as \"from\" address in email communications", "example": "support@example.com", "nullable": true }, "sendMerchantNotifications": { "type": "boolean", "description": "Whether to send merchant (admin) notification emails for appointment activity", "example": false, "default": false }, "merchantNotificationEmail": { "type": "string", "description": "Email address that receives merchant (admin) appointment notifications", "example": "owner@example.com", "nullable": true }, "defaultScheduleGap": { "type": "string", "description": "Default time gap for scheduling", "enum": [ "every-10-minutes", "every-15-minutes", "every-20-minutes", "every-30-minutes", "every-60-minutes" ], "default": "every-15-minutes" }, "defaultAdvanceScheduleDays": { "type": "number", "description": "How many days in advance customers can schedule appointments. Use -1 for unlimited.", "example": 30, "default": 30, "maximum": 3650 }, "defaultSkipCheckout": { "type": "boolean", "description": "Whether to skip the checkout page by default (Shopify merchants only)", "example": false, "default": false }, "createdAt": { "format": "date-time", "type": "string", "description": "When the settings were created", "example": "2025-06-05T12:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "When the settings were last updated", "example": "2025-06-05T14:30:00Z", "nullable": true } }, "required": [ "id", "storeId", "isEnabled", "timezone", "timeFormat", "dateFormat", "reservationGap", "sendAppointmentConfirmationEmail", "sendAppointmentReminderEmail", "sendAppointmentReminderEmailTimeBefore", "sendAppointmentFeedbackEmail", "customerCalendarUrl", "storefrontBaseUrl", "emailFromAddress", "sendMerchantNotifications", "merchantNotificationEmail", "defaultScheduleGap", "defaultAdvanceScheduleDays", "defaultSkipCheckout", "createdAt", "updatedAt" ] }, "PlanFeature": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the plan feature", "example": "550e8400-e29b-41d4-a716-446655440000" }, "planId": { "type": "string", "description": "ID of the subscription plan this feature belongs to", "example": "550e8400-e29b-41d4-a716-446655440000" }, "feature": { "type": "string", "description": "Name of the feature", "enum": [ "number-of-products", "number-of-staff-members", "number-of-physical-locations", "staff-members-portal", "customer-portal", "group-appointments", "custom-product-duration", "cancellation", "rescheduling", "customer-cancellation", "customer-rescheduling", "custom-checkout-fields", "ui-customization", "email-customization", "customer-reviews", "white-label" ], "example": "staff-members-portal" }, "config": { "type": "object", "description": "Additional configuration for the feature", "example": "{ \"count\": 10 }", "nullable": true } }, "required": [ "id", "planId", "feature", "config" ] }, "StorefrontSetting": { "type": "object", "properties": { "id": { "type": "string", "description": "Primary identifier of the storefront settings row", "example": "550e8400-e29b-41d4-a716-446655440000" }, "storeId": { "type": "string", "description": "The unique identifier of the store that owns these storefront settings", "example": "store-123" }, "themeMode": { "type": "string", "description": "Theme mode (light or dark)", "enum": [ "light", "dark" ], "default": "light" }, "primaryColor": { "type": "string", "description": "Primary brand color in hexadecimal format", "example": "#171717", "default": "#171717" }, "primaryForegroundColor": { "type": "string", "description": "Primary foreground color in hexadecimal format", "example": "#FAFAFA", "default": "#FAFAFA" }, "secondaryColor": { "type": "string", "description": "Secondary brand color in hexadecimal format", "example": "#F5F5F5", "default": "#F5F5F5" }, "secondaryForegroundColor": { "type": "string", "description": "Secondary foreground color in hexadecimal format", "example": "#171717", "default": "#171717" }, "destructiveColor": { "type": "string", "description": "Destructive/error color in hexadecimal format", "example": "#E7000B", "default": "#E7000B" }, "accentColor": { "type": "string", "description": "Accent color in hexadecimal format", "example": "#F5F5F5", "default": "#F5F5F5" }, "accentForegroundColor": { "type": "string", "description": "Accent foreground color in hexadecimal format", "example": "#171717", "default": "#171717" }, "backgroundColor": { "type": "string", "description": "Background color in hexadecimal format", "example": "#FFFFFF", "default": "#FFFFFF" }, "foregroundColor": { "type": "string", "description": "Foreground/text color in hexadecimal format", "example": "#0A0A0A", "default": "#0A0A0A" }, "cardColor": { "type": "string", "description": "Card background color in hexadecimal format", "example": "#FFFFFF", "default": "#FFFFFF" }, "cardForegroundColor": { "type": "string", "description": "Card foreground color in hexadecimal format", "example": "#0A0A0A", "default": "#0A0A0A" }, "popoverColor": { "type": "string", "description": "Popover background color in hexadecimal format", "example": "#FFFFFF", "default": "#FFFFFF" }, "popoverForegroundColor": { "type": "string", "description": "Popover foreground color in hexadecimal format", "example": "#0A0A0A", "default": "#0A0A0A" }, "mutedColor": { "type": "string", "description": "Muted color in hexadecimal format", "example": "#F5F5F5", "default": "#F5F5F5" }, "mutedForegroundColor": { "type": "string", "description": "Muted foreground color in hexadecimal format", "example": "#737373", "default": "#737373" }, "borderColor": { "type": "string", "description": "Border color in hexadecimal format", "example": "#E5E5E5", "default": "#E5E5E5" }, "inputColor": { "type": "string", "description": "Input border color in hexadecimal format", "example": "#E5E5E5", "default": "#E5E5E5" }, "ringColor": { "type": "string", "description": "Focus ring color in hexadecimal format", "example": "#A1A1A1", "default": "#A1A1A1" }, "sidebarColor": { "type": "string", "description": "Sidebar background color in hexadecimal format", "example": "#FAFAFA", "default": "#FAFAFA" }, "sidebarForegroundColor": { "type": "string", "description": "Sidebar foreground color in hexadecimal format", "example": "#0A0A0A", "default": "#0A0A0A" }, "sidebarPrimaryColor": { "type": "string", "description": "Sidebar primary color in hexadecimal format", "example": "#171717", "default": "#171717" }, "sidebarPrimaryForegroundColor": { "type": "string", "description": "Sidebar primary foreground color in hexadecimal format", "example": "#FAFAFA", "default": "#FAFAFA" }, "sidebarAccentColor": { "type": "string", "description": "Sidebar accent color in hexadecimal format", "example": "#F5F5F5", "default": "#F5F5F5" }, "sidebarAccentForegroundColor": { "type": "string", "description": "Sidebar accent foreground color in hexadecimal format", "example": "#171717", "default": "#171717" }, "sidebarBorderColor": { "type": "string", "description": "Sidebar border color in hexadecimal format", "example": "#E5E5E5", "default": "#E5E5E5" }, "sidebarRingColor": { "type": "string", "description": "Sidebar ring color in hexadecimal format", "example": "#A1A1A1", "default": "#A1A1A1" }, "borderRadius": { "type": "number", "description": "Border radius in rem units", "example": 0.625, "default": 0.625 }, "sansSerifFont": { "type": "string", "description": "Sans-serif font family", "example": "Inter, system-ui, sans-serif", "nullable": true }, "serifFont": { "type": "string", "description": "Serif font family", "example": "Georgia, serif", "nullable": true }, "monospaceFont": { "type": "string", "description": "Monospace font family", "example": "JetBrains Mono, monospace", "nullable": true }, "letterSpacing": { "type": "number", "description": "Letter spacing in em units", "example": 0, "default": 0 }, "shadowColor": { "type": "string", "description": "Shadow color in hexadecimal format", "example": "#000000", "default": "#000000" }, "shadowOpacity": { "type": "number", "description": "Shadow opacity (0-1)", "example": 0.1, "default": 0.1 }, "shadowBlurRadius": { "type": "number", "description": "Shadow blur radius in pixels", "example": 3, "default": 3 }, "shadowSpread": { "type": "number", "description": "Shadow spread in pixels", "example": 0, "default": 0 }, "shadowOffsetX": { "type": "number", "description": "Shadow offset X in pixels", "example": 0, "default": 0 }, "shadowOffsetY": { "type": "number", "description": "Shadow offset Y in pixels", "example": 1, "default": 1 }, "dateFormat": { "type": "string", "description": "The format used for displaying dates", "example": "YYYY-MM-DD", "default": "YYYY-MM-DD" }, "timeFormat": { "type": "string", "description": "The format used for displaying times", "enum": [ "12H", "24H" ], "example": "24H", "default": "24H" }, "locales": { "description": "Active language codes enabled for the storefront", "example": [ "en", "pl", "de" ], "default": [ "en" ], "type": "array", "items": { "type": "string" } }, "defaultLocale": { "type": "string", "description": "Default language code for the storefront", "example": "en", "default": "en" }, "logoImageId": { "type": "string", "description": "ID of the logo image associated with the storefront", "example": "123e4567-e89b-12d3-a456-426614174001", "nullable": true }, "iconImageId": { "type": "string", "description": "ID of the icon image associated with the storefront", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "bannerImageId": { "type": "string", "description": "ID of the banner image associated with the storefront", "example": "123e4567-e89b-12d3-a456-426614174003", "nullable": true }, "passwordProtectionEnabled": { "type": "boolean", "description": "When the storefront settings were created", "default": false, "example": "2025-06-05T12:00:00Z" }, "password": { "type": "string", "description": "Password for accessing the storefront when protection is enabled", "nullable": true }, "updatedAt": { "format": "date-time", "type": "string", "description": "When the storefront settings were last updated", "example": "2025-06-05T14:30:00Z", "nullable": true }, "logoImage": { "description": "Logo image metadata", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] }, "iconImage": { "description": "Icon image metadata", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] }, "bannerImage": { "description": "Banner image metadata", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "storeId", "themeMode", "primaryColor", "primaryForegroundColor", "secondaryColor", "secondaryForegroundColor", "destructiveColor", "accentColor", "accentForegroundColor", "backgroundColor", "foregroundColor", "cardColor", "cardForegroundColor", "popoverColor", "popoverForegroundColor", "mutedColor", "mutedForegroundColor", "borderColor", "inputColor", "ringColor", "sidebarColor", "sidebarForegroundColor", "sidebarPrimaryColor", "sidebarPrimaryForegroundColor", "sidebarAccentColor", "sidebarAccentForegroundColor", "sidebarBorderColor", "sidebarRingColor", "borderRadius", "sansSerifFont", "serifFont", "monospaceFont", "letterSpacing", "shadowColor", "shadowOpacity", "shadowBlurRadius", "shadowSpread", "shadowOffsetX", "shadowOffsetY", "dateFormat", "timeFormat", "locales", "defaultLocale", "logoImageId", "iconImageId", "bannerImageId", "passwordProtectionEnabled", "password", "updatedAt" ] }, "StoreContactInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "Primary identifier of the contact info row" }, "storeId": { "type": "string", "description": "The unique identifier of the store that owns this contact info", "example": "store-uuid" }, "addressLine1": { "type": "string", "description": "First line of the business address", "example": "123 Main Street", "nullable": true }, "addressLine2": { "type": "string", "description": "Second line of the business address", "example": "Suite 100", "nullable": true }, "city": { "type": "string", "description": "City", "example": "New York", "nullable": true }, "state": { "type": "string", "description": "State or province", "example": "NY", "nullable": true }, "postalCode": { "type": "string", "description": "Postal code", "example": "10001", "nullable": true }, "country": { "type": "string", "description": "Country", "example": "United States", "nullable": true }, "addressPlaceId": { "type": "string", "description": "Google Place ID for the address", "example": "ChIJN1t_tDeuEmsRUsoyG83frY4", "nullable": true }, "latitude": { "type": "number", "description": "Latitude coordinate", "example": 40.7128, "nullable": true }, "longitude": { "type": "number", "description": "Longitude coordinate", "example": -74.006, "nullable": true }, "contactEmail": { "type": "string", "description": "Contact email address", "example": "contact@example.com", "nullable": true }, "contactPhoneNumbers": { "description": "Array of contact phone numbers", "example": [ "+1234567890", "+0987654321" ], "nullable": true, "type": "array", "items": { "type": "string" } }, "socialMediaLinks": { "description": "Array of social media links", "example": [ { "type": "instagram", "link": "https://instagram.com/username" }, { "type": "custom", "name": "My Website", "link": "https://example.com" } ], "nullable": true, "type": "array", "items": { "type": "object" } }, "createdAt": { "format": "date-time", "type": "string", "description": "When the contact info was created", "example": "2025-01-01T00:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "When the contact info was last updated", "example": "2025-01-02T00:00:00Z", "nullable": true } }, "required": [ "id", "storeId", "addressLine1", "addressLine2", "city", "state", "postalCode", "country", "addressPlaceId", "latitude", "longitude", "contactEmail", "contactPhoneNumbers", "socialMediaLinks", "createdAt", "updatedAt" ] }, "CheckoutSetting": { "type": "object", "properties": { "id": { "type": "string", "description": "Primary identifier of the checkout settings row" }, "storeId": { "type": "string", "description": "The unique identifier of the store that owns these checkout settings", "example": "store-uuid", "nullable": true }, "customerFirstNameRequired": { "type": "boolean", "description": "Whether the customer first name is required at checkout. The last name and email are always required.", "example": true, "default": true }, "customerPhoneRequirement": { "example": "optional", "$ref": "#/components/schemas/CheckoutFieldRequirement" }, "customerCompanyNameRequirement": { "example": "hidden", "$ref": "#/components/schemas/CheckoutFieldRequirement" }, "customerCompanyVatNumberRequirement": { "example": "hidden", "$ref": "#/components/schemas/CheckoutFieldRequirement" }, "customerBillingAddressRequirement": { "example": "hidden", "$ref": "#/components/schemas/CheckoutFieldRequirement" }, "emailMarketingOptIn": { "example": "checkout_and_account", "$ref": "#/components/schemas/MarketingOptInDisplay" }, "smsMarketingOptIn": { "example": "dont_show", "$ref": "#/components/schemas/MarketingOptInDisplay" }, "whatsappMarketingOptIn": { "example": "dont_show", "$ref": "#/components/schemas/MarketingOptInDisplay" }, "createdAt": { "format": "date-time", "type": "string", "description": "When the settings were created", "example": "2025-06-05T12:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "When the settings were last updated", "example": "2025-06-05T14:30:00Z", "nullable": true } }, "required": [ "id", "storeId", "customerFirstNameRequired", "customerPhoneRequirement", "customerCompanyNameRequirement", "customerCompanyVatNumberRequirement", "customerBillingAddressRequirement", "emailMarketingOptIn", "smsMarketingOptIn", "whatsappMarketingOptIn", "createdAt", "updatedAt" ] }, "StorePublicSettings": { "type": "object", "properties": { "name": { "type": "string", "description": "Store name", "example": "My Store" }, "domain": { "type": "string", "description": "Store domain", "example": "my-store.opencals.com", "nullable": false }, "externalDomain": { "type": "string", "description": "Store domain (e.g., Shopify domain)", "example": "my-store.myshopify.com", "nullable": false }, "currency": { "type": "string", "description": "Store currency", "example": "USD", "nullable": false }, "settings": { "description": "Store settings", "allOf": [ { "$ref": "#/components/schemas/Setting" } ] }, "platform": { "type": "object", "description": "Store platform (e.g., Shopify)", "example": "shopify", "nullable": true }, "features": { "description": "Store features", "type": "array", "items": { "$ref": "#/components/schemas/PlanFeature" } }, "storefrontSettings": { "description": "Storefront presentation configuration", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/StorefrontSetting" } ] }, "contactInfo": { "description": "Store contact information", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/StoreContactInfo" } ] }, "checkoutSettings": { "description": "Checkout required-field configuration", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CheckoutSetting" } ] } } }, "AvailabilitySlot": { "type": "object", "properties": { "productId": { "type": "string", "description": "ID of the product this slot belongs to", "example": "123e4567-e89b-12d3-a456-426614174000" }, "locationId": { "type": "string", "description": "ID of the location this slot is associated with, or null if not location-specific", "example": "123e4567-e89b-12d3-a456-426614174001", "nullable": true }, "staffMemberId": { "type": "string", "description": "ID of the staff member this slot is associated with, or null if not staff-specific", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "fromDate": { "type": "string", "description": "Start date of the slot (YYYY-MM-DD, UTC)", "example": "2026-04-10" }, "fromTime": { "type": "string", "description": "Start time of the slot (HH:MM:SS, UTC)", "example": "09:00:00" }, "toDate": { "type": "string", "description": "End date of the slot (YYYY-MM-DD, UTC) — differs from fromDate for cross-midnight slots", "example": "2026-04-10" }, "toTime": { "type": "string", "description": "End time of the slot (HH:MM:SS, UTC)", "example": "09:30:00" } }, "required": [ "productId", "fromDate", "fromTime", "toDate", "toTime" ] }, "CurrentAvailabilitySlot": { "type": "object", "properties": { "productId": { "type": "string", "description": "ID of the product this slot belongs to", "example": "123e4567-e89b-12d3-a456-426614174000" }, "fromDate": { "type": "string", "description": "Start date of the slot (YYYY-MM-DD, UTC)", "example": "2026-04-10" }, "fromTime": { "type": "string", "description": "Start time of the slot (HH:MM:SS, UTC)", "example": "09:00:00" }, "toDate": { "type": "string", "description": "End date of the slot (YYYY-MM-DD, UTC)", "example": "2026-04-10" }, "toTime": { "type": "string", "description": "End time of the slot (HH:MM:SS, UTC)", "example": "09:30:00" }, "staffMemberIds": { "description": "Comma-separated staff member IDs associated with this slot, or null", "nullable": true, "type": "array", "items": { "type": "string" } }, "locationIds": { "description": "Comma-separated location IDs associated with this slot, or null", "nullable": true, "type": "array", "items": { "type": "string" } }, "attendees": { "type": "number", "description": "Total booked attendees overlapping this slot" }, "maxAttendees": { "type": "number", "description": "Maximum attendees capacity for this product" } }, "required": [ "productId", "fromDate", "fromTime", "toDate", "toTime", "attendees", "maxAttendees" ] }, "ProductSlugVariantStaffMemberLocation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the location", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this location", "example": "123e4567-e89b-12d3-a456-426614174001" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this location (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "title": { "type": "string", "description": "Name of the location", "example": "Main Office", "nullable": true }, "description": { "type": "string", "description": "Description of the location", "example": "Our main downtown office location with 3 treatment rooms", "nullable": true }, "slug": { "type": "string", "description": "URL-friendly slug for the location (unique per store)", "example": "new-york" }, "type": { "type": "string", "description": "Type of location", "enum": [ "physical", "online", "delivery" ], "example": "physical" }, "link": { "type": "string", "description": "URL link for online locations", "example": "https://zoom.us/j/123456789", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of address for physical locations", "example": "123 Main Street", "nullable": true }, "addressLine2": { "type": "string", "description": "Second line of address for physical locations", "example": "Suite 200", "nullable": true }, "city": { "type": "string", "description": "City for physical locations", "example": "San Francisco", "nullable": true }, "state": { "type": "string", "description": "State/province for physical locations", "example": "CA", "nullable": true }, "postalCode": { "type": "string", "description": "Postal code for physical locations", "example": "94105", "nullable": true }, "country": { "type": "string", "description": "Country for physical locations", "example": "United States", "nullable": true }, "displayAddress": { "type": "string", "description": "Merchant-defined display address that overrides the auto-formatted address (emails, booking page). Null falls back to the concatenated address fields.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressPlaceId": { "type": "string", "description": "Google Place ID for the physical address", "example": "ChIJIQBpAG2ahYAR_6128GcTUEo", "nullable": true }, "latitude": { "type": "number", "description": "Latitude in WGS84", "example": 37.4224764, "nullable": true }, "longitude": { "type": "number", "description": "Longitude in WGS84", "example": -122.0842499, "nullable": true }, "createdAt": { "type": "string", "description": "Date when the location was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the location was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "type": "string", "description": "Date when the location was deleted (for soft deletes)", "example": "2023-03-10T11:45:00Z", "nullable": true }, "address": { "type": "string", "description": "The formatted address string", "nullable": true } }, "required": [ "id", "storeId", "scheduleId", "title", "description", "slug", "type", "link", "addressLine1", "addressLine2", "city", "state", "postalCode", "country", "addressPlaceId", "latitude", "longitude", "createdAt", "updatedAt", "deletedAt", "address" ] }, "ProductSlugVariantStaffMember": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this staff member record", "example": "123e4567-e89b-12d3-a456-426614174111" }, "userId": { "type": "string", "description": "User ID of the staff member login identity (nullable until linked)", "example": "user-uuid" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this staff member, defines their availability", "example": "123e4567-e89b-12d3-a456-426614174000" }, "imageId": { "type": "string", "description": "ID of the image associated with this staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "firstName": { "type": "string", "description": "First name of the staff member", "example": "John" }, "lastName": { "type": "string", "description": "Last name of the staff member", "example": "Doe" }, "email": { "type": "string", "description": "Email address of the staff member, used for notifications and calendar integration", "example": "john.doe@example.com" }, "slug": { "type": "string", "description": "URL-friendly slug for the staff member (unique per store)", "example": "mike" }, "refreshToken": { "type": "string", "description": "Refresh token for integrations like Google Calendar", "example": "abc123xyz456" }, "createdAt": { "type": "string", "description": "Date and time when the staff member was created", "example": "2025-05-01T12:00:00Z" }, "updatedAt": { "type": "string", "description": "Date and time when the staff member was last updated", "example": "2025-05-15T14:30:00Z" }, "deletedAt": { "type": "string", "description": "Date and time when the staff member was soft deleted", "example": "2025-06-01T09:15:00Z" }, "image": { "description": "Profile image of the staff member", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] }, "locations": { "description": "Locations where this staff member works", "type": "array", "items": { "$ref": "#/components/schemas/ProductSlugVariantStaffMemberLocation" } } }, "required": [ "id", "storeId", "userId", "scheduleId", "imageId", "firstName", "lastName", "email", "slug", "refreshToken", "createdAt", "updatedAt", "deletedAt", "locations" ] }, "ProductSlugVariantLocationStaffMember": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this staff member record", "example": "123e4567-e89b-12d3-a456-426614174111" }, "userId": { "type": "string", "description": "User ID of the staff member login identity (nullable until linked)", "example": "user-uuid" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this staff member, defines their availability", "example": "123e4567-e89b-12d3-a456-426614174000" }, "imageId": { "type": "string", "description": "ID of the image associated with this staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "firstName": { "type": "string", "description": "First name of the staff member", "example": "John" }, "lastName": { "type": "string", "description": "Last name of the staff member", "example": "Doe" }, "email": { "type": "string", "description": "Email address of the staff member, used for notifications and calendar integration", "example": "john.doe@example.com" }, "slug": { "type": "string", "description": "URL-friendly slug for the staff member (unique per store)", "example": "mike" }, "refreshToken": { "type": "string", "description": "Refresh token for integrations like Google Calendar", "example": "abc123xyz456" }, "createdAt": { "type": "string", "description": "Date and time when the staff member was created", "example": "2025-05-01T12:00:00Z" }, "updatedAt": { "type": "string", "description": "Date and time when the staff member was last updated", "example": "2025-05-15T14:30:00Z" }, "deletedAt": { "type": "string", "description": "Date and time when the staff member was soft deleted", "example": "2025-06-01T09:15:00Z" }, "image": { "description": "Profile image of the staff member", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "storeId", "userId", "scheduleId", "imageId", "firstName", "lastName", "email", "slug", "refreshToken", "createdAt", "updatedAt", "deletedAt" ] }, "ProductSlugVariantLocation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the location", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this location", "example": "123e4567-e89b-12d3-a456-426614174001" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this location (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "title": { "type": "string", "description": "Name of the location", "example": "Main Office", "nullable": true }, "description": { "type": "string", "description": "Description of the location", "example": "Our main downtown office location with 3 treatment rooms", "nullable": true }, "slug": { "type": "string", "description": "URL-friendly slug for the location (unique per store)", "example": "new-york" }, "type": { "type": "string", "description": "Type of location", "enum": [ "physical", "online", "delivery" ], "example": "physical" }, "link": { "type": "string", "description": "URL link for online locations", "example": "https://zoom.us/j/123456789", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of address for physical locations", "example": "123 Main Street", "nullable": true }, "addressLine2": { "type": "string", "description": "Second line of address for physical locations", "example": "Suite 200", "nullable": true }, "city": { "type": "string", "description": "City for physical locations", "example": "San Francisco", "nullable": true }, "state": { "type": "string", "description": "State/province for physical locations", "example": "CA", "nullable": true }, "postalCode": { "type": "string", "description": "Postal code for physical locations", "example": "94105", "nullable": true }, "country": { "type": "string", "description": "Country for physical locations", "example": "United States", "nullable": true }, "displayAddress": { "type": "string", "description": "Merchant-defined display address that overrides the auto-formatted address (emails, booking page). Null falls back to the concatenated address fields.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressPlaceId": { "type": "string", "description": "Google Place ID for the physical address", "example": "ChIJIQBpAG2ahYAR_6128GcTUEo", "nullable": true }, "latitude": { "type": "number", "description": "Latitude in WGS84", "example": 37.4224764, "nullable": true }, "longitude": { "type": "number", "description": "Longitude in WGS84", "example": -122.0842499, "nullable": true }, "createdAt": { "type": "string", "description": "Date when the location was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the location was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "type": "string", "description": "Date when the location was deleted (for soft deletes)", "example": "2023-03-10T11:45:00Z", "nullable": true }, "address": { "type": "string", "description": "The formatted address string", "nullable": true }, "staffMembers": { "description": "Staff members who can work at this location", "type": "array", "items": { "$ref": "#/components/schemas/ProductSlugVariantLocationStaffMember" } } }, "required": [ "id", "storeId", "scheduleId", "title", "description", "slug", "type", "link", "addressLine1", "addressLine2", "city", "state", "postalCode", "country", "addressPlaceId", "latitude", "longitude", "createdAt", "updatedAt", "deletedAt", "address", "staffMembers" ] }, "ProductSlugVariant": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "productId": { "type": "string", "description": "ID of the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID)", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID)", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this product", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the product (unique per store)", "example": "haircut-basic" }, "scheduleId": { "type": "string", "description": "ID of the schedule associated with this product" }, "productPoolId": { "type": "string", "description": "ID of the product pool this product belongs to (controls overlap prevention)", "nullable": true }, "title": { "type": "string", "description": "Title of the product", "example": "Haircut Service" }, "variantTitle": { "type": "string", "description": "Title of the specific product variant", "example": "Short Hair" }, "description": { "type": "string", "description": "Detailed description of the product" }, "imageId": { "type": "string", "description": "ID of the product image" }, "color": { "type": "string", "description": "Color code for displaying the product", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "BLUE", "default": "slate" }, "price": { "type": "number", "description": "Price of the product", "example": 250 }, "taxable": { "type": "boolean", "description": "Whether the product is taxable", "default": false }, "duration": { "type": "number", "description": "Duration of the service in seconds", "example": 3600 }, "allowCustomDuration": { "type": "boolean", "description": "Whether customers can customize the duration by selecting multiples of the base service duration (e.g., if base duration is 1 day, customers can book 1, 2, 3+ days)", "default": false }, "maxDuration": { "type": "number", "description": "When allow_custom_duration=true, maximum duration allowed for multi-duration bookings in seconds (-1 for unlimited)", "default": -1 }, "maxAttendees": { "type": "number", "description": "Maximum number of attendees allowed", "default": 1 }, "maxGuests": { "type": "number", "description": "Maximum number of guests allowed per appointment. Null means unlimited.", "nullable": true }, "allowGuests": { "type": "boolean", "description": "Whether customers can invite guests to the appointment", "default": false }, "allowCustomerReschedule": { "type": "boolean", "description": "Whether customers can reschedule their bookings", "default": false }, "allowCustomerCancel": { "type": "boolean", "description": "Whether customers can cancel their bookings", "default": false }, "rescheduleGap": { "type": "number", "description": "Time in seconds before appointment when rescheduling is no longer allowed" }, "cancelGap": { "type": "number", "description": "Time in seconds before appointment when cancellation is no longer allowed" }, "beforeGap": { "type": "number", "description": "Buffer time in seconds required before this service" }, "afterGap": { "type": "number", "description": "Buffer time in seconds required after this service" }, "fixedTimes": { "type": "boolean", "description": "When allow_custom_duration=true, whether appointments must start and end at fixed times (like fixed check-in/check-out times for multi-duration bookings)", "default": false }, "fixedStartTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must start (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "09:00:00" }, "fixedEndTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must end (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "17:00:00" }, "advanceScheduleThreshold": { "type": "number", "description": "How many days in advance bookings can be made", "default": 0 }, "sendConfirmationEmail": { "type": "boolean", "description": "Whether to send confirmation emails for bookings", "default": true }, "sendReminderEmail": { "type": "boolean", "description": "Whether to send reminder emails before appointments", "default": false }, "sendFeedbackEmail": { "type": "boolean", "description": "Whether to send feedback request emails after appointments", "default": false }, "skipCheckout": { "type": "boolean", "description": "Whether to skip the checkout process for this product (Shopify merchants only)", "default": false }, "status": { "type": "string", "description": "Current status of the product", "enum": [ "active", "inactive" ], "example": "ACTIVE", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the product was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the product was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the product was deleted (for soft deletes)" }, "image": { "description": "Primary image of the product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] }, "images": { "description": "Images associated with this product", "type": "array", "items": { "$ref": "#/components/schemas/Image" } }, "staffMembers": { "description": "Staff members who can provide this service", "type": "array", "items": { "$ref": "#/components/schemas/ProductSlugVariantStaffMember" } }, "locations": { "description": "Locations where this service is offered", "type": "array", "items": { "$ref": "#/components/schemas/ProductSlugVariantLocation" } } }, "required": [ "id", "productId", "externalId", "externalVariantId", "storeId", "slug", "scheduleId", "productPoolId", "title", "variantTitle", "description", "imageId", "color", "price", "taxable", "duration", "allowCustomDuration", "maxDuration", "maxAttendees", "maxGuests", "allowGuests", "allowCustomerReschedule", "allowCustomerCancel", "rescheduleGap", "cancelGap", "beforeGap", "afterGap", "fixedTimes", "fixedStartTime", "fixedEndTime", "advanceScheduleThreshold", "sendConfirmationEmail", "sendReminderEmail", "sendFeedbackEmail", "skipCheckout", "status", "createdAt", "updatedAt", "deletedAt", "images", "staffMembers", "locations" ] }, "ProductSlugResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "productId": { "type": "string", "description": "ID of the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID)", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID)", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this product", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the product (unique per store)", "example": "haircut-basic" }, "scheduleId": { "type": "string", "description": "ID of the schedule associated with this product" }, "productPoolId": { "type": "string", "description": "ID of the product pool this product belongs to (controls overlap prevention)", "nullable": true }, "title": { "type": "string", "description": "Title of the product", "example": "Haircut Service" }, "variantTitle": { "type": "string", "description": "Title of the specific product variant", "example": "Short Hair" }, "description": { "type": "string", "description": "Detailed description of the product" }, "imageId": { "type": "string", "description": "ID of the product image" }, "color": { "type": "string", "description": "Color code for displaying the product", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "BLUE", "default": "slate" }, "price": { "type": "number", "description": "Price of the product", "example": 250 }, "taxable": { "type": "boolean", "description": "Whether the product is taxable", "default": false }, "duration": { "type": "number", "description": "Duration of the service in seconds", "example": 3600 }, "allowCustomDuration": { "type": "boolean", "description": "Whether customers can customize the duration by selecting multiples of the base service duration (e.g., if base duration is 1 day, customers can book 1, 2, 3+ days)", "default": false }, "maxDuration": { "type": "number", "description": "When allow_custom_duration=true, maximum duration allowed for multi-duration bookings in seconds (-1 for unlimited)", "default": -1 }, "maxAttendees": { "type": "number", "description": "Maximum number of attendees allowed", "default": 1 }, "maxGuests": { "type": "number", "description": "Maximum number of guests allowed per appointment. Null means unlimited.", "nullable": true }, "allowGuests": { "type": "boolean", "description": "Whether customers can invite guests to the appointment", "default": false }, "allowCustomerReschedule": { "type": "boolean", "description": "Whether customers can reschedule their bookings", "default": false }, "allowCustomerCancel": { "type": "boolean", "description": "Whether customers can cancel their bookings", "default": false }, "rescheduleGap": { "type": "number", "description": "Time in seconds before appointment when rescheduling is no longer allowed" }, "cancelGap": { "type": "number", "description": "Time in seconds before appointment when cancellation is no longer allowed" }, "beforeGap": { "type": "number", "description": "Buffer time in seconds required before this service" }, "afterGap": { "type": "number", "description": "Buffer time in seconds required after this service" }, "fixedTimes": { "type": "boolean", "description": "When allow_custom_duration=true, whether appointments must start and end at fixed times (like fixed check-in/check-out times for multi-duration bookings)", "default": false }, "fixedStartTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must start (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "09:00:00" }, "fixedEndTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must end (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "17:00:00" }, "advanceScheduleThreshold": { "type": "number", "description": "How many days in advance bookings can be made", "default": 0 }, "sendConfirmationEmail": { "type": "boolean", "description": "Whether to send confirmation emails for bookings", "default": true }, "sendReminderEmail": { "type": "boolean", "description": "Whether to send reminder emails before appointments", "default": false }, "sendFeedbackEmail": { "type": "boolean", "description": "Whether to send feedback request emails after appointments", "default": false }, "skipCheckout": { "type": "boolean", "description": "Whether to skip the checkout process for this product (Shopify merchants only)", "default": false }, "status": { "type": "string", "description": "Current status of the product", "enum": [ "active", "inactive" ], "example": "ACTIVE", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the product was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the product was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the product was deleted (for soft deletes)" }, "image": { "description": "Primary image of the product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] }, "variants": { "description": "Variants of this product", "type": "array", "items": { "$ref": "#/components/schemas/ProductSlugVariant" } } }, "required": [ "id", "productId", "externalId", "externalVariantId", "storeId", "slug", "scheduleId", "productPoolId", "title", "variantTitle", "description", "imageId", "color", "price", "taxable", "duration", "allowCustomDuration", "maxDuration", "maxAttendees", "maxGuests", "allowGuests", "allowCustomerReschedule", "allowCustomerCancel", "rescheduleGap", "cancelGap", "beforeGap", "afterGap", "fixedTimes", "fixedStartTime", "fixedEndTime", "advanceScheduleThreshold", "sendConfirmationEmail", "sendReminderEmail", "sendFeedbackEmail", "skipCheckout", "status", "createdAt", "updatedAt", "deletedAt", "variants" ] }, "ProductDetailStaffMember": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this staff member record", "example": "123e4567-e89b-12d3-a456-426614174111" }, "userId": { "type": "string", "description": "User ID of the staff member login identity (nullable until linked)", "example": "user-uuid" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this staff member, defines their availability", "example": "123e4567-e89b-12d3-a456-426614174000" }, "imageId": { "type": "string", "description": "ID of the image associated with this staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "firstName": { "type": "string", "description": "First name of the staff member", "example": "John" }, "lastName": { "type": "string", "description": "Last name of the staff member", "example": "Doe" }, "email": { "type": "string", "description": "Email address of the staff member, used for notifications and calendar integration", "example": "john.doe@example.com" }, "slug": { "type": "string", "description": "URL-friendly slug for the staff member (unique per store)", "example": "mike" }, "refreshToken": { "type": "string", "description": "Refresh token for integrations like Google Calendar", "example": "abc123xyz456" }, "createdAt": { "type": "string", "description": "Date and time when the staff member was created", "example": "2025-05-01T12:00:00Z" }, "updatedAt": { "type": "string", "description": "Date and time when the staff member was last updated", "example": "2025-05-15T14:30:00Z" }, "deletedAt": { "type": "string", "description": "Date and time when the staff member was soft deleted", "example": "2025-06-01T09:15:00Z" }, "image": { "description": "Profile image of the staff member", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "storeId", "userId", "scheduleId", "imageId", "firstName", "lastName", "email", "slug", "refreshToken", "createdAt", "updatedAt", "deletedAt" ] }, "ProductDetailLocation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the location", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this location", "example": "123e4567-e89b-12d3-a456-426614174001" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this location (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "title": { "type": "string", "description": "Name of the location", "example": "Main Office", "nullable": true }, "description": { "type": "string", "description": "Description of the location", "example": "Our main downtown office location with 3 treatment rooms", "nullable": true }, "slug": { "type": "string", "description": "URL-friendly slug for the location (unique per store)", "example": "new-york" }, "type": { "type": "string", "description": "Type of location", "enum": [ "physical", "online", "delivery" ], "example": "physical" }, "link": { "type": "string", "description": "URL link for online locations", "example": "https://zoom.us/j/123456789", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of address for physical locations", "example": "123 Main Street", "nullable": true }, "addressLine2": { "type": "string", "description": "Second line of address for physical locations", "example": "Suite 200", "nullable": true }, "city": { "type": "string", "description": "City for physical locations", "example": "San Francisco", "nullable": true }, "state": { "type": "string", "description": "State/province for physical locations", "example": "CA", "nullable": true }, "postalCode": { "type": "string", "description": "Postal code for physical locations", "example": "94105", "nullable": true }, "country": { "type": "string", "description": "Country for physical locations", "example": "United States", "nullable": true }, "displayAddress": { "type": "string", "description": "Merchant-defined display address that overrides the auto-formatted address (emails, booking page). Null falls back to the concatenated address fields.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressPlaceId": { "type": "string", "description": "Google Place ID for the physical address", "example": "ChIJIQBpAG2ahYAR_6128GcTUEo", "nullable": true }, "latitude": { "type": "number", "description": "Latitude in WGS84", "example": 37.4224764, "nullable": true }, "longitude": { "type": "number", "description": "Longitude in WGS84", "example": -122.0842499, "nullable": true }, "createdAt": { "type": "string", "description": "Date when the location was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the location was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "type": "string", "description": "Date when the location was deleted (for soft deletes)", "example": "2023-03-10T11:45:00Z", "nullable": true }, "address": { "type": "string", "description": "The formatted address string", "nullable": true } }, "required": [ "id", "storeId", "scheduleId", "title", "description", "slug", "type", "link", "addressLine1", "addressLine2", "city", "state", "postalCode", "country", "addressPlaceId", "latitude", "longitude", "createdAt", "updatedAt", "deletedAt", "address" ] }, "ProductDetailSchedule": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the schedule", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this schedule", "example": "123e4567-e89b-12d3-a456-426614174001" }, "name": { "type": "string", "description": "Name of the schedule", "example": "Standard Business Hours", "nullable": true }, "timezone": { "type": "string", "description": "Timezone for the schedule", "example": "UTC", "default": "UTC" }, "scheduleGap": { "type": "string", "description": "Time slot frequency for the schedule", "enum": [ "every-10-minutes", "every-15-minutes", "every-20-minutes", "every-30-minutes", "every-60-minutes" ], "example": "every-15-minutes", "default": "every-15-minutes" }, "appointmentsGap": { "type": "number", "description": "Buffer time between appointments in seconds", "example": 900 }, "advanceScheduleDays": { "type": "number", "description": "Number of days customers can book in advance (-1 for unlimited)", "example": 60, "default": -1 }, "availabilityType": { "type": "string", "description": "Type of availability pattern for this schedule", "enum": [ "continuous", "recurring", "non-recurring" ], "example": "recurring", "default": "continuous" }, "status": { "type": "string", "description": "Status of the schedule", "enum": [ "active", "inactive" ], "example": "active", "default": "inactive" }, "createdAt": { "type": "string", "description": "Date when the schedule was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the schedule was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date when the schedule was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true } }, "required": [ "id", "storeId", "name", "timezone", "scheduleGap", "appointmentsGap", "advanceScheduleDays", "availabilityType", "status", "createdAt", "updatedAt", "deletedAt" ] }, "ProductDetailFeedbackQuestion": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the feedback question", "example": "550e8400-e29b-41d4-a716-446655440000" }, "internalName": { "type": "string", "description": "Internal name for the question (not shown to customers)", "example": "Service Quality Rating Question" }, "required": { "type": "boolean", "description": "Whether the question is required to be answered", "example": true }, "type": { "type": "string", "description": "Type of input for the question", "enum": [ "single-line-text-field", "multi-line-text-field", "dropdown", "rating", "checkbox", "file-upload" ], "example": "rating" }, "order": { "type": "number", "description": "Display order of the question (lower numbers appear first)", "example": 1, "default": 0 }, "alwaysShow": { "type": "boolean", "description": "Whether this question is shown for all products in the store", "example": false, "default": false }, "fileConfig": { "type": "object", "description": "File-upload constraints (allowed categories, max size, max files). Only set when type is file-upload.", "example": { "categories": [ "images", "pdf" ], "maxSizeBytes": 26214400, "maxFiles": 5 }, "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the question was created", "example": "2023-01-01T00:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the question was last updated", "example": "2023-01-15T00:00:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date when the question was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this question", "example": "store-uuid" } }, "required": [ "id", "internalName", "required", "type", "order", "alwaysShow", "createdAt", "updatedAt", "deletedAt", "storeId" ] }, "ProductDetailCheckoutQuestion": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the checkout question", "example": "550e8400-e29b-41d4-a716-446655440000" }, "internalName": { "type": "string", "description": "Internal name for the question (not shown to customers)", "example": "Customer Allergies Question" }, "required": { "type": "boolean", "description": "Whether the question is required to be answered", "example": true }, "type": { "type": "string", "description": "Type of input for the question", "enum": [ "single-line-text-field", "multi-line-text-field", "dropdown", "rating", "checkbox", "file-upload" ], "example": "single-line-text-field" }, "order": { "type": "number", "description": "Display order of the question (lower numbers appear first)", "example": 1, "default": 0 }, "alwaysShow": { "type": "boolean", "description": "Whether this question is shown for all products in the store", "example": false, "default": false }, "fileConfig": { "type": "object", "description": "File-upload constraints (allowed categories, max size, max files). Only set when type is file-upload.", "example": { "categories": [ "images", "pdf" ], "maxSizeBytes": 26214400, "maxFiles": 5 }, "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the question was created", "example": "2023-01-01T00:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the question was last updated", "example": "2023-01-15T00:00:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date when the question was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this question", "example": "store-uuid" } }, "required": [ "id", "internalName", "required", "type", "order", "alwaysShow", "createdAt", "updatedAt", "deletedAt", "storeId" ] }, "ProductDetailCollection": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the product collection" }, "storeId": { "type": "string", "description": "Identifier of the store that owns the collection" }, "title": { "type": "string", "description": "Title of the product collection", "example": "Hair Services" }, "description": { "type": "string", "description": "Description of the product collection" }, "slug": { "type": "string", "description": "URL-friendly slug for the product collection (unique per store)", "example": "featured" }, "isVisible": { "type": "boolean", "description": "Visibility flag for the collection", "default": true }, "createdAt": { "type": "string", "description": "Timestamp when the collection was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the collection was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the collection was soft-deleted" } }, "required": [ "id", "storeId", "title", "description", "slug", "isVisible", "createdAt", "updatedAt", "deletedAt" ] }, "ProductDetailVariant": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "productId": { "type": "string", "description": "ID of the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID)", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID)", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this product", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the product (unique per store)", "example": "haircut-basic" }, "scheduleId": { "type": "string", "description": "ID of the schedule associated with this product" }, "productPoolId": { "type": "string", "description": "ID of the product pool this product belongs to (controls overlap prevention)", "nullable": true }, "title": { "type": "string", "description": "Title of the product", "example": "Haircut Service" }, "variantTitle": { "type": "string", "description": "Title of the specific product variant", "example": "Short Hair" }, "description": { "type": "string", "description": "Detailed description of the product" }, "imageId": { "type": "string", "description": "ID of the product image" }, "color": { "type": "string", "description": "Color code for displaying the product", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "BLUE", "default": "slate" }, "price": { "type": "number", "description": "Price of the product", "example": 250 }, "taxable": { "type": "boolean", "description": "Whether the product is taxable", "default": false }, "duration": { "type": "number", "description": "Duration of the service in seconds", "example": 3600 }, "allowCustomDuration": { "type": "boolean", "description": "Whether customers can customize the duration by selecting multiples of the base service duration (e.g., if base duration is 1 day, customers can book 1, 2, 3+ days)", "default": false }, "maxDuration": { "type": "number", "description": "When allow_custom_duration=true, maximum duration allowed for multi-duration bookings in seconds (-1 for unlimited)", "default": -1 }, "maxAttendees": { "type": "number", "description": "Maximum number of attendees allowed", "default": 1 }, "maxGuests": { "type": "number", "description": "Maximum number of guests allowed per appointment. Null means unlimited.", "nullable": true }, "allowGuests": { "type": "boolean", "description": "Whether customers can invite guests to the appointment", "default": false }, "allowCustomerReschedule": { "type": "boolean", "description": "Whether customers can reschedule their bookings", "default": false }, "allowCustomerCancel": { "type": "boolean", "description": "Whether customers can cancel their bookings", "default": false }, "rescheduleGap": { "type": "number", "description": "Time in seconds before appointment when rescheduling is no longer allowed" }, "cancelGap": { "type": "number", "description": "Time in seconds before appointment when cancellation is no longer allowed" }, "beforeGap": { "type": "number", "description": "Buffer time in seconds required before this service" }, "afterGap": { "type": "number", "description": "Buffer time in seconds required after this service" }, "fixedTimes": { "type": "boolean", "description": "When allow_custom_duration=true, whether appointments must start and end at fixed times (like fixed check-in/check-out times for multi-duration bookings)", "default": false }, "fixedStartTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must start (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "09:00:00" }, "fixedEndTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must end (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "17:00:00" }, "advanceScheduleThreshold": { "type": "number", "description": "How many days in advance bookings can be made", "default": 0 }, "sendConfirmationEmail": { "type": "boolean", "description": "Whether to send confirmation emails for bookings", "default": true }, "sendReminderEmail": { "type": "boolean", "description": "Whether to send reminder emails before appointments", "default": false }, "sendFeedbackEmail": { "type": "boolean", "description": "Whether to send feedback request emails after appointments", "default": false }, "skipCheckout": { "type": "boolean", "description": "Whether to skip the checkout process for this product (Shopify merchants only)", "default": false }, "status": { "type": "string", "description": "Current status of the product", "enum": [ "active", "inactive" ], "example": "ACTIVE", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the product was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the product was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the product was deleted (for soft deletes)" }, "image": { "description": "Primary image of the product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "productId", "externalId", "externalVariantId", "storeId", "slug", "scheduleId", "productPoolId", "title", "variantTitle", "description", "imageId", "color", "price", "taxable", "duration", "allowCustomDuration", "maxDuration", "maxAttendees", "maxGuests", "allowGuests", "allowCustomerReschedule", "allowCustomerCancel", "rescheduleGap", "cancelGap", "beforeGap", "afterGap", "fixedTimes", "fixedStartTime", "fixedEndTime", "advanceScheduleThreshold", "sendConfirmationEmail", "sendReminderEmail", "sendFeedbackEmail", "skipCheckout", "status", "createdAt", "updatedAt", "deletedAt" ] }, "ProductDetailAddOn": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the add-on", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID) for synced add-ons", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID) for synced add-ons", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this add-on", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the add-on (unique per store)", "example": "child-seat" }, "title": { "type": "string", "description": "Title of the add-on", "example": "Child Seat" }, "description": { "type": "string", "description": "Detailed description of the add-on" }, "imageId": { "type": "string", "description": "ID of the primary image for the add-on" }, "color": { "type": "string", "description": "Color code used when displaying the add-on", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "slate", "default": "slate" }, "price": { "type": "number", "description": "Unit price of the add-on", "example": 15 }, "taxable": { "type": "boolean", "description": "Whether the add-on is taxable", "default": true }, "durationMultiplied": { "type": "boolean", "description": "When true, the add-on is charged per base-duration unit of the parent appointment. Quantity on the cart/order line item mirrors the parent CartItem.quantity (i.e., the booked duration units). Only meaningful for attached products with allowCustomDuration=true.", "default": false }, "maxQuantity": { "type": "number", "description": "Maximum quantity a customer can pick for this add-on. Only applies to fixed add-ons (durationMultiplied=false). Null means unlimited.", "example": 4, "minimum": 1, "nullable": true }, "status": { "type": "string", "description": "Current status of the add-on", "enum": [ "active", "inactive" ], "example": "active", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the add-on was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the add-on was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the add-on was soft-deleted" }, "image": { "description": "Primary image of the add-on", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "externalId", "externalVariantId", "storeId", "slug", "title", "description", "imageId", "color", "price", "taxable", "durationMultiplied", "maxQuantity", "status", "createdAt", "updatedAt", "deletedAt" ] }, "ProductDetailProductPool": { "type": "object", "properties": { "id": { "type": "string" }, "storeId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "deletedAt": { "type": "string" } }, "required": [ "id", "storeId", "name", "description", "status", "createdAt", "updatedAt", "deletedAt" ] }, "ProductDetailResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "productId": { "type": "string", "description": "ID of the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID)", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID)", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this product", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the product (unique per store)", "example": "haircut-basic" }, "scheduleId": { "type": "string", "description": "ID of the schedule associated with this product" }, "productPoolId": { "type": "string", "description": "ID of the product pool this product belongs to (controls overlap prevention)", "nullable": true }, "title": { "type": "string", "description": "Title of the product", "example": "Haircut Service" }, "variantTitle": { "type": "string", "description": "Title of the specific product variant", "example": "Short Hair" }, "description": { "type": "string", "description": "Detailed description of the product" }, "imageId": { "type": "string", "description": "ID of the product image" }, "color": { "type": "string", "description": "Color code for displaying the product", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "BLUE", "default": "slate" }, "price": { "type": "number", "description": "Price of the product", "example": 250 }, "taxable": { "type": "boolean", "description": "Whether the product is taxable", "default": false }, "duration": { "type": "number", "description": "Duration of the service in seconds", "example": 3600 }, "allowCustomDuration": { "type": "boolean", "description": "Whether customers can customize the duration by selecting multiples of the base service duration (e.g., if base duration is 1 day, customers can book 1, 2, 3+ days)", "default": false }, "maxDuration": { "type": "number", "description": "When allow_custom_duration=true, maximum duration allowed for multi-duration bookings in seconds (-1 for unlimited)", "default": -1 }, "maxAttendees": { "type": "number", "description": "Maximum number of attendees allowed", "default": 1 }, "maxGuests": { "type": "number", "description": "Maximum number of guests allowed per appointment. Null means unlimited.", "nullable": true }, "allowGuests": { "type": "boolean", "description": "Whether customers can invite guests to the appointment", "default": false }, "allowCustomerReschedule": { "type": "boolean", "description": "Whether customers can reschedule their bookings", "default": false }, "allowCustomerCancel": { "type": "boolean", "description": "Whether customers can cancel their bookings", "default": false }, "rescheduleGap": { "type": "number", "description": "Time in seconds before appointment when rescheduling is no longer allowed" }, "cancelGap": { "type": "number", "description": "Time in seconds before appointment when cancellation is no longer allowed" }, "beforeGap": { "type": "number", "description": "Buffer time in seconds required before this service" }, "afterGap": { "type": "number", "description": "Buffer time in seconds required after this service" }, "fixedTimes": { "type": "boolean", "description": "When allow_custom_duration=true, whether appointments must start and end at fixed times (like fixed check-in/check-out times for multi-duration bookings)", "default": false }, "fixedStartTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must start (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "09:00:00" }, "fixedEndTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must end (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "17:00:00" }, "advanceScheduleThreshold": { "type": "number", "description": "How many days in advance bookings can be made", "default": 0 }, "sendConfirmationEmail": { "type": "boolean", "description": "Whether to send confirmation emails for bookings", "default": true }, "sendReminderEmail": { "type": "boolean", "description": "Whether to send reminder emails before appointments", "default": false }, "sendFeedbackEmail": { "type": "boolean", "description": "Whether to send feedback request emails after appointments", "default": false }, "skipCheckout": { "type": "boolean", "description": "Whether to skip the checkout process for this product (Shopify merchants only)", "default": false }, "status": { "type": "string", "description": "Current status of the product", "enum": [ "active", "inactive" ], "example": "ACTIVE", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the product was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the product was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the product was deleted (for soft deletes)" }, "image": { "description": "Primary image of the product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] }, "staffMembers": { "description": "Staff members who can provide this service", "type": "array", "items": { "$ref": "#/components/schemas/ProductDetailStaffMember" } }, "locations": { "description": "Locations where this service is offered", "type": "array", "items": { "$ref": "#/components/schemas/ProductDetailLocation" } }, "schedule": { "description": "Schedule associated with this product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ProductDetailSchedule" } ] }, "images": { "description": "Images associated with this product", "type": "array", "items": { "$ref": "#/components/schemas/Image" } }, "feedbackQuestions": { "description": "Feedback questions associated with this product", "type": "array", "items": { "$ref": "#/components/schemas/ProductDetailFeedbackQuestion" } }, "checkoutQuestions": { "description": "Checkout questions associated with this product", "type": "array", "items": { "$ref": "#/components/schemas/ProductDetailCheckoutQuestion" } }, "collections": { "description": "Collections assigned to this product", "type": "array", "items": { "$ref": "#/components/schemas/ProductDetailCollection" } }, "variants": { "description": "Variants of this product", "type": "array", "items": { "$ref": "#/components/schemas/ProductDetailVariant" } }, "addOns": { "description": "Add-ons that can be attached to this product at booking time", "type": "array", "items": { "$ref": "#/components/schemas/ProductDetailAddOn" } }, "productPool": { "description": "Resource group this product belongs to", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ProductDetailProductPool" } ] } }, "required": [ "id", "productId", "externalId", "externalVariantId", "storeId", "slug", "scheduleId", "productPoolId", "title", "variantTitle", "description", "imageId", "color", "price", "taxable", "duration", "allowCustomDuration", "maxDuration", "maxAttendees", "maxGuests", "allowGuests", "allowCustomerReschedule", "allowCustomerCancel", "rescheduleGap", "cancelGap", "beforeGap", "afterGap", "fixedTimes", "fixedStartTime", "fixedEndTime", "advanceScheduleThreshold", "sendConfirmationEmail", "sendReminderEmail", "sendFeedbackEmail", "skipCheckout", "status", "createdAt", "updatedAt", "deletedAt", "staffMembers", "locations", "schedule", "images", "feedbackQuestions", "checkoutQuestions", "collections", "variants", "addOns", "productPool" ] }, "ProductExternalIdStaffMember": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this staff member record", "example": "123e4567-e89b-12d3-a456-426614174111" }, "userId": { "type": "string", "description": "User ID of the staff member login identity (nullable until linked)", "example": "user-uuid" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this staff member, defines their availability", "example": "123e4567-e89b-12d3-a456-426614174000" }, "imageId": { "type": "string", "description": "ID of the image associated with this staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "firstName": { "type": "string", "description": "First name of the staff member", "example": "John" }, "lastName": { "type": "string", "description": "Last name of the staff member", "example": "Doe" }, "email": { "type": "string", "description": "Email address of the staff member, used for notifications and calendar integration", "example": "john.doe@example.com" }, "slug": { "type": "string", "description": "URL-friendly slug for the staff member (unique per store)", "example": "mike" }, "refreshToken": { "type": "string", "description": "Refresh token for integrations like Google Calendar", "example": "abc123xyz456" }, "createdAt": { "type": "string", "description": "Date and time when the staff member was created", "example": "2025-05-01T12:00:00Z" }, "updatedAt": { "type": "string", "description": "Date and time when the staff member was last updated", "example": "2025-05-15T14:30:00Z" }, "deletedAt": { "type": "string", "description": "Date and time when the staff member was soft deleted", "example": "2025-06-01T09:15:00Z" }, "image": { "description": "Profile image of the staff member", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "storeId", "userId", "scheduleId", "imageId", "firstName", "lastName", "email", "slug", "refreshToken", "createdAt", "updatedAt", "deletedAt" ] }, "ProductExternalIdLocationStaffMember": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this staff member record", "example": "123e4567-e89b-12d3-a456-426614174111" }, "userId": { "type": "string", "description": "User ID of the staff member login identity (nullable until linked)", "example": "user-uuid" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this staff member, defines their availability", "example": "123e4567-e89b-12d3-a456-426614174000" }, "imageId": { "type": "string", "description": "ID of the image associated with this staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "firstName": { "type": "string", "description": "First name of the staff member", "example": "John" }, "lastName": { "type": "string", "description": "Last name of the staff member", "example": "Doe" }, "email": { "type": "string", "description": "Email address of the staff member, used for notifications and calendar integration", "example": "john.doe@example.com" }, "slug": { "type": "string", "description": "URL-friendly slug for the staff member (unique per store)", "example": "mike" }, "refreshToken": { "type": "string", "description": "Refresh token for integrations like Google Calendar", "example": "abc123xyz456" }, "createdAt": { "type": "string", "description": "Date and time when the staff member was created", "example": "2025-05-01T12:00:00Z" }, "updatedAt": { "type": "string", "description": "Date and time when the staff member was last updated", "example": "2025-05-15T14:30:00Z" }, "deletedAt": { "type": "string", "description": "Date and time when the staff member was soft deleted", "example": "2025-06-01T09:15:00Z" }, "image": { "description": "Profile image of the staff member", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "storeId", "userId", "scheduleId", "imageId", "firstName", "lastName", "email", "slug", "refreshToken", "createdAt", "updatedAt", "deletedAt" ] }, "ProductExternalIdLocationSchedule": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the schedule", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this schedule", "example": "123e4567-e89b-12d3-a456-426614174001" }, "name": { "type": "string", "description": "Name of the schedule", "example": "Standard Business Hours", "nullable": true }, "timezone": { "type": "string", "description": "Timezone for the schedule", "example": "UTC", "default": "UTC" }, "scheduleGap": { "type": "string", "description": "Time slot frequency for the schedule", "enum": [ "every-10-minutes", "every-15-minutes", "every-20-minutes", "every-30-minutes", "every-60-minutes" ], "example": "every-15-minutes", "default": "every-15-minutes" }, "appointmentsGap": { "type": "number", "description": "Buffer time between appointments in seconds", "example": 900 }, "advanceScheduleDays": { "type": "number", "description": "Number of days customers can book in advance (-1 for unlimited)", "example": 60, "default": -1 }, "availabilityType": { "type": "string", "description": "Type of availability pattern for this schedule", "enum": [ "continuous", "recurring", "non-recurring" ], "example": "recurring", "default": "continuous" }, "status": { "type": "string", "description": "Status of the schedule", "enum": [ "active", "inactive" ], "example": "active", "default": "inactive" }, "createdAt": { "type": "string", "description": "Date when the schedule was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the schedule was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date when the schedule was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true } }, "required": [ "id", "storeId", "name", "timezone", "scheduleGap", "appointmentsGap", "advanceScheduleDays", "availabilityType", "status", "createdAt", "updatedAt", "deletedAt" ] }, "ProductExternalIdLocationAvailability": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the location availability record", "example": "123e4567-e89b-12d3-a456-426614174000" }, "locationId": { "type": "string", "description": "ID of the location this availability applies to", "example": "123e4567-e89b-12d3-a456-426614174001" }, "fromDate": { "type": "string", "description": "Start date of the availability period (for specific date ranges) - specified in the location's schedule timezone, or user settings timezone if no schedule is assigned", "example": "2023-06-15", "nullable": true }, "fromTime": { "type": "string", "description": "Start time of the availability period - specified in the location's schedule timezone, or user settings timezone if no schedule is assigned", "example": "09:00:00" }, "toDate": { "type": "string", "description": "End date of the availability period (for specific date ranges) - specified in the location's schedule timezone, or user settings timezone if no schedule is assigned", "example": "2023-06-15", "nullable": true }, "toTime": { "type": "string", "description": "End time of the availability period - specified in the location's schedule timezone, or user settings timezone if no schedule is assigned", "example": "17:00:00" }, "day": { "type": "number", "description": "Day of the week (1=Monday to 7=Sunday) (for recurring weekly availabilities)", "example": 1, "nullable": true }, "status": { "type": "string", "description": "Status indicating whether this time period is available or unavailable", "enum": [ "available", "unavailable" ], "example": "available" }, "createdAt": { "format": "date-time", "type": "string", "description": "Date when the availability record was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date when the availability record was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true } }, "required": [ "id", "locationId", "fromDate", "fromTime", "toDate", "toTime", "day", "status", "createdAt", "updatedAt" ] }, "ProductExternalIdLocation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the location", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this location", "example": "123e4567-e89b-12d3-a456-426614174001" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this location (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "title": { "type": "string", "description": "Name of the location", "example": "Main Office", "nullable": true }, "description": { "type": "string", "description": "Description of the location", "example": "Our main downtown office location with 3 treatment rooms", "nullable": true }, "slug": { "type": "string", "description": "URL-friendly slug for the location (unique per store)", "example": "new-york" }, "type": { "type": "string", "description": "Type of location", "enum": [ "physical", "online", "delivery" ], "example": "physical" }, "link": { "type": "string", "description": "URL link for online locations", "example": "https://zoom.us/j/123456789", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of address for physical locations", "example": "123 Main Street", "nullable": true }, "addressLine2": { "type": "string", "description": "Second line of address for physical locations", "example": "Suite 200", "nullable": true }, "city": { "type": "string", "description": "City for physical locations", "example": "San Francisco", "nullable": true }, "state": { "type": "string", "description": "State/province for physical locations", "example": "CA", "nullable": true }, "postalCode": { "type": "string", "description": "Postal code for physical locations", "example": "94105", "nullable": true }, "country": { "type": "string", "description": "Country for physical locations", "example": "United States", "nullable": true }, "displayAddress": { "type": "string", "description": "Merchant-defined display address that overrides the auto-formatted address (emails, booking page). Null falls back to the concatenated address fields.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressPlaceId": { "type": "string", "description": "Google Place ID for the physical address", "example": "ChIJIQBpAG2ahYAR_6128GcTUEo", "nullable": true }, "latitude": { "type": "number", "description": "Latitude in WGS84", "example": 37.4224764, "nullable": true }, "longitude": { "type": "number", "description": "Longitude in WGS84", "example": -122.0842499, "nullable": true }, "createdAt": { "type": "string", "description": "Date when the location was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the location was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "type": "string", "description": "Date when the location was deleted (for soft deletes)", "example": "2023-03-10T11:45:00Z", "nullable": true }, "address": { "type": "string", "description": "The formatted address string", "nullable": true }, "staffMembers": { "description": "Staff members who can work at this location", "type": "array", "items": { "$ref": "#/components/schemas/ProductExternalIdLocationStaffMember" } }, "schedule": { "description": "Schedule assigned to the location", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ProductExternalIdLocationSchedule" } ] }, "availabilities": { "description": "Availability records for this location", "type": "array", "items": { "$ref": "#/components/schemas/ProductExternalIdLocationAvailability" } } }, "required": [ "id", "storeId", "scheduleId", "title", "description", "slug", "type", "link", "addressLine1", "addressLine2", "city", "state", "postalCode", "country", "addressPlaceId", "latitude", "longitude", "createdAt", "updatedAt", "deletedAt", "address", "staffMembers", "schedule", "availabilities" ] }, "ProductExternalIdFeedbackQuestion": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the feedback question", "example": "550e8400-e29b-41d4-a716-446655440000" }, "internalName": { "type": "string", "description": "Internal name for the question (not shown to customers)", "example": "Service Quality Rating Question" }, "required": { "type": "boolean", "description": "Whether the question is required to be answered", "example": true }, "type": { "type": "string", "description": "Type of input for the question", "enum": [ "single-line-text-field", "multi-line-text-field", "dropdown", "rating", "checkbox", "file-upload" ], "example": "rating" }, "order": { "type": "number", "description": "Display order of the question (lower numbers appear first)", "example": 1, "default": 0 }, "alwaysShow": { "type": "boolean", "description": "Whether this question is shown for all products in the store", "example": false, "default": false }, "fileConfig": { "type": "object", "description": "File-upload constraints (allowed categories, max size, max files). Only set when type is file-upload.", "example": { "categories": [ "images", "pdf" ], "maxSizeBytes": 26214400, "maxFiles": 5 }, "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the question was created", "example": "2023-01-01T00:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the question was last updated", "example": "2023-01-15T00:00:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date when the question was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this question", "example": "store-uuid" } }, "required": [ "id", "internalName", "required", "type", "order", "alwaysShow", "createdAt", "updatedAt", "deletedAt", "storeId" ] }, "ProductExternalIdCheckoutQuestion": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the checkout question", "example": "550e8400-e29b-41d4-a716-446655440000" }, "internalName": { "type": "string", "description": "Internal name for the question (not shown to customers)", "example": "Customer Allergies Question" }, "required": { "type": "boolean", "description": "Whether the question is required to be answered", "example": true }, "type": { "type": "string", "description": "Type of input for the question", "enum": [ "single-line-text-field", "multi-line-text-field", "dropdown", "rating", "checkbox", "file-upload" ], "example": "single-line-text-field" }, "order": { "type": "number", "description": "Display order of the question (lower numbers appear first)", "example": 1, "default": 0 }, "alwaysShow": { "type": "boolean", "description": "Whether this question is shown for all products in the store", "example": false, "default": false }, "fileConfig": { "type": "object", "description": "File-upload constraints (allowed categories, max size, max files). Only set when type is file-upload.", "example": { "categories": [ "images", "pdf" ], "maxSizeBytes": 26214400, "maxFiles": 5 }, "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the question was created", "example": "2023-01-01T00:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the question was last updated", "example": "2023-01-15T00:00:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date when the question was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this question", "example": "store-uuid" } }, "required": [ "id", "internalName", "required", "type", "order", "alwaysShow", "createdAt", "updatedAt", "deletedAt", "storeId" ] }, "ProductExternalIdResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "productId": { "type": "string", "description": "ID of the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID)", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID)", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this product", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the product (unique per store)", "example": "haircut-basic" }, "scheduleId": { "type": "string", "description": "ID of the schedule associated with this product" }, "productPoolId": { "type": "string", "description": "ID of the product pool this product belongs to (controls overlap prevention)", "nullable": true }, "title": { "type": "string", "description": "Title of the product", "example": "Haircut Service" }, "variantTitle": { "type": "string", "description": "Title of the specific product variant", "example": "Short Hair" }, "description": { "type": "string", "description": "Detailed description of the product" }, "imageId": { "type": "string", "description": "ID of the product image" }, "color": { "type": "string", "description": "Color code for displaying the product", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "BLUE", "default": "slate" }, "price": { "type": "number", "description": "Price of the product", "example": 250 }, "taxable": { "type": "boolean", "description": "Whether the product is taxable", "default": false }, "duration": { "type": "number", "description": "Duration of the service in seconds", "example": 3600 }, "allowCustomDuration": { "type": "boolean", "description": "Whether customers can customize the duration by selecting multiples of the base service duration (e.g., if base duration is 1 day, customers can book 1, 2, 3+ days)", "default": false }, "maxDuration": { "type": "number", "description": "When allow_custom_duration=true, maximum duration allowed for multi-duration bookings in seconds (-1 for unlimited)", "default": -1 }, "maxAttendees": { "type": "number", "description": "Maximum number of attendees allowed", "default": 1 }, "maxGuests": { "type": "number", "description": "Maximum number of guests allowed per appointment. Null means unlimited.", "nullable": true }, "allowGuests": { "type": "boolean", "description": "Whether customers can invite guests to the appointment", "default": false }, "allowCustomerReschedule": { "type": "boolean", "description": "Whether customers can reschedule their bookings", "default": false }, "allowCustomerCancel": { "type": "boolean", "description": "Whether customers can cancel their bookings", "default": false }, "rescheduleGap": { "type": "number", "description": "Time in seconds before appointment when rescheduling is no longer allowed" }, "cancelGap": { "type": "number", "description": "Time in seconds before appointment when cancellation is no longer allowed" }, "beforeGap": { "type": "number", "description": "Buffer time in seconds required before this service" }, "afterGap": { "type": "number", "description": "Buffer time in seconds required after this service" }, "fixedTimes": { "type": "boolean", "description": "When allow_custom_duration=true, whether appointments must start and end at fixed times (like fixed check-in/check-out times for multi-duration bookings)", "default": false }, "fixedStartTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must start (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "09:00:00" }, "fixedEndTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must end (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "17:00:00" }, "advanceScheduleThreshold": { "type": "number", "description": "How many days in advance bookings can be made", "default": 0 }, "sendConfirmationEmail": { "type": "boolean", "description": "Whether to send confirmation emails for bookings", "default": true }, "sendReminderEmail": { "type": "boolean", "description": "Whether to send reminder emails before appointments", "default": false }, "sendFeedbackEmail": { "type": "boolean", "description": "Whether to send feedback request emails after appointments", "default": false }, "skipCheckout": { "type": "boolean", "description": "Whether to skip the checkout process for this product (Shopify merchants only)", "default": false }, "status": { "type": "string", "description": "Current status of the product", "enum": [ "active", "inactive" ], "example": "ACTIVE", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the product was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the product was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the product was deleted (for soft deletes)" }, "image": { "description": "Primary image of the product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] }, "staffMembers": { "description": "Staff members who can provide this service", "type": "array", "items": { "$ref": "#/components/schemas/ProductExternalIdStaffMember" } }, "locations": { "description": "Locations where this service is offered", "type": "array", "items": { "$ref": "#/components/schemas/ProductExternalIdLocation" } }, "feedbackQuestions": { "description": "Feedback questions associated with this product", "type": "array", "items": { "$ref": "#/components/schemas/ProductExternalIdFeedbackQuestion" } }, "checkoutQuestions": { "description": "Checkout questions associated with this product", "type": "array", "items": { "$ref": "#/components/schemas/ProductExternalIdCheckoutQuestion" } } }, "required": [ "id", "productId", "externalId", "externalVariantId", "storeId", "slug", "scheduleId", "productPoolId", "title", "variantTitle", "description", "imageId", "color", "price", "taxable", "duration", "allowCustomDuration", "maxDuration", "maxAttendees", "maxGuests", "allowGuests", "allowCustomerReschedule", "allowCustomerCancel", "rescheduleGap", "cancelGap", "beforeGap", "afterGap", "fixedTimes", "fixedStartTime", "fixedEndTime", "advanceScheduleThreshold", "sendConfirmationEmail", "sendReminderEmail", "sendFeedbackEmail", "skipCheckout", "status", "createdAt", "updatedAt", "deletedAt", "staffMembers", "locations", "feedbackQuestions", "checkoutQuestions" ] }, "ProductExternalVariantStaffMember": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this staff member record", "example": "123e4567-e89b-12d3-a456-426614174111" }, "userId": { "type": "string", "description": "User ID of the staff member login identity (nullable until linked)", "example": "user-uuid" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this staff member, defines their availability", "example": "123e4567-e89b-12d3-a456-426614174000" }, "imageId": { "type": "string", "description": "ID of the image associated with this staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "firstName": { "type": "string", "description": "First name of the staff member", "example": "John" }, "lastName": { "type": "string", "description": "Last name of the staff member", "example": "Doe" }, "email": { "type": "string", "description": "Email address of the staff member, used for notifications and calendar integration", "example": "john.doe@example.com" }, "slug": { "type": "string", "description": "URL-friendly slug for the staff member (unique per store)", "example": "mike" }, "refreshToken": { "type": "string", "description": "Refresh token for integrations like Google Calendar", "example": "abc123xyz456" }, "createdAt": { "type": "string", "description": "Date and time when the staff member was created", "example": "2025-05-01T12:00:00Z" }, "updatedAt": { "type": "string", "description": "Date and time when the staff member was last updated", "example": "2025-05-15T14:30:00Z" }, "deletedAt": { "type": "string", "description": "Date and time when the staff member was soft deleted", "example": "2025-06-01T09:15:00Z" }, "image": { "description": "Profile image of the staff member", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "storeId", "userId", "scheduleId", "imageId", "firstName", "lastName", "email", "slug", "refreshToken", "createdAt", "updatedAt", "deletedAt" ] }, "ProductExternalVariantLocationStaffMember": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this staff member record", "example": "123e4567-e89b-12d3-a456-426614174111" }, "userId": { "type": "string", "description": "User ID of the staff member login identity (nullable until linked)", "example": "user-uuid" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this staff member, defines their availability", "example": "123e4567-e89b-12d3-a456-426614174000" }, "imageId": { "type": "string", "description": "ID of the image associated with this staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "firstName": { "type": "string", "description": "First name of the staff member", "example": "John" }, "lastName": { "type": "string", "description": "Last name of the staff member", "example": "Doe" }, "email": { "type": "string", "description": "Email address of the staff member, used for notifications and calendar integration", "example": "john.doe@example.com" }, "slug": { "type": "string", "description": "URL-friendly slug for the staff member (unique per store)", "example": "mike" }, "refreshToken": { "type": "string", "description": "Refresh token for integrations like Google Calendar", "example": "abc123xyz456" }, "createdAt": { "type": "string", "description": "Date and time when the staff member was created", "example": "2025-05-01T12:00:00Z" }, "updatedAt": { "type": "string", "description": "Date and time when the staff member was last updated", "example": "2025-05-15T14:30:00Z" }, "deletedAt": { "type": "string", "description": "Date and time when the staff member was soft deleted", "example": "2025-06-01T09:15:00Z" }, "image": { "description": "Profile image of the staff member", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "storeId", "userId", "scheduleId", "imageId", "firstName", "lastName", "email", "slug", "refreshToken", "createdAt", "updatedAt", "deletedAt" ] }, "ProductExternalVariantLocationSchedule": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the schedule", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this schedule", "example": "123e4567-e89b-12d3-a456-426614174001" }, "name": { "type": "string", "description": "Name of the schedule", "example": "Standard Business Hours", "nullable": true }, "timezone": { "type": "string", "description": "Timezone for the schedule", "example": "UTC", "default": "UTC" }, "scheduleGap": { "type": "string", "description": "Time slot frequency for the schedule", "enum": [ "every-10-minutes", "every-15-minutes", "every-20-minutes", "every-30-minutes", "every-60-minutes" ], "example": "every-15-minutes", "default": "every-15-minutes" }, "appointmentsGap": { "type": "number", "description": "Buffer time between appointments in seconds", "example": 900 }, "advanceScheduleDays": { "type": "number", "description": "Number of days customers can book in advance (-1 for unlimited)", "example": 60, "default": -1 }, "availabilityType": { "type": "string", "description": "Type of availability pattern for this schedule", "enum": [ "continuous", "recurring", "non-recurring" ], "example": "recurring", "default": "continuous" }, "status": { "type": "string", "description": "Status of the schedule", "enum": [ "active", "inactive" ], "example": "active", "default": "inactive" }, "createdAt": { "type": "string", "description": "Date when the schedule was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the schedule was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date when the schedule was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true } }, "required": [ "id", "storeId", "name", "timezone", "scheduleGap", "appointmentsGap", "advanceScheduleDays", "availabilityType", "status", "createdAt", "updatedAt", "deletedAt" ] }, "ProductExternalVariantLocationAvailability": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the location availability record", "example": "123e4567-e89b-12d3-a456-426614174000" }, "locationId": { "type": "string", "description": "ID of the location this availability applies to", "example": "123e4567-e89b-12d3-a456-426614174001" }, "fromDate": { "type": "string", "description": "Start date of the availability period (for specific date ranges) - specified in the location's schedule timezone, or user settings timezone if no schedule is assigned", "example": "2023-06-15", "nullable": true }, "fromTime": { "type": "string", "description": "Start time of the availability period - specified in the location's schedule timezone, or user settings timezone if no schedule is assigned", "example": "09:00:00" }, "toDate": { "type": "string", "description": "End date of the availability period (for specific date ranges) - specified in the location's schedule timezone, or user settings timezone if no schedule is assigned", "example": "2023-06-15", "nullable": true }, "toTime": { "type": "string", "description": "End time of the availability period - specified in the location's schedule timezone, or user settings timezone if no schedule is assigned", "example": "17:00:00" }, "day": { "type": "number", "description": "Day of the week (1=Monday to 7=Sunday) (for recurring weekly availabilities)", "example": 1, "nullable": true }, "status": { "type": "string", "description": "Status indicating whether this time period is available or unavailable", "enum": [ "available", "unavailable" ], "example": "available" }, "createdAt": { "format": "date-time", "type": "string", "description": "Date when the availability record was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date when the availability record was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true } }, "required": [ "id", "locationId", "fromDate", "fromTime", "toDate", "toTime", "day", "status", "createdAt", "updatedAt" ] }, "ProductExternalVariantLocation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the location", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this location", "example": "123e4567-e89b-12d3-a456-426614174001" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this location (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "title": { "type": "string", "description": "Name of the location", "example": "Main Office", "nullable": true }, "description": { "type": "string", "description": "Description of the location", "example": "Our main downtown office location with 3 treatment rooms", "nullable": true }, "slug": { "type": "string", "description": "URL-friendly slug for the location (unique per store)", "example": "new-york" }, "type": { "type": "string", "description": "Type of location", "enum": [ "physical", "online", "delivery" ], "example": "physical" }, "link": { "type": "string", "description": "URL link for online locations", "example": "https://zoom.us/j/123456789", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of address for physical locations", "example": "123 Main Street", "nullable": true }, "addressLine2": { "type": "string", "description": "Second line of address for physical locations", "example": "Suite 200", "nullable": true }, "city": { "type": "string", "description": "City for physical locations", "example": "San Francisco", "nullable": true }, "state": { "type": "string", "description": "State/province for physical locations", "example": "CA", "nullable": true }, "postalCode": { "type": "string", "description": "Postal code for physical locations", "example": "94105", "nullable": true }, "country": { "type": "string", "description": "Country for physical locations", "example": "United States", "nullable": true }, "displayAddress": { "type": "string", "description": "Merchant-defined display address that overrides the auto-formatted address (emails, booking page). Null falls back to the concatenated address fields.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressPlaceId": { "type": "string", "description": "Google Place ID for the physical address", "example": "ChIJIQBpAG2ahYAR_6128GcTUEo", "nullable": true }, "latitude": { "type": "number", "description": "Latitude in WGS84", "example": 37.4224764, "nullable": true }, "longitude": { "type": "number", "description": "Longitude in WGS84", "example": -122.0842499, "nullable": true }, "createdAt": { "type": "string", "description": "Date when the location was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the location was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "type": "string", "description": "Date when the location was deleted (for soft deletes)", "example": "2023-03-10T11:45:00Z", "nullable": true }, "address": { "type": "string", "description": "The formatted address string", "nullable": true }, "staffMembers": { "description": "Staff members who can work at this location", "type": "array", "items": { "$ref": "#/components/schemas/ProductExternalVariantLocationStaffMember" } }, "schedule": { "description": "Schedule assigned to the location", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ProductExternalVariantLocationSchedule" } ] }, "availabilities": { "description": "Availability records for this location", "type": "array", "items": { "$ref": "#/components/schemas/ProductExternalVariantLocationAvailability" } } }, "required": [ "id", "storeId", "scheduleId", "title", "description", "slug", "type", "link", "addressLine1", "addressLine2", "city", "state", "postalCode", "country", "addressPlaceId", "latitude", "longitude", "createdAt", "updatedAt", "deletedAt", "address", "staffMembers", "schedule", "availabilities" ] }, "ProductExternalVariantSchedule": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the schedule", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this schedule", "example": "123e4567-e89b-12d3-a456-426614174001" }, "name": { "type": "string", "description": "Name of the schedule", "example": "Standard Business Hours", "nullable": true }, "timezone": { "type": "string", "description": "Timezone for the schedule", "example": "UTC", "default": "UTC" }, "scheduleGap": { "type": "string", "description": "Time slot frequency for the schedule", "enum": [ "every-10-minutes", "every-15-minutes", "every-20-minutes", "every-30-minutes", "every-60-minutes" ], "example": "every-15-minutes", "default": "every-15-minutes" }, "appointmentsGap": { "type": "number", "description": "Buffer time between appointments in seconds", "example": 900 }, "advanceScheduleDays": { "type": "number", "description": "Number of days customers can book in advance (-1 for unlimited)", "example": 60, "default": -1 }, "availabilityType": { "type": "string", "description": "Type of availability pattern for this schedule", "enum": [ "continuous", "recurring", "non-recurring" ], "example": "recurring", "default": "continuous" }, "status": { "type": "string", "description": "Status of the schedule", "enum": [ "active", "inactive" ], "example": "active", "default": "inactive" }, "createdAt": { "type": "string", "description": "Date when the schedule was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the schedule was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date when the schedule was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true } }, "required": [ "id", "storeId", "name", "timezone", "scheduleGap", "appointmentsGap", "advanceScheduleDays", "availabilityType", "status", "createdAt", "updatedAt", "deletedAt" ] }, "ProductExternalVariantFeedbackQuestionTranslation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the translation", "example": "550e8400-e29b-41d4-a716-446655440000" }, "questionId": { "type": "string", "description": "ID of the feedback question this translation belongs to", "example": "550e8400-e29b-41d4-a716-446655440000" }, "title": { "type": "string", "description": "Translated title of the question shown to customers", "example": "How would you rate our service?" }, "description": { "type": "string", "description": "Translated description or additional instructions for the question", "example": "Please rate your overall satisfaction with our service." }, "options": { "description": "Available options for dropdown or rating questions in this language", "example": [ "Poor", "Fair", "Good", "Very Good", "Excellent" ], "nullable": true, "type": "array", "items": { "type": "string" } }, "languageCode": { "type": "string", "description": "Language code for this translation", "enum": [ "af", "ak", "am", "ar", "as", "az", "be", "bg", "bm", "bn", "bo", "br", "bs", "ca", "ce", "cs", "cu", "cy", "da", "de", "dz", "ee", "el", "en", "eo", "es", "et", "eu", "fa", "ff", "fi", "fo", "fr", "fy", "ga", "gd", "gl", "gu", "gv", "ha", "he", "hi", "hr", "hu", "hy", "ia", "id", "ig", "ii", "is", "it", "ja", "jv", "ka", "ki", "kk", "kl", "km", "kn", "ko", "ks", "ku", "kw", "ky", "lb", "lg", "ln", "lo", "lt", "lu", "lv", "mg", "mi", "mk", "ml", "mn", "mr", "ms", "mt", "my", "nb", "nd", "ne", "nl", "nn", "no", "om", "or", "os", "pa", "pl", "ps", "pt", "pt_br", "pt_pt", "qu", "rm", "rn", "ro", "ru", "rw", "sd", "se", "sg", "si", "sk", "sl", "sn", "so", "sq", "sr", "su", "sv", "sw", "ta", "te", "tg", "th", "ti", "tk", "to", "tr", "tt", "ug", "uk", "ur", "uz", "vi", "vo", "wo", "xh", "yi", "yo", "zh", "zh_cn", "zh_tw", "zu" ], "example": "en" }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the translation was created", "example": "2023-01-01T00:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the translation was last updated", "example": "2023-01-15T00:00:00Z", "nullable": true } }, "required": [ "id", "questionId", "title", "description", "options", "languageCode", "createdAt", "updatedAt" ] }, "ProductExternalVariantFeedbackQuestion": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the feedback question", "example": "550e8400-e29b-41d4-a716-446655440000" }, "internalName": { "type": "string", "description": "Internal name for the question (not shown to customers)", "example": "Service Quality Rating Question" }, "required": { "type": "boolean", "description": "Whether the question is required to be answered", "example": true }, "type": { "type": "string", "description": "Type of input for the question", "enum": [ "single-line-text-field", "multi-line-text-field", "dropdown", "rating", "checkbox", "file-upload" ], "example": "rating" }, "order": { "type": "number", "description": "Display order of the question (lower numbers appear first)", "example": 1, "default": 0 }, "alwaysShow": { "type": "boolean", "description": "Whether this question is shown for all products in the store", "example": false, "default": false }, "fileConfig": { "type": "object", "description": "File-upload constraints (allowed categories, max size, max files). Only set when type is file-upload.", "example": { "categories": [ "images", "pdf" ], "maxSizeBytes": 26214400, "maxFiles": 5 }, "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the question was created", "example": "2023-01-01T00:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the question was last updated", "example": "2023-01-15T00:00:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date when the question was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this question", "example": "store-uuid" }, "translations": { "description": "Translations of this question in various languages", "type": "array", "items": { "$ref": "#/components/schemas/ProductExternalVariantFeedbackQuestionTranslation" } } }, "required": [ "id", "internalName", "required", "type", "order", "alwaysShow", "createdAt", "updatedAt", "deletedAt", "storeId", "translations" ] }, "ProductExternalVariantCheckoutQuestionTranslation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the translation", "example": "550e8400-e29b-41d4-a716-446655440000" }, "questionId": { "type": "string", "description": "ID of the checkout question this translation belongs to", "example": "550e8400-e29b-41d4-a716-446655440000" }, "title": { "type": "string", "description": "Translated title of the question shown to customers", "example": "Do you have any allergies?" }, "description": { "type": "string", "description": "Translated description or additional instructions for the question", "example": "Please let us know about any food allergies or dietary restrictions." }, "options": { "description": "Available options for dropdown or checkbox questions in this language", "example": [ "Nut allergy", "Gluten intolerance", "Lactose intolerance", "None" ], "nullable": true, "type": "array", "items": { "type": "string" } }, "languageCode": { "type": "string", "description": "Language code for this translation", "enum": [ "af", "ak", "am", "ar", "as", "az", "be", "bg", "bm", "bn", "bo", "br", "bs", "ca", "ce", "cs", "cu", "cy", "da", "de", "dz", "ee", "el", "en", "eo", "es", "et", "eu", "fa", "ff", "fi", "fo", "fr", "fy", "ga", "gd", "gl", "gu", "gv", "ha", "he", "hi", "hr", "hu", "hy", "ia", "id", "ig", "ii", "is", "it", "ja", "jv", "ka", "ki", "kk", "kl", "km", "kn", "ko", "ks", "ku", "kw", "ky", "lb", "lg", "ln", "lo", "lt", "lu", "lv", "mg", "mi", "mk", "ml", "mn", "mr", "ms", "mt", "my", "nb", "nd", "ne", "nl", "nn", "no", "om", "or", "os", "pa", "pl", "ps", "pt", "pt_br", "pt_pt", "qu", "rm", "rn", "ro", "ru", "rw", "sd", "se", "sg", "si", "sk", "sl", "sn", "so", "sq", "sr", "su", "sv", "sw", "ta", "te", "tg", "th", "ti", "tk", "to", "tr", "tt", "ug", "uk", "ur", "uz", "vi", "vo", "wo", "xh", "yi", "yo", "zh", "zh_cn", "zh_tw", "zu" ], "example": "en" }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the translation was created", "example": "2023-01-01T00:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the translation was last updated", "example": "2023-01-15T00:00:00Z", "nullable": true } }, "required": [ "id", "questionId", "title", "description", "options", "languageCode", "createdAt", "updatedAt" ] }, "ProductExternalVariantCheckoutQuestion": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the checkout question", "example": "550e8400-e29b-41d4-a716-446655440000" }, "internalName": { "type": "string", "description": "Internal name for the question (not shown to customers)", "example": "Customer Allergies Question" }, "required": { "type": "boolean", "description": "Whether the question is required to be answered", "example": true }, "type": { "type": "string", "description": "Type of input for the question", "enum": [ "single-line-text-field", "multi-line-text-field", "dropdown", "rating", "checkbox", "file-upload" ], "example": "single-line-text-field" }, "order": { "type": "number", "description": "Display order of the question (lower numbers appear first)", "example": 1, "default": 0 }, "alwaysShow": { "type": "boolean", "description": "Whether this question is shown for all products in the store", "example": false, "default": false }, "fileConfig": { "type": "object", "description": "File-upload constraints (allowed categories, max size, max files). Only set when type is file-upload.", "example": { "categories": [ "images", "pdf" ], "maxSizeBytes": 26214400, "maxFiles": 5 }, "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the question was created", "example": "2023-01-01T00:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the question was last updated", "example": "2023-01-15T00:00:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date when the question was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this question", "example": "store-uuid" }, "translations": { "description": "Translations of this question in various languages", "type": "array", "items": { "$ref": "#/components/schemas/ProductExternalVariantCheckoutQuestionTranslation" } } }, "required": [ "id", "internalName", "required", "type", "order", "alwaysShow", "createdAt", "updatedAt", "deletedAt", "storeId", "translations" ] }, "ProductExternalVariantResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "productId": { "type": "string", "description": "ID of the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID)", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID)", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this product", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the product (unique per store)", "example": "haircut-basic" }, "scheduleId": { "type": "string", "description": "ID of the schedule associated with this product" }, "productPoolId": { "type": "string", "description": "ID of the product pool this product belongs to (controls overlap prevention)", "nullable": true }, "title": { "type": "string", "description": "Title of the product", "example": "Haircut Service" }, "variantTitle": { "type": "string", "description": "Title of the specific product variant", "example": "Short Hair" }, "description": { "type": "string", "description": "Detailed description of the product" }, "imageId": { "type": "string", "description": "ID of the product image" }, "color": { "type": "string", "description": "Color code for displaying the product", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "BLUE", "default": "slate" }, "price": { "type": "number", "description": "Price of the product", "example": 250 }, "taxable": { "type": "boolean", "description": "Whether the product is taxable", "default": false }, "duration": { "type": "number", "description": "Duration of the service in seconds", "example": 3600 }, "allowCustomDuration": { "type": "boolean", "description": "Whether customers can customize the duration by selecting multiples of the base service duration (e.g., if base duration is 1 day, customers can book 1, 2, 3+ days)", "default": false }, "maxDuration": { "type": "number", "description": "When allow_custom_duration=true, maximum duration allowed for multi-duration bookings in seconds (-1 for unlimited)", "default": -1 }, "maxAttendees": { "type": "number", "description": "Maximum number of attendees allowed", "default": 1 }, "maxGuests": { "type": "number", "description": "Maximum number of guests allowed per appointment. Null means unlimited.", "nullable": true }, "allowGuests": { "type": "boolean", "description": "Whether customers can invite guests to the appointment", "default": false }, "allowCustomerReschedule": { "type": "boolean", "description": "Whether customers can reschedule their bookings", "default": false }, "allowCustomerCancel": { "type": "boolean", "description": "Whether customers can cancel their bookings", "default": false }, "rescheduleGap": { "type": "number", "description": "Time in seconds before appointment when rescheduling is no longer allowed" }, "cancelGap": { "type": "number", "description": "Time in seconds before appointment when cancellation is no longer allowed" }, "beforeGap": { "type": "number", "description": "Buffer time in seconds required before this service" }, "afterGap": { "type": "number", "description": "Buffer time in seconds required after this service" }, "fixedTimes": { "type": "boolean", "description": "When allow_custom_duration=true, whether appointments must start and end at fixed times (like fixed check-in/check-out times for multi-duration bookings)", "default": false }, "fixedStartTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must start (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "09:00:00" }, "fixedEndTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must end (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "17:00:00" }, "advanceScheduleThreshold": { "type": "number", "description": "How many days in advance bookings can be made", "default": 0 }, "sendConfirmationEmail": { "type": "boolean", "description": "Whether to send confirmation emails for bookings", "default": true }, "sendReminderEmail": { "type": "boolean", "description": "Whether to send reminder emails before appointments", "default": false }, "sendFeedbackEmail": { "type": "boolean", "description": "Whether to send feedback request emails after appointments", "default": false }, "skipCheckout": { "type": "boolean", "description": "Whether to skip the checkout process for this product (Shopify merchants only)", "default": false }, "status": { "type": "string", "description": "Current status of the product", "enum": [ "active", "inactive" ], "example": "ACTIVE", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the product was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the product was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the product was deleted (for soft deletes)" }, "image": { "description": "Primary image of the product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] }, "staffMembers": { "description": "Staff members who can provide this service", "type": "array", "items": { "$ref": "#/components/schemas/ProductExternalVariantStaffMember" } }, "locations": { "description": "Locations where this service is offered", "type": "array", "items": { "$ref": "#/components/schemas/ProductExternalVariantLocation" } }, "schedule": { "description": "Schedule associated with this product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ProductExternalVariantSchedule" } ] }, "feedbackQuestions": { "description": "Feedback questions associated with this product", "type": "array", "items": { "$ref": "#/components/schemas/ProductExternalVariantFeedbackQuestion" } }, "checkoutQuestions": { "description": "Checkout questions associated with this product", "type": "array", "items": { "$ref": "#/components/schemas/ProductExternalVariantCheckoutQuestion" } } }, "required": [ "id", "productId", "externalId", "externalVariantId", "storeId", "slug", "scheduleId", "productPoolId", "title", "variantTitle", "description", "imageId", "color", "price", "taxable", "duration", "allowCustomDuration", "maxDuration", "maxAttendees", "maxGuests", "allowGuests", "allowCustomerReschedule", "allowCustomerCancel", "rescheduleGap", "cancelGap", "beforeGap", "afterGap", "fixedTimes", "fixedStartTime", "fixedEndTime", "advanceScheduleThreshold", "sendConfirmationEmail", "sendReminderEmail", "sendFeedbackEmail", "skipCheckout", "status", "createdAt", "updatedAt", "deletedAt", "staffMembers", "locations", "schedule", "feedbackQuestions", "checkoutQuestions" ] }, "ProductListVariantStaffMemberLocation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the location", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this location", "example": "123e4567-e89b-12d3-a456-426614174001" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this location (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "title": { "type": "string", "description": "Name of the location", "example": "Main Office", "nullable": true }, "description": { "type": "string", "description": "Description of the location", "example": "Our main downtown office location with 3 treatment rooms", "nullable": true }, "slug": { "type": "string", "description": "URL-friendly slug for the location (unique per store)", "example": "new-york" }, "type": { "type": "string", "description": "Type of location", "enum": [ "physical", "online", "delivery" ], "example": "physical" }, "link": { "type": "string", "description": "URL link for online locations", "example": "https://zoom.us/j/123456789", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of address for physical locations", "example": "123 Main Street", "nullable": true }, "addressLine2": { "type": "string", "description": "Second line of address for physical locations", "example": "Suite 200", "nullable": true }, "city": { "type": "string", "description": "City for physical locations", "example": "San Francisco", "nullable": true }, "state": { "type": "string", "description": "State/province for physical locations", "example": "CA", "nullable": true }, "postalCode": { "type": "string", "description": "Postal code for physical locations", "example": "94105", "nullable": true }, "country": { "type": "string", "description": "Country for physical locations", "example": "United States", "nullable": true }, "displayAddress": { "type": "string", "description": "Merchant-defined display address that overrides the auto-formatted address (emails, booking page). Null falls back to the concatenated address fields.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressPlaceId": { "type": "string", "description": "Google Place ID for the physical address", "example": "ChIJIQBpAG2ahYAR_6128GcTUEo", "nullable": true }, "latitude": { "type": "number", "description": "Latitude in WGS84", "example": 37.4224764, "nullable": true }, "longitude": { "type": "number", "description": "Longitude in WGS84", "example": -122.0842499, "nullable": true }, "createdAt": { "type": "string", "description": "Date when the location was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the location was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "type": "string", "description": "Date when the location was deleted (for soft deletes)", "example": "2023-03-10T11:45:00Z", "nullable": true }, "address": { "type": "string", "description": "The formatted address string", "nullable": true } }, "required": [ "id", "storeId", "scheduleId", "title", "description", "slug", "type", "link", "addressLine1", "addressLine2", "city", "state", "postalCode", "country", "addressPlaceId", "latitude", "longitude", "createdAt", "updatedAt", "deletedAt", "address" ] }, "ProductListVariantStaffMember": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this staff member record", "example": "123e4567-e89b-12d3-a456-426614174111" }, "userId": { "type": "string", "description": "User ID of the staff member login identity (nullable until linked)", "example": "user-uuid" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this staff member, defines their availability", "example": "123e4567-e89b-12d3-a456-426614174000" }, "imageId": { "type": "string", "description": "ID of the image associated with this staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "firstName": { "type": "string", "description": "First name of the staff member", "example": "John" }, "lastName": { "type": "string", "description": "Last name of the staff member", "example": "Doe" }, "email": { "type": "string", "description": "Email address of the staff member, used for notifications and calendar integration", "example": "john.doe@example.com" }, "slug": { "type": "string", "description": "URL-friendly slug for the staff member (unique per store)", "example": "mike" }, "refreshToken": { "type": "string", "description": "Refresh token for integrations like Google Calendar", "example": "abc123xyz456" }, "createdAt": { "type": "string", "description": "Date and time when the staff member was created", "example": "2025-05-01T12:00:00Z" }, "updatedAt": { "type": "string", "description": "Date and time when the staff member was last updated", "example": "2025-05-15T14:30:00Z" }, "deletedAt": { "type": "string", "description": "Date and time when the staff member was soft deleted", "example": "2025-06-01T09:15:00Z" }, "image": { "description": "Profile image of the staff member", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] }, "locations": { "description": "Locations where this staff member works", "type": "array", "items": { "$ref": "#/components/schemas/ProductListVariantStaffMemberLocation" } } }, "required": [ "id", "storeId", "userId", "scheduleId", "imageId", "firstName", "lastName", "email", "slug", "refreshToken", "createdAt", "updatedAt", "deletedAt", "locations" ] }, "ProductListVariantLocationStaffMember": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this staff member record", "example": "123e4567-e89b-12d3-a456-426614174111" }, "userId": { "type": "string", "description": "User ID of the staff member login identity (nullable until linked)", "example": "user-uuid" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this staff member, defines their availability", "example": "123e4567-e89b-12d3-a456-426614174000" }, "imageId": { "type": "string", "description": "ID of the image associated with this staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "firstName": { "type": "string", "description": "First name of the staff member", "example": "John" }, "lastName": { "type": "string", "description": "Last name of the staff member", "example": "Doe" }, "email": { "type": "string", "description": "Email address of the staff member, used for notifications and calendar integration", "example": "john.doe@example.com" }, "slug": { "type": "string", "description": "URL-friendly slug for the staff member (unique per store)", "example": "mike" }, "refreshToken": { "type": "string", "description": "Refresh token for integrations like Google Calendar", "example": "abc123xyz456" }, "createdAt": { "type": "string", "description": "Date and time when the staff member was created", "example": "2025-05-01T12:00:00Z" }, "updatedAt": { "type": "string", "description": "Date and time when the staff member was last updated", "example": "2025-05-15T14:30:00Z" }, "deletedAt": { "type": "string", "description": "Date and time when the staff member was soft deleted", "example": "2025-06-01T09:15:00Z" }, "image": { "description": "Profile image of the staff member", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "storeId", "userId", "scheduleId", "imageId", "firstName", "lastName", "email", "slug", "refreshToken", "createdAt", "updatedAt", "deletedAt" ] }, "ProductListVariantLocation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the location", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this location", "example": "123e4567-e89b-12d3-a456-426614174001" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this location (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "title": { "type": "string", "description": "Name of the location", "example": "Main Office", "nullable": true }, "description": { "type": "string", "description": "Description of the location", "example": "Our main downtown office location with 3 treatment rooms", "nullable": true }, "slug": { "type": "string", "description": "URL-friendly slug for the location (unique per store)", "example": "new-york" }, "type": { "type": "string", "description": "Type of location", "enum": [ "physical", "online", "delivery" ], "example": "physical" }, "link": { "type": "string", "description": "URL link for online locations", "example": "https://zoom.us/j/123456789", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of address for physical locations", "example": "123 Main Street", "nullable": true }, "addressLine2": { "type": "string", "description": "Second line of address for physical locations", "example": "Suite 200", "nullable": true }, "city": { "type": "string", "description": "City for physical locations", "example": "San Francisco", "nullable": true }, "state": { "type": "string", "description": "State/province for physical locations", "example": "CA", "nullable": true }, "postalCode": { "type": "string", "description": "Postal code for physical locations", "example": "94105", "nullable": true }, "country": { "type": "string", "description": "Country for physical locations", "example": "United States", "nullable": true }, "displayAddress": { "type": "string", "description": "Merchant-defined display address that overrides the auto-formatted address (emails, booking page). Null falls back to the concatenated address fields.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressPlaceId": { "type": "string", "description": "Google Place ID for the physical address", "example": "ChIJIQBpAG2ahYAR_6128GcTUEo", "nullable": true }, "latitude": { "type": "number", "description": "Latitude in WGS84", "example": 37.4224764, "nullable": true }, "longitude": { "type": "number", "description": "Longitude in WGS84", "example": -122.0842499, "nullable": true }, "createdAt": { "type": "string", "description": "Date when the location was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the location was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "type": "string", "description": "Date when the location was deleted (for soft deletes)", "example": "2023-03-10T11:45:00Z", "nullable": true }, "address": { "type": "string", "description": "The formatted address string", "nullable": true }, "staffMembers": { "description": "Staff members who can work at this location", "type": "array", "items": { "$ref": "#/components/schemas/ProductListVariantLocationStaffMember" } } }, "required": [ "id", "storeId", "scheduleId", "title", "description", "slug", "type", "link", "addressLine1", "addressLine2", "city", "state", "postalCode", "country", "addressPlaceId", "latitude", "longitude", "createdAt", "updatedAt", "deletedAt", "address", "staffMembers" ] }, "ProductListVariantSchedule": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the schedule", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this schedule", "example": "123e4567-e89b-12d3-a456-426614174001" }, "name": { "type": "string", "description": "Name of the schedule", "example": "Standard Business Hours", "nullable": true }, "timezone": { "type": "string", "description": "Timezone for the schedule", "example": "UTC", "default": "UTC" }, "scheduleGap": { "type": "string", "description": "Time slot frequency for the schedule", "enum": [ "every-10-minutes", "every-15-minutes", "every-20-minutes", "every-30-minutes", "every-60-minutes" ], "example": "every-15-minutes", "default": "every-15-minutes" }, "appointmentsGap": { "type": "number", "description": "Buffer time between appointments in seconds", "example": 900 }, "advanceScheduleDays": { "type": "number", "description": "Number of days customers can book in advance (-1 for unlimited)", "example": 60, "default": -1 }, "availabilityType": { "type": "string", "description": "Type of availability pattern for this schedule", "enum": [ "continuous", "recurring", "non-recurring" ], "example": "recurring", "default": "continuous" }, "status": { "type": "string", "description": "Status of the schedule", "enum": [ "active", "inactive" ], "example": "active", "default": "inactive" }, "createdAt": { "type": "string", "description": "Date when the schedule was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the schedule was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date when the schedule was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true } }, "required": [ "id", "storeId", "name", "timezone", "scheduleGap", "appointmentsGap", "advanceScheduleDays", "availabilityType", "status", "createdAt", "updatedAt", "deletedAt" ] }, "ProductListVariantCollection": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the product collection" }, "storeId": { "type": "string", "description": "Identifier of the store that owns the collection" }, "title": { "type": "string", "description": "Title of the product collection", "example": "Hair Services" }, "description": { "type": "string", "description": "Description of the product collection" }, "slug": { "type": "string", "description": "URL-friendly slug for the product collection (unique per store)", "example": "featured" }, "isVisible": { "type": "boolean", "description": "Visibility flag for the collection", "default": true }, "createdAt": { "type": "string", "description": "Timestamp when the collection was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the collection was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the collection was soft-deleted" } }, "required": [ "id", "storeId", "title", "description", "slug", "isVisible", "createdAt", "updatedAt", "deletedAt" ] }, "ProductListVariantProductPool": { "type": "object", "properties": { "id": { "type": "string" }, "storeId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "deletedAt": { "type": "string" } }, "required": [ "id", "storeId", "name", "description", "status", "createdAt", "updatedAt", "deletedAt" ] }, "ProductListVariant": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "productId": { "type": "string", "description": "ID of the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID)", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID)", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this product", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the product (unique per store)", "example": "haircut-basic" }, "scheduleId": { "type": "string", "description": "ID of the schedule associated with this product" }, "productPoolId": { "type": "string", "description": "ID of the product pool this product belongs to (controls overlap prevention)", "nullable": true }, "title": { "type": "string", "description": "Title of the product", "example": "Haircut Service" }, "variantTitle": { "type": "string", "description": "Title of the specific product variant", "example": "Short Hair" }, "description": { "type": "string", "description": "Detailed description of the product" }, "imageId": { "type": "string", "description": "ID of the product image" }, "color": { "type": "string", "description": "Color code for displaying the product", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "BLUE", "default": "slate" }, "price": { "type": "number", "description": "Price of the product", "example": 250 }, "taxable": { "type": "boolean", "description": "Whether the product is taxable", "default": false }, "duration": { "type": "number", "description": "Duration of the service in seconds", "example": 3600 }, "allowCustomDuration": { "type": "boolean", "description": "Whether customers can customize the duration by selecting multiples of the base service duration (e.g., if base duration is 1 day, customers can book 1, 2, 3+ days)", "default": false }, "maxDuration": { "type": "number", "description": "When allow_custom_duration=true, maximum duration allowed for multi-duration bookings in seconds (-1 for unlimited)", "default": -1 }, "maxAttendees": { "type": "number", "description": "Maximum number of attendees allowed", "default": 1 }, "maxGuests": { "type": "number", "description": "Maximum number of guests allowed per appointment. Null means unlimited.", "nullable": true }, "allowGuests": { "type": "boolean", "description": "Whether customers can invite guests to the appointment", "default": false }, "allowCustomerReschedule": { "type": "boolean", "description": "Whether customers can reschedule their bookings", "default": false }, "allowCustomerCancel": { "type": "boolean", "description": "Whether customers can cancel their bookings", "default": false }, "rescheduleGap": { "type": "number", "description": "Time in seconds before appointment when rescheduling is no longer allowed" }, "cancelGap": { "type": "number", "description": "Time in seconds before appointment when cancellation is no longer allowed" }, "beforeGap": { "type": "number", "description": "Buffer time in seconds required before this service" }, "afterGap": { "type": "number", "description": "Buffer time in seconds required after this service" }, "fixedTimes": { "type": "boolean", "description": "When allow_custom_duration=true, whether appointments must start and end at fixed times (like fixed check-in/check-out times for multi-duration bookings)", "default": false }, "fixedStartTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must start (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "09:00:00" }, "fixedEndTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must end (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "17:00:00" }, "advanceScheduleThreshold": { "type": "number", "description": "How many days in advance bookings can be made", "default": 0 }, "sendConfirmationEmail": { "type": "boolean", "description": "Whether to send confirmation emails for bookings", "default": true }, "sendReminderEmail": { "type": "boolean", "description": "Whether to send reminder emails before appointments", "default": false }, "sendFeedbackEmail": { "type": "boolean", "description": "Whether to send feedback request emails after appointments", "default": false }, "skipCheckout": { "type": "boolean", "description": "Whether to skip the checkout process for this product (Shopify merchants only)", "default": false }, "status": { "type": "string", "description": "Current status of the product", "enum": [ "active", "inactive" ], "example": "ACTIVE", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the product was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the product was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the product was deleted (for soft deletes)" }, "image": { "description": "Primary image of the product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] }, "staffMembers": { "description": "Staff members who can provide this service", "type": "array", "items": { "$ref": "#/components/schemas/ProductListVariantStaffMember" } }, "locations": { "description": "Locations where this service is offered", "type": "array", "items": { "$ref": "#/components/schemas/ProductListVariantLocation" } }, "schedule": { "description": "Schedule associated with this product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ProductListVariantSchedule" } ] }, "images": { "description": "Images associated with this product", "type": "array", "items": { "$ref": "#/components/schemas/Image" } }, "collections": { "description": "Collections assigned to this product", "type": "array", "items": { "$ref": "#/components/schemas/ProductListVariantCollection" } }, "productPool": { "description": "Resource group this product belongs to", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ProductListVariantProductPool" } ] } }, "required": [ "id", "productId", "externalId", "externalVariantId", "storeId", "slug", "scheduleId", "productPoolId", "title", "variantTitle", "description", "imageId", "color", "price", "taxable", "duration", "allowCustomDuration", "maxDuration", "maxAttendees", "maxGuests", "allowGuests", "allowCustomerReschedule", "allowCustomerCancel", "rescheduleGap", "cancelGap", "beforeGap", "afterGap", "fixedTimes", "fixedStartTime", "fixedEndTime", "advanceScheduleThreshold", "sendConfirmationEmail", "sendReminderEmail", "sendFeedbackEmail", "skipCheckout", "status", "createdAt", "updatedAt", "deletedAt", "staffMembers", "locations", "schedule", "images", "collections", "productPool" ] }, "ProductListItemResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "productId": { "type": "string", "description": "ID of the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID)", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID)", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this product", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the product (unique per store)", "example": "haircut-basic" }, "scheduleId": { "type": "string", "description": "ID of the schedule associated with this product" }, "productPoolId": { "type": "string", "description": "ID of the product pool this product belongs to (controls overlap prevention)", "nullable": true }, "title": { "type": "string", "description": "Title of the product", "example": "Haircut Service" }, "variantTitle": { "type": "string", "description": "Title of the specific product variant", "example": "Short Hair" }, "description": { "type": "string", "description": "Detailed description of the product" }, "imageId": { "type": "string", "description": "ID of the product image" }, "color": { "type": "string", "description": "Color code for displaying the product", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "BLUE", "default": "slate" }, "price": { "type": "number", "description": "Price of the product", "example": 250 }, "taxable": { "type": "boolean", "description": "Whether the product is taxable", "default": false }, "duration": { "type": "number", "description": "Duration of the service in seconds", "example": 3600 }, "allowCustomDuration": { "type": "boolean", "description": "Whether customers can customize the duration by selecting multiples of the base service duration (e.g., if base duration is 1 day, customers can book 1, 2, 3+ days)", "default": false }, "maxDuration": { "type": "number", "description": "When allow_custom_duration=true, maximum duration allowed for multi-duration bookings in seconds (-1 for unlimited)", "default": -1 }, "maxAttendees": { "type": "number", "description": "Maximum number of attendees allowed", "default": 1 }, "maxGuests": { "type": "number", "description": "Maximum number of guests allowed per appointment. Null means unlimited.", "nullable": true }, "allowGuests": { "type": "boolean", "description": "Whether customers can invite guests to the appointment", "default": false }, "allowCustomerReschedule": { "type": "boolean", "description": "Whether customers can reschedule their bookings", "default": false }, "allowCustomerCancel": { "type": "boolean", "description": "Whether customers can cancel their bookings", "default": false }, "rescheduleGap": { "type": "number", "description": "Time in seconds before appointment when rescheduling is no longer allowed" }, "cancelGap": { "type": "number", "description": "Time in seconds before appointment when cancellation is no longer allowed" }, "beforeGap": { "type": "number", "description": "Buffer time in seconds required before this service" }, "afterGap": { "type": "number", "description": "Buffer time in seconds required after this service" }, "fixedTimes": { "type": "boolean", "description": "When allow_custom_duration=true, whether appointments must start and end at fixed times (like fixed check-in/check-out times for multi-duration bookings)", "default": false }, "fixedStartTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must start (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "09:00:00" }, "fixedEndTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must end (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "17:00:00" }, "advanceScheduleThreshold": { "type": "number", "description": "How many days in advance bookings can be made", "default": 0 }, "sendConfirmationEmail": { "type": "boolean", "description": "Whether to send confirmation emails for bookings", "default": true }, "sendReminderEmail": { "type": "boolean", "description": "Whether to send reminder emails before appointments", "default": false }, "sendFeedbackEmail": { "type": "boolean", "description": "Whether to send feedback request emails after appointments", "default": false }, "skipCheckout": { "type": "boolean", "description": "Whether to skip the checkout process for this product (Shopify merchants only)", "default": false }, "status": { "type": "string", "description": "Current status of the product", "enum": [ "active", "inactive" ], "example": "ACTIVE", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the product was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the product was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the product was deleted (for soft deletes)" }, "image": { "description": "Primary image of the product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] }, "variants": { "description": "Variants of this product", "type": "array", "items": { "$ref": "#/components/schemas/ProductListVariant" } } }, "required": [ "id", "productId", "externalId", "externalVariantId", "storeId", "slug", "scheduleId", "productPoolId", "title", "variantTitle", "description", "imageId", "color", "price", "taxable", "duration", "allowCustomDuration", "maxDuration", "maxAttendees", "maxGuests", "allowGuests", "allowCustomerReschedule", "allowCustomerCancel", "rescheduleGap", "cancelGap", "beforeGap", "afterGap", "fixedTimes", "fixedStartTime", "fixedEndTime", "advanceScheduleThreshold", "sendConfirmationEmail", "sendReminderEmail", "sendFeedbackEmail", "skipCheckout", "status", "createdAt", "updatedAt", "deletedAt", "variants" ] }, "AddOnListProduct": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "productId": { "type": "string", "description": "ID of the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID)", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID)", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this product", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the product (unique per store)", "example": "haircut-basic" }, "scheduleId": { "type": "string", "description": "ID of the schedule associated with this product" }, "productPoolId": { "type": "string", "description": "ID of the product pool this product belongs to (controls overlap prevention)", "nullable": true }, "title": { "type": "string", "description": "Title of the product", "example": "Haircut Service" }, "variantTitle": { "type": "string", "description": "Title of the specific product variant", "example": "Short Hair" }, "description": { "type": "string", "description": "Detailed description of the product" }, "imageId": { "type": "string", "description": "ID of the product image" }, "color": { "type": "string", "description": "Color code for displaying the product", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "BLUE", "default": "slate" }, "price": { "type": "number", "description": "Price of the product", "example": 250 }, "taxable": { "type": "boolean", "description": "Whether the product is taxable", "default": false }, "duration": { "type": "number", "description": "Duration of the service in seconds", "example": 3600 }, "allowCustomDuration": { "type": "boolean", "description": "Whether customers can customize the duration by selecting multiples of the base service duration (e.g., if base duration is 1 day, customers can book 1, 2, 3+ days)", "default": false }, "maxDuration": { "type": "number", "description": "When allow_custom_duration=true, maximum duration allowed for multi-duration bookings in seconds (-1 for unlimited)", "default": -1 }, "maxAttendees": { "type": "number", "description": "Maximum number of attendees allowed", "default": 1 }, "maxGuests": { "type": "number", "description": "Maximum number of guests allowed per appointment. Null means unlimited.", "nullable": true }, "allowGuests": { "type": "boolean", "description": "Whether customers can invite guests to the appointment", "default": false }, "allowCustomerReschedule": { "type": "boolean", "description": "Whether customers can reschedule their bookings", "default": false }, "allowCustomerCancel": { "type": "boolean", "description": "Whether customers can cancel their bookings", "default": false }, "rescheduleGap": { "type": "number", "description": "Time in seconds before appointment when rescheduling is no longer allowed" }, "cancelGap": { "type": "number", "description": "Time in seconds before appointment when cancellation is no longer allowed" }, "beforeGap": { "type": "number", "description": "Buffer time in seconds required before this service" }, "afterGap": { "type": "number", "description": "Buffer time in seconds required after this service" }, "fixedTimes": { "type": "boolean", "description": "When allow_custom_duration=true, whether appointments must start and end at fixed times (like fixed check-in/check-out times for multi-duration bookings)", "default": false }, "fixedStartTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must start (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "09:00:00" }, "fixedEndTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must end (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "17:00:00" }, "advanceScheduleThreshold": { "type": "number", "description": "How many days in advance bookings can be made", "default": 0 }, "sendConfirmationEmail": { "type": "boolean", "description": "Whether to send confirmation emails for bookings", "default": true }, "sendReminderEmail": { "type": "boolean", "description": "Whether to send reminder emails before appointments", "default": false }, "sendFeedbackEmail": { "type": "boolean", "description": "Whether to send feedback request emails after appointments", "default": false }, "skipCheckout": { "type": "boolean", "description": "Whether to skip the checkout process for this product (Shopify merchants only)", "default": false }, "status": { "type": "string", "description": "Current status of the product", "enum": [ "active", "inactive" ], "example": "ACTIVE", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the product was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the product was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the product was deleted (for soft deletes)" }, "image": { "description": "Primary image of the product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "productId", "externalId", "externalVariantId", "storeId", "slug", "scheduleId", "productPoolId", "title", "variantTitle", "description", "imageId", "color", "price", "taxable", "duration", "allowCustomDuration", "maxDuration", "maxAttendees", "maxGuests", "allowGuests", "allowCustomerReschedule", "allowCustomerCancel", "rescheduleGap", "cancelGap", "beforeGap", "afterGap", "fixedTimes", "fixedStartTime", "fixedEndTime", "advanceScheduleThreshold", "sendConfirmationEmail", "sendReminderEmail", "sendFeedbackEmail", "skipCheckout", "status", "createdAt", "updatedAt", "deletedAt" ] }, "AddOnListLocation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the location", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this location", "example": "123e4567-e89b-12d3-a456-426614174001" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this location (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "title": { "type": "string", "description": "Name of the location", "example": "Main Office", "nullable": true }, "description": { "type": "string", "description": "Description of the location", "example": "Our main downtown office location with 3 treatment rooms", "nullable": true }, "slug": { "type": "string", "description": "URL-friendly slug for the location (unique per store)", "example": "new-york" }, "type": { "type": "string", "description": "Type of location", "enum": [ "physical", "online", "delivery" ], "example": "physical" }, "link": { "type": "string", "description": "URL link for online locations", "example": "https://zoom.us/j/123456789", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of address for physical locations", "example": "123 Main Street", "nullable": true }, "addressLine2": { "type": "string", "description": "Second line of address for physical locations", "example": "Suite 200", "nullable": true }, "city": { "type": "string", "description": "City for physical locations", "example": "San Francisco", "nullable": true }, "state": { "type": "string", "description": "State/province for physical locations", "example": "CA", "nullable": true }, "postalCode": { "type": "string", "description": "Postal code for physical locations", "example": "94105", "nullable": true }, "country": { "type": "string", "description": "Country for physical locations", "example": "United States", "nullable": true }, "displayAddress": { "type": "string", "description": "Merchant-defined display address that overrides the auto-formatted address (emails, booking page). Null falls back to the concatenated address fields.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressPlaceId": { "type": "string", "description": "Google Place ID for the physical address", "example": "ChIJIQBpAG2ahYAR_6128GcTUEo", "nullable": true }, "latitude": { "type": "number", "description": "Latitude in WGS84", "example": 37.4224764, "nullable": true }, "longitude": { "type": "number", "description": "Longitude in WGS84", "example": -122.0842499, "nullable": true }, "createdAt": { "type": "string", "description": "Date when the location was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the location was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "type": "string", "description": "Date when the location was deleted (for soft deletes)", "example": "2023-03-10T11:45:00Z", "nullable": true }, "address": { "type": "string", "description": "The formatted address string", "nullable": true } }, "required": [ "id", "storeId", "scheduleId", "title", "description", "slug", "type", "link", "addressLine1", "addressLine2", "city", "state", "postalCode", "country", "addressPlaceId", "latitude", "longitude", "createdAt", "updatedAt", "deletedAt", "address" ] }, "AddOnListStaffMember": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this staff member record", "example": "123e4567-e89b-12d3-a456-426614174111" }, "userId": { "type": "string", "description": "User ID of the staff member login identity (nullable until linked)", "example": "user-uuid" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this staff member, defines their availability", "example": "123e4567-e89b-12d3-a456-426614174000" }, "imageId": { "type": "string", "description": "ID of the image associated with this staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "firstName": { "type": "string", "description": "First name of the staff member", "example": "John" }, "lastName": { "type": "string", "description": "Last name of the staff member", "example": "Doe" }, "email": { "type": "string", "description": "Email address of the staff member, used for notifications and calendar integration", "example": "john.doe@example.com" }, "slug": { "type": "string", "description": "URL-friendly slug for the staff member (unique per store)", "example": "mike" }, "refreshToken": { "type": "string", "description": "Refresh token for integrations like Google Calendar", "example": "abc123xyz456" }, "createdAt": { "type": "string", "description": "Date and time when the staff member was created", "example": "2025-05-01T12:00:00Z" }, "updatedAt": { "type": "string", "description": "Date and time when the staff member was last updated", "example": "2025-05-15T14:30:00Z" }, "deletedAt": { "type": "string", "description": "Date and time when the staff member was soft deleted", "example": "2025-06-01T09:15:00Z" }, "image": { "description": "Profile image of the staff member", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "storeId", "userId", "scheduleId", "imageId", "firstName", "lastName", "email", "slug", "refreshToken", "createdAt", "updatedAt", "deletedAt" ] }, "AddOnListItemResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the add-on", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID) for synced add-ons", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID) for synced add-ons", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this add-on", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the add-on (unique per store)", "example": "child-seat" }, "title": { "type": "string", "description": "Title of the add-on", "example": "Child Seat" }, "description": { "type": "string", "description": "Detailed description of the add-on" }, "imageId": { "type": "string", "description": "ID of the primary image for the add-on" }, "color": { "type": "string", "description": "Color code used when displaying the add-on", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "slate", "default": "slate" }, "price": { "type": "number", "description": "Unit price of the add-on", "example": 15 }, "taxable": { "type": "boolean", "description": "Whether the add-on is taxable", "default": true }, "durationMultiplied": { "type": "boolean", "description": "When true, the add-on is charged per base-duration unit of the parent appointment. Quantity on the cart/order line item mirrors the parent CartItem.quantity (i.e., the booked duration units). Only meaningful for attached products with allowCustomDuration=true.", "default": false }, "maxQuantity": { "type": "number", "description": "Maximum quantity a customer can pick for this add-on. Only applies to fixed add-ons (durationMultiplied=false). Null means unlimited.", "example": 4, "minimum": 1, "nullable": true }, "status": { "type": "string", "description": "Current status of the add-on", "enum": [ "active", "inactive" ], "example": "active", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the add-on was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the add-on was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the add-on was soft-deleted" }, "image": { "description": "Primary image of the add-on", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] }, "products": { "description": "Products that offer this add-on at checkout", "type": "array", "items": { "$ref": "#/components/schemas/AddOnListProduct" } }, "locations": { "description": "Locations where this add-on is available", "type": "array", "items": { "$ref": "#/components/schemas/AddOnListLocation" } }, "staffMembers": { "description": "Staff members who can deliver this add-on", "type": "array", "items": { "$ref": "#/components/schemas/AddOnListStaffMember" } } }, "required": [ "id", "externalId", "externalVariantId", "storeId", "slug", "title", "description", "imageId", "color", "price", "taxable", "durationMultiplied", "maxQuantity", "status", "createdAt", "updatedAt", "deletedAt", "products", "locations", "staffMembers" ] }, "LocationDetailProduct": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "productId": { "type": "string", "description": "ID of the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID)", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID)", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this product", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the product (unique per store)", "example": "haircut-basic" }, "scheduleId": { "type": "string", "description": "ID of the schedule associated with this product" }, "productPoolId": { "type": "string", "description": "ID of the product pool this product belongs to (controls overlap prevention)", "nullable": true }, "title": { "type": "string", "description": "Title of the product", "example": "Haircut Service" }, "variantTitle": { "type": "string", "description": "Title of the specific product variant", "example": "Short Hair" }, "description": { "type": "string", "description": "Detailed description of the product" }, "imageId": { "type": "string", "description": "ID of the product image" }, "color": { "type": "string", "description": "Color code for displaying the product", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "BLUE", "default": "slate" }, "price": { "type": "number", "description": "Price of the product", "example": 250 }, "taxable": { "type": "boolean", "description": "Whether the product is taxable", "default": false }, "duration": { "type": "number", "description": "Duration of the service in seconds", "example": 3600 }, "allowCustomDuration": { "type": "boolean", "description": "Whether customers can customize the duration by selecting multiples of the base service duration (e.g., if base duration is 1 day, customers can book 1, 2, 3+ days)", "default": false }, "maxDuration": { "type": "number", "description": "When allow_custom_duration=true, maximum duration allowed for multi-duration bookings in seconds (-1 for unlimited)", "default": -1 }, "maxAttendees": { "type": "number", "description": "Maximum number of attendees allowed", "default": 1 }, "maxGuests": { "type": "number", "description": "Maximum number of guests allowed per appointment. Null means unlimited.", "nullable": true }, "allowGuests": { "type": "boolean", "description": "Whether customers can invite guests to the appointment", "default": false }, "allowCustomerReschedule": { "type": "boolean", "description": "Whether customers can reschedule their bookings", "default": false }, "allowCustomerCancel": { "type": "boolean", "description": "Whether customers can cancel their bookings", "default": false }, "rescheduleGap": { "type": "number", "description": "Time in seconds before appointment when rescheduling is no longer allowed" }, "cancelGap": { "type": "number", "description": "Time in seconds before appointment when cancellation is no longer allowed" }, "beforeGap": { "type": "number", "description": "Buffer time in seconds required before this service" }, "afterGap": { "type": "number", "description": "Buffer time in seconds required after this service" }, "fixedTimes": { "type": "boolean", "description": "When allow_custom_duration=true, whether appointments must start and end at fixed times (like fixed check-in/check-out times for multi-duration bookings)", "default": false }, "fixedStartTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must start (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "09:00:00" }, "fixedEndTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must end (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "17:00:00" }, "advanceScheduleThreshold": { "type": "number", "description": "How many days in advance bookings can be made", "default": 0 }, "sendConfirmationEmail": { "type": "boolean", "description": "Whether to send confirmation emails for bookings", "default": true }, "sendReminderEmail": { "type": "boolean", "description": "Whether to send reminder emails before appointments", "default": false }, "sendFeedbackEmail": { "type": "boolean", "description": "Whether to send feedback request emails after appointments", "default": false }, "skipCheckout": { "type": "boolean", "description": "Whether to skip the checkout process for this product (Shopify merchants only)", "default": false }, "status": { "type": "string", "description": "Current status of the product", "enum": [ "active", "inactive" ], "example": "ACTIVE", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the product was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the product was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the product was deleted (for soft deletes)" }, "image": { "description": "Primary image of the product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "productId", "externalId", "externalVariantId", "storeId", "slug", "scheduleId", "productPoolId", "title", "variantTitle", "description", "imageId", "color", "price", "taxable", "duration", "allowCustomDuration", "maxDuration", "maxAttendees", "maxGuests", "allowGuests", "allowCustomerReschedule", "allowCustomerCancel", "rescheduleGap", "cancelGap", "beforeGap", "afterGap", "fixedTimes", "fixedStartTime", "fixedEndTime", "advanceScheduleThreshold", "sendConfirmationEmail", "sendReminderEmail", "sendFeedbackEmail", "skipCheckout", "status", "createdAt", "updatedAt", "deletedAt" ] }, "LocationDetailStaffMember": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this staff member record", "example": "123e4567-e89b-12d3-a456-426614174111" }, "userId": { "type": "string", "description": "User ID of the staff member login identity (nullable until linked)", "example": "user-uuid" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this staff member, defines their availability", "example": "123e4567-e89b-12d3-a456-426614174000" }, "imageId": { "type": "string", "description": "ID of the image associated with this staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "firstName": { "type": "string", "description": "First name of the staff member", "example": "John" }, "lastName": { "type": "string", "description": "Last name of the staff member", "example": "Doe" }, "email": { "type": "string", "description": "Email address of the staff member, used for notifications and calendar integration", "example": "john.doe@example.com" }, "slug": { "type": "string", "description": "URL-friendly slug for the staff member (unique per store)", "example": "mike" }, "refreshToken": { "type": "string", "description": "Refresh token for integrations like Google Calendar", "example": "abc123xyz456" }, "createdAt": { "type": "string", "description": "Date and time when the staff member was created", "example": "2025-05-01T12:00:00Z" }, "updatedAt": { "type": "string", "description": "Date and time when the staff member was last updated", "example": "2025-05-15T14:30:00Z" }, "deletedAt": { "type": "string", "description": "Date and time when the staff member was soft deleted", "example": "2025-06-01T09:15:00Z" }, "image": { "description": "Profile image of the staff member", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "storeId", "userId", "scheduleId", "imageId", "firstName", "lastName", "email", "slug", "refreshToken", "createdAt", "updatedAt", "deletedAt" ] }, "LocationDetailSchedule": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the schedule", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this schedule", "example": "123e4567-e89b-12d3-a456-426614174001" }, "name": { "type": "string", "description": "Name of the schedule", "example": "Standard Business Hours", "nullable": true }, "timezone": { "type": "string", "description": "Timezone for the schedule", "example": "UTC", "default": "UTC" }, "scheduleGap": { "type": "string", "description": "Time slot frequency for the schedule", "enum": [ "every-10-minutes", "every-15-minutes", "every-20-minutes", "every-30-minutes", "every-60-minutes" ], "example": "every-15-minutes", "default": "every-15-minutes" }, "appointmentsGap": { "type": "number", "description": "Buffer time between appointments in seconds", "example": 900 }, "advanceScheduleDays": { "type": "number", "description": "Number of days customers can book in advance (-1 for unlimited)", "example": 60, "default": -1 }, "availabilityType": { "type": "string", "description": "Type of availability pattern for this schedule", "enum": [ "continuous", "recurring", "non-recurring" ], "example": "recurring", "default": "continuous" }, "status": { "type": "string", "description": "Status of the schedule", "enum": [ "active", "inactive" ], "example": "active", "default": "inactive" }, "createdAt": { "type": "string", "description": "Date when the schedule was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the schedule was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date when the schedule was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true } }, "required": [ "id", "storeId", "name", "timezone", "scheduleGap", "appointmentsGap", "advanceScheduleDays", "availabilityType", "status", "createdAt", "updatedAt", "deletedAt" ] }, "LocationDetailAvailability": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the location availability record", "example": "123e4567-e89b-12d3-a456-426614174000" }, "locationId": { "type": "string", "description": "ID of the location this availability applies to", "example": "123e4567-e89b-12d3-a456-426614174001" }, "fromDate": { "type": "string", "description": "Start date of the availability period (for specific date ranges) - specified in the location's schedule timezone, or user settings timezone if no schedule is assigned", "example": "2023-06-15", "nullable": true }, "fromTime": { "type": "string", "description": "Start time of the availability period - specified in the location's schedule timezone, or user settings timezone if no schedule is assigned", "example": "09:00:00" }, "toDate": { "type": "string", "description": "End date of the availability period (for specific date ranges) - specified in the location's schedule timezone, or user settings timezone if no schedule is assigned", "example": "2023-06-15", "nullable": true }, "toTime": { "type": "string", "description": "End time of the availability period - specified in the location's schedule timezone, or user settings timezone if no schedule is assigned", "example": "17:00:00" }, "day": { "type": "number", "description": "Day of the week (1=Monday to 7=Sunday) (for recurring weekly availabilities)", "example": 1, "nullable": true }, "status": { "type": "string", "description": "Status indicating whether this time period is available or unavailable", "enum": [ "available", "unavailable" ], "example": "available" }, "createdAt": { "format": "date-time", "type": "string", "description": "Date when the availability record was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date when the availability record was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true } }, "required": [ "id", "locationId", "fromDate", "fromTime", "toDate", "toTime", "day", "status", "createdAt", "updatedAt" ] }, "LocationDetailResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the location", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this location", "example": "123e4567-e89b-12d3-a456-426614174001" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this location (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "title": { "type": "string", "description": "Name of the location", "example": "Main Office", "nullable": true }, "description": { "type": "string", "description": "Description of the location", "example": "Our main downtown office location with 3 treatment rooms", "nullable": true }, "slug": { "type": "string", "description": "URL-friendly slug for the location (unique per store)", "example": "new-york" }, "type": { "type": "string", "description": "Type of location", "enum": [ "physical", "online", "delivery" ], "example": "physical" }, "link": { "type": "string", "description": "URL link for online locations", "example": "https://zoom.us/j/123456789", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of address for physical locations", "example": "123 Main Street", "nullable": true }, "addressLine2": { "type": "string", "description": "Second line of address for physical locations", "example": "Suite 200", "nullable": true }, "city": { "type": "string", "description": "City for physical locations", "example": "San Francisco", "nullable": true }, "state": { "type": "string", "description": "State/province for physical locations", "example": "CA", "nullable": true }, "postalCode": { "type": "string", "description": "Postal code for physical locations", "example": "94105", "nullable": true }, "country": { "type": "string", "description": "Country for physical locations", "example": "United States", "nullable": true }, "displayAddress": { "type": "string", "description": "Merchant-defined display address that overrides the auto-formatted address (emails, booking page). Null falls back to the concatenated address fields.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressPlaceId": { "type": "string", "description": "Google Place ID for the physical address", "example": "ChIJIQBpAG2ahYAR_6128GcTUEo", "nullable": true }, "latitude": { "type": "number", "description": "Latitude in WGS84", "example": 37.4224764, "nullable": true }, "longitude": { "type": "number", "description": "Longitude in WGS84", "example": -122.0842499, "nullable": true }, "createdAt": { "type": "string", "description": "Date when the location was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the location was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "type": "string", "description": "Date when the location was deleted (for soft deletes)", "example": "2023-03-10T11:45:00Z", "nullable": true }, "address": { "type": "string", "description": "The formatted address string", "nullable": true }, "products": { "description": "Products that can be offered at this location", "type": "array", "items": { "$ref": "#/components/schemas/LocationDetailProduct" } }, "staffMembers": { "description": "Staff members who can work at this location", "type": "array", "items": { "$ref": "#/components/schemas/LocationDetailStaffMember" } }, "schedule": { "description": "Schedule assigned to the location", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/LocationDetailSchedule" } ] }, "availabilities": { "description": "Availability records for this location", "type": "array", "items": { "$ref": "#/components/schemas/LocationDetailAvailability" } } }, "required": [ "id", "storeId", "scheduleId", "title", "description", "slug", "type", "link", "addressLine1", "addressLine2", "city", "state", "postalCode", "country", "addressPlaceId", "latitude", "longitude", "createdAt", "updatedAt", "deletedAt", "address", "products", "staffMembers", "schedule", "availabilities" ] }, "ProductCollectionProduct": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "productId": { "type": "string", "description": "ID of the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID)", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID)", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this product", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the product (unique per store)", "example": "haircut-basic" }, "scheduleId": { "type": "string", "description": "ID of the schedule associated with this product" }, "productPoolId": { "type": "string", "description": "ID of the product pool this product belongs to (controls overlap prevention)", "nullable": true }, "title": { "type": "string", "description": "Title of the product", "example": "Haircut Service" }, "variantTitle": { "type": "string", "description": "Title of the specific product variant", "example": "Short Hair" }, "description": { "type": "string", "description": "Detailed description of the product" }, "imageId": { "type": "string", "description": "ID of the product image" }, "color": { "type": "string", "description": "Color code for displaying the product", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "BLUE", "default": "slate" }, "price": { "type": "number", "description": "Price of the product", "example": 250 }, "taxable": { "type": "boolean", "description": "Whether the product is taxable", "default": false }, "duration": { "type": "number", "description": "Duration of the service in seconds", "example": 3600 }, "allowCustomDuration": { "type": "boolean", "description": "Whether customers can customize the duration by selecting multiples of the base service duration (e.g., if base duration is 1 day, customers can book 1, 2, 3+ days)", "default": false }, "maxDuration": { "type": "number", "description": "When allow_custom_duration=true, maximum duration allowed for multi-duration bookings in seconds (-1 for unlimited)", "default": -1 }, "maxAttendees": { "type": "number", "description": "Maximum number of attendees allowed", "default": 1 }, "maxGuests": { "type": "number", "description": "Maximum number of guests allowed per appointment. Null means unlimited.", "nullable": true }, "allowGuests": { "type": "boolean", "description": "Whether customers can invite guests to the appointment", "default": false }, "allowCustomerReschedule": { "type": "boolean", "description": "Whether customers can reschedule their bookings", "default": false }, "allowCustomerCancel": { "type": "boolean", "description": "Whether customers can cancel their bookings", "default": false }, "rescheduleGap": { "type": "number", "description": "Time in seconds before appointment when rescheduling is no longer allowed" }, "cancelGap": { "type": "number", "description": "Time in seconds before appointment when cancellation is no longer allowed" }, "beforeGap": { "type": "number", "description": "Buffer time in seconds required before this service" }, "afterGap": { "type": "number", "description": "Buffer time in seconds required after this service" }, "fixedTimes": { "type": "boolean", "description": "When allow_custom_duration=true, whether appointments must start and end at fixed times (like fixed check-in/check-out times for multi-duration bookings)", "default": false }, "fixedStartTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must start (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "09:00:00" }, "fixedEndTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must end (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "17:00:00" }, "advanceScheduleThreshold": { "type": "number", "description": "How many days in advance bookings can be made", "default": 0 }, "sendConfirmationEmail": { "type": "boolean", "description": "Whether to send confirmation emails for bookings", "default": true }, "sendReminderEmail": { "type": "boolean", "description": "Whether to send reminder emails before appointments", "default": false }, "sendFeedbackEmail": { "type": "boolean", "description": "Whether to send feedback request emails after appointments", "default": false }, "skipCheckout": { "type": "boolean", "description": "Whether to skip the checkout process for this product (Shopify merchants only)", "default": false }, "status": { "type": "string", "description": "Current status of the product", "enum": [ "active", "inactive" ], "example": "ACTIVE", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the product was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the product was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the product was deleted (for soft deletes)" }, "image": { "description": "Primary image of the product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "productId", "externalId", "externalVariantId", "storeId", "slug", "scheduleId", "productPoolId", "title", "variantTitle", "description", "imageId", "color", "price", "taxable", "duration", "allowCustomDuration", "maxDuration", "maxAttendees", "maxGuests", "allowGuests", "allowCustomerReschedule", "allowCustomerCancel", "rescheduleGap", "cancelGap", "beforeGap", "afterGap", "fixedTimes", "fixedStartTime", "fixedEndTime", "advanceScheduleThreshold", "sendConfirmationEmail", "sendReminderEmail", "sendFeedbackEmail", "skipCheckout", "status", "createdAt", "updatedAt", "deletedAt" ] }, "ProductCollectionResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the product collection" }, "storeId": { "type": "string", "description": "Identifier of the store that owns the collection" }, "title": { "type": "string", "description": "Title of the product collection", "example": "Hair Services" }, "description": { "type": "string", "description": "Description of the product collection" }, "slug": { "type": "string", "description": "URL-friendly slug for the product collection (unique per store)", "example": "featured" }, "isVisible": { "type": "boolean", "description": "Visibility flag for the collection", "default": true }, "createdAt": { "type": "string", "description": "Timestamp when the collection was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the collection was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the collection was soft-deleted" }, "products": { "description": "Products assigned to this collection", "type": "array", "items": { "$ref": "#/components/schemas/ProductCollectionProduct" } } }, "required": [ "id", "storeId", "title", "description", "slug", "isVisible", "createdAt", "updatedAt", "deletedAt", "products" ] }, "StaffMemberDetailSchedule": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the schedule", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this schedule", "example": "123e4567-e89b-12d3-a456-426614174001" }, "name": { "type": "string", "description": "Name of the schedule", "example": "Standard Business Hours", "nullable": true }, "timezone": { "type": "string", "description": "Timezone for the schedule", "example": "UTC", "default": "UTC" }, "scheduleGap": { "type": "string", "description": "Time slot frequency for the schedule", "enum": [ "every-10-minutes", "every-15-minutes", "every-20-minutes", "every-30-minutes", "every-60-minutes" ], "example": "every-15-minutes", "default": "every-15-minutes" }, "appointmentsGap": { "type": "number", "description": "Buffer time between appointments in seconds", "example": 900 }, "advanceScheduleDays": { "type": "number", "description": "Number of days customers can book in advance (-1 for unlimited)", "example": 60, "default": -1 }, "availabilityType": { "type": "string", "description": "Type of availability pattern for this schedule", "enum": [ "continuous", "recurring", "non-recurring" ], "example": "recurring", "default": "continuous" }, "status": { "type": "string", "description": "Status of the schedule", "enum": [ "active", "inactive" ], "example": "active", "default": "inactive" }, "createdAt": { "type": "string", "description": "Date when the schedule was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the schedule was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date when the schedule was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true } }, "required": [ "id", "storeId", "name", "timezone", "scheduleGap", "appointmentsGap", "advanceScheduleDays", "availabilityType", "status", "createdAt", "updatedAt", "deletedAt" ] }, "StaffMemberDetailProduct": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "productId": { "type": "string", "description": "ID of the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID)", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID)", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this product", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the product (unique per store)", "example": "haircut-basic" }, "scheduleId": { "type": "string", "description": "ID of the schedule associated with this product" }, "productPoolId": { "type": "string", "description": "ID of the product pool this product belongs to (controls overlap prevention)", "nullable": true }, "title": { "type": "string", "description": "Title of the product", "example": "Haircut Service" }, "variantTitle": { "type": "string", "description": "Title of the specific product variant", "example": "Short Hair" }, "description": { "type": "string", "description": "Detailed description of the product" }, "imageId": { "type": "string", "description": "ID of the product image" }, "color": { "type": "string", "description": "Color code for displaying the product", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "BLUE", "default": "slate" }, "price": { "type": "number", "description": "Price of the product", "example": 250 }, "taxable": { "type": "boolean", "description": "Whether the product is taxable", "default": false }, "duration": { "type": "number", "description": "Duration of the service in seconds", "example": 3600 }, "allowCustomDuration": { "type": "boolean", "description": "Whether customers can customize the duration by selecting multiples of the base service duration (e.g., if base duration is 1 day, customers can book 1, 2, 3+ days)", "default": false }, "maxDuration": { "type": "number", "description": "When allow_custom_duration=true, maximum duration allowed for multi-duration bookings in seconds (-1 for unlimited)", "default": -1 }, "maxAttendees": { "type": "number", "description": "Maximum number of attendees allowed", "default": 1 }, "maxGuests": { "type": "number", "description": "Maximum number of guests allowed per appointment. Null means unlimited.", "nullable": true }, "allowGuests": { "type": "boolean", "description": "Whether customers can invite guests to the appointment", "default": false }, "allowCustomerReschedule": { "type": "boolean", "description": "Whether customers can reschedule their bookings", "default": false }, "allowCustomerCancel": { "type": "boolean", "description": "Whether customers can cancel their bookings", "default": false }, "rescheduleGap": { "type": "number", "description": "Time in seconds before appointment when rescheduling is no longer allowed" }, "cancelGap": { "type": "number", "description": "Time in seconds before appointment when cancellation is no longer allowed" }, "beforeGap": { "type": "number", "description": "Buffer time in seconds required before this service" }, "afterGap": { "type": "number", "description": "Buffer time in seconds required after this service" }, "fixedTimes": { "type": "boolean", "description": "When allow_custom_duration=true, whether appointments must start and end at fixed times (like fixed check-in/check-out times for multi-duration bookings)", "default": false }, "fixedStartTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must start (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "09:00:00" }, "fixedEndTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must end (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "17:00:00" }, "advanceScheduleThreshold": { "type": "number", "description": "How many days in advance bookings can be made", "default": 0 }, "sendConfirmationEmail": { "type": "boolean", "description": "Whether to send confirmation emails for bookings", "default": true }, "sendReminderEmail": { "type": "boolean", "description": "Whether to send reminder emails before appointments", "default": false }, "sendFeedbackEmail": { "type": "boolean", "description": "Whether to send feedback request emails after appointments", "default": false }, "skipCheckout": { "type": "boolean", "description": "Whether to skip the checkout process for this product (Shopify merchants only)", "default": false }, "status": { "type": "string", "description": "Current status of the product", "enum": [ "active", "inactive" ], "example": "ACTIVE", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the product was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the product was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the product was deleted (for soft deletes)" }, "image": { "description": "Primary image of the product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "productId", "externalId", "externalVariantId", "storeId", "slug", "scheduleId", "productPoolId", "title", "variantTitle", "description", "imageId", "color", "price", "taxable", "duration", "allowCustomDuration", "maxDuration", "maxAttendees", "maxGuests", "allowGuests", "allowCustomerReschedule", "allowCustomerCancel", "rescheduleGap", "cancelGap", "beforeGap", "afterGap", "fixedTimes", "fixedStartTime", "fixedEndTime", "advanceScheduleThreshold", "sendConfirmationEmail", "sendReminderEmail", "sendFeedbackEmail", "skipCheckout", "status", "createdAt", "updatedAt", "deletedAt" ] }, "StaffMemberDetailLocation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the location", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this location", "example": "123e4567-e89b-12d3-a456-426614174001" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this location (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "title": { "type": "string", "description": "Name of the location", "example": "Main Office", "nullable": true }, "description": { "type": "string", "description": "Description of the location", "example": "Our main downtown office location with 3 treatment rooms", "nullable": true }, "slug": { "type": "string", "description": "URL-friendly slug for the location (unique per store)", "example": "new-york" }, "type": { "type": "string", "description": "Type of location", "enum": [ "physical", "online", "delivery" ], "example": "physical" }, "link": { "type": "string", "description": "URL link for online locations", "example": "https://zoom.us/j/123456789", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of address for physical locations", "example": "123 Main Street", "nullable": true }, "addressLine2": { "type": "string", "description": "Second line of address for physical locations", "example": "Suite 200", "nullable": true }, "city": { "type": "string", "description": "City for physical locations", "example": "San Francisco", "nullable": true }, "state": { "type": "string", "description": "State/province for physical locations", "example": "CA", "nullable": true }, "postalCode": { "type": "string", "description": "Postal code for physical locations", "example": "94105", "nullable": true }, "country": { "type": "string", "description": "Country for physical locations", "example": "United States", "nullable": true }, "displayAddress": { "type": "string", "description": "Merchant-defined display address that overrides the auto-formatted address (emails, booking page). Null falls back to the concatenated address fields.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressPlaceId": { "type": "string", "description": "Google Place ID for the physical address", "example": "ChIJIQBpAG2ahYAR_6128GcTUEo", "nullable": true }, "latitude": { "type": "number", "description": "Latitude in WGS84", "example": 37.4224764, "nullable": true }, "longitude": { "type": "number", "description": "Longitude in WGS84", "example": -122.0842499, "nullable": true }, "createdAt": { "type": "string", "description": "Date when the location was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the location was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "type": "string", "description": "Date when the location was deleted (for soft deletes)", "example": "2023-03-10T11:45:00Z", "nullable": true }, "address": { "type": "string", "description": "The formatted address string", "nullable": true } }, "required": [ "id", "storeId", "scheduleId", "title", "description", "slug", "type", "link", "addressLine1", "addressLine2", "city", "state", "postalCode", "country", "addressPlaceId", "latitude", "longitude", "createdAt", "updatedAt", "deletedAt", "address" ] }, "StaffMemberDetailUser": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the user", "example": "550e8400-e29b-41d4-a716-446655440000" }, "parentId": { "type": "string", "description": "ID of the parent user (for staff members)", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "name": { "type": "string", "description": "Full name of the user", "example": "John Smith" }, "email": { "type": "string", "description": "Email address of the user", "example": "john.smith@example.com" }, "password": { "type": "string", "description": "Hashed password of the user", "nullable": true }, "refreshToken": { "type": "string", "description": "Refresh token for authentication", "nullable": true }, "role": { "type": "string", "description": "Role of the user in the system", "enum": [ "admin", "staff-member", "store-owner", "manager" ], "default": "store-owner", "example": "store-owner" }, "status": { "type": "string", "description": "Current status of the user account", "enum": [ "active", "inactive", "banned", "deleted" ], "default": "active", "example": "active" }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the user was created", "example": "2023-01-01T00:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the user was last updated", "example": "2023-01-15T00:00:00Z" }, "emailVerifiedAt": { "format": "date-time", "type": "string", "description": "Date and time when the user verified email", "example": "2023-01-02T00:00:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date and time when the user was soft-deleted", "example": "2023-02-01T00:00:00Z", "nullable": true }, "isEmailVerified": { "type": "boolean", "description": "Indicates whether user email is verified" }, "isPasswordSet": { "type": "boolean", "description": "Indicates whether user password is set" } }, "required": [ "id", "parentId", "name", "email", "password", "refreshToken", "role", "status", "createdAt", "updatedAt", "emailVerifiedAt", "deletedAt", "isEmailVerified", "isPasswordSet" ] }, "StaffMemberDetailResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this staff member record", "example": "123e4567-e89b-12d3-a456-426614174111" }, "userId": { "type": "string", "description": "User ID of the staff member login identity (nullable until linked)", "example": "user-uuid" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this staff member, defines their availability", "example": "123e4567-e89b-12d3-a456-426614174000" }, "imageId": { "type": "string", "description": "ID of the image associated with this staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "firstName": { "type": "string", "description": "First name of the staff member", "example": "John" }, "lastName": { "type": "string", "description": "Last name of the staff member", "example": "Doe" }, "email": { "type": "string", "description": "Email address of the staff member, used for notifications and calendar integration", "example": "john.doe@example.com" }, "slug": { "type": "string", "description": "URL-friendly slug for the staff member (unique per store)", "example": "mike" }, "refreshToken": { "type": "string", "description": "Refresh token for integrations like Google Calendar", "example": "abc123xyz456" }, "createdAt": { "type": "string", "description": "Date and time when the staff member was created", "example": "2025-05-01T12:00:00Z" }, "updatedAt": { "type": "string", "description": "Date and time when the staff member was last updated", "example": "2025-05-15T14:30:00Z" }, "deletedAt": { "type": "string", "description": "Date and time when the staff member was soft deleted", "example": "2025-06-01T09:15:00Z" }, "image": { "description": "Profile image of the staff member", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] }, "schedule": { "description": "Schedule defining when this staff member is available", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/StaffMemberDetailSchedule" } ] }, "products": { "description": "Products (services) this staff member can provide", "type": "array", "items": { "$ref": "#/components/schemas/StaffMemberDetailProduct" } }, "locations": { "description": "Locations where this staff member works", "type": "array", "items": { "$ref": "#/components/schemas/StaffMemberDetailLocation" } }, "user": { "description": "Login user linked to this staff member", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/StaffMemberDetailUser" } ] } }, "required": [ "id", "storeId", "userId", "scheduleId", "imageId", "firstName", "lastName", "email", "slug", "refreshToken", "createdAt", "updatedAt", "deletedAt", "schedule", "products", "locations", "user" ] }, "StaffMemberListSchedule": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the schedule", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this schedule", "example": "123e4567-e89b-12d3-a456-426614174001" }, "name": { "type": "string", "description": "Name of the schedule", "example": "Standard Business Hours", "nullable": true }, "timezone": { "type": "string", "description": "Timezone for the schedule", "example": "UTC", "default": "UTC" }, "scheduleGap": { "type": "string", "description": "Time slot frequency for the schedule", "enum": [ "every-10-minutes", "every-15-minutes", "every-20-minutes", "every-30-minutes", "every-60-minutes" ], "example": "every-15-minutes", "default": "every-15-minutes" }, "appointmentsGap": { "type": "number", "description": "Buffer time between appointments in seconds", "example": 900 }, "advanceScheduleDays": { "type": "number", "description": "Number of days customers can book in advance (-1 for unlimited)", "example": 60, "default": -1 }, "availabilityType": { "type": "string", "description": "Type of availability pattern for this schedule", "enum": [ "continuous", "recurring", "non-recurring" ], "example": "recurring", "default": "continuous" }, "status": { "type": "string", "description": "Status of the schedule", "enum": [ "active", "inactive" ], "example": "active", "default": "inactive" }, "createdAt": { "type": "string", "description": "Date when the schedule was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the schedule was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date when the schedule was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true } }, "required": [ "id", "storeId", "name", "timezone", "scheduleGap", "appointmentsGap", "advanceScheduleDays", "availabilityType", "status", "createdAt", "updatedAt", "deletedAt" ] }, "StaffMemberListProduct": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "productId": { "type": "string", "description": "ID of the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID)", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID)", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this product", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the product (unique per store)", "example": "haircut-basic" }, "scheduleId": { "type": "string", "description": "ID of the schedule associated with this product" }, "productPoolId": { "type": "string", "description": "ID of the product pool this product belongs to (controls overlap prevention)", "nullable": true }, "title": { "type": "string", "description": "Title of the product", "example": "Haircut Service" }, "variantTitle": { "type": "string", "description": "Title of the specific product variant", "example": "Short Hair" }, "description": { "type": "string", "description": "Detailed description of the product" }, "imageId": { "type": "string", "description": "ID of the product image" }, "color": { "type": "string", "description": "Color code for displaying the product", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "BLUE", "default": "slate" }, "price": { "type": "number", "description": "Price of the product", "example": 250 }, "taxable": { "type": "boolean", "description": "Whether the product is taxable", "default": false }, "duration": { "type": "number", "description": "Duration of the service in seconds", "example": 3600 }, "allowCustomDuration": { "type": "boolean", "description": "Whether customers can customize the duration by selecting multiples of the base service duration (e.g., if base duration is 1 day, customers can book 1, 2, 3+ days)", "default": false }, "maxDuration": { "type": "number", "description": "When allow_custom_duration=true, maximum duration allowed for multi-duration bookings in seconds (-1 for unlimited)", "default": -1 }, "maxAttendees": { "type": "number", "description": "Maximum number of attendees allowed", "default": 1 }, "maxGuests": { "type": "number", "description": "Maximum number of guests allowed per appointment. Null means unlimited.", "nullable": true }, "allowGuests": { "type": "boolean", "description": "Whether customers can invite guests to the appointment", "default": false }, "allowCustomerReschedule": { "type": "boolean", "description": "Whether customers can reschedule their bookings", "default": false }, "allowCustomerCancel": { "type": "boolean", "description": "Whether customers can cancel their bookings", "default": false }, "rescheduleGap": { "type": "number", "description": "Time in seconds before appointment when rescheduling is no longer allowed" }, "cancelGap": { "type": "number", "description": "Time in seconds before appointment when cancellation is no longer allowed" }, "beforeGap": { "type": "number", "description": "Buffer time in seconds required before this service" }, "afterGap": { "type": "number", "description": "Buffer time in seconds required after this service" }, "fixedTimes": { "type": "boolean", "description": "When allow_custom_duration=true, whether appointments must start and end at fixed times (like fixed check-in/check-out times for multi-duration bookings)", "default": false }, "fixedStartTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must start (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "09:00:00" }, "fixedEndTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must end (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "17:00:00" }, "advanceScheduleThreshold": { "type": "number", "description": "How many days in advance bookings can be made", "default": 0 }, "sendConfirmationEmail": { "type": "boolean", "description": "Whether to send confirmation emails for bookings", "default": true }, "sendReminderEmail": { "type": "boolean", "description": "Whether to send reminder emails before appointments", "default": false }, "sendFeedbackEmail": { "type": "boolean", "description": "Whether to send feedback request emails after appointments", "default": false }, "skipCheckout": { "type": "boolean", "description": "Whether to skip the checkout process for this product (Shopify merchants only)", "default": false }, "status": { "type": "string", "description": "Current status of the product", "enum": [ "active", "inactive" ], "example": "ACTIVE", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the product was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the product was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the product was deleted (for soft deletes)" }, "image": { "description": "Primary image of the product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "productId", "externalId", "externalVariantId", "storeId", "slug", "scheduleId", "productPoolId", "title", "variantTitle", "description", "imageId", "color", "price", "taxable", "duration", "allowCustomDuration", "maxDuration", "maxAttendees", "maxGuests", "allowGuests", "allowCustomerReschedule", "allowCustomerCancel", "rescheduleGap", "cancelGap", "beforeGap", "afterGap", "fixedTimes", "fixedStartTime", "fixedEndTime", "advanceScheduleThreshold", "sendConfirmationEmail", "sendReminderEmail", "sendFeedbackEmail", "skipCheckout", "status", "createdAt", "updatedAt", "deletedAt" ] }, "StaffMemberListLocation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the location", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this location", "example": "123e4567-e89b-12d3-a456-426614174001" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this location (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "title": { "type": "string", "description": "Name of the location", "example": "Main Office", "nullable": true }, "description": { "type": "string", "description": "Description of the location", "example": "Our main downtown office location with 3 treatment rooms", "nullable": true }, "slug": { "type": "string", "description": "URL-friendly slug for the location (unique per store)", "example": "new-york" }, "type": { "type": "string", "description": "Type of location", "enum": [ "physical", "online", "delivery" ], "example": "physical" }, "link": { "type": "string", "description": "URL link for online locations", "example": "https://zoom.us/j/123456789", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of address for physical locations", "example": "123 Main Street", "nullable": true }, "addressLine2": { "type": "string", "description": "Second line of address for physical locations", "example": "Suite 200", "nullable": true }, "city": { "type": "string", "description": "City for physical locations", "example": "San Francisco", "nullable": true }, "state": { "type": "string", "description": "State/province for physical locations", "example": "CA", "nullable": true }, "postalCode": { "type": "string", "description": "Postal code for physical locations", "example": "94105", "nullable": true }, "country": { "type": "string", "description": "Country for physical locations", "example": "United States", "nullable": true }, "displayAddress": { "type": "string", "description": "Merchant-defined display address that overrides the auto-formatted address (emails, booking page). Null falls back to the concatenated address fields.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressPlaceId": { "type": "string", "description": "Google Place ID for the physical address", "example": "ChIJIQBpAG2ahYAR_6128GcTUEo", "nullable": true }, "latitude": { "type": "number", "description": "Latitude in WGS84", "example": 37.4224764, "nullable": true }, "longitude": { "type": "number", "description": "Longitude in WGS84", "example": -122.0842499, "nullable": true }, "createdAt": { "type": "string", "description": "Date when the location was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the location was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "type": "string", "description": "Date when the location was deleted (for soft deletes)", "example": "2023-03-10T11:45:00Z", "nullable": true }, "address": { "type": "string", "description": "The formatted address string", "nullable": true } }, "required": [ "id", "storeId", "scheduleId", "title", "description", "slug", "type", "link", "addressLine1", "addressLine2", "city", "state", "postalCode", "country", "addressPlaceId", "latitude", "longitude", "createdAt", "updatedAt", "deletedAt", "address" ] }, "StaffMemberListItemResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this staff member record", "example": "123e4567-e89b-12d3-a456-426614174111" }, "userId": { "type": "string", "description": "User ID of the staff member login identity (nullable until linked)", "example": "user-uuid" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this staff member, defines their availability", "example": "123e4567-e89b-12d3-a456-426614174000" }, "imageId": { "type": "string", "description": "ID of the image associated with this staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "firstName": { "type": "string", "description": "First name of the staff member", "example": "John" }, "lastName": { "type": "string", "description": "Last name of the staff member", "example": "Doe" }, "email": { "type": "string", "description": "Email address of the staff member, used for notifications and calendar integration", "example": "john.doe@example.com" }, "slug": { "type": "string", "description": "URL-friendly slug for the staff member (unique per store)", "example": "mike" }, "refreshToken": { "type": "string", "description": "Refresh token for integrations like Google Calendar", "example": "abc123xyz456" }, "createdAt": { "type": "string", "description": "Date and time when the staff member was created", "example": "2025-05-01T12:00:00Z" }, "updatedAt": { "type": "string", "description": "Date and time when the staff member was last updated", "example": "2025-05-15T14:30:00Z" }, "deletedAt": { "type": "string", "description": "Date and time when the staff member was soft deleted", "example": "2025-06-01T09:15:00Z" }, "image": { "description": "Profile image of the staff member", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] }, "schedule": { "description": "Schedule defining when this staff member is available", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/StaffMemberListSchedule" } ] }, "products": { "description": "Products (services) this staff member can provide", "type": "array", "items": { "$ref": "#/components/schemas/StaffMemberListProduct" } }, "locations": { "description": "Locations where this staff member works", "type": "array", "items": { "$ref": "#/components/schemas/StaffMemberListLocation" } } }, "required": [ "id", "storeId", "userId", "scheduleId", "imageId", "firstName", "lastName", "email", "slug", "refreshToken", "createdAt", "updatedAt", "deletedAt", "schedule", "products", "locations" ] }, "AddOnDetailLocation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the location", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this location", "example": "123e4567-e89b-12d3-a456-426614174001" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this location (if any)", "example": "123e4567-e89b-12d3-a456-426614174002", "nullable": true }, "title": { "type": "string", "description": "Name of the location", "example": "Main Office", "nullable": true }, "description": { "type": "string", "description": "Description of the location", "example": "Our main downtown office location with 3 treatment rooms", "nullable": true }, "slug": { "type": "string", "description": "URL-friendly slug for the location (unique per store)", "example": "new-york" }, "type": { "type": "string", "description": "Type of location", "enum": [ "physical", "online", "delivery" ], "example": "physical" }, "link": { "type": "string", "description": "URL link for online locations", "example": "https://zoom.us/j/123456789", "nullable": true }, "addressLine1": { "type": "string", "description": "First line of address for physical locations", "example": "123 Main Street", "nullable": true }, "addressLine2": { "type": "string", "description": "Second line of address for physical locations", "example": "Suite 200", "nullable": true }, "city": { "type": "string", "description": "City for physical locations", "example": "San Francisco", "nullable": true }, "state": { "type": "string", "description": "State/province for physical locations", "example": "CA", "nullable": true }, "postalCode": { "type": "string", "description": "Postal code for physical locations", "example": "94105", "nullable": true }, "country": { "type": "string", "description": "Country for physical locations", "example": "United States", "nullable": true }, "displayAddress": { "type": "string", "description": "Merchant-defined display address that overrides the auto-formatted address (emails, booking page). Null falls back to the concatenated address fields.", "example": "Podcast House, Floor 3, 87 Turmill Street, London, EC1M 5QU", "nullable": true }, "addressPlaceId": { "type": "string", "description": "Google Place ID for the physical address", "example": "ChIJIQBpAG2ahYAR_6128GcTUEo", "nullable": true }, "latitude": { "type": "number", "description": "Latitude in WGS84", "example": 37.4224764, "nullable": true }, "longitude": { "type": "number", "description": "Longitude in WGS84", "example": -122.0842499, "nullable": true }, "createdAt": { "type": "string", "description": "Date when the location was created", "example": "2023-01-20T08:30:00Z" }, "updatedAt": { "type": "string", "description": "Date when the location was last updated", "example": "2023-02-15T14:20:00Z", "nullable": true }, "deletedAt": { "type": "string", "description": "Date when the location was deleted (for soft deletes)", "example": "2023-03-10T11:45:00Z", "nullable": true }, "address": { "type": "string", "description": "The formatted address string", "nullable": true } }, "required": [ "id", "storeId", "scheduleId", "title", "description", "slug", "type", "link", "addressLine1", "addressLine2", "city", "state", "postalCode", "country", "addressPlaceId", "latitude", "longitude", "createdAt", "updatedAt", "deletedAt", "address" ] }, "AddOnDetailStaffMember": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "storeId": { "type": "string", "description": "ID of the store that owns this staff member record", "example": "123e4567-e89b-12d3-a456-426614174111" }, "userId": { "type": "string", "description": "User ID of the staff member login identity (nullable until linked)", "example": "user-uuid" }, "scheduleId": { "type": "string", "description": "ID of the schedule assigned to this staff member, defines their availability", "example": "123e4567-e89b-12d3-a456-426614174000" }, "imageId": { "type": "string", "description": "ID of the image associated with this staff member", "example": "123e4567-e89b-12d3-a456-426614174000" }, "firstName": { "type": "string", "description": "First name of the staff member", "example": "John" }, "lastName": { "type": "string", "description": "Last name of the staff member", "example": "Doe" }, "email": { "type": "string", "description": "Email address of the staff member, used for notifications and calendar integration", "example": "john.doe@example.com" }, "slug": { "type": "string", "description": "URL-friendly slug for the staff member (unique per store)", "example": "mike" }, "refreshToken": { "type": "string", "description": "Refresh token for integrations like Google Calendar", "example": "abc123xyz456" }, "createdAt": { "type": "string", "description": "Date and time when the staff member was created", "example": "2025-05-01T12:00:00Z" }, "updatedAt": { "type": "string", "description": "Date and time when the staff member was last updated", "example": "2025-05-15T14:30:00Z" }, "deletedAt": { "type": "string", "description": "Date and time when the staff member was soft deleted", "example": "2025-06-01T09:15:00Z" }, "image": { "description": "Profile image of the staff member", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "storeId", "userId", "scheduleId", "imageId", "firstName", "lastName", "email", "slug", "refreshToken", "createdAt", "updatedAt", "deletedAt" ] }, "AddOnDetailProduct": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "productId": { "type": "string", "description": "ID of the product", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID)", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID)", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this product", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the product (unique per store)", "example": "haircut-basic" }, "scheduleId": { "type": "string", "description": "ID of the schedule associated with this product" }, "productPoolId": { "type": "string", "description": "ID of the product pool this product belongs to (controls overlap prevention)", "nullable": true }, "title": { "type": "string", "description": "Title of the product", "example": "Haircut Service" }, "variantTitle": { "type": "string", "description": "Title of the specific product variant", "example": "Short Hair" }, "description": { "type": "string", "description": "Detailed description of the product" }, "imageId": { "type": "string", "description": "ID of the product image" }, "color": { "type": "string", "description": "Color code for displaying the product", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "BLUE", "default": "slate" }, "price": { "type": "number", "description": "Price of the product", "example": 250 }, "taxable": { "type": "boolean", "description": "Whether the product is taxable", "default": false }, "duration": { "type": "number", "description": "Duration of the service in seconds", "example": 3600 }, "allowCustomDuration": { "type": "boolean", "description": "Whether customers can customize the duration by selecting multiples of the base service duration (e.g., if base duration is 1 day, customers can book 1, 2, 3+ days)", "default": false }, "maxDuration": { "type": "number", "description": "When allow_custom_duration=true, maximum duration allowed for multi-duration bookings in seconds (-1 for unlimited)", "default": -1 }, "maxAttendees": { "type": "number", "description": "Maximum number of attendees allowed", "default": 1 }, "maxGuests": { "type": "number", "description": "Maximum number of guests allowed per appointment. Null means unlimited.", "nullable": true }, "allowGuests": { "type": "boolean", "description": "Whether customers can invite guests to the appointment", "default": false }, "allowCustomerReschedule": { "type": "boolean", "description": "Whether customers can reschedule their bookings", "default": false }, "allowCustomerCancel": { "type": "boolean", "description": "Whether customers can cancel their bookings", "default": false }, "rescheduleGap": { "type": "number", "description": "Time in seconds before appointment when rescheduling is no longer allowed" }, "cancelGap": { "type": "number", "description": "Time in seconds before appointment when cancellation is no longer allowed" }, "beforeGap": { "type": "number", "description": "Buffer time in seconds required before this service" }, "afterGap": { "type": "number", "description": "Buffer time in seconds required after this service" }, "fixedTimes": { "type": "boolean", "description": "When allow_custom_duration=true, whether appointments must start and end at fixed times (like fixed check-in/check-out times for multi-duration bookings)", "default": false }, "fixedStartTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must start (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "09:00:00" }, "fixedEndTime": { "type": "string", "description": "When allow_custom_duration=true and fixed_times=true, the fixed time when appointments must end (HH:MM:SS) - specified in the product's schedule timezone, or user settings timezone if no schedule is assigned", "example": "17:00:00" }, "advanceScheduleThreshold": { "type": "number", "description": "How many days in advance bookings can be made", "default": 0 }, "sendConfirmationEmail": { "type": "boolean", "description": "Whether to send confirmation emails for bookings", "default": true }, "sendReminderEmail": { "type": "boolean", "description": "Whether to send reminder emails before appointments", "default": false }, "sendFeedbackEmail": { "type": "boolean", "description": "Whether to send feedback request emails after appointments", "default": false }, "skipCheckout": { "type": "boolean", "description": "Whether to skip the checkout process for this product (Shopify merchants only)", "default": false }, "status": { "type": "string", "description": "Current status of the product", "enum": [ "active", "inactive" ], "example": "ACTIVE", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the product was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the product was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the product was deleted (for soft deletes)" }, "image": { "description": "Primary image of the product", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] } }, "required": [ "id", "productId", "externalId", "externalVariantId", "storeId", "slug", "scheduleId", "productPoolId", "title", "variantTitle", "description", "imageId", "color", "price", "taxable", "duration", "allowCustomDuration", "maxDuration", "maxAttendees", "maxGuests", "allowGuests", "allowCustomerReschedule", "allowCustomerCancel", "rescheduleGap", "cancelGap", "beforeGap", "afterGap", "fixedTimes", "fixedStartTime", "fixedEndTime", "advanceScheduleThreshold", "sendConfirmationEmail", "sendReminderEmail", "sendFeedbackEmail", "skipCheckout", "status", "createdAt", "updatedAt", "deletedAt" ] }, "AddOnDetailResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the add-on", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External platform product ID (e.g. Shopify Product ID) for synced add-ons", "example": "1234567890" }, "externalVariantId": { "type": "string", "description": "External platform variant ID (e.g. Shopify Variant ID) for synced add-ons", "example": "9876543210" }, "storeId": { "type": "string", "description": "ID of the store that owns this add-on", "example": "123e4567-e89b-12d3-a456-426614174001" }, "slug": { "type": "string", "description": "URL-friendly slug for the add-on (unique per store)", "example": "child-seat" }, "title": { "type": "string", "description": "Title of the add-on", "example": "Child Seat" }, "description": { "type": "string", "description": "Detailed description of the add-on" }, "imageId": { "type": "string", "description": "ID of the primary image for the add-on" }, "color": { "type": "string", "description": "Color code used when displaying the add-on", "enum": [ "slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose" ], "example": "slate", "default": "slate" }, "price": { "type": "number", "description": "Unit price of the add-on", "example": 15 }, "taxable": { "type": "boolean", "description": "Whether the add-on is taxable", "default": true }, "durationMultiplied": { "type": "boolean", "description": "When true, the add-on is charged per base-duration unit of the parent appointment. Quantity on the cart/order line item mirrors the parent CartItem.quantity (i.e., the booked duration units). Only meaningful for attached products with allowCustomDuration=true.", "default": false }, "maxQuantity": { "type": "number", "description": "Maximum quantity a customer can pick for this add-on. Only applies to fixed add-ons (durationMultiplied=false). Null means unlimited.", "example": 4, "minimum": 1, "nullable": true }, "status": { "type": "string", "description": "Current status of the add-on", "enum": [ "active", "inactive" ], "example": "active", "default": "active" }, "createdAt": { "type": "string", "description": "Timestamp when the add-on was created" }, "updatedAt": { "type": "string", "description": "Timestamp when the add-on was last updated" }, "deletedAt": { "type": "string", "description": "Timestamp when the add-on was soft-deleted" }, "image": { "description": "Primary image of the add-on", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Image" } ] }, "images": { "description": "Gallery images for this add-on", "type": "array", "items": { "$ref": "#/components/schemas/Image" } }, "locations": { "description": "Locations where this add-on is available", "type": "array", "items": { "$ref": "#/components/schemas/AddOnDetailLocation" } }, "staffMembers": { "description": "Staff members who can deliver this add-on", "type": "array", "items": { "$ref": "#/components/schemas/AddOnDetailStaffMember" } }, "products": { "description": "Products that offer this add-on at checkout", "type": "array", "items": { "$ref": "#/components/schemas/AddOnDetailProduct" } } }, "required": [ "id", "externalId", "externalVariantId", "storeId", "slug", "title", "description", "imageId", "color", "price", "taxable", "durationMultiplied", "maxQuantity", "status", "createdAt", "updatedAt", "deletedAt", "images", "locations", "staffMembers", "products" ] }, "CustomerProviderCatalogItem": { "type": "object", "properties": { "name": { "type": "string", "description": "Provider identifier", "enum": [ "stripe", "cash", "bank_transfer", "shopify", "no_payment_required" ], "example": "stripe" }, "displayName": { "type": "string", "description": "Display name for UI", "example": "Stripe" }, "description": { "type": "string", "description": "Human-readable description", "example": "Accept cards and wallets with Stripe" }, "checkoutMode": { "type": "string", "description": "Checkout integration mode", "enum": [ "internal", "redirect", "manual", "none" ], "example": "internal" }, "icon": { "type": "string", "description": "Icon identifier", "example": "stripe" }, "mode": { "type": "string", "description": "Provider mode (test or live) - only for providers that support it", "enum": [ "test", "live" ], "example": "test" } }, "required": [ "name", "displayName", "checkoutMode" ] }, "PaymentSettingResponse": { "type": "object", "properties": { "id": { "type": "string" }, "storeId": { "type": "string", "description": "Store id" }, "captureMethod": { "type": "string", "enum": [ "automatic", "manual", "on_fulfillment" ] } }, "required": [ "id", "storeId", "captureMethod" ] }, "InvoiceResponse": { "type": "object", "properties": { "id": { "type": "string" }, "storeId": { "type": "string", "description": "Store that owns the invoice" }, "orderId": { "type": "string", "description": "Order the invoice was issued for" }, "customerId": { "type": "string", "description": "Customer the invoice is billed to" }, "number": { "type": "string", "description": "Human-facing invoice number", "example": "INV-1001" }, "provider": { "type": "string", "description": "Provider used to issue the invoice", "enum": [ "stripe", "cash", "bank_transfer", "shopify", "no_payment_required" ] }, "kind": { "type": "string", "description": "Whether this is a collectible invoice or a paid receipt", "enum": [ "collectible", "receipt" ] }, "status": { "type": "string", "enum": [ "draft", "sent", "paid", "void", "failed" ] }, "amountDue": { "type": "number", "description": "Outstanding amount this invoice is for", "example": 49.99 }, "currencyCode": { "type": "string", "description": "Currency code", "example": "USD" }, "snapshot": { "type": "object", "description": "Immutable snapshot of the billable state at issue time" }, "externalId": { "type": "string", "description": "External invoice id (Stripe invoice id / Shopify reference)" }, "paymentIntentId": { "type": "string", "description": "For receipts: the Stripe PaymentIntent (pi_...) this receipt documents. Null for collectible invoices.", "nullable": true }, "externalUrl": { "type": "string", "description": "Hosted invoice / payment URL (e.g. Stripe hosted_invoice_url)" }, "pdfStorageKey": { "type": "string", "description": "S3 object key of the generated PDF (manual invoices)" }, "error": { "type": "string", "description": "Failure reason when status is failed" }, "issuedAt": { "format": "date-time", "type": "string", "description": "When the invoice was issued" }, "dueAt": { "format": "date-time", "type": "string", "description": "When the invoice is due" }, "sentAt": { "format": "date-time", "type": "string", "description": "When the invoice was delivered to the customer" }, "paidAt": { "format": "date-time", "type": "string", "description": "When the outstanding amount was paid" } }, "required": [ "id", "storeId", "orderId", "customerId", "number", "provider", "kind", "status", "amountDue", "currencyCode", "snapshot", "externalId", "paymentIntentId", "externalUrl", "pdfStorageKey", "error", "issuedAt", "dueAt", "sentAt", "paidAt" ] }, "FeedbackQuestionResponseTranslation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the translation", "example": "550e8400-e29b-41d4-a716-446655440000" }, "questionId": { "type": "string", "description": "ID of the feedback question this translation belongs to", "example": "550e8400-e29b-41d4-a716-446655440000" }, "title": { "type": "string", "description": "Translated title of the question shown to customers", "example": "How would you rate our service?" }, "description": { "type": "string", "description": "Translated description or additional instructions for the question", "example": "Please rate your overall satisfaction with our service." }, "options": { "description": "Available options for dropdown or rating questions in this language", "example": [ "Poor", "Fair", "Good", "Very Good", "Excellent" ], "nullable": true, "type": "array", "items": { "type": "string" } }, "languageCode": { "type": "string", "description": "Language code for this translation", "enum": [ "af", "ak", "am", "ar", "as", "az", "be", "bg", "bm", "bn", "bo", "br", "bs", "ca", "ce", "cs", "cu", "cy", "da", "de", "dz", "ee", "el", "en", "eo", "es", "et", "eu", "fa", "ff", "fi", "fo", "fr", "fy", "ga", "gd", "gl", "gu", "gv", "ha", "he", "hi", "hr", "hu", "hy", "ia", "id", "ig", "ii", "is", "it", "ja", "jv", "ka", "ki", "kk", "kl", "km", "kn", "ko", "ks", "ku", "kw", "ky", "lb", "lg", "ln", "lo", "lt", "lu", "lv", "mg", "mi", "mk", "ml", "mn", "mr", "ms", "mt", "my", "nb", "nd", "ne", "nl", "nn", "no", "om", "or", "os", "pa", "pl", "ps", "pt", "pt_br", "pt_pt", "qu", "rm", "rn", "ro", "ru", "rw", "sd", "se", "sg", "si", "sk", "sl", "sn", "so", "sq", "sr", "su", "sv", "sw", "ta", "te", "tg", "th", "ti", "tk", "to", "tr", "tt", "ug", "uk", "ur", "uz", "vi", "vo", "wo", "xh", "yi", "yo", "zh", "zh_cn", "zh_tw", "zu" ], "example": "en" }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the translation was created", "example": "2023-01-01T00:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the translation was last updated", "example": "2023-01-15T00:00:00Z", "nullable": true } }, "required": [ "id", "questionId", "title", "description", "options", "languageCode", "createdAt", "updatedAt" ] }, "FeedbackQuestionResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the feedback question", "example": "550e8400-e29b-41d4-a716-446655440000" }, "internalName": { "type": "string", "description": "Internal name for the question (not shown to customers)", "example": "Service Quality Rating Question" }, "required": { "type": "boolean", "description": "Whether the question is required to be answered", "example": true }, "type": { "type": "string", "description": "Type of input for the question", "enum": [ "single-line-text-field", "multi-line-text-field", "dropdown", "rating", "checkbox", "file-upload" ], "example": "rating" }, "order": { "type": "number", "description": "Display order of the question (lower numbers appear first)", "example": 1, "default": 0 }, "alwaysShow": { "type": "boolean", "description": "Whether this question is shown for all products in the store", "example": false, "default": false }, "fileConfig": { "type": "object", "description": "File-upload constraints (allowed categories, max size, max files). Only set when type is file-upload.", "example": { "categories": [ "images", "pdf" ], "maxSizeBytes": 26214400, "maxFiles": 5 }, "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the question was created", "example": "2023-01-01T00:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the question was last updated", "example": "2023-01-15T00:00:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date when the question was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this question", "example": "store-uuid" }, "translations": { "description": "Translations of this question (filtered to the requested language)", "type": "array", "items": { "$ref": "#/components/schemas/FeedbackQuestionResponseTranslation" } } }, "required": [ "id", "internalName", "required", "type", "order", "alwaysShow", "createdAt", "updatedAt", "deletedAt", "storeId", "translations" ] }, "CheckoutQuestionResponseTranslation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the translation", "example": "550e8400-e29b-41d4-a716-446655440000" }, "questionId": { "type": "string", "description": "ID of the checkout question this translation belongs to", "example": "550e8400-e29b-41d4-a716-446655440000" }, "title": { "type": "string", "description": "Translated title of the question shown to customers", "example": "Do you have any allergies?" }, "description": { "type": "string", "description": "Translated description or additional instructions for the question", "example": "Please let us know about any food allergies or dietary restrictions." }, "options": { "description": "Available options for dropdown or checkbox questions in this language", "example": [ "Nut allergy", "Gluten intolerance", "Lactose intolerance", "None" ], "nullable": true, "type": "array", "items": { "type": "string" } }, "languageCode": { "type": "string", "description": "Language code for this translation", "enum": [ "af", "ak", "am", "ar", "as", "az", "be", "bg", "bm", "bn", "bo", "br", "bs", "ca", "ce", "cs", "cu", "cy", "da", "de", "dz", "ee", "el", "en", "eo", "es", "et", "eu", "fa", "ff", "fi", "fo", "fr", "fy", "ga", "gd", "gl", "gu", "gv", "ha", "he", "hi", "hr", "hu", "hy", "ia", "id", "ig", "ii", "is", "it", "ja", "jv", "ka", "ki", "kk", "kl", "km", "kn", "ko", "ks", "ku", "kw", "ky", "lb", "lg", "ln", "lo", "lt", "lu", "lv", "mg", "mi", "mk", "ml", "mn", "mr", "ms", "mt", "my", "nb", "nd", "ne", "nl", "nn", "no", "om", "or", "os", "pa", "pl", "ps", "pt", "pt_br", "pt_pt", "qu", "rm", "rn", "ro", "ru", "rw", "sd", "se", "sg", "si", "sk", "sl", "sn", "so", "sq", "sr", "su", "sv", "sw", "ta", "te", "tg", "th", "ti", "tk", "to", "tr", "tt", "ug", "uk", "ur", "uz", "vi", "vo", "wo", "xh", "yi", "yo", "zh", "zh_cn", "zh_tw", "zu" ], "example": "en" }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the translation was created", "example": "2023-01-01T00:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the translation was last updated", "example": "2023-01-15T00:00:00Z", "nullable": true } }, "required": [ "id", "questionId", "title", "description", "options", "languageCode", "createdAt", "updatedAt" ] }, "CheckoutQuestionResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the checkout question", "example": "550e8400-e29b-41d4-a716-446655440000" }, "internalName": { "type": "string", "description": "Internal name for the question (not shown to customers)", "example": "Customer Allergies Question" }, "required": { "type": "boolean", "description": "Whether the question is required to be answered", "example": true }, "type": { "type": "string", "description": "Type of input for the question", "enum": [ "single-line-text-field", "multi-line-text-field", "dropdown", "rating", "checkbox", "file-upload" ], "example": "single-line-text-field" }, "order": { "type": "number", "description": "Display order of the question (lower numbers appear first)", "example": 1, "default": 0 }, "alwaysShow": { "type": "boolean", "description": "Whether this question is shown for all products in the store", "example": false, "default": false }, "fileConfig": { "type": "object", "description": "File-upload constraints (allowed categories, max size, max files). Only set when type is file-upload.", "example": { "categories": [ "images", "pdf" ], "maxSizeBytes": 26214400, "maxFiles": 5 }, "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Date and time when the question was created", "example": "2023-01-01T00:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date and time when the question was last updated", "example": "2023-01-15T00:00:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Date when the question was soft-deleted", "example": "2023-06-03T09:45:00Z", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this question", "example": "store-uuid" }, "translations": { "description": "Translations of this question (filtered to the requested language)", "type": "array", "items": { "$ref": "#/components/schemas/CheckoutQuestionResponseTranslation" } } }, "required": [ "id", "internalName", "required", "type", "order", "alwaysShow", "createdAt", "updatedAt", "deletedAt", "storeId", "translations" ] }, "GenerateUploadUrl": { "type": "object", "properties": { "questionId": { "type": "string", "description": "ID of the file-upload question the file answers", "format": "uuid" }, "questionKind": { "type": "string", "description": "Whether the question is a checkout or feedback question", "enum": [ "checkout", "feedback" ] }, "filename": { "type": "string", "description": "Original filename", "example": "logo.png" }, "mime": { "type": "string", "description": "MIME type of the file", "example": "image/png" }, "size": { "type": "number", "description": "Size of the file in bytes", "example": 20480 } }, "required": [ "questionId", "questionKind", "filename", "mime", "size" ] }, "GenerateUploadUrlResponse": { "type": "object", "properties": { "fileId": { "type": "string", "description": "ID of the created file record (store this as part of the answer)" }, "presignedUrl": { "type": "string", "description": "Presigned S3 PUT URL — upload the bytes here with a matching Content-Type" }, "expiresIn": { "type": "number", "description": "Seconds until the presigned URL expires", "example": 3600 } }, "required": [ "fileId", "presignedUrl", "expiresIn" ] }, "ImageResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier", "example": "123e4567-e89b-12d3-a456-426614174000" }, "externalId": { "type": "string", "description": "External identifier for the image (e.g., from storage provider)", "example": "img_123456", "nullable": true }, "url": { "type": "string", "description": "URL where the image can be accessed", "example": "https://storage.example.com/images/product-image.jpg" }, "filename": { "type": "string", "description": "Original filename of the uploaded image", "example": "product-image.jpg", "nullable": true }, "mime": { "type": "string", "description": "MIME type of the image", "example": "image/jpeg", "nullable": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Creation timestamp", "example": "2023-01-01T12:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Last update timestamp", "example": "2023-01-02T12:00:00Z", "nullable": true }, "deletedAt": { "format": "date-time", "type": "string", "description": "Soft deletion timestamp", "example": "2023-01-03T12:00:00Z", "nullable": true }, "storeId": { "type": "string", "description": "ID of the store that owns this image", "example": "store-uuid", "nullable": true } }, "required": [ "id", "externalId", "url", "filename", "mime", "createdAt", "updatedAt", "deletedAt", "storeId" ] } } }, "security": [ { "Storefront API key": [] } ], "x-tagGroups": [ { "name": "Storefront", "tags": [ "Products", "Product Collections", "Staff Members", "Locations", "Cart", "Checkout", "Checkout Questions", "Store", "Payment", "Images" ] }, { "name": "Customer", "tags": [ "Auth", "Self-Service", "Appointments", "Orders", "Feedback Questions" ] } ] }