Sign in
Listings V2

Create listing

Changed on

Create a new listing with variants

Creates a listing with stock lots that have variant attributes (quality tier, crafted source, etc). Uses database transaction for atomicity. Supports unified pricing (one price for all variants) or per-variant pricing (different prices per quality tier).

The variant deduplication logic ensures that variants with identical attributes are reused across listings, preventing duplicate variant records.

Requirements:

  • 14.1: POST /api/v2/listings endpoint
  • 14.2: Accept title, description, game_item_id
  • 14.3: Accept pricing_mode and base_price
  • 14.4: Accept array of lots with variant_attributes
  • 14.5: Create or reuse variants based on variant_attributes
  • 14.6: Create stock_lots for each lot
  • 14.7: Use database transaction for atomicity
  • 14.8: Validate all inputs before creating listing
  • 14.9: Return created listing with listing_id
  • 14.11: Validate seller ownership before creation
post/listings

Request

  • Base URL: /api/v2 (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /api/v2/listings
  • Auth: verified (a scheme the document does not define)

Request body

titlestring required

Listing title (max 500 chars)

descriptionstring required

Listing description (markdown supported)

game_item_idstring required

Game item UUID being sold

pricing_mode'unified' | 'per_variant' required

Pricing strategy: unified price for all variants or per-variant pricing

base_pricenumber double

Base price for all variants (required if pricing_mode is 'unified')

photo_resource_idsstring[]

Optional array of image resource UUIDs to attach as photos

external_photo_urlsstring[]

Optional array of external image URLs to link as photos (validated against domain allowlist)

pickup_method'delivery' | 'pickup' | 'any'

Pickup method: how the buyer receives the item

quantity_unit'unit' | 'scu'

Quantity unit: 'unit' for discrete items, 'scu' for cargo measured in cSCU

min_order_quantitynumber double

Minimum quantity per order for this listing

max_order_quantitynumber double

Maximum quantity per order for this listing

min_order_valuenumber double

Minimum order value (aUEC) for this listing

max_order_valuenumber double

Maximum order value (aUEC) for this listing

shop_idstring required

Shop ID to create the listing under. Required — use GET /shops/mine to list available shops, or POST /shops/quick to create one.

sale_type'fixed' | 'auction' | 'negotiable'

Sale type: fixed price, auction, or negotiable

status'active' | 'inactive'

Initial listing status (default: 'active'). Use 'inactive' for draft/prep.

visibility'public' | 'private'

Listing visibility (default: 'public'). Use 'private' for org-internal listings (contractor only).

Response

Created listing with listing_id

listing_idstring required
shop_idstring required
titlestring required
descriptionstring required
status'active' | 'inactive' | 'sold' | 'expired' | 'cancelled' required
created_atstring required
updated_atstring required

Changes

  • 19788c56fb02Revision changes
    • ○

      added the new optional request property

  • d7022de919cbRevision changes
    • ▲

      added the new required request property

    • ▲

      removed the required property from the response with the status

    • ▲

      removed the required property from the response with the status

    • ●

      removed the request property

    • ○

      added the required property to the response with the status