API docs by Redocly

Mascot Public API (1.0.0)

Download OpenAPI specification:

License: LicenseRef-Proprietary

Public API for inventory, commerce, shipping, and event integrations.

The Mascot Public API lets an authorized collector manage inventory, publish listings, process bulk operations, discover and purchase products, manage offers, retrieve sales, purchase shipping labels, and receive signed webhooks.

All /api/public/v1 operations require both api_key and auth_token headers. Each operation also identifies the scope required by the auth token.

See the integration guides for prerequisites and complete call sequences. This reference defines only the public HTTP contract.

Marketplace connections

Discover the collector's connected sales channels.

List marketplace connections

Returns the collector's supported marketplace connections. Each connection has its own connection_id, so multiple accounts for the same marketplace are returned separately. Use these IDs in the item listing request. No marketplace credentials are exposed.

Authorizations:
(ApiKeyAuthToken)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List locations for a marketplace connection

Returns locations that may be supplied when listing through this connection. Shopify, Square, and Walmart can return selectable locations. Connections without a location concept, including Mascot Network, return an empty array.

Authorizations:
(ApiKeyAuthToken)
path Parameters
connectionId
required
integer <int64> >= 1

Concrete marketplace connection ID.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Items

Manage a collector's inventory and listing lifecycle.

Create an item

Enriches and persists one inventory item synchronously. Use an item feed for bulk creation. Graded and raw items have different identification prerequisites described by the request schema. Supplied image URLs are downloaded and copied to Mascot storage before the item is created. Creating an item does not publish it; call the listing endpoint separately.

Authorizations:
(ApiKeyAuthToken)
Request Body schema: application/json
required
One of
category
string (ItemCategory)
Enum: "SPORTS_CARD" "TRADING_CARD_GAME"
front_image_url
string <uri> (ImageUrl) <= 2048 characters ^https?://
back_image_url
string <uri> (ImageUrl) <= 2048 characters ^https?://
additional_image_urls
Array of strings <uri> (ImageUrl) <= 8 items unique [ items <uri > <= 2048 characters ^https?:// ]

Together with front and back, no more than eight unique image URLs are accepted.

item_cost
number <float> (NonNegativeAmount) >= 0

Non-negative amount in USD.

item_price
number <float> (NonNegativeAmount) >= 0

Non-negative amount in USD.

quantity
integer >= 0
purchase_date
string <date-time>
expected_delivery_date
string <date-time>
item_received_date
string <date-time>
purchased_from
string <= 255 characters
buyer
string <= 255 characters
location
string <= 255 characters
sku
string <= 255 characters
weight_lbs
number <float> (NonNegativeAmount) >= 0

Non-negative amount in USD.

keep_if_out_of_stock
boolean
buyers_premium_cost
number <float> (NonNegativeAmount) >= 0

Non-negative amount in USD.

shipping_insurance_cost
number <float> (NonNegativeAmount) >= 0

Non-negative amount in USD.

tax_cost
number <float> (NonNegativeAmount) >= 0

Non-negative amount in USD.

grading_cost
number <float> (NonNegativeAmount) >= 0

Non-negative amount in USD.

other_cost
number <float> (NonNegativeAmount) >= 0

Non-negative amount in USD.

other_cost_description
string <= 255 characters

Requires other_cost when provided.

minimum_offer
number <float> (NonNegativeAmount) >= 0

Non-negative amount in USD.

auto_accept_price
number <float> (NonNegativeAmount) >= 0

Non-negative amount in USD.

auction_start_price
number <float> (NonNegativeAmount) >= 0

Non-negative amount in USD.

auction_reserve_price
number <float> >= 0

Requires auction_start_price when provided.

marketplace_title
string <= 255 characters
marketplace_description
string <= 10000 characters
tags
Array of strings <= 50 items [ items [ 1 .. 255 ] characters ]
type
required
any
Value: "GRADED"
external_id
required
string [ 1 .. 255 ] characters

Identifier assigned by the integration. It must be unique among non-deleted items for this API key.

cert_number
required
string^[A-Za-z0-9-]{6,13}$
authenticator
string
Enum: "PSA" "PSA/DNA" "SGC" "BGS" "CGC" "TAG" "ISA" "AGS" "MBA"

When omitted, Mascot uses the grader configured for the integration or detects it when possible.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "GRADED",
  • "category": "SPORTS_CARD",
  • "external_id": "inventory-123",
  • "cert_number": "12345678",
  • "authenticator": "PSA",
  • "quantity": 1,
  • "item_price": 125
}

Response samples

