Full Inventory Sync

Sync your complete inventory in a single request. Choose between overwrite mode (replace everything) or add mode (only add/update).

Sync Modes

overwrite - Replaces your entire inventory. Items not in the request will be removed.
add - Only adds new listings or updates existing ones. Does not remove anything.

POST/inventory/syncinventory:write

Full Inventory Sync

Push your complete inventory catalog. Use 'overwrite' mode for full replacement or 'add' mode to only upsert.

On larger screens, use the API Playground panel on the right to try this endpoint.

Name	Type	Required	Description
`mode`	stringoverwrite \| add	Required	Sync mode
`items`	array	Required	Array of inventory items to sync
`strict`	boolean	Optional	If true, fail entire batch on any error. Default: false (partial success)

bash

curl -X POST "https://api.ctcgx.com/api/v1/inventory/sync" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "overwrite",
  "items": [
    {
      "tcgplayerId": "12345",
      "quantity": 4,
      "price": 599,
      "condition": "NM",
      "finish": "nonfoil"
    },
    {
      "scryfallId": "abc-123-def",
      "quantity": 2,
      "price": 1299,
      "condition": "LP",
      "finish": "foil"
    }
  ]
}'

Response

Returns counts of items processed, created, updated, deleted, and any errors.

json

{
  "success": true,
  "processed": 2,
  "created": 1,
  "updated": 1,
  "deleted": 0,
  "failed": 0,
  "errors": []
}

Item Structure

Each item in the items array requires at least one external ID for product lookup, plus quantity and price for the listing.

Product Identification

At least one of these IDs is required to identify the product:

Field	Type	Description
ctcgxProductId	string	CTCGX product ID
scryfallId	string	Scryfall ID (Magic: The Gathering)
tcgplayerId	string	TCGPlayer product ID
cardmarketId	string	Cardmarket ID
cardtraderId	string	Cardtrader ID
pokemontcgId	string	Pokemon TCG API ID
ygoprodeckId	string	YGOProDeck ID (Yu-Gi-Oh)
fabId	string	Flesh and Blood ID
lorcanaId	string	Lorcana ID
optcgId	string	One Piece TCG ID
swudbId	string	Star Wars Unlimited DB ID

Listing Details

Field	Type	Required	Description
quantity	number	Yes	Stock quantity
price	number	Yes	Price in cents CAD (e.g., 599 = $5.99)
condition	string	No	Card condition (see values below)
finish	string	No	Card finish (see values below)
language	string	No	Card language (default: "English")
edition	string	No	Edition (for games that use editions)
imageUrl	string	Conditional	Required for graded, signed, or damaged cards

Graded Cards

Field	Type	Description
isGraded	boolean	Set to true for graded cards
gradingCompany	string	Required if isGraded (see values below)
grade	string	Required if isGraded (e.g., "10", "9.5")
certNumber	string	Certification number

Special Attributes

Field	Type	Description
isSigned	boolean	Whether the card is signed
signedBy	string	Who signed the card
isError	boolean	Whether the card has a printing error
errorType	string	Required if isError (see values below)

Valid Values Reference

Condition

Mint, Near Mint, Lightly Played, Moderately Played, Heavily Played, Damaged

Aliases accepted: NM, LP, MP, HP, DMG, SP, EX, GD

Finish

Normal, Foil, Holofoil, Reverse Holofoil, Etched Foil, Cold Foil, Rainbow Foil, Textured Foil

Aliases accepted: nonfoil, non-foil, holo, reverse, etched

Language

English, Japanese, Korean, Chinese (Simplified), Chinese (Traditional), German, French, Italian, Spanish, Portuguese, Russian, Asian-English

Edition

1st Edition, Unlimited, Limited Edition, Shadowless, Alpha, Beta

Grading Company

PSA, BGS, CGC, SGC, ACE

Error Type

Miscut, Crimped, Off-Center, Misprint, Ink Error, Double Print, Missing Ink, Square Cut, Other

Error Handling

By default, the API uses partial success mode: valid items are processed while failed items are collected in the errors array. Each error includes the item index and specific details about what failed.

{
  "success": false,
  "processed": 95,
  "created": 90,
  "updated": 5,
  "deleted": 0,
  "failed": 5,
  "errors": [
    {
      "index": 12,
      "externalId": "99999",
      "error": "Product not found: tcgplayerId=\"99999\" does not match any product in our database."
    },
    {
      "index": 45,
      "externalId": "invalid-id",
      "error": "Product not found: scryfallId=\"invalid-id\" does not match any product in our database."
    }
  ]
}

Strict Mode

Set "strict": true to fail the entire batch if any item has errors. In strict mode, all items are validated first - if any fail, nothing is processed. This is useful when you need all-or-nothing behavior for data consistency.