Skip to main content

Admin API Concepts

This guide explains the key concepts and entities specific to the Admin API. These concepts are used for backend operations and administrative tasks.

Inventory & Products​

Items​

Description: Products in your inventory. Items can be of different types: ReleaseItem (vinyl records, CDs), ProductItem (general products), or BookItem (books).

Usage: Create, update, and manage your product catalog. Each item contains metadata, descriptions, images, and can have multiple listings.

Key Fields: _id, id, type, title, descriptions, data, listings, seo

Example: A vinyl record release with artist information, tracklist, and format details.

Listings​

Description: Product variants or individual sellable units of an item. An item can have multiple listings (e.g., different conditions, formats, or locations).

Usage: Manage stock levels, pricing, availability, and listing-specific attributes like condition, location, and supplier codes.

Key Fields: _id, id, status, stock, prices, available, posted, location, supplierCode

Example: A specific vinyl record listing with "Near Mint" condition, priced at $29.99, with 5 units in stock.

Inventory​

Description: The complete collection of items and listings in your store, with filtering and pagination capabilities.

Usage: Query and filter your inventory by stock status, type, categories, artists, labels, formats, and more.

Key Operations: Search, filter, paginate, and export inventory data.

Suppliers​

Description: Entities that supply products to your store. Used for tracking product sources and supplier information.

Usage: Manage supplier relationships, track supplier codes on listings, and generate supplier reports.

Key Fields: _id, name, addresses, contacts, taxInformation

Orders & Checkouts​

Orders​

Description: Completed customer purchases with payment, shipping, and fulfillment information.

Usage: Process orders, update order status, handle fulfillments, manage shipping, and track order lifecycle.

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

Example: A customer order containing 3 vinyl records, with shipping address and payment details.

Checkouts​

Description: Shopping cart sessions that can be converted into orders. Represents the pre-purchase state.

Usage: Create checkouts, add/remove items, update addresses, apply vouchers, and submit for payment.

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

Content & Organization​

Collections​

Description: Curated groups of items organized for display purposes (e.g., "New Arrivals", "Jazz Collection").

Usage: Organize products into themed collections, control display order, and create custom storefront sections.

Key Fields: _id, id, title, handle, viewType, sort, banner, seo

Example: A "Limited Edition Releases" collection featuring rare vinyl records.

Articles​

Description: Blog posts, pages, or content pieces for your storefront. Supports rich content with blocks, rows, and columns.

Usage: Create blog content, static pages, homepage content, and marketing materials.

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

Themes​

Description: Customizable storefront designs controlling colors, layouts, typography, and visual elements.

Usage: Customize your storefront appearance, create multiple theme variations, and manage design settings.

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

Templates​

Description: Reusable design templates for emails, invoices, and other documents.

Usage: Create and manage email templates, invoice templates, and other document formats.

Playlists​

Description: Curated lists of items, often used for audio previews or featured product collections.

Usage: Create playlists of items, manage playlist entries, and display curated selections.

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

Media & Assets​

Media​

Description: Images, files, and other media assets used throughout your store (product images, banners, etc.).

Usage: Upload, manage, and organize media files for items, collections, articles, and themes.

Key Operations: Upload media, generate signed URLs, organize media libraries.

Tracklists​

Description: Lists of tracks/songs for release items (vinyl records, CDs). Includes track titles, artists, durations, and positions.

Usage: Manage track information for music releases, display track listings, and enable audio previews.

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

Example: A 12-track album with track names, artist credits, and durations.

Audio Snippets​

Description: Audio preview files associated with release items. Used for playing track previews on product pages.

Usage: Upload and manage audio previews, generate signed URLs for playback, and track play counts.

Key Operations: Upload snippets, generate playback URLs, track analytics

Music-Specific Concepts​

Artists​

Description: Musical artists or performers associated with release items. Can include Discogs integration.

Usage: Browse items by artist, display artist information, and manage artist relationships.

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

Example: "The Beatles" artist entry with profile, images, and associated releases.

Labels​

Description: Record labels that released items. Used for organizing and filtering by label.

Usage: Filter inventory by label, display label information, and manage label relationships.

Key Fields: _id, id, name, discogsId, profile, images, country, subLabels

Example: "Blue Note Records" label with associated releases and sub-labels.

Formats​

Description: Physical formats of releases (e.g., "12" Vinyl", "CD", "Cassette"). Includes format details like quantity and descriptions.

Usage: Specify and filter by release formats, display format information on product pages.

Key Fields: name, qty, descriptions, text

Example: "12" Vinyl, 33 RPM, Album" format with quantity and description.

Genres & Styles​

Description: Musical genres (e.g., "Jazz", "Rock") and styles (e.g., "Bebop", "Hard Bop") for categorizing releases.

Usage: Filter and organize inventory by musical genre and style, improve discoverability.

Example: A jazz release with genre "Jazz" and styles ["Bebop", "Hard Bop"].

Users & Authentication​

Users (Admin)​

Description: Administrative users who manage the store. Includes SuperAdmin and Admin roles with different permission levels.

Usage: Manage admin accounts, assign roles and permissions, control access to store operations.

Key Fields: _id, email, firstName, lastName, type, role, verification

Users (Buyer)​

Description: Customer accounts for end users. Managed through the Admin API for administrative purposes.

Usage: View customer information, manage customer accounts, access order history, and handle customer support.

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

Sessions​

Description: Authentication sessions for admin users. Created via login mutations and used for API authentication.

Usage: Authenticate API requests, manage session lifecycle, and control access to admin operations.

Key Fields: _id, jwt, expires, user, origin, configRef

Access Keys​

Description: API credentials (access key + secret key) for programmatic access to the Admin API.

Usage: Server-to-server authentication, automated integrations, and API access without user login.

Key Operations: Create access keys, authenticate via sessionLoginApi, manage key permissions

Discounts & Promotions​

Vouchers​

Description: Discount codes and promotional vouchers that can be applied to checkouts.

Usage: Create discount codes, manage voucher rules (percentage, fixed amount), set expiration dates, and track usage.

Key Fields: _id, code, type, value, expires, usageLimit, minimumSpend

Credits​

Description: Store credit system for customers. Can be issued, redeemed, and tracked.

Usage: Issue credits to customers, manage credit balances, and handle credit redemptions.

Configuration & Settings​

Config​

Description: Store configuration and settings including payment methods, shipping policies, taxes, domains, and integrations.

Usage: Configure store settings, manage payment processors, set up shipping zones, configure tax rules, and manage domains.

Key Fields: _id, shopName, sites, modules, taxes, eshop, storage

Shipping Policies​

Description: Rules and methods for calculating shipping costs based on location, weight, and order value.

Usage: Define shipping zones, set up shipping methods, configure free shipping thresholds, and manage shipping rates.

Taxes​

Description: Tax configuration including tax definitions, rules, and country-specific settings.

Usage: Configure tax rates, set up tax collection rules, manage tax definitions, and handle tax calculations.

Integrations​

Discogs​

Description: Integration with Discogs marketplace for syncing inventory, listing items, and importing release data.

Usage: Import release data from Discogs, sync inventory, list items on Discogs, and manage Discogs listings.

Key Operations: Search Discogs, import releases, sync inventory, manage listings

Jobs​

Description: Background jobs for long-running operations like bulk imports, exports, and data processing.

Usage: Track job progress, handle bulk operations, and monitor asynchronous tasks.

Key Fields: _id, status, type, progress, results

Other Concepts​

Lists​

Description: Email lists for marketing and communication purposes.

Usage: Manage subscriber lists, handle opt-ins/opt-outs, and organize customer communications.

Campaigns​

Description: Marketing campaigns for tracking and analytics.

Usage: Create campaigns, track metrics, and measure campaign performance.

Messages​

Description: Communication messages associated with orders or support conversations.

Usage: Send messages to customers, handle order communications, and manage support conversations.

Invoices​

Description: Invoice generation and management for orders.

Usage: Generate invoices, manage invoice data, and handle invoice-related operations.

Notifications​

Description: System notifications and alerts for admins.

Usage: Manage notification settings, receive system alerts, and handle notification preferences.

Dashboard​

Description: Analytics and statistics dashboard data.

Usage: Access store statistics, view sales data, and monitor business metrics.

Usage Patterns​

Inventory Management​

Create items → Add listings → Update stock → Manage pricing

Order Processing​

Receive order → Update status → Fulfill order → Handle shipping

Content Management​

Create collections → Add items → Configure themes → Publish content

User Management​

Create admin users → Assign roles → Manage permissions → Handle authentication

Next Steps​