Content type
application/json
{
  • "category": "SPORTS_CARD",
  • "front_image_url": "http://example.com",
  • "back_image_url": "http://example.com",
  • "additional_image_urls": [],
  • "item_cost": 0.1,
  • "item_price": 0.1,
  • "quantity": 0,
  • "purchase_date": "2019-08-24T14:15:22Z",
  • "expected_delivery_date": "2019-08-24T14:15:22Z",
  • "item_received_date": "2019-08-24T14:15:22Z",
  • "purchased_from": "string",
  • "buyer": "string",
  • "location": "string",
  • "sku": "string",
  • "weight_lbs": 0.1,
  • "keep_if_out_of_stock": true,
  • "buyers_premium_cost": 0.1,
  • "shipping_insurance_cost": 0.1,
  • "tax_cost": 0.1,
  • "grading_cost": 0.1,
  • "other_cost": 0.1,
  • "other_cost_description": "string",
  • "minimum_offer": 0.1,
  • "auto_accept_price": 0.1,
  • "auction_start_price": 0.1,
  • "auction_reserve_price": 0.1,
  • "marketplace_title": "string",
  • "marketplace_description": "string",
  • "tags": [
    ],
  • "type": "GRADED",
  • "external_id": "string",
  • "cert_number": "string",
  • "authenticator": "PSA",
  • "item_id": "4d8cd62e-a579-4dae-af8c-3172f96f8f7c",
  • "listing_status": "LISTED",
  • "total_cost": 0.1,
  • "listings": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "title": "string",
  • "subtitle": "string",
  • "quantity_available": 0,
  • "quantity_sold": 0,
  • "storage_location": "string",
  • "templated_marketplace_title": "string",
  • "templated_marketplace_description": "string",
  • "aspects": [
    ],
  • "inventory": [
    ],
  • "recent_comp": {},
  • "vcp_pricing": {
    },
  • "vcp_sync_status": "string",
  • "waxstat_slug": "string",
  • "waxstat_url": "http://example.com",
  • "parent_item_id": "aad554c9-a7a7-461f-b303-0b14f60473bc",
  • "auto_repricing": {
    },
  • "mba_certification": {
    }
}

Find items

Returns in-stock, non-deleted items for the authenticated collector. Every result uses the same complete public item representation returned by the item detail endpoint.

Authorizations:
(ApiKeyAuthToken)
query Parameters
page
integer >= 1
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50
external_id
string <= 255 characters
type
string (ItemType)
Enum: "GRADED" "RAW"
category
string (ItemCategory)
Enum: "SPORTS_CARD" "TRADING_CARD_GAME"
sku
string
cert_number
string
updated_after
string <date-time>

Return items updated strictly after this ISO-8601 timestamp.

tag
Array of strings[ items <= 255 characters ]

Return items that have any of these tags. Repeat the parameter or separate values with commas. Matching is case-insensitive.

is_listed
boolean

When true, return items with a current non-ended marketplace listing. When false, return items that are not currently listed.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "pagination": {
    }
}

Get an item

Returns the current public representation of one non-deleted item owned by the collector.

Authorizations:
(ApiKeyAuthToken)
path Parameters
itemId
required
string <uuid>

Public UUID returned by the item API.

Responses

Response samples

Content type
application/json
{
  • "category": "SPORTS_CARD",
  • "front_image_url": "http://example.com",
  • "back_image_url": "http://example.com",
  • "additional_image_urls": [],
  • "item_cost": 0.1,
  • "item_price": 0.1,
  • "quantity": 0,
  • "purchase_date": "2019-08-24T14:15:22Z",
  • "expected_delivery_date": "2019-08-24T14:15:22Z",
  • "item_received_date": "2019-08-24T14:15:22Z",
  • "purchased_from": "string",
  • "buyer": "string",
  • "location": "string",
  • "sku": "string",
  • "weight_lbs": 0.1,
  • "keep_if_out_of_stock": true,
  • "buyers_premium_cost": 0.1,
  • "shipping_insurance_cost": 0.1,
  • "tax_cost": 0.1,
  • "grading_cost": 0.1,
  • "other_cost": 0.1,
  • "other_cost_description": "string",
  • "minimum_offer": 0.1,
  • "auto_accept_price": 0.1,
  • "auction_start_price": 0.1,
  • "auction_reserve_price": 0.1,
  • "marketplace_title": "string",
  • "marketplace_description": "string",
  • "tags": [
    ],
  • "type": "GRADED",
  • "external_id": "string",
  • "cert_number": "string",
  • "authenticator": "PSA",
  • "item_id": "4d8cd62e-a579-4dae-af8c-3172f96f8f7c",
  • "listing_status": "LISTED",
  • "total_cost": 0.1,
  • "listings": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "title": "string",
  • "subtitle": "string",
  • "quantity_available": 0,
  • "quantity_sold": 0,
  • "storage_location": "string",
  • "templated_marketplace_title": "string",
  • "templated_marketplace_description": "string",
  • "aspects": [
    ],
  • "inventory": [
    ],
  • "recent_comp": {},
  • "vcp_pricing": {
    },
  • "vcp_sync_status": "string",
  • "waxstat_slug": "string",
  • "waxstat_url": "http://example.com",
  • "parent_item_id": "aad554c9-a7a7-461f-b303-0b14f60473bc",
  • "auto_repricing": {
    },
  • "mba_certification": {
    }
}

Update an item

Applies a top-level JSON Merge Patch. Omitted fields remain unchanged, null clears an optional field, and arrays replace their previous value. Setting quantity to zero requests delisting automatically. Delisting completes asynchronously; observe listing_status or subscribe to item listing webhooks.

Authorizations:
(ApiKeyAuthToken)
path Parameters
itemId
required
string <uuid>

Public UUID returned by the item API.

Request Body schema: application/json
required
non-empty
category
string (ItemCategory)
Enum: "SPORTS_CARD" "TRADING_CARD_GAME"
front_image_url
string <uri> (ImageUrl) <= 2048 characters ^https?://
back_image_url
string <uri> (ImageUrl) <= 2048 characters ^https?://
additional_image_urls
Array of strings <uri> (ImageUrl) <= 8 items unique [ items <uri > <= 2048 characters ^https?:// ]

Together with front and back, no more than eight unique image URLs are accepted.

item_cost
number <float> (NonNegativeAmount) >= 0

Non-negative amount in USD.

item_price
number <float> (NonNegativeAmount) >= 0

Non-negative amount in USD.

quantity
integer >= 0
purchase_date
string <date-time>
expected_delivery_date
string <date-time>
item_received_date
string <date-time>
purchased_from
string <= 255 characters
buyer
string <= 255 characters
location
string <= 255 characters
sku
string <= 255 characters
weight_lbs
number <float> (NonNegativeAmount) >= 0

Non-negative amount in USD.

keep_if_out_of_stock
boolean
buyers_premium_cost
number <float> (NonNegativeAmount) >= 0

Non-negative amount in USD.

shipping_insurance_cost
number <float> (NonNegativeAmount) >= 0

Non-negative amount in USD.

tax_cost
number <float> (NonNegativeAmount) >= 0

Non-negative amount in USD.

grading_cost
number <float> (NonNegativeAmount) >= 0

Non-negative amount in USD.

other_cost
number <float> (NonNegativeAmount) >= 0

Non-negative amount in USD.

other_cost_description
string <= 255 characters

Requires other_cost when provided.

minimum_offer
number <float> (NonNegativeAmount) >= 0

Non-negative amount in USD.

auto_accept_price
number <float> (NonNegativeAmount) >= 0

Non-negative amount in USD.

auction_start_price
number <float> (NonNegativeAmount) >= 0

Non-negative amount in USD.

auction_reserve_price
number <float> >= 0

Requires auction_start_price when provided.

marketplace_title
string <= 255 characters
marketplace_description
string <= 10000 characters
tags
Array of strings <= 50 items [ items [ 1 .. 255 ] characters ]

Responses

Request samples

Content type
application/json
{
  • "quantity": 2,
  • "item_price": 130
}

Response samples

Content type
application/json
{
  • "category": "SPORTS_CARD",
  • "front_image_url": "http://example.com",
  • "back_image_url": "http://example.com",
  • "additional_image_urls": [],
  • "item_cost": 0.1,
  • "item_price": 0.1,
  • "quantity": 0,
  • "purchase_date": "2019-08-24T14:15:22Z",
  • "expected_delivery_date": "2019-08-24T14:15:22Z",
  • "item_received_date": "2019-08-24T14:15:22Z",
  • "purchased_from": "string",
  • "buyer": "string",
  • "location": "string",
  • "sku": "string",
  • "weight_lbs": 0.1,
  • "keep_if_out_of_stock": true,
  • "buyers_premium_cost": 0.1,
  • "shipping_insurance_cost": 0.1,
  • "tax_cost": 0.1,
  • "grading_cost": 0.1,
  • "other_cost": 0.1,
  • "other_cost_description": "string",
  • "minimum_offer": 0.1,
  • "auto_accept_price": 0.1,
  • "auction_start_price": 0.1,
  • "auction_reserve_price": 0.1,
  • "marketplace_title": "string",
  • "marketplace_description": "string",
  • "tags": [
    ],
  • "type": "GRADED",
  • "external_id": "string",
  • "cert_number": "string",
  • "authenticator": "PSA",
  • "item_id": "4d8cd62e-a579-4dae-af8c-3172f96f8f7c",
  • "listing_status": "LISTED",
  • "total_cost": 0.1,
  • "listings": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "title": "string",
  • "subtitle": "string",
  • "quantity_available": 0,
  • "quantity_sold": 0,
  • "storage_location": "string",
  • "templated_marketplace_title": "string",
  • "templated_marketplace_description": "string",
  • "aspects": [
    ],
  • "inventory": [
    ],
  • "recent_comp": {},
  • "vcp_pricing": {
    },
  • "vcp_sync_status": "string",
  • "waxstat_slug": "string",
  • "waxstat_url": "http://example.com",
  • "parent_item_id": "aad554c9-a7a7-461f-b303-0b14f60473bc",
  • "auto_repricing": {
    },
  • "mba_certification": {
    }
}

Delete an item

Soft-deletes the item and requests delisting. The item's external ID becomes reusable by this API key. A successful response means the delete request was accepted; marketplace delisting may still be in progress.

Authorizations:
(ApiKeyAuthToken)
path Parameters
itemId
required
string <uuid>

Public UUID returned by the item API.

Responses

Response samples

Content type
application/json
{
  • "error": "invalid_token",
  • "message": "Invalid or missing public API credentials"
}

List an item

Requests publication through the explicitly selected marketplace connections. Obtain the connection IDs from GET /api/public/v1/marketplace-connections. Multiple connections for the same marketplace may be selected. The item must have a listing price greater than zero and available quantity. Publication is asynchronous; poll the item or use item listing webhooks to observe the result.

Authorizations:
(ApiKeyAuthToken)
path Parameters
itemId
required
string <uuid>

Public UUID returned by the item API.

Request Body schema: application/json
required
required
Array of objects (ItemListingConnectionRequest) [ 1 .. 50 ] items unique

Concrete marketplace connections and optional per-connection locations.

Responses

Request samples

Content type
application/json
{
  • "connections": [
    ]
}

Response samples

Content type
application/json
{
  • "error": "bad_request",
  • "message": "The request is invalid."
}

Delist an item

Requests delisting from supported destinations where the item may still be available. Processing is asynchronous. While it is pending, the item reports DELISTING; the terminal state is available through the item API and item listing webhooks.

Authorizations:
(ApiKeyAuthToken)
path Parameters
itemId
required
string <uuid>

Public UUID returned by the item API.

query Parameters
connections
Array of integers <int64> <= 50 items unique [ items <int64 > >= 1 ]

Connection IDs to delist. Omit this parameter to delist the item from every current destination. Selecting Mascot Network also removes every listing distributed through it.

Responses

Response samples

Content type
application/json
{
  • "error": "invalid_token",
  • "message": "Invalid or missing public API credentials"
}

Item feeds

Submit and monitor asynchronous bulk inventory operations.

Create an item feed

Submits a bulk CREATE, UPDATE, DELETE, LIST, or DELIST operation. The response is returned before task processing finishes. Store feed_id, then poll the feed until its status is FINISHED or subscribe to item_feed.finished.

Feeds are visible only to the API key that created them, even when another API key belongs to the same collector.

Authorizations:
(ApiKeyAuthToken)
Request Body schema: application/json
required
One of
type
required
any
Value: "CREATE"
required
Array of Graded item (object) or Raw item (object) (CreateFeedItem) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
Example
{
  • "type": "CREATE",
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "feed_id": "9369c69c-ec8e-4e41-ac71-b17373635837",
  • "type": "CREATE",
  • "status": "QUEUED",
  • "total_count": 1,
  • "success_count": 0,
  • "pending_count": 0,
  • "error_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get an item feed

Returns aggregate status and task counts for a feed created by this API key.

Authorizations:
(ApiKeyAuthToken)
path Parameters
feedId
required
string <uuid>

Item feed identifier returned when the feed was submitted.

Responses

Response samples

Content type
application/json
{
  • "feed_id": "9369c69c-ec8e-4e41-ac71-b17373635837",
  • "type": "CREATE",
  • "status": "QUEUED",
  • "total_count": 1,
  • "success_count": 0,
  • "pending_count": 0,
  • "error_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Find item feed tasks

Returns feed tasks in their original request order. Inspect tasks with status ERROR after the feed finishes. Task errors do not cause successful tasks to roll back.

Authorizations:
(ApiKeyAuthToken)
path Parameters
feedId
required
string <uuid>

Item feed identifier returned when the feed was submitted.

query Parameters
page
integer >= 1
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50

Responses

Response samples

Content type
application/json
{
  • "tasks": [
    ],
  • "pagination": {
    }
}

Products

Discover products offered by other collectors.

Find products

Searches products that are actively listed, in stock, and available for you to purchase. Your own listings are excluded, so an empty products array is returned when nothing else currently matches.

Results use cursor pagination over a snapshot taken when the first page is requested. To retrieve the next page, send next_cursor unchanged as cursor and repeat every filter, sort, and direction from the original request.

Authorizations:
(ApiKeyAuthToken)
query Parameters
cursor
string

Opaque cursor returned by the previous page.

limit
integer [ 1 .. 100 ]
Default: 50
query
string

Full-text product search.

sort
string
Enum: "relevance" "newest" "price" "year" "grade" "title"

Defaults to relevance when query is supplied and newest otherwise.

direction
string
Default: "desc"
Enum: "asc" "desc"
price_min
number >= 0
price_max
number >= 0
year_min
integer
year_max
integer
categories
string

Comma-separated category names.

graded
boolean
graders
string

Comma-separated grader names.

grade_min
number
grade_max
number
verified_cert
boolean
sport
string
game
string
manufacturer
string
subject
string
cert_number
string
upc
string
serial_numbered
boolean
offers_allowed
boolean
has_shipping_discount
boolean

Filter by whether a lower combined-shipping total is currently available.

Responses

Response samples

Content type
application/json
{
  • "products": [
    ],
  • "next_cursor": "string",
  • "has_more": true
}

Get a product

Returns a product that is actively listed, in stock, and available for you to purchase. Your own listings return 404.

Authorizations:
(ApiKeyAuthToken)
path Parameters
productId
required
string <uuid>

Product identifier returned by product discovery.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "title": "string",
  • "identifiers": {
    },
  • "buy_now_price": {
    },
  • "shipping": {
    },
  • "offers_allowed": true,
  • "aspects": [
    ],
  • "images": {}
}

Purchases

Buy products and retrieve buyer orders.

Buy a product

Purchases one unit using the collector's saved payment method. The buyer must have a usable saved payment method and a default shipping address, and the product must still be available.

external_id makes the request idempotent for this API key. Repeating the same external ID with the same product returns the existing result. Reusing it for another product returns 409 idempotency_conflict.

When compatible with a previous order whose shipping label has not been created, Mascot may combine shipping automatically. The returned order and totals are authoritative.

Authorizations:
(ApiKeyAuthToken)
Request Body schema: application/json
required
external_id
required
string [ 1 .. 255 ] characters

Idempotency identifier assigned by the buyer integration.

product_id
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "external_id": "purchase-1001",
  • "product_id": "018f3a7e-0df8-7a40-a918-2d728f60c98f"
}

Response samples

Content type
application/json
{
  • "order_id": "string",
  • "status": "PROCESSING",
  • "items": [
    ],
  • "totals": {
    },
  • "shipping": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Find purchases

Returns purchases made by the authenticated collector, grouped by Mascot order.

Authorizations:
(ApiKeyAuthToken)
query Parameters
page
integer >= 1
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50

Responses

Response samples

Content type
application/json
{
  • "purchases": [
    ],
  • "page": 1,
  • "page_size": 1,
  • "total_elements": 0,
  • "total_pages": 0
}

Get a purchase

Returns a buyer order, including its current shipping and tracking details.

Authorizations:
(ApiKeyAuthToken)
path Parameters
orderId
required
string

Mascot order ID returned by a buy or accepted-offer response.

Responses

Response samples

Content type
application/json
{
  • "order_id": "string",
  • "status": "PROCESSING",
  • "items": [
    ],
  • "totals": {
    },
  • "shipping": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Offers

Submit offers and respond to seller counter-offers.

Create an offer

Submits a buyer offer for an available product that allows offers. external_id is idempotent for this API key. Reusing it with the same product and amount returns the current result; reusing it with different input returns 409 idempotency_conflict.

Most successful requests return an offer. If the offer completes a purchase immediately, the response is the same purchase payload returned by the buy endpoint.

Authorizations:
(ApiKeyAuthToken)
Request Body schema: application/json
required
external_id
required
string [ 1 .. 255 ] characters

Idempotency identifier assigned by the buyer integration.

product_id
required
string <uuid>
amount
required
number decimal places <= 2 >= 0.01

Amount offered by the buyer.

Responses

Request samples

Content type
application/json
{
  • "external_id": "offer-1001",
  • "product_id": "018f3a7e-0df8-7a40-a918-2d728f60c98f",
  • "amount": 110
}

Response samples

Content type
application/json
Example
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "thread_id": "1de43264-67cb-48af-89f9-e865c375bb84",
  • "product_id": "0d012afa-f885-4e65-aeca-37e27701e2d1",
  • "status": "PENDING",
  • "from_side": "BUYER",
  • "amount": 0,
  • "expires_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Find offers

Returns offer threads belonging to the authenticated buyer, with the latest state of each thread.

Authorizations:
(ApiKeyAuthToken)
query Parameters
status
string
Value: "ACTIVE"

Set to ACTIVE to return only pending, unexpired offer threads.

page
integer >= 1
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50

Responses

Response samples

Content type
application/json
{
  • "offers": [
    ],
  • "page": 1,
  • "page_size": 1,
  • "total_elements": 0,
  • "total_pages": 0
}

Get an offer

Returns the latest state in the requested buyer-owned offer thread.

Authorizations:
(ApiKeyAuthToken)
path Parameters
offerId
required
string <uuid>

Offer identifier returned by the offer API or an offer webhook.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "thread_id": "1de43264-67cb-48af-89f9-e865c375bb84",
  • "product_id": "0d012afa-f885-4e65-aeca-37e27701e2d1",
  • "status": "PENDING",
  • "from_side": "BUYER",
  • "amount": 0,
  • "expires_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Accept a seller counter-offer

Accepts the latest pending seller counter-offer and purchases one unit using the saved payment method. Buyers cannot submit another counter-offer; they can only accept or reject the seller's counter. The buyer must have a usable saved payment method and default shipping address. external_id makes the action idempotent.

Authorizations:
(ApiKeyAuthToken)
path Parameters
offerId
required
string <uuid>

Offer identifier returned by the offer API or an offer webhook.

Request Body schema: application/json
required
external_id
required
string [ 1 .. 255 ] characters

Idempotency identifier for this accept or reject action.

Responses

Request samples

Content type
application/json
{
  • "external_id": "accept-offer-1001"
}

Response samples

Content type
application/json
{
  • "order_id": "string",
  • "status": "PROCESSING",
  • "items": [
    ],
  • "totals": {
    },
  • "shipping": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Reject a seller counter-offer

Rejects the latest pending seller counter-offer. external_id makes the action idempotent.

Authorizations:
(ApiKeyAuthToken)
path Parameters
offerId
required
string <uuid>

Offer identifier returned by the offer API or an offer webhook.

Request Body schema: application/json
required
external_id
required
string [ 1 .. 255 ] characters

Idempotency identifier for this accept or reject action.

Responses

Request samples

Content type
application/json
{
  • "external_id": "reject-offer-1001"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "thread_id": "1de43264-67cb-48af-89f9-e865c375bb84",
  • "product_id": "0d012afa-f885-4e65-aeca-37e27701e2d1",
  • "status": "PENDING",
  • "from_side": "BUYER",
  • "amount": 0,
  • "expires_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Sales

Retrieve the authenticated collector's sales.

Find sales

Returns sales belonging to the authenticated seller. Each sale includes public order state, sold items, shipping address, and shipment tracking when available. The payload is the same public sale representation used by sale and shipment webhooks.

Authorizations:
(ApiKeyAuthToken)
query Parameters
page
integer >= 1
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50
direction
string
Default: "DESC"
Enum: "ASC" "DESC"

Sort direction by order date.

Responses

Response samples

Content type
application/json
{
  • "sales": [
    ],
  • "pagination": {
    }
}

Shipping

Purchase and manage shipping labels for eligible sales.

Find ship-from locations

Returns the collector's ship-from locations. Use an ID from this response when selecting a non-default origin for a shipping batch.

Authorizations:
(ApiKeyAuthToken)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Find sales eligible for shipping

Returns sales that can be considered for batch label creation from the selected ship-from location. Batch shipping must be enabled for the collector. When no location is supplied, Mascot uses the default ship-from location, or the first available location.

Check ready_for_shipping immediately before submitting a batch; eligibility can change.

Authorizations:
(ApiKeyAuthToken)
query Parameters
ship_from_location_id
string <uuid>
page
integer >= 1
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50

Responses

Response samples

Content type
application/json
{
  • "sales": [
    ],
  • "pagination": {
    }
}

Create a shipping batch

Starts asynchronous label creation for eligible sales. Batch shipping must be enabled and the collector must have a ship-from location. Every selected sale must currently report ready_for_shipping: true.

external_id is idempotent for this API key and collector. Repeating the same external ID with the same normalized sale IDs, location, and ship date returns the existing batch. Reusing it for different input returns 409 conflict.

Poll the returned batch until it reaches FINISHED, ACTION_REQUIRED, or FAILED, or subscribe to the corresponding shipping-batch webhook events.

Authorizations:
(ApiKeyAuthToken)
Request Body schema: application/json
required
external_id
required
string [ 1 .. 255 ] characters

Idempotency identifier assigned by the integration.

sale_ids
required
Array of strings <uuid> [ 1 .. 100 ] items unique [ items <uuid > ]
ship_from_location_id
string <uuid>

Uses the collector's default ship-from location when omitted.

ship_date
string <date>

Cannot be in the future. Uses the current date when omitted.

Responses

Request samples

Content type
application/json
{
  • "external_id": "shipping-batch-1001",
  • "sale_ids": [
    ],
  • "ship_from_location_id": "018f3a7e-0df8-7a40-a918-2d728f60c98f",
  • "ship_date": "2026-08-24"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "external_id": "string",
  • "status": "QUEUED",
  • "stage": "VALIDATING",
  • "counts": {
    },
  • "ship_date": "2019-08-24",
  • "ship_from_location_id": "cfb9a46c-5e0e-4064-98ff-0fc1838e9656",
  • "ship_from_location_name": "string",
  • "labels_available": true,
  • "pick_list_available": true,
  • "manifest_available": true,
  • "failure_message": "string",
  • "retired": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z"
}

Find shipping batches

Returns the collector's shipping batches, newest first.

Authorizations:
(ApiKeyAuthToken)
query Parameters
page
integer >= 1
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50
status
string (ShippingBatchStatus)
Enum: "QUEUED" "IN_PROGRESS" "ACTION_REQUIRED" "FINISHED" "FAILED"
date_from
string <date>
date_to
string <date>

Must be on or after date_from.

ship_from_location_id
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "batches": [
    ],
  • "pagination": {
    }
}

Get a shipping batch

Returns aggregate state, each shipment result, and the documents currently available for the batch.

Authorizations:
(ApiKeyAuthToken)
path Parameters
batchId
required
string <uuid>

Shipping batch identifier.

Responses

Response samples

Content type
application/json
{
  • "batch": {
    },
  • "items": [
    ],
  • "available_documents": [
    ]
}

Retry a shipping batch

Creates a new asynchronous batch for recoverable failed shipments. The original batch must contain failed shipments and use today's ship date. Use a new external_id for the retry. If the ship date is no longer today, submit a new batch from the eligible-sales endpoint.

Authorizations:
(ApiKeyAuthToken)
path Parameters
batchId
required
string <uuid>

Shipping batch identifier.

Request Body schema: application/json
required
external_id
required
string [ 1 .. 255 ] characters

New idempotency identifier for the retry batch.

Responses

Request samples

Content type
application/json
{
  • "external_id": "shipping-retry-1001"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "external_id": "string",
  • "status": "QUEUED",
  • "stage": "VALIDATING",
  • "counts": {
    },
  • "ship_date": "2019-08-24",
  • "ship_from_location_id": "cfb9a46c-5e0e-4064-98ff-0fc1838e9656",
  • "ship_from_location_name": "string",
  • "labels_available": true,
  • "pick_list_available": true,
  • "manifest_available": true,
  • "failure_message": "string",
  • "retired": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z"
}

Remove failed items from a shipping batch

Completes a partially successful batch by removing its failed shipments and regenerating the remaining documents. At least one label must have succeeded. If every shipment failed, retry the batch instead.

Authorizations:
(ApiKeyAuthToken)
path Parameters
batchId
required
string <uuid>

Shipping batch identifier.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "external_id": "string",
  • "status": "QUEUED",
  • "stage": "VALIDATING",
  • "counts": {
    },
  • "ship_date": "2019-08-24",
  • "ship_from_location_id": "cfb9a46c-5e0e-4064-98ff-0fc1838e9656",
  • "ship_from_location_name": "string",
  • "labels_available": true,
  • "pick_list_available": true,
  • "manifest_available": true,
  • "failure_message": "string",
  • "retired": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z"
}

Get shipping labels

Returns a temporary download URL after labels_available becomes true.

Authorizations:
(ApiKeyAuthToken)
path Parameters
batchId
required
string <uuid>

Shipping batch identifier.

Responses

Response samples

Content type
application/json
{}

Get a shipping pick list

Returns a temporary download URL after pick_list_available becomes true.

Authorizations:
(ApiKeyAuthToken)
path Parameters
batchId
required
string <uuid>

Shipping batch identifier.

Responses

Response samples

Content type
application/json
{}

Get a shipping manifest

Returns a temporary download URL after manifest_available becomes true.

Authorizations:
(ApiKeyAuthToken)
path Parameters
batchId
required
string <uuid>

Shipping batch identifier.

Responses

Response samples

Content type
application/json
{}

Webhook endpoints

Configure destinations for signed event deliveries.

Create a webhook endpoint

Registers a public HTTPS URL and the events it should receive. The API key must have the read scope associated with every requested event type. The response returns the signing secret exactly once; store it securely before discarding the response.

Webhook endpoints belong to the API key that creates them.

Authorizations:
(ApiKeyAuthToken)
Request Body schema: application/json
required
url
required
string <uri> <= 2048 characters ^https://

Public HTTPS destination. Redirects are not followed.

event_types
required
Array of strings (WebhookEventType) non-empty unique
Items Enum: "item.created" "item.updated" "item.deleted" "listing.status_changed" "listing.failed" "listing.delisting_failed" "item_feed.finished" "sale.created" "sale.updated" "shipment.tracking_updated" "shipping_batch.finished" "shipping_batch.action_required" "shipping_batch.failed" "purchase.created" "purchase.updated" "offer.created" "offer.updated"

The API key must have the corresponding read scope for every selected event.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "url": "http://example.com",
  • "event_types": [
    ],
  • "status": "ACTIVE",
  • "secret": "string",
  • "consecutive_failure_count": 0,
  • "last_success_at": "2019-08-24T14:15:22Z",
  • "last_failure_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Find webhook endpoints

Returns webhook endpoints created by this API key. Signing secrets are never returned by read operations.

Authorizations:
(ApiKeyAuthToken)
query Parameters
page
integer >= 1
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50

Responses

Response samples

Content type
application/json
{
  • "subscriptions": [
    ],
  • "pagination": {
    }
}

Get a webhook endpoint

Returns endpoint configuration and delivery health, without the signing secret.

Authorizations:
(ApiKeyAuthToken)
path Parameters
id
required
string <uuid>

Webhook endpoint identifier.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "url": "http://example.com",
  • "event_types": [
    ],
  • "status": "ACTIVE",
  • "secret": "string",
  • "consecutive_failure_count": 0,
  • "last_success_at": "2019-08-24T14:15:22Z",
  • "last_failure_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Replace a webhook endpoint configuration

Replaces the URL and event selection. This operation does not rotate the signing secret.

Authorizations:
(ApiKeyAuthToken)
path Parameters
id
required
string <uuid>

Webhook endpoint identifier.

Request Body schema: application/json
required
url
required
string <uri> <= 2048 characters ^https://

Public HTTPS destination. Redirects are not followed.

event_types
required
Array of strings (WebhookEventType) non-empty unique
Items Enum: "item.created" "item.updated" "item.deleted" "listing.status_changed" "listing.failed" "listing.delisting_failed" "item_feed.finished" "sale.created" "sale.updated" "shipment.tracking_updated" "shipping_batch.finished" "shipping_batch.action_required" "shipping_batch.failed" "purchase.created" "purchase.updated" "offer.created" "offer.updated"

The API key must have the corresponding read scope for every selected event.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "url": "http://example.com",
  • "event_types": [
    ],
  • "status": "ACTIVE",
  • "secret": "string",
  • "consecutive_failure_count": 0,
  • "last_success_at": "2019-08-24T14:15:22Z",
  • "last_failure_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Disable a webhook endpoint

Disables the endpoint. It remains visible and can later be enabled again.

Authorizations:
(ApiKeyAuthToken)
path Parameters
id
required
string <uuid>

Webhook endpoint identifier.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "url": "http://example.com",
  • "event_types": [
    ],
  • "status": "ACTIVE",
  • "secret": "string",
  • "consecutive_failure_count": 0,
  • "last_success_at": "2019-08-24T14:15:22Z",
  • "last_failure_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Disable a webhook endpoint

Stops future deliveries to this endpoint until it is enabled again.

Authorizations:
(ApiKeyAuthToken)
path Parameters
id
required
string <uuid>

Webhook endpoint identifier.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "url": "http://example.com",
  • "event_types": [
    ],
  • "status": "ACTIVE",
  • "secret": "string",
  • "consecutive_failure_count": 0,
  • "last_success_at": "2019-08-24T14:15:22Z",
  • "last_failure_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Enable a webhook endpoint

Revalidates the endpoint URL and resumes delivery of new events.

Authorizations:
(ApiKeyAuthToken)
path Parameters
id
required
string <uuid>

Webhook endpoint identifier.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "url": "http://example.com",
  • "event_types": [
    ],
  • "status": "ACTIVE",
  • "secret": "string",
  • "consecutive_failure_count": 0,
  • "last_success_at": "2019-08-24T14:15:22Z",
  • "last_failure_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Rotate a webhook signing secret

Replaces the endpoint's signing secret. The response returns the new secret exactly once and subsequent deliveries use it.

Authorizations:
(ApiKeyAuthToken)
path Parameters
id
required
string <uuid>

Webhook endpoint identifier.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "url": "http://example.com",
  • "event_types": [
    ],
  • "status": "ACTIVE",
  • "secret": "string",
  • "consecutive_failure_count": 0,
  • "last_success_at": "2019-08-24T14:15:22Z",
  • "last_failure_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Webhook events

Receive a Mascot webhook event Webhook

Mascot sends the event to the URL configured on the webhook endpoint. Calculate HMAC-SHA256(secret, timestamp + "." + raw_request_body) and compare it with the hexadecimal value in Mascot-Webhook-Signature. Verify the signature using the raw bytes before parsing JSON, compare in constant time, and reject stale timestamps.

Return any 2xx status after durably accepting the event. Delivery is at least once, so consumers must deduplicate using the event ID. A 410 Gone response disables the endpoint. Other non-2xx responses and network failures are retried up to ten attempts over 72 hours.

header Parameters
Mascot-Event-Id
required
string
Mascot-Event-Type
required
string (WebhookEventType)
Enum: "item.created" "item.updated" "item.deleted" "listing.status_changed" "listing.failed" "listing.delisting_failed" "item_feed.finished" "sale.created" "sale.updated" "shipment.tracking_updated" "shipping_batch.finished" "shipping_batch.action_required" "shipping_batch.failed" "purchase.created" "purchase.updated" "offer.created" "offer.updated"
Mascot-Delivery-Id
required
string
Mascot-Delivery-Attempt
required
integer >= 1
Mascot-Webhook-Timestamp
required
string
Mascot-Webhook-Signature
required
string^v1=[a-f0-9]+$
Request Body schema: application/json
required
id
required
string

Stable event identifier. Use it to deduplicate deliveries.

type
required
string (WebhookEventType)
Enum: "item.created" "item.updated" "item.deleted" "listing.status_changed" "listing.failed" "listing.delisting_failed" "item_feed.finished" "sale.created" "sale.updated" "shipment.tracking_updated" "shipping_batch.finished" "shipping_batch.action_required" "shipping_batch.failed" "purchase.created" "purchase.updated" "offer.created" "offer.updated"
api_version
required
string
Value: "v1"
created_at
required
string <date-time>
required
Item (object) or DeletedItemEvent (object) or ItemFeed (object) or Sale (object) or ShippingBatch (object) or Purchase (object) or Offer (object)

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "type": "item.created",
  • "api_version": "v1",
  • "created_at": "2019-08-24T14:15:22Z",
  • "data": {
    }
}