Inventory and listings

Use synchronous item endpoints for one item at a time and item feeds for bulk operations.

Creating an item

Every item requires:

• A unique external_id assigned by your integration.
• type set to GRADED or RAW.
• A supported category when category data is provided.

A graded item requires a certification number. A raw item requires publicly accessible front and back image URLs. The API reference contains the accepted certification-number format, authenticators, image limits, and optional inventory fields.

During creation, Mascot downloads every supplied image and stores a copy. Each URL must remain accessible until the synchronous request finishes, identify a supported image, and return no more than 15 MB. The created item contains Mascot-hosted image URLs rather than the source URLs.

POST /api/public/v1/items returns the stored item and its item_id. Creation does not list the item automatically.

External and Mascot identifiers

• external_id is your stable identifier for the item mapping owned by the API key.
• item_id is a stable public UUID used by item detail, update, delete, list, delist, and bulk item actions. Internal numeric inventory identifiers are never exposed.

Only one non-deleted item can use a given external ID for an API key and collector. Deleting an item makes that external ID reusable.

Updating an item

PATCH /api/public/v1/items/{itemId} uses top-level JSON Merge Patch behavior:

• Omitted properties remain unchanged.
• null clears an optional value.
• Arrays replace the existing array.
• type, external_id, cert_number, and authenticator cannot be changed.

Quantity can be updated to zero. Doing so requests delisting automatically. Quantity cannot be lower than the quantity already sold.

Listing prerequisites

Before calling POST /api/public/v1/items/{itemId}/listing:

• Call GET /api/public/v1/marketplace-connections and select one or more connections.
• A separate connection is returned for each connected account, including multiple accounts for the same marketplace and Mascot Network.
• For Shopify, Square, or Walmart, call GET /api/public/v1/marketplace-connections/{connectionId}/locations when a specific inventory location should be used.
• The item has a listing price greater than zero.
• The item has available inventory.

Send the selected connections in the listing request. location_id is optional and belongs to the concrete connection:

{
  "connections": [
    {"connection_id": 42, "location_id": "123456789"},
    {"connection_id": 57}
  ]
}

The listing call is asynchronous and returns no listing identifiers. Mascot attempts publication only through the selected connections.

Observe the item-level result through:

• GET /api/public/v1/items/{itemId}.
• GET /api/public/v1/items.
• listing.status_changed, listing.failed, and listing.delisting_failed webhooks.

The item detail includes listings, with the marketplace, concrete connection_id, current listing status, and marketplace URL. Mascot Network URLs open the product in Mercury.

The public states are:

State	Meaning
LISTED	At least one relevant listing has not ended
DELISTING	A delist operation was accepted and has not reached its terminal state
NOT_LISTED	No relevant listing remains

listing.failed is sent only when listing has reached a terminal failure and the item was not published successfully anywhere.

Delisting and deleting

DELETE /api/public/v1/items/{itemId}/listing requests delisting from every current destination. Use ?connections=42,57 to delist only the selected concrete connections. Selecting the Mascot Network connection removes the Mercury listing and every listing distributed through it. Processing completes asynchronously.

DELETE /api/public/v1/items/{itemId} soft-deletes the item and also requests delisting. A successful delete response means Mascot accepted the operation; it does not assert that every remote listing has already ended.