Skip to main content

Client API Concepts

This guide explains the key concepts and entities specific to the Client API. These concepts are optimized for frontend applications and customer-facing features.

Products & Inventory​

Items​

Description: Public-facing product information. Same item types as Admin API (ReleaseItem, ProductItem, BookItem) but with customer-visible fields only.

Usage: Display products on storefront, show product details, and enable product browsing.

Key Fields: _id, id, title, price, images, listings, data, uri, path

Note: Some admin-only fields are not exposed in the Client API.

Listings​

Description: Sellable product variants visible to customers. Includes pricing, stock availability, and purchase options.

Usage: Display product variants, show pricing and availability, and enable purchases.

Key Fields: _id, id, prices, stock, available, preOrder, options

Inventory​

Description: Public inventory browsing with filtering and search capabilities.

Usage: Browse products, search inventory, filter by various criteria (genre, artist, format, price, etc.).

Key Operations: Filter inventory, search products, paginate results, get suggestions

Shopping & Orders​

Checkouts​

Description: Shopping cart functionality for customers. Create carts, add items, and proceed to checkout.

Usage: Build shopping cart experiences, manage cart items, apply vouchers, and handle checkout flow.

Key Fields: _id, id, items, totals, billing, shipping, vouchers, buyer

Example: A customer's shopping cart with 2 items, shipping address, and applied discount code.

Orders​

Description: Customer's order history and order details. Read-only access to customer's own orders.

Usage: Display order history, show order details, track order status, and handle order communications.

Key Fields: _id, id, status, created, totals, items, billing, shipping, messages

Content & Discovery​

Collections​

Description: Curated product collections displayed on the storefront.

Usage: Show featured collections, browse by category, and display organized product groups.

Key Fields: _id, id, title, handle, banner, description, sort

Articles​

Description: Blog posts and content pages for the storefront.

Usage: Display blog content, create content pages, and show homepage articles.

Key Fields: _id, id, title, handle, content, published, type, tags

Themes​

Description: Storefront theme configuration and styling.

Usage: Access theme settings for rendering the storefront, apply theme styles, and customize appearance.

Key Fields: _id, id, title, colors, settings, css

Playlists​

Description: Curated playlists of items, often for audio previews or featured selections.

Usage: Display playlists, enable audio playback, and showcase curated content.

Key Fields: _id, id, title, items, entries

Music-Specific Concepts​

Artists​

Description: Musical artists browsable by customers. Includes artist information and associated releases.

Usage: Browse by artist, display artist pages, and show artist-related products.

Key Fields: _id, id, name, images, profile, country, tags

Labels​

Description: Record labels browsable by customers. Used for filtering and discovery.

Usage: Browse by label, display label pages, and filter products by label.

Key Fields: _id, id, name, images, profile, country, tags

Tracklists​

Description: Track listings for release items, visible to customers on product pages.

Usage: Display track information, enable audio previews, and show release details.

Key Fields: title, artists, position, duration, uri

Formats, Genres, Styles​

Description: Used for filtering and organizing products in the storefront.

Usage: Filter products by format, genre, or style, and improve product discoverability.

Users & Authentication​

Users (Buyer)​

Description: Customer accounts for end users. Customers can view and update their own profile.

Usage: Customer registration, login, profile management, and preference settings.

Key Fields: _id, email, firstName, lastName, addresses, preferences, isSubscribed

Sessions​

Description: Customer authentication sessions. Created via login and used for authenticated operations.

Usage: Authenticate customer requests, maintain login state, and enable personalized features.

Key Fields: _id, jwt, expires, user

Note: Sessions expire after 3 months and are automatically extended on activity.

Wantlist​

Description: Customer's wishlist of wanted items. Customers can add items to their wantlist.

Usage: Enable customers to save items for later, track wanted products, and receive notifications.

Key Operations: Add items to wantlist, view wantlist, filter inventory by wantlist status

Configuration​

Config​

Description: Public store configuration and settings visible to customers.

Usage: Access store settings, payment methods, shipping options, and public configuration data.

Key Fields: shopName, currency, modules, eshop, sites

Note: Only public configuration is exposed; sensitive admin settings are not available.

Description: Product search functionality for finding items by term.

Usage: Enable customers to search products, implement search functionality, and improve discoverability.

Key Operations: Search by term, filter search results, get search suggestions

Suggestions​

Description: Product recommendations and suggestions based on genres, styles, or related items.

Usage: Display product recommendations, show related items, and improve product discovery.

Key Operations: Get suggestions by genre/style, find related items, get recommendations

Usage Patterns​

Shopping Flow​

Browse inventory → Add to checkout → Apply voucher → Submit order

Discovery​

Search products → Filter by criteria → View collections → Browse by artist/label

Account Management​

Register → Login → Update profile → View orders → Manage wantlist

Content Browsing​

View articles → Browse playlists → Explore collections → Discover products

Next Steps​