Developer API

Build integrations, automate your store, and access marketplace data programmatically with our REST API.

Interactive Docs API Reference

https://heroesandmore.com/api/v1/

What You Can Build

Automate Your Store

Create and manage listings, update prices, import inventory in bulk, and handle orders programmatically.

Market Data & Pricing

Access price guide data, historical sales, and market trends to build analytics tools and pricing engines.

Collection Management

Build custom collection trackers, value portfolios, import/export tools, and integrate with other platforms.

Authentication

The API uses JWT (JSON Web Tokens) for authentication. Obtain a token pair, then include the access token in the Authorization header.

1. Get your tokens

# POST /api/v1/auth/token/
curl -X POST https://heroesandmore.com/api/v1/auth/token/ \
  -H "Content-Type: application/json" \
  -d '{"username": "your_username", "password": "your_password"}'

# Response:
{
  "access": "eyJ0eXAiOiJKV1Qi...",
  "refresh": "eyJ0eXAiOiJKV1Qi..."
}
        

2. Use the access token

curl https://heroesandmore.com/api/v1/marketplace/listings/ \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1Qi..."
        

3. Refresh when expired

# POST /api/v1/auth/token/refresh/
curl -X POST https://heroesandmore.com/api/v1/auth/token/refresh/ \
  -H "Content-Type: application/json" \
  -d '{"refresh": "eyJ0eXAiOiJKV1Qi..."}'
        

Access tokens expire after 60 minutes. Refresh tokens expire after 7 days. Some endpoints (browsing listings, price guide) are available without authentication.

Quick Example: Create & Publish a Listing

# Step 1: Create a draft listing
curl -X POST https://heroesandmore.com/api/v1/marketplace/listings/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "1993 Upper Deck Derek Jeter RC #449 PSA 10",
    "description": "Gem Mint condition, fresh from PSA.",
    "category": 5,
    "listing_type": "fixed_price",
    "price": "499.99",
    "condition": "graded",
    "quantity": 1,
    "shipping_mode": "flat",
    "shipping_price": "4.99"
  }'

# Response includes the listing ID:
{ "id": 1234, "status": "draft", ... }

# Step 2: Upload images
curl -X POST https://heroesandmore.com/api/v1/marketplace/listings/1234/images/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "image=@card_front.jpg"

# Step 3: Publish the listing
curl -X POST https://heroesandmore.com/api/v1/marketplace/listings/1234/publish/ \
  -H "Authorization: Bearer YOUR_TOKEN"
        

API Endpoints

All endpoints are relative to https://heroesandmore.com/api/v1/. See the interactive docs for full request/response schemas.

Authentication

Method	Endpoint	Description
POST	/auth/token/	Obtain JWT token pair
POST	/auth/token/refresh/	Refresh access token
POST	/auth/google/	Login with Google OAuth
POST	/auth/apple/	Login with Apple Sign In

Account

Method	Endpoint	Description
POST	/accounts/register/	Register a new user
GET	/accounts/me/	Get your profile
PATCH	/accounts/me/	Update your profile
POST	/accounts/me/avatar/	Upload avatar image
GET	/accounts/profiles/{username}/	Get a public user profile
GET	/accounts/profiles/{username}/listings/	Get a user's active listings
GET	/accounts/profiles/{username}/reviews/	Get a user's reviews

Marketplace — Listings

Method	Endpoint	Description
GET	/marketplace/listings/	Browse listings (paginated, filterable by category, type, price, condition)
POST	/marketplace/listings/	Create a new draft listing
GET	/marketplace/listings/{id}/	Get listing details
PATCH	/marketplace/listings/{id}/	Update your listing
DELETE	/marketplace/listings/{id}/	Delete your listing
POST	/marketplace/listings/{id}/publish/	Publish a draft listing (makes it active)
POST	/marketplace/listings/{id}/relist/	Relist an expired or cancelled listing
POST	/marketplace/listings/{id}/images/	Upload an image (multipart form-data)
DELETE	/marketplace/listings/{id}/images/{image_id}/	Delete an image
POST	/marketplace/listings/{id}/videos/	Upload a video (multipart form-data)
DELETE	/marketplace/listings/{id}/videos/{video_id}/	Delete a video

Marketplace — Bidding, Offers & Orders

Method	Endpoint	Description
POST	/marketplace/listings/{id}/bid/	Place a bid on an auction (proxy bidding supported)
GET	/marketplace/listings/{id}/bids/	Get bid history for a listing
POST	/marketplace/listings/{id}/offer/	Make an offer on a fixed-price listing
GET	/marketplace/offers/	List your offers (sent and received)
POST	/marketplace/offers/{id}/accept/	Accept an offer (seller only)
POST	/marketplace/offers/{id}/decline/	Decline an offer (seller only)
POST	/marketplace/listings/{id}/save/	Save a listing
DELETE	/marketplace/listings/{id}/save/	Unsave a listing
GET	/marketplace/saved/	List your saved listings
GET	/marketplace/orders/	List your orders (as buyer or seller)
GET	/marketplace/orders/{id}/	Get order details
POST	/marketplace/orders/{id}/ship/	Mark order as shipped (seller only)

