Listings

Manage your own listings. Reading needs listings:read; creating, updating and deleting need listings:write. The account must have a fully verified Stripe payout setup before it can create listings (the same requirement as the dashboard): a key without one gets 403 authorization_error on POST /listings.

List your listings

Query parameters

This is the same listing shape used in the catalog listings embed (see Cards), plus owner-only fields (status, raw quantity, listable, created_at, updated_at) since every listing on this endpoint belongs to you.

Response fields

Returns a paginated list of listing objects. The fields marked owner-only below are exactly the ones missing from the public shape the catalog embeds return.

curl "https://tcgplein.nl/api/v1/listings?status=active" \
  -H "Authorization: Bearer tcgp_live_K7mP2xQ9vZ4nR8wT3yL6bC1jD5sF0gH7uM2oA9iE"

Create listings

Creates up to 100 listings in one call. Each item is validated and saved independently: a mistake in one item never sinks the rest of the batch. The response is always HTTP 200, even when every item failed. Check each item's own status, not the HTTP status code, to see what happened.

Each item needs exactly one of card (a card identifier) or product (a sealed product slug), plus language, price and quantity. Cards additionally require condition; when condition is G (graded), grading_company and grading_grade are also required. photo_urls is optional: up to 10 publicly reachable image URLs, fetched and attached asynchronously after the listing is created. There's no multipart upload in v1, only importable URLs, and the same public-URL safety rules as webhook endpoints apply (see Webhooks).

Body

The item-count cap is enforced by request validation, so a batch of more than 100 items always gets 422 validation_error.

Response fields

Not a data envelope: results, created and failed are top-level fields.

Shipping is configured once per account, not per listing, so the API never takes shipping input. If your account has every shipping option switched off, creation still succeeds but the response carries a warnings entry: without at least one enabled option buyers get an empty shipping selection at checkout and cannot order anything you list.

curl -X POST "https://tcgplein.nl/api/v1/listings" \
  -H "Authorization: Bearer tcgp_live_K7mP2xQ9vZ4nR8wT3yL6bC1jD5sF0gH7uM2oA9iE" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "card": "pbl_63",
        "condition": "NM",
        "language": "EN",
        "price": 4.50,
        "quantity": 3,
        "photo_urls": ["https://example.com/photos/pbl-63-front.jpg"]
      },
      {
        "product": "unknown-product-slug",
        "language": "EN",
        "price": 19.99,
        "quantity": 1
      }
    ]
  }'

<?php

$body = json_encode(['items' => [
    ['card' => 'pbl_63', 'condition' => 'NM', 'language' => 'EN', 'price' => 4.50, 'quantity' => 3],
]]);

$ch = curl_init('https://tcgplein.nl/api/v1/listings');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer tcgp_live_K7mP2xQ9vZ4nR8wT3yL6bC1jD5sF0gH7uM2oA9iE',
    'Content-Type: application/json',
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
echo "Created {$result['created']}, failed {$result['failed']}";

const response = await fetch('https://tcgplein.nl/api/v1/listings', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer tcgp_live_K7mP2xQ9vZ4nR8wT3yL6bC1jD5sF0gH7uM2oA9iE',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    items: [
      { card: 'pbl_63', condition: 'NM', language: 'EN', price: 4.50, quantity: 3 },
    ],
  }),
});

const result = await response.json();
console.log(`Created ${result.created}, failed ${result.failed}`);

{
  "results": [
    {
      "status": "created",
      "listing": { "id": 5231, "price": 4.50, "currency": "EUR", "quantity": 3, "status": "active" },
      "index": 0
    },
    {
      "status": "failed",
      "errors": { "product": ["Unknown identifier."] },
      "index": 1
    }
  ],
  "created": 1,
  "failed": 1
}

A failed item because of an ambiguous card or set shortcut also carries a candidates field, the same shape as the 409 ambiguous_identifier error (see Identifiers). Here it's attached to the item's result object rather than thrown as a top-level error, since one ambiguous item shouldn't fail the whole batch.

Update a listing

{id} is the listing's id. All body fields are optional; only send what you want to change.

Body

Stock and status are reconciled automatically after the update, mirroring what happens when a listing sells out on the marketplace itself. Setting quantity: 0 is the idiom for taking a listing off-sale without deleting it: the listing is flipped to sold automatically, even if you didn't send status in the same request. The reverse also holds: restocking a sold listing (sending a quantity greater than 0) flips it back to active automatically. The same rule also means sending status: "sold" on its own, while the listing's quantity is still above 0, validates but is immediately reconciled back to active: pair it with quantity: 0 if you want it to actually stay off-sale.

Response fields

Returns the updated listing under data, with no links / meta. Because it's your own listing, the owner-only fields are always present:

curl -X PATCH "https://tcgplein.nl/api/v1/listings/5231" \
  -H "Authorization: Bearer tcgp_live_K7mP2xQ9vZ4nR8wT3yL6bC1jD5sF0gH7uM2oA9iE" \
  -H "Content-Type: application/json" \
  -d '{"quantity": 0}'

Delete a listing

{id} is the listing's id; there are no other parameters and no body. Returns 204 No Content on success, with no response fields. A listing with an open order can't be deleted: that returns 409 conflict instead, until the order completes. A listing id that doesn't belong to you 404s, the same as if it didn't exist.

curl -X DELETE "https://tcgplein.nl/api/v1/listings/5231" \
  -H "Authorization: Bearer tcgp_live_K7mP2xQ9vZ4nR8wT3yL6bC1jD5sF0gH7uM2oA9iE"