Skip to main content

Getting started

The Mascot Public API supports two integration roles:

  • Sellers manage inventory, listings, sales, and shipping.
  • Buyers discover products, purchase them, and manage offers.

An integration can use either or both roles when its credentials include the required scopes.

Base URL and headers​

Production requests use:

https://app-api.withmascot.com

Mascot provides both credentials. Every /api/public/v1 request must send them as headers:

api_key: <API key provided by Mascot>
auth_token: <auth token provided by Mascot>

Send JSON request bodies with Content-Type: application/json.

See Authentication for header usage and credential-handling requirements.

Seller sequence​

  1. Create an item synchronously, or submit an item feed for bulk inventory.
  2. Store the returned item_id; continue using your own external_id for reconciliation.
  3. Update inventory data when it changes.
  4. Read the marketplace connections, then request listing with the selected connection IDs after the item has a positive price and available quantity.
  5. Observe listing_status by reading the item or receiving item webhooks.
  6. Retrieve sales and shipment changes.
  7. For eligible sales, create and monitor an asynchronous shipping batch.

See Inventory and listings, Bulk operations, and Sales and shipping.

Buyer sequence​

  1. Search products using cursor pagination.
  2. Read the selected product again before acting on its ID.
  3. Either buy immediately or create an offer when offers_allowed is true.
  4. Store the returned Mascot order_id after a purchase.
  5. Retrieve the purchase for its latest shipping and tracking information, or subscribe to buyer webhooks.

See Buying and Offers.

API reference​

The API reference contains the exact methods, paths, parameters, request schemas, response schemas, scopes, validation constraints, and status codes. The bundled OpenAPI document can be used by compatible client-generation and validation tools.