Create listing
Create a new listing for the authenticated seller.
Use this endpoint for single listing creation when you already know the target item URN and listing attributes.
Authentication and ownership:
- The caller must authenticate as a seller account.
- The seller must be active; inactive or missing seller records are rejected.
Input validation:
urnmust resolve to an existing catalog item.gradingProvider,gradingScore, andgradingNumbermust be supplied together or omitted together.notesis optional, normalized by the API, and limited to 255 characters.referenceis optional seller/integration metadata, normalized by the API, and limited to 255 characters.- Empty-string
referencevalues are treated as a clear request (nullin storage).
Listing validity rules:
- Listings priced at
>= 2000(lowest-denomination integer) require an attachment photo. - Listings that include grading metadata also require an attachment photo.
- When a photo is required, the listing is created with
valid: falseand becomes valid after a qualifying attachment is finalized.
Side effects:
- Emits
LISTING_CREATEDto seller webhooks. - Invalidates seller stats cache tags.
- Records listing analytics events for internal reporting.
Returns the complete listing resource with seller, item, attachment metadata, and the normalized reference value.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Data required to create a listing
Product condition
Price in pence
Languages of the card
URN of the product being listed
Total quantity for this listings
Variants of the listed card
Seller's comment about the listing
Provider responsible for grading the card
Score assigned to the card by the grading provider
Certificate or registration number issued by the grading provider
True when the listing is hidden from buyers
Private notes for the seller such as SKUs or storage locations
255Third-party integration reference for this listing
255Response
Listing created
Product condition
Price in pence
Languages of the card
Timestamp when the listing was created
Timestamp when the listing was last updated
Details of the item being listed
- Option 1
- Option 2
Seller of the listing
True when the listing has active item holds
True when the listing meets all requirements
True when the listing is hidden from buyers
Total quantity for this listings
Total available for this listing
Variants of the listed card
Seller's comment about the listing
Provider responsible for grading the card
Score assigned to the card by the grading provider
Certificate or registration number issued by the grading provider
Image attachments for the listing
Private notes for the seller such as SKUs or storage locations
255Third-party integration reference for this listing
255