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: loggedin (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

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

contractor_spectrum_idstring

Optional contractor spectrum_id — if provided, listing is created on behalf of the org

Response

Created listing with listing_id

listing_idstring required
seller_idstring required
seller_type'user' | 'contractor' required
titlestring required
descriptionstring required
status'active' | 'sold' | 'expired' | 'cancelled' required
created_atstring required
updated_atstring required

Changes

  • v2a3060250b39bRevision changes
    • ○

      the endpoint scheme security loggedin was added to the API

    • ○

      the endpoint scheme security jwt was removed from the API

    • ○

      added the new optional request property