# Galactic Core API Documentation ## Docs - [Get current user](https://docs.tybritelabs.com/api-reference/authentication/get-current-user.md): Get current authenticated user details. **⚠️ SECRET KEY REQUIRED** This endpoint requires a secret key (tybrite_sk_*). Publishable keys will return 403 Forbidden. **Special Headers:** - `x-auth-token`: **REQUIRED** - Authentication token from login/register response **Usage:** ``` GET /v… - [Login with email and password](https://docs.tybritelabs.com/api-reference/authentication/login-with-email-and-password.md): Authenticate using email and password credentials. Returns user details and session tokens upon successful authentication. **⚠️ SECRET KEY REQUIRED** This endpoint requires a secret key (tybrite_sk_*). Publishable keys will return 403 Forbidden. - [Logout current session](https://docs.tybritelabs.com/api-reference/authentication/logout-current-session.md): Invalidate the current access and refresh tokens. **⚠️ SECRET KEY REQUIRED** This endpoint requires a secret key (tybrite_sk_*). Publishable keys will return 403 Forbidden. - [Refresh access token](https://docs.tybritelabs.com/api-reference/authentication/refresh-access-token.md): Get new access token using refresh token. **⚠️ SECRET KEY REQUIRED** This endpoint requires a secret key (tybrite_sk_*). Publishable keys will return 403 Forbidden. - [Register customer account](https://docs.tybritelabs.com/api-reference/authentication/register-customer-account.md): Create a new customer account with email and password. Returns user details and authentication tokens upon successful registration. **Multi-Store Support:** - If the email is already registered at another store, a new customer record is created for this store (linked to the existing auth.users… - [Request password reset](https://docs.tybritelabs.com/api-reference/authentication/request-password-reset.md): Send a password reset link to the customer's email. **⚠️ SECRET KEY REQUIRED** This endpoint requires a secret key (tybrite_sk_*). Publishable keys will return 403 Forbidden. - [Send magic link / OTP](https://docs.tybritelabs.com/api-reference/authentication/send-magic-link-otp.md): Send a passwordless authentication link or OTP code to the customer's email. The link/code is valid for 15 minutes. **⚠️ SECRET KEY REQUIRED** This endpoint requires a secret key (tybrite_sk_*). Publishable keys will return 403 Forbidden. - [Update password](https://docs.tybritelabs.com/api-reference/authentication/update-password.md): Update user password (requires authentication). **⚠️ SECRET KEY REQUIRED** This endpoint requires a secret key (tybrite_sk_*). Publishable keys will return 403 Forbidden. **Special Headers:** - `x-auth-token`: **REQUIRED** - Authentication token from login/register response **Usage:** ``… - [Verify OTP code](https://docs.tybritelabs.com/api-reference/authentication/verify-otp-code.md): Verify the OTP code sent via email and complete authentication. **⚠️ SECRET KEY REQUIRED** This endpoint requires a secret key (tybrite_sk_*). Publishable keys will return 403 Forbidden. - [Add to cart](https://docs.tybritelabs.com/api-reference/cart-&-wishlist/add-to-cart.md): Add item to cart with automatic stock checking. If the same variant already exists in the cart, the quantity is incremented. - [Add to wishlist](https://docs.tybritelabs.com/api-reference/cart-&-wishlist/add-to-wishlist.md): Add a variant to a customer's wishlist. Returns `201 Created` on success. If the same `(customer_id, product_id, variant_id)` already exists, returns `409 Conflict` instead of duplicating the entry. - [Clear cart](https://docs.tybritelabs.com/api-reference/cart-&-wishlist/clear-cart.md): Clear all items from a cart for the given customer or session. - [Get cart](https://docs.tybritelabs.com/api-reference/cart-&-wishlist/get-cart.md): Retrieve cart contents for customer or session. **Cart Association:** - Provide `X-Session-Id` header for anonymous carts (before customer login) - Provide `customer_id` query parameter for authenticated customer carts - If both provided, `customer_id` takes precedence - If neither provided, retu… - [Get wishlist](https://docs.tybritelabs.com/api-reference/cart-&-wishlist/get-wishlist.md): Retrieve a customer's wishlist. Wishlists are always customer-scoped, so `customer_id` is required (anonymous wishlists are not supported). - [Merge carts](https://docs.tybritelabs.com/api-reference/cart-&-wishlist/merge-carts.md): Merge an anonymous session cart into a customer cart after login. - [Move wishlist item to cart](https://docs.tybritelabs.com/api-reference/cart-&-wishlist/move-wishlist-item-to-cart.md): Atomically move a wishlist item into the customer's cart. The variant's stock is validated; on success the item is added to (or merged with) the cart and removed from the wishlist. Returns the refreshed cart. - [Remove cart item](https://docs.tybritelabs.com/api-reference/cart-&-wishlist/remove-cart-item.md): Remove a specific item from the cart by its cart item ID. - [Remove from wishlist](https://docs.tybritelabs.com/api-reference/cart-&-wishlist/remove-from-wishlist.md): Remove a wishlist item by ID. The item is scoped to the supplied `customer_id`, which is required. - [Update cart item](https://docs.tybritelabs.com/api-reference/cart-&-wishlist/update-cart-item.md): Update the quantity of an existing cart item. Setting `quantity` to `0` removes the item from the cart. Ownership is verified against either `customer_id` (when provided) or the `X-Session-Id` header. - [Get blog post by slug](https://docs.tybritelabs.com/api-reference/cms/get-blog-post-by-slug.md) - [Get lookbook details by slug](https://docs.tybritelabs.com/api-reference/cms/get-lookbook-details-by-slug.md) - [List blog posts](https://docs.tybritelabs.com/api-reference/cms/list-blog-posts.md) - [List lookbooks](https://docs.tybritelabs.com/api-reference/cms/list-lookbooks.md) - [Create customer](https://docs.tybritelabs.com/api-reference/customers/create-customer.md): Requires secret key - [Get customer details](https://docs.tybritelabs.com/api-reference/customers/get-customer-details.md): Returns the authenticated customer's profile + store-level metrics. - [Update customer](https://docs.tybritelabs.com/api-reference/customers/update-customer.md): Partially update the authenticated customer's profile. Only the fields provided in the request body are updated. - [Check gift card balance](https://docs.tybritelabs.com/api-reference/gift-cards/check-gift-card-balance.md): Look up a gift card by code and check its validity, balance, expiry and maximum-usage rules. Accessible with both publishable (`tybrite_pk_*`) and secret (`tybrite_sk_*`) API keys. - [List gift cards](https://docs.tybritelabs.com/api-reference/gift-cards/list-gift-cards.md): Retrieve gift cards belonging to a specific customer, scoped to the authenticated store. - [Introduction](https://docs.tybritelabs.com/api-reference/introduction.md): Reference for the Tybrite API and the Galactic Core infrastructure - [Create new conversation](https://docs.tybritelabs.com/api-reference/messaging/create-new-conversation.md): Start a new message thread with an initial customer message. Requires a secret key. - [Delete message](https://docs.tybritelabs.com/api-reference/messaging/delete-message.md): Deletes a message. Requires a secret key. - [Edit message](https://docs.tybritelabs.com/api-reference/messaging/edit-message.md): Edits the content of an existing message. Sets `is_edited = true` and records `edited_at`. Cannot edit a soft-deleted message. Requires a secret key. - [Get messages in a thread](https://docs.tybritelabs.com/api-reference/messaging/get-messages-in-a-thread.md): Returns messages in a thread. Soft-deleted messages are excluded by default. Supports cursor-based pagination and sort order (default: oldest first). - [Get thread details](https://docs.tybritelabs.com/api-reference/messaging/get-thread-details.md) - [List message threads](https://docs.tybritelabs.com/api-reference/messaging/list-message-threads.md): Returns messaging threads filtered by customer. Supports cursor-based pagination, field filtering, and server-side status/priority/archived/unread filtering. Pinned threads are returned first in the result set. - [Mark thread as read](https://docs.tybritelabs.com/api-reference/messaging/mark-thread-as-read.md): Resets `unread_count_store` to 0 and marks all customer messages in the thread as `read`. Requires a secret key. - [Send message to thread](https://docs.tybritelabs.com/api-reference/messaging/send-message-to-thread.md): Add a message to an existing thread - [Update thread](https://docs.tybritelabs.com/api-reference/messaging/update-thread.md): Update thread status, priority, or toggle the archived/muted/pinned state. Requires a secret key. - [Create order](https://docs.tybritelabs.com/api-reference/orders/create-order.md): Create a new order with HMAC signature verification and idempotency protection. - [Get order details](https://docs.tybritelabs.com/api-reference/orders/get-order-details.md): Retrieve detailed information about a specific order including line items and status. - [Update order](https://docs.tybritelabs.com/api-reference/orders/update-order.md): Update specific fields of an existing order with HMAC signature verification and idempotency protection. - [Get available payment methods](https://docs.tybritelabs.com/api-reference/payments/get-available-payment-methods.md): Retrieve all configured payment methods for the store, including their supported currencies, integration types, and environment status. - [Initialize payment](https://docs.tybritelabs.com/api-reference/payments/initialize-payment.md): Initialize a payment transaction with HMAC signature verification and idempotency protection. - [Verify payment status](https://docs.tybritelabs.com/api-reference/payments/verify-payment-status.md): Verify the status of a payment transaction using the payment reference. This endpoint queries the payment provider's API to get the current status. **⚠️ SECRET KEY REQUIRED** This endpoint requires a secret key (tybrite_sk_*). Publishable keys will return 403 Forbidden. **Why Secret Key?**… - [Get prices for multiple products with dynamic pricing and multi-currency support](https://docs.tybritelabs.com/api-reference/pricing/get-prices-for-multiple-products-with-dynamic-pricing-and-multi-currency-support.md): Calculate dynamic prices for products based on customer segment, location, volume, and geographic currency detection. **Multi-Currency Support:** - Automatically detects currency based on customer location (coordinates or place name) - Converts prices from store's base currency to detected curren… - [Get product pricing by SEO-friendly slug with dynamic pricing and multi-currency support](https://docs.tybritelabs.com/api-reference/pricing/get-product-pricing-by-seo-friendly-slug-with-dynamic-pricing-and-multi-currency-support.md): Calculate dynamic price for a single product using its SEO-friendly slug with geographic currency detection. **SEO-Friendly URLs:** - Use product slugs instead of UUIDs for better SEO - Example: `/v1/prices/products/by-slug/sony-wh-1000xm4-a089d` - Slug format: `{product-name}-{short-id}` **Re… - [Get single product pricing with dynamic pricing and multi-currency support](https://docs.tybritelabs.com/api-reference/pricing/get-single-product-pricing-with-dynamic-pricing-and-multi-currency-support.md): Calculate dynamic price for a single product with geographic currency detection. **Response Structure:** - Simple products: Flat structure with all data at root level - Multi-variant products: Hierarchical structure with product-level data + variants array - Each variant gets its own pricing calc… - [Get items in a product collection](https://docs.tybritelabs.com/api-reference/products/get-items-in-a-product-collection.md): Returns all items belonging to a product collection, ordered by `sort_order`. Each item contains the linked online product row along with its sort position. If the collection has no items (or does not exist), an empty array is returned. - [Get product by ID or variant ID](https://docs.tybritelabs.com/api-reference/products/get-product-by-id-or-variant-id.md): Retrieve complete details for a single product using either its product ID or variant ID. **Response Structure:** - **Simple products (no variants):** Flat structure with all data at root level - **Multi-variant products:** Hierarchical structure with: - Product-level data at root (name, descri… - [Get product by SEO-friendly slug](https://docs.tybritelabs.com/api-reference/products/get-product-by-seo-friendly-slug.md): Retrieve product information using a human-readable, SEO-friendly slug. **Response Structure:** Same as GET /v1/products/{id}: - **Simple products:** Flat structure with all data at root - **Multi-variant products:** Hierarchical structure with product-level data + variants array **Field Filte… - [Get product collection by ID](https://docs.tybritelabs.com/api-reference/products/get-product-collection-by-id.md) - [Get product specifications](https://docs.tybritelabs.com/api-reference/products/get-product-specifications.md): Retrieves the latest specification version for a specific product - [List product collections](https://docs.tybritelabs.com/api-reference/products/list-product-collections.md) - [List product specifications](https://docs.tybritelabs.com/api-reference/products/list-product-specifications.md): Returns a paginated list of product specifications for the authenticated store, ordered by most recently updated. Supports filtering by `product_id` and `status`. - [List products with filtering and pagination](https://docs.tybritelabs.com/api-reference/products/list-products-with-filtering-and-pagination.md): Retrieve a paginated list of products with support for filtering, search, and field selection. **Response Structure:** Returns flat structure with default variant data only (no variants array). This keeps payloads small for fast catalog browsing. Use the `has_variants` flag to determine if a det… - [Get promotion details](https://docs.tybritelabs.com/api-reference/promotions/get-promotion-details.md) - [List promotions](https://docs.tybritelabs.com/api-reference/promotions/list-promotions.md): Get active promotions, optionally filtered by cart total - [Get product recommendations](https://docs.tybritelabs.com/api-reference/recommendations/get-product-recommendations.md): AI-powered product recommendations with 5 types: - **similar**: Products similar to given product (embedding-based) - **also-bought**: Frequently purchased together (co-purchase matrix) - **trending**: Currently trending products (velocity-based) - **personalized**: Based on customer preferences - *… - [Semantic search](https://docs.tybritelabs.com/api-reference/search/semantic-search.md): Semantic search using embeddings and cosine similarity. Understands natural language queries like "wireless headphones with noise cancellation". **✅ BOTH KEY TYPES SUPPORTED** This endpoint works with both secret keys (tybrite_sk_*) and publishable keys (tybrite_pk_*). **Note:** Despite usi… - [Simple text search](https://docs.tybritelabs.com/api-reference/search/simple-text-search.md): Fast text-based search using - [Calculate shipping fee](https://docs.tybritelabs.com/api-reference/shipping/calculate-shipping-fee.md): Calculate the delivery fee for a customer based on their location and order total. **Location Input Options:** - **Option 1:** Provide `latitude` and `longitude` (GPS coordinates) - **Option 2:** Provide `place_name` (e.g., "Westlands, Nairobi, Kenya") - automatically geocoded using Nominatim… - [Get shipping zones and pricing tiers](https://docs.tybritelabs.com/api-reference/shipping/get-shipping-zones-and-pricing-tiers.md): Retrieve available delivery zones and distance-based pricing tiers for the store. **Returns:** - **pricing_tiers**: Distance-based pricing (e.g., 0-5km: KES 50, 5-10km: KES 100) - **delivery_zones**: Custom polygon zones (e.g., CBD Zone: KES 150) **Dual Pricing System:** - Distance-based tiers… - [API information](https://docs.tybritelabs.com/api-reference/system/api-information.md): Returns basic API information including version, documentation URL, and available endpoint prefixes. This endpoint does not require authentication. - [Get comprehensive store information](https://docs.tybritelabs.com/api-reference/system/get-comprehensive-store-information.md): Returns comprehensive store metadata and configuration in a single API call. Designed for LLMs and AI agents to quickly understand store context without making multiple API calls. **Purpose:** This endpoint consolidates store metadata that would normally require 10+ separate API calls: - Store b… - [Health check](https://docs.tybritelabs.com/api-reference/system/health-check.md): Returns the health status of the API gateway. This endpoint does not require authentication. - [Get category](https://docs.tybritelabs.com/api-reference/taxonomy/get-category.md): Retrieve a single product category by ID. Accepts both publishable and secret API keys. - [Get subcategory by ID](https://docs.tybritelabs.com/api-reference/taxonomy/get-subcategory-by-id.md): Retrieve a single subcategory by ID. Accepts both publishable and secret API keys. - [List categories](https://docs.tybritelabs.com/api-reference/taxonomy/list-categories.md): Retrieve all product categories for the authenticated store. Accepts both publishable and secret API keys. - [List subcategories](https://docs.tybritelabs.com/api-reference/taxonomy/list-subcategories.md): Retrieve all product subcategories. Optionally filter by parent category. Accepts both publishable and secret API keys. - [Create a webhook endpoint](https://docs.tybritelabs.com/api-reference/webhooks/create-a-webhook-endpoint.md): Register a new HTTPS endpoint to receive outbound event notifications. The `signing_secret` is returned **once** at creation — store it immediately. It cannot be retrieved again; rotate it via a DELETE + re-create if lost. - [Delete a webhook endpoint](https://docs.tybritelabs.com/api-reference/webhooks/delete-a-webhook-endpoint.md): Soft-deletes the endpoint. In-flight deliveries are not cancelled. - [Get a webhook endpoint](https://docs.tybritelabs.com/api-reference/webhooks/get-a-webhook-endpoint.md): Returns full details for a single endpoint including delivery statistics. - [Get a webhook event](https://docs.tybritelabs.com/api-reference/webhooks/get-a-webhook-event.md): Returns a single event with all its delivery attempts across all endpoints. - [List webhook endpoints](https://docs.tybritelabs.com/api-reference/webhooks/list-webhook-endpoints.md): Returns all webhook endpoints for the authenticated store. Soft-deleted endpoints are excluded. - [List webhook events](https://docs.tybritelabs.com/api-reference/webhooks/list-webhook-events.md): Returns the event log for your store in reverse-chronological order. Use this for debugging delivery failures or auditing event history. - [Retry a webhook event](https://docs.tybritelabs.com/api-reference/webhooks/retry-a-webhook-event.md): Manually re-delivers the event to all enabled endpoints that are subscribed to its event type. Each re-delivery is recorded as a new attempt in the delivery log. - [Send a test event](https://docs.tybritelabs.com/api-reference/webhooks/send-a-test-event.md): Sends a synthetic test payload to the endpoint immediately. Useful for verifying signature verification and endpoint connectivity during integration. - [Update a webhook endpoint](https://docs.tybritelabs.com/api-reference/webhooks/update-a-webhook-endpoint.md): Partially update a webhook endpoint. All fields are optional. - [Authentication](https://docs.tybritelabs.com/authentication.md): Learn how to secure your Tybrite commerce integrations using API keys and HMAC signing. - [Custom Integrations](https://docs.tybritelabs.com/custom-integrations.md): Give your commerce stack ultimate flexibility by integrating custom payment and shipping providers while keeping Galactic Core as your source of truth. - [Introduction](https://docs.tybritelabs.com/index.md): Welcome to the new home for your documentation - [Quickstart](https://docs.tybritelabs.com/quickstart.md): Start building awesome documentation in minutes - [Authenticated Session](https://docs.tybritelabs.com/sdk/api-reference/classes/AuthenticationService.md): Reference for the AuthenticationService class in the Tybrite SDK. - [Cart & Wishlist](https://docs.tybritelabs.com/sdk/api-reference/classes/CartWishlistService.md): Reference for the CartWishlistService class in the Tybrite SDK. - [CMS (Blog & Lookbooks)](https://docs.tybritelabs.com/sdk/api-reference/classes/CmsService.md): Reference for the CmsService class in the Tybrite SDK. - [Customers](https://docs.tybritelabs.com/sdk/api-reference/classes/CustomersService.md): Reference for the CustomersService class in the Tybrite SDK. - [Gift Cards](https://docs.tybritelabs.com/sdk/api-reference/classes/GiftCardsService.md): Reference for the GiftCardsService class in the Tybrite SDK. - [Messaging & Support](https://docs.tybritelabs.com/sdk/api-reference/classes/MessagingService.md): Reference for the MessagingService class in the Tybrite SDK. - [Orders](https://docs.tybritelabs.com/sdk/api-reference/classes/OrdersService.md): Reference for the OrdersService class in the Tybrite SDK. - [Payments](https://docs.tybritelabs.com/sdk/api-reference/classes/PaymentsService.md): Reference for the PaymentsService class in the Tybrite SDK. - [Dynamic Pricing](https://docs.tybritelabs.com/sdk/api-reference/classes/PricingService.md): Reference for the PricingService class in the Tybrite SDK. - [Products](https://docs.tybritelabs.com/sdk/api-reference/classes/ProductsService.md): Reference for the ProductsService class in the Tybrite SDK. - [Promotions](https://docs.tybritelabs.com/sdk/api-reference/classes/PromotionsService.md): Reference for the PromotionsService class in the Tybrite SDK. - [AI Recommendations](https://docs.tybritelabs.com/sdk/api-reference/classes/RecommendationsService.md): Reference for the RecommendationsService class in the Tybrite SDK. - [Smart Search](https://docs.tybritelabs.com/sdk/api-reference/classes/SearchService.md): Reference for the SearchService class in the Tybrite SDK. - [Shipping & Logistics](https://docs.tybritelabs.com/sdk/api-reference/classes/ShippingService.md): Reference for the ShippingService class in the Tybrite SDK. - [System Status](https://docs.tybritelabs.com/sdk/api-reference/classes/SystemService.md): Reference for the SystemService class in the Tybrite SDK. - [Taxonomy (Categories)](https://docs.tybritelabs.com/sdk/api-reference/classes/TaxonomyService.md): Reference for the TaxonomyService class in the Tybrite SDK. - [Webhooks](https://docs.tybritelabs.com/sdk/api-reference/classes/WebhooksService.md): Reference for the WebhooksService class in the Tybrite SDK. - [Introduction](https://docs.tybritelabs.com/sdk/introduction.md): Get started with the Tybrite TypeScript SDK for building commerce applications. - [Webhooks](https://docs.tybritelabs.com/webhooks.md): Receive real-time event notifications when orders, payments, customers, and other resources change state in your store. ## OpenAPI Specs - [openapi](https://docs.tybritelabs.com/openapi.yaml) ## Optional - [Dashboard](https://app.tybrite.com) - [GitHub](https://github.com/tybrite) - [Support](mailto:support@tybrite.com)