Managing Listings

Use this guide to manage and sync a seller’s listings between your application and Managem.

​

Before you start

1. Confirm the connected user has a seller account with Get seller status.
2. Decide how you will mapping managem data in your system:
   • Between your internal product records
   • And Managem items (using URN, external IDs or game/set/name)
   • And Seller’s Listing IDs
3. Choose your write strategy:
   • Use Bulk create listings for smaller batches (up to 200 listings per request).
   • Use Create an import for large catalogs.

​

Choose an item identity strategy

For stable syncs, map each of your products to a Managem item using a predictable identifier order. Recommended order:

1. URN (best and most deterministic)
2. CARDMARKET_ID
3. TCGPLAYER_ID
4. GAME + SET + NAME

Useful lookup endpoints:

• Lookup item for single item resolution by urn or slug
• Lookup items by URN for batch URN hydration (up to 200 per request)
• Full-text faceted search when you need fallback discovery by text/facets

​

Run your initial sync

​

1. Pull the seller’s current listings

Use Search your listings and paginate with from and size. Store at least:

• listing.id
• reference
• item.urn
• condition
• language
• variants
• price
• quantity
• hidden

​

2. Handle duplicate listings

The seller may have previously listed the same item with your service & Managem. A great experience would be to de-duplicate these listings. These attributes are useful to detect duplicates:

• item.game
• item.set.name
• item.number
• price
• quantity
• condition

​

3. Create and configure a webhook

Create a webhook with Create webhook. Subscribe to events your sync process needs, such as:

• LISTING_CREATED
• LISTING_UPDATED
• LISTING_DELETED
• ORDER_CREATED
• ORDER_UPDATED

​

4. Test webhook delivery

Run Test webhook delivery and confirm statusCode: 200 before going live.

​

5. Backfill listings from your system

• Write your internal listing ID into reference when creating listings. This gives you a stable integration-owned key per seller listing.
• Keep a seller-scoped mapping in your system between reference and listing.id.
• reference values are trimmed and limited to 255 characters. Empty values clear an existing reference.
• For large datasets, upload CSV jobs with Create an import, then monitor with:
  • List imports
  • Retrieve an import
• For smaller batches, push directly with Bulk create listings

For CSV format and error handling, see:

• Building a CSV
• Creating an Import
• Handling Import Errors

​

Keep listings in sync

Your ongoing sync loop should be webhook-driven. When you receive events:

• LISTING_CREATED: create or update local listing mapping.
• LISTING_UPDATED: update local listing state (price, quantity, visibility, notes, and reference mapping).
• LISTING_DELETED: mark listing inactive in your system.
• ORDER_CREATED and ORDER_UPDATED: update availability/reserved quantities in your local model.
• TEST: use only as a connectivity check.

Ensure that your implementation is idempotent, so that retries do not create duplicate records or unintended side effects. Use unique constraints and update logic where appropriate to maintain data integrity.

​

Handle failures and drift

If webhook delivery degrades:

• Inspect failures with List delivery failures
• Inspect a specific failure with Retrieve webhook failure
• Download HAR traces with Download failure HAR
• Monitor trends using Get delivery metrics

Also run a periodic reconciliation job:

1. Re-fetch listings with POST /seller/listings/search.
2. Compare marketplace state with your local state.
3. Repair mismatches and refresh mapping records.

This gives you a safety net for missed webhooks or transient processing failures.