> For the complete documentation index, see [llms.txt](https://cardsiq.gitbook.io/cardsiq-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cardsiq.gitbook.io/cardsiq-docs/partners/partner-guide.md). # Partner Guide Learn how collectibles businesses use CardsIQ as an operating platform across live commerce, inventory, buybacks, product creation, and fulfillment. ## Overview CardsIQ partners are collectibles businesses using the platform to operate one or more parts of their business. The platform is modular. A partner may begin with a specific workflow, such as Instant Buybacks or StreamIQ, and expand into additional CardsIQ modules as its operation grows. ## What CardsIQ Provides CardsIQ gives partners a shared operating environment for workflows that are usually spread across multiple tools. Depending on the partner's configuration, CardsIQ can support: * Live-shopping operations * Instant Buybacks * Inventory management * Product creation and licensed repacks * Campaigns and acquisition strategies * Payments and verification * Reconciliation and fulfillment * Operational reporting ### Reviewing break offers After an approval is confirmed, the review modal shows a brief green success animation and advances to the next matching, reviewable offer without closing. The last offer shows an all-reviewed message. Failed approvals stay on the current offer; queue-loading failures offer a retry without repeating approval. Settlement still completes before another offer can be approved. The public live-sales ticker and its details modal display the card's saved market value at offer generation, with the CardsIQ mark. They do not display the seller's offer amount or use the protected/reference pricing baseline. Records without a saved market snapshot show an unavailable value. ### Seller VIP perks The seller directory shows individual badges beside the email for a higher buyback rate (green rising arrow), Product Ranges pricing (purple chart), and Keep Open offers (amber clock). Hover or focus a badge to see its meaning. Multiple enabled perks show multiple badges on desktop and mobile. Any one of these three perks qualifies the seller for the VIP tab and the fulfillment VIP crown, scoped to the current partner. Equal or lower buyback rates, fee discounts, and value-tier rate overrides alone do not qualify. Changing a perk refreshes the directory and its VIP count. ### Developer applications Applications start empty. Create an application with a Digital Pack, Inventory Tool, or Custom type. Existing applications without a type are classified as Custom. Types are fixed at creation; renaming an application does not change it. The Inventory menu shows Digital Inventory only when the account has a non-archived Digital Pack application. Inventory Tool and Custom applications do not enable that menu item. Existing inventory permissions and page-access restrictions still apply. The menu refreshes after application changes and on page reload; archiving the last Digital Pack application hides it. ### Account-based API plan estimates The plan chooser analyzes the authenticated partner's last 30 days of inventory, API requests, webhook events, and settled buyback transactions. No workload is entered manually. Expand the calculation to inspect the sources, observation window, per-endpoint credits, and observed peak requests per second per key. Refresh retrieves a new account snapshot; it never changes the subscription. Recommendations select the lowest-priced currently offered plan covering the first-month credit budget. The budget includes one initial inventory sync (up to 500 cards per page) and 20% planning headroom. Recurring API traffic uses the observed request cadence, not an assumed four-hour schedule. Buybacks and uploads are not separately charged per card; their inventory events are already included in the webhook estimate. Webhook planning rounds up blocks of 200 events at 10 credits per block; billing charges completed blocks only. Skipped events and delivery retries are not additional events. Non-skipped pending events are included as potential deliveries, so this is a capacity estimate rather than an invoice. Without an endpoint, event history does not exist: distinct recently changed cards are a proxy, not a reconstruction of every repricing run. Cost-only changes can move the inventory stamp without producing webhook events. This and short integration histories show a provisional fit. Unknown future growth is not invented. If no offered plan fits, contact CardsIQ. All plans currently share the same per-key request cap; concurrency is shown separately and never used to imply an upgrade removes that cap. ### Inventory market valuation The All Inventory count is a compact grading-company breakdown with the overall count retained in its header. Counts cover every available, non-missing card in the account, independent of table filters and pages. Raw cards use the CardsIQ logo; PSA, BGS, SGC and CGC have individual metrics, and additional or unknown graders remain visible. Missing backend grading totals display an unavailable state rather than page-only counts. The header still resets inventory filters. Valuation metrics reuse the existing ALT and Card Ladder provider logos. Grader branding uses official [SGC](https://www.gosgc.com/favicon.ico) and [CGC](https://www.cgccards.com/resources/images/logos/icons/apple-touch-icon.png?cache=1) icons stored locally; PSA, BGS and other graders use labeled badges where no local official asset is available. All Inventory shows four compact portfolio totals: ALT Value, Card Ladder Value, ALT Last Sale and Card Ladder Last Sale. Each card contributes once to each total. A missing value uses that provider's last sale, and a missing last sale uses that provider's value. If both are missing, the other provider is used. Raw-card last sale is included in all four totals, not added as a fifth total. No partner-declared value or inventory cost is substituted. The valuation KPI is display-only, with no filter or settings toggle. Existing account fallback preferences still apply server-side; same-provider fallback always comes first. Offer and case-building pricing are unchanged. Multi-metric cards share aligned headers, labels and values and expand vertically when labels or coverage text wrap rather than clipping content at a fixed height. Totals cover the full owned portfolio (`available`, `reserved`, `held`), including physically missing stock, and are independent of table filters and pagination. Sold, gifted, shipped, vaulted and in-case cards retain their existing exclusions. Cards without any usable positive price appear as awaiting valuation and enter the totals on the next inventory refresh after their pricing is updated. Deployment requires the matching backend, including the startup schema addition `company_types.inventory_valuation_priority`, before the frontend. Older backend responses display valuations as unavailable rather than showing partial sums. ### Shared navigation and Live Operations The operational Partner Portal sidebar now places **Search** below CardsIQ branding. Enter a cert number or SKU to open the existing inventory details. When the sidebar is collapsed, its search icon opens the same lookup experience; mobile provides Search inside the single navigation drawer. No new search matching or backend behavior is introduced. The shared header displays **Live Operations** with the current live-stream count and compact platform/status badges where space permits. Open it to see stream and breaker details, current break status, existing floor/ceiling badges and the same StreamIQ stream/active-break links. The panel adapts to a mobile bottom sheet and supports Escape dismissal. It uses existing live data, not the sample data powering the frontend preview modules. On mobile, one menu button in the application header opens the left navigation drawer. Branding and Search stay at the top, only navigation scrolls, and wallet/notification/logout controls remain at the bottom. Escape, backdrop and accessible route navigation close the drawer. There is no duplicate horizontal route shortcut bar. Desktop navigation retains its compact sidebar and rail. ### Feature availability Localhost (`NEXT_PUBLIC_APP_ENV=local`) exposes Workforce, Marketplaces, Sourcing and report preview tabs. Workforce, Marketplaces and Sourcing stay locked in Develop (`NEXT_PUBLIC_APP_ENV=develop`), Production and other deployments. Developers menus and routes are available on Develop; their existing Production availability is unchanged. Developer subscription confirmation, role and tenant permissions still apply in every environment. Live Buybacks Reports remains available subject to role permissions. Campaigns and Agreements remain hidden, and the existing explicit Billing flag is unchanged. Disabled modules remain visible to otherwise-authorized users with a small **Coming Soon** badge. Groups can expand, but their children cannot navigate. Direct URLs show the Coming Soon state rather than the unfinished workspace. Availability is baked into the frontend build, not inferred from `NODE_ENV`. The Develop workflow explicitly supplies `NEXT_PUBLIC_APP_ENV=develop`. Rebuild and deploy the frontend to update deployed menus and routes; legacy per-module flags do not override the preview release gates. ## Workforce and Payroll (Frontend Preview) Workforce sits above Wallet and includes Overview, Employees, Scheduling, Time & Attendance and Compensation at `/partner/workforce` and its `/employees`, `/scheduling`, `/time`, `/compensation` child routes. Employee records are independent of CardsIQ accounts. Partners can configure departments and locations, schedule remote or on-site employees, record manager-assisted demo time and explicit breaks, correct entries with reasons, and submit/review timesheets. Scheduled hours are expected work, not worked time. Compensation supports effective-dated components and illustrative overtime policies; these do not determine legally compliant final wages. Reports adds `/partner/reports/payroll`, **Payroll & Commissions**, using the same employees, approved recorded time, compensation and qualifying mock activity. Prepare, review exceptions, submit, approve/reject and export a proposed gross-pay preview without processing payments. **Reports** is one sidebar destination with seven route-driven views: Overview, Streams & Breaks, Buybacks, Inventory & COGS, Financial Activity, Payroll & Commissions and Report Center. The shared header is **Financial Reports**. There is no demo/operational source toggle: Reports is entirely a frontend demo preview. Existing stream, breaker, inventory, financial and payroll deep links open the appropriate view. The separate Inventory module is unchanged. Stream/break/breaker profitability, received/pending/cancelled buybacks, inventory valuation/COGS and the activity ledger derive from one organization-scoped demo dataset. Filters, sorting, pagination, detail drawers and filtered CSV/PDF exports are available. Report Center links to the authorized report/export workflows. Commission breakdowns use the existing Workforce employee IDs, agreements and assignments; estimates remain excluded from payroll. Sample stream fees are illustrative, not real platform rates or legal wage rules. Reports retains its existing permissions and follows the same localhost-only preview policy. Deployed Develop and Production cannot opt in with the former `NEXT_PUBLIC_PARTNER_REPORTS_ENABLED` flag. Disabled Reports remains visible with Coming Soon; it does not mount the reporting workspace. Workforce state persists in memory while moving between Workforce and Reports inside the Partner Portal, and resets on refresh, logout/identity changes or leaving the partner layout. Employee account links are demonstration references; they neither create logins nor grant portal access. Operational access uses existing team permissions. Compensation/payroll additionally require existing billing and wallet visibility; financial mutation/review requires billing-manage. No payroll payments, SSN/bank collection, employee authentication or backend persistence are implemented. See the [authoritative engineering handoff](https://github.com/CardsIQ/cardsiq_frontend/tree/develop/documentation/engineering/MENU_ITEMS_BRANCH_ENGINEERING_HANDOFF.md) for models, approval/audit rules, calculation assumptions, future restricted employee self-service and backend/legal requirements. ## Break Offer Review Open a pending offer to review it in-place. When multiple reviewable offers are available, Previous and Next controls move through the current filtered queue. Next loads another page when needed; the position indicates when only loaded offers are counted. Locked offers are skipped. Navigation and settlement actions are disabled while an approval, rejection or navigation request is in progress. Offer details slide between records without reopening the modal, with animation disabled for reduced-motion preferences. Settlement confirmations remain unchanged. ## Marketplaces (Frontend Preview) The Partner Portal includes a Marketplaces navigation group before Sourcing, Developers and Acquisitions, with four pages: * `/partner/marketplaces` - Overview * `/partner/marketplaces/orders` - Orders * `/partner/marketplaces/transactions` - Transactions * `/partner/marketplaces/connections` - Connected Accounts Overview, Orders, and Transactions provide a read-only frontend preview with shared sample orders, items, financial events, filters, and linked details. Connected Accounts includes simulated connection and verification workflows and account management. No real accounts are connected or marketplace data requested. Preview changes persist between Marketplace pages in memory and reset on reload or leaving the module. Detail links survive reload by stable sample IDs, but local account mutations do not. These pages inherit partner session and company-type protections. Financial activity pages require existing `wallet` access; Connected Accounts retains `dashboard` access and managing preview connections requires `dashboard: manage`. No new permission group is introduced. See the [consolidated engineering handoff](https://github.com/CardsIQ/cardsiq_frontend/tree/develop/documentation/engineering/MENU_ITEMS_BRANCH_ENGINEERING_HANDOFF.md) for normalized models, monetary formulas, and the remaining integration work. Marketplaces is intended as the external selling-channel integration and activity layer. Acquisitions remains the inventory acquisition and reconciliation layer, and Inventory remains the inventory management layer. These independent modules can share data in future without merging workflows. ## Sourcing (Frontend Preview) Sourcing is a separate navigation group between Marketplaces and Acquisitions: * `/partner/sourcing` - Overview * `/partner/sourcing/vendors` - Vendors * `/partner/sourcing/shows` - Shows * `/partner/sourcing/campaigns` - Campaigns * `/partner/sourcing/orders` - Orders * `/partner/sourcing/shipments` - Shipments The preview models direct vendor relationships, shared vendor-owned inventory, buying strategies, shows, campaigns, direct purchase/sale orders, partial shipment manifests and receiving. Sample data and simulated mutations are tenant-scoped and shared across the Sourcing pages in memory. Refreshing or leaving the module resets preview changes. There is no backend persistence, payment processing, shipping-label generation or inventory ownership transfer. Sourcing inherits existing partner authentication and `wallet` view/manage permissions. It introduces no new authorization group. Vendor relationships are organization-specific; shared vendor listings are not partner-owned inventory. Future receipt-to-acquisition workflows are documented, not wired. Acquisitions and Inventory remain unchanged. The [consolidated engineering handoff](https://github.com/CardsIQ/cardsiq_frontend/tree/develop/documentation/engineering/MENU_ITEMS_BRANCH_ENGINEERING_HANDOFF.md) is the single reference for the modules' models, workflow contracts, mock boundaries, remaining backend work and validation results. ## Developers (Frontend Preview) Developers is an expandable section below Sourcing and above Acquisitions: * `/partner/developers` - Developer Overview * `/partner/developers/keys` - API Keys * `/partner/developers/usage` - Usage & Billing * `/partner/developers/applications` - Applications * `/partner/developers/docs` - API Documentation The Developers menu displays a compact live API readiness pill in the same slot as other menu badges. Desktop and mobile navigation, the collapsed rail and the Overview share one health poller. Operational means the backend and database passed readiness; missing health routes or failed checks never display healthy. This is independent of subscription status and does not measure every endpoint or external provider. The plan picker includes a compact branded API introduction with the available inventory feed, status-update and sales-data endpoints from the shared catalog, plus a link to API documentation. This introduction is informational only and appears for first subscriptions, renewals and plan changes. The subscribed Overview dashboard remains unchanged. Plan cards use distinct tier icons, with a highlighted Professional recommendation. The introduction uses the existing gradient CardsIQ mark and a dark wordmark on the light surface. Each endpoint card includes a collapsed credit breakdown with request costs, a practical example and estimated monthly volumes calculated from each offered plan's included credits. These are endpoint-only examples, not separate quotas: credits are shared across requests and webhooks. Inventory volumes assume full 500-card pages; sales lookups require two credits per certificate. The preview includes expiring key metadata, one-time nonfunctional demonstration secrets, permission-constrained proposed scopes, rotation and revocation, usage charts and filters, a reconciled credit ledger, simulated purchases and limits, registered applications and organization-scoped third-party consent. Documentation examples and endpoint prices are proposed, not verified API contracts. There is no live request executor, billing, payment or authentication. Developer Tools uses the `developers` permission group. Owner, Admin and CardsIQ roles have manage access, including credential and application management. Owner and Admin do not need a separate Developer assignment. API subscription management accepts `developers: manage` or `billing: manage`; an active subscription is still required for paid tools. The live Developer API service decodes encoded response envelopes using the shared API decoder before reading pricing, subscription or credential data. Unreadable encoded responses show an explicit error rather than an empty state. A null subscription is valid even when the response carries the encoding flag: it means the partner has not subscribed. Under Account > Team Members, an Owner or Admin can add a member or change an existing non-owner member's role to **Developer**. This assigns them to the **Engineering Team** automatically. Developers can manage API keys, applications and webhooks, purchase and manage Coinflow API subscriptions, and view inventory. They cannot access partner billing, spend the partner wallet, purchase wallet- funded credits or manage team members. No separate engineering login type or team database entity is needed. Membership is refreshed from `/company/team/me` when a partner session mounts, regains focus or reconnects, and after role changes. Cached permission maps are replaced with the current role matrix, including newly added permission groups. A failed membership check displays a retryable error instead of granting Owner access. Legacy members with a null role retain the backend's Owner mapping only after a successful self-membership lookup. See the [authoritative branch engineering handoff](https://github.com/CardsIQ/cardsiq_frontend/tree/develop/documentation/engineering/MENU_ITEMS_BRANCH_ENGINEERING_HANDOFF.md) for Marketplaces, Sourcing and Developers models, adapter methods, backend security requirements, metering decisions and validation. ## One Platform Across Teams Different teams inside a collectibles business may interact with different parts of CardsIQ. Break teams can focus on live operations. Inventory teams can manage the movement of collectibles. Finance and administrative users can manage the workflows relevant to their responsibilities. The goal is to keep those teams connected without requiring everyone to work from the same spreadsheets or disconnected systems. ## Starting with CardsIQ Partner onboarding is designed around the workflows the business plans to use. CardsIQ works with the partner to configure the relevant modules, connect supported infrastructure, establish the operational process, and prepare the team for production use. The exact implementation varies by partner because the platform is designed to fit different collectibles business models. ## Growing with the Platform CardsIQ is intended to become more valuable as more of the partner's operation becomes connected. A business may start with live-commerce operations, then connect buybacks. Buybacks can feed inventory. Inventory can support repacks. Campaigns can create new acquisition channels. The same operational record can then continue into reconciliation and fulfillment. That connected model is the core of the CardsIQ partner experience. ## Related Documentation * [Platform Overview](/cardsiq-docs/cardsiq/platform-overview.md) * [StreamIQ](/cardsiq-docs/platform-features/streamiq.md) * [Instant Buybacks](/cardsiq-docs/platform-features/instant-buybacks.md) * [Pricing & Billing](/cardsiq-docs/partners/pricing-and-billing.md)