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:

• urn must resolve to an existing catalog item.
• gradingProvider, gradingScore, and gradingNumber must be supplied together or omitted together.
• notes is optional, normalized by the API, and limited to 255 characters.
• reference is optional seller/integration metadata, normalized by the API, and limited to 255 characters.
• Empty-string reference values are treated as a clear request (null in 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: false and becomes valid after a qualifying attachment is finalized.

Side effects:

• Emits LISTING_CREATED to 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.