Marketplace — Checkout & Payment

Method	Endpoint	Description
POST	/marketplace/checkout/{listing_id}/	Initiate checkout for a listing
POST	/marketplace/payment/intent/	Create a Stripe payment intent
POST	/marketplace/payment/confirm/	Confirm payment and create the order

Marketplace — Auctions

Method	Endpoint	Description
GET	/marketplace/auctions/ending-soon/	Auctions ending soon
GET	/marketplace/auctions/events/	List auction events
GET	/marketplace/auctions/events/{slug}/	Get auction event details
GET	/marketplace/auctions/events/{slug}/lots/	Get lots in an auction event
GET	/marketplace/auctions/platform/	List official platform auctions
GET	/marketplace/auctions/autobid/	List your auto-bids
DELETE	/marketplace/auctions/autobid/{id}/	Cancel an auto-bid

Collections

Method	Endpoint	Description
GET	/collections/	List collections (your own + public when authenticated)
POST	/collections/	Create a new collection
GET	/collections/public/	Browse all public collections
GET	/collections/{id}/	Get collection details
PATCH	/collections/{id}/	Update a collection
DELETE	/collections/{id}/	Delete a collection
GET	/collections/{id}/items/	List items in a collection
POST	/collections/{id}/items/	Add item to collection
DELETE	/collections/{id}/items/{item_id}/	Remove item from collection
GET	/collections/{id}/value/	Get collection valuation summary
GET	/collections/{id}/value_history/	Get collection value history (for charts)
POST	/collections/import/	Import collection from CSV (multipart)

Price Guide

Method	Endpoint	Description
GET	/pricing/items/	Search price guide items
GET	/pricing/items/{id}/	Get price guide item details
GET	/pricing/items/{id}/grades/	Get grade-level pricing breakdown
GET	/pricing/items/{id}/sales/	Get recent sale records
GET	/pricing/items/{id}/history/	Get price history (monthly data for charts)
GET	/pricing/trending/	Get trending items
GET	/pricing/categories/	Get price guide categories

Seller Tools

Method	Endpoint	Description
GET	/seller/dashboard/	Get seller dashboard stats
GET	/seller/analytics/	Get detailed seller analytics
GET	/seller/subscription/	Get current subscription details
POST	/seller/subscription/upgrade/	Upgrade subscription tier
GET	/seller/inventory/	List inventory items
POST	/seller/inventory/	Add inventory item
PATCH	/seller/inventory/{id}/	Update inventory item
DELETE	/seller/inventory/{id}/	Delete inventory item
GET	/seller/imports/	List bulk imports
POST	/seller/imports/	Create bulk import (CSV upload)
GET	/seller/orders/	List seller orders
GET	/seller/sales/	Get sales history
GET	/seller/billing-history/	Get billing/payment history

Items & Categories

Method	Endpoint	Description
GET	/items/categories/	Get category tree (hierarchical)
GET	/items/categories/list/	Get flat category list
GET	/items/categories/{slug}/	Get category details
GET	/items/categories/{slug}/listings/	Get listings in a category
GET	/items/search/	Global search (items + listings)
GET	/items/autocomplete/	Autocomplete search suggestions

Shipping

Method	Endpoint	Description
GET	/shipping/addresses/	List your saved addresses
POST	/shipping/addresses/	Add a new address
POST	/shipping/addresses/validate/	Validate an address via EasyPost
POST	/shipping/rates/	Get shipping rates for a listing
POST	/shipping/labels/{order_id}/buy/	Purchase a shipping label
GET	/shipping/tracking/{order_id}/	Get tracking information

Affiliates

Method	Endpoint	Description
POST	/affiliates/join/	Join the affiliate program
GET	/affiliates/dashboard/	Get affiliate stats & referral link
PUT	/affiliates/settings/	Update affiliate PayPal email
GET	/affiliates/referrals/	List your referrals
GET	/affiliates/commissions/	List your commissions (filterable by status)
GET	/affiliates/payouts/	List your payout history

Explore All Endpoints Full Reference

Pagination

List endpoints return paginated results with count, next, previous, and results.

{
  "count": 142,
  "next": "https://heroesandmore.com/api/v1/marketplace/listings/?page=2",
  "previous": null,
  "results": [...]
}
                

Use ?page=N to navigate pages. Default page size is 20.

Rate Limits

Requests are rate-limited to ensure fair usage for all developers.

Type	Limit
Anonymous	100 requests/hour
Authenticated	1,000 requests/hour

Rate limit headers are included in every response. Contact us if you need higher limits.

Need Help?

Have questions about the API or need higher rate limits? We're here to help.

Contact Developer Support