How to Connect a Digital Goods Catalog to a Marketplace

Short Answer

Connecting digital goods to a marketplace means integrating a supplier API into your existing marketplace infrastructure to add gift cards, game top-ups, and similar products as a new category. The integration has three phases: catalog import (pull products from supplier and create listings), order flow (trigger supplier API on purchase), and stock management (keep listings in sync with supplier availability). The technical work is a one-time build; ongoing operations are automated.

Definition: Connecting a digital goods catalog to a marketplace means using a wholesale supplier's API to populate a new product category, automatically fulfill orders, and maintain accurate stock and pricing — without the marketplace operator handling any physical inventory.

Key takeaway: Digital goods are the most backend-integration-friendly product category for marketplace expansion. No warehouse, no logistics, no returns process. The entire fulfillment chain is: API call in → code out. The complexity is in catalog management (region accuracy, naming, pricing) and order flow reliability — not in physical operations.

Who This Guide Is For

• Marketplace operators adding digital goods as a new product category
• Developers integrating a digital goods supplier API into an existing platform
• Product managers defining the integration requirements for digital goods

Integration Architecture Overview

Marketplace                    Supplier API
    │                               │
    ├─ Phase 1: Catalog Import ─────▶ GET /api/products/?category_id_or_slug=...
    │  Pull all products             Returns product ids, names, prices, regions
    │  Create marketplace listings   (run daily or on change)
    │                               │
    ├─ Phase 2: Stock Sync ─────────▶ GET /api/products/{id_or_slug}
    │  Check before showing product  Availability reflected in product data
    │  (real-time on product page)   │
    │                               │
    ├─ Phase 3: Order Flow ─────────▶ POST /api/orders/
    │  Buyer completes checkout       { "items": [{ "itemId": "product_01k...", "quantity": N }] }
    │  Marketplace deducts payment    │
    │                          ◀─────┤ { order_id, items[].externalData when completed }
    │  Deliver code to buyer          │
    │                               │
    └─ Phase 4: Reconciliation ─────▶ GET /api/orders/?statuses=completed&limit=200&offset=0
       Daily finance export          Paginate to reconcile all completed orders

Phase 1: Catalog Import

What the API Returns

A typical supplier catalog endpoint returns:

{
  "results": [
    {
      "id": "product_01krgfgww8eth9xvvysd6y7r4j",
      "name": "Steam Gift Card $20",
      "region": "US",
      "currency": "USD",
      "face_value": 20.00,
      "price": 18.40,
      "category": "gaming",
      "available": true
    }
  ]
}

How to Map to Marketplace Listings

Rules:

• One marketplace listing per supplier product id — no merging
• Include region in the product title always
• Store the supplier product id in your database to use as itemId when placing orders

Catalog Update Schedule

Phase 2: Stock Management

Show only in-stock products to buyers. Check availability at two points:

1. Product listing page load — query GET /api/products/{id_or_slug} to show "In Stock" or "Currently Unavailable" (availability is reflected in the product data)
2. Checkout initiation — check availability again; block checkout if out of stock since page load

GET /api/products/steam-20-usd
→ { "id": "product_01k...", "name": "Steam Gift Card $20", "available": true, ... }

Cache product responses for 5–15 minutes (not longer) to reduce API load while staying current.

Phase 3: Order Flow

When a buyer completes checkout:

1. Marketplace confirms payment (buyer charged)
2. Call POST /api/orders/ with { "items": [{ "itemId": "product_01k...", "quantity": N }] }
3. Receive codes in response (synchronous) or by polling GET /api/orders/{order_id} until completed (FoxReload has no webhooks); codes are in items[].externalData
4. Store order_id and codes in your database
5. Deliver code to buyer (in-app notification, email, or order history page)
6. Mark order as completed

Error handling:

Phase 4: Reconciliation

Pull order history from supplier API daily for finance reconciliation:

GET /api/orders/?statuses=completed&limit=200&offset=0
→ [ { order_id, items, timestamp }, ... ]   (paginate with offset to cover full period)

Match against your marketplace transaction records. Discrepancies require investigation.

Pricing Strategy for Marketplace Digital Goods

Set retail price above wholesale cost + marketplace commission + payment fee + target margin:

Retail price = Wholesale ÷ (1 − marketplace_commission% − payment_fee% − target_margin%)

Example (marketplace 10% commission, card payment 2.5%, target margin 5%):

Retail = $18.40 ÷ (1 − 0.10 − 0.025 − 0.05)
Retail = $18.40 ÷ 0.825
Retail = $22.30

Verify that this retail price is competitive. If it is not, either negotiate better wholesale pricing or evaluate whether this channel is viable for this product.

Catalog Size Recommendations

Start focused; expand after validating the integration:

Starting with 200 SKUs before validating the fulfillment flow creates debugging complexity. Start narrow; scale after the pipeline is proven.

Technical Checklist

Catalog:

• Supplier API credentials configured in production environment
• Catalog import job scheduled (daily minimum) via GET /api/products/?category_id_or_slug=...
• Each supplier product id (itemId) mapped 1:1 to marketplace listing
• Region included in product title for all regional products
• Retail price calculated with margin formula applied per product

Availability:

• Availability check (GET /api/products/{id_or_slug}) implemented on product page load
• Availability check implemented at checkout initiation
• Cache TTL set to 5–15 minutes
• Unavailable products hidden or marked unavailable

Orders:

• Order creation call triggered on payment confirmation (not on payment initiation)
• Supplier order ID stored in your order database
• Code delivered to buyer on order completion
• Error states handled: timeout, failure, out-of-stock
• Alert configured for order failures exceeding threshold

Finance:

• Daily reconciliation job against supplier order API
• Discrepancy alerting configured
• Wholesale cost recorded per order for margin reporting