Developer API

Integrate your market data with your own systems.

I'm a market organiser

This page is for developers. If you'd like to connect your website or system to Itinerant Traders, share this page with your web developer or development agency.

I'm a developer

You're in the right place. Generate an API key at /account/api (Pro plan required), then use the endpoints below to integrate market data into your application.

Get API access

Authentication

All requests require an Authorization header with a Bearer token.

Keys are generated at /account/api (Pro plan required)
Rate limit: 60 requests per minute per key
Keys are scoped to your markets only

curl -H "Authorization: Bearer it_live_your_key_here" \
  https://itineranttraders.com.au/api/v1/markets

Getting started

1
Generate an API key
Go to /account/api (Pro plan required) and create a key. Copy it — it is only shown once.

Make your first request

curl -H "Authorization: Bearer it_live_your_key_here" \
  https://itineranttraders.com.au/api/v1/markets

Handle the response

const res = await fetch(
  'https://itineranttraders.com.au/api/v1/markets',
  { headers: { Authorization: 'Bearer it_live_your_key_here' } }
);

const { data } = await res.json();

console.log(data); // array of your markets

Response format

All responses return JSON.

Success

{
  "data": [ ... ],
  "meta": { "count": 3 }
}

Error

{
  "error": "Booking is not confirmed",
  "code": 409
}

Endpoints

GET/api/v1/markets

List all active markets belonging to your account.

{
  "data": [
    {
      "id": 12,
      "name": "Riverside Makers Market",
      "slug": "riverside-makers-market",
      "region": "VIC",
      "market_type": "Artisan"
    }
  ],
  "meta": { "count": 1 }
}

GET/api/v1/markets/:slug

Retrieve a single market by slug.

Path: slug — the market's URL slug

{
  "data": {
    "id": 12,
    "name": "Riverside Makers Market",
    "slug": "riverside-makers-market",
    "region": "VIC",
    "market_type": "Artisan",
    "booking_enabled": true
  },
  "meta": { "count": 1 }
}

GET/api/v1/markets/:slug/events

List upcoming scheduled events with confirmed and pending booking counts.

Path: slug — market slug

{
  "data": [
    {
      "id": 88,
      "starts_at": "2025-08-16T22:00:00.000Z",
      "ends_at": "2025-08-17T02:00:00.000Z",
      "status": "scheduled",
      "confirmed_count": 14,
      "pending_count": 3
    }
  ],
  "meta": { "count": 1 }
}

GET/api/v1/markets/:slug/events/:eventId/roster

List confirmed and pending bookings for a specific event.

Path: slug, eventId

{
  "data": [
    {
      "booking_id": 201,
      "trading_name": "Clover & Clay",
      "contact_email": "hello@cloverandclay.com.au",
      "status": "confirmed",
      "stall_number": "A4",
      "amount_cents": 4500,
      "approved_at": "2025-07-01T09:12:00.000Z"
    }
  ],
  "meta": { "count": 1 }
}

GET/api/v1/markets/:slug/stallholders

List all distinct stallholders who have ever booked at this market, with visit counts.

Path: slug

{
  "data": [
    {
      "business_entity_id": 55,
      "trading_name": "Clover & Clay",
      "contact_email": "hello@cloverandclay.com.au",
      "total_bookings": 6,
      "last_attended": "2025-07-19T22:00:00.000Z"
    }
  ],
  "meta": { "count": 1 }
}

GET/api/v1/markets/:slug/waitlist

List the waitlist for the market's next upcoming event.

Path: slug

{
  "data": [
    {
      "entry_id": 9,
      "trading_name": "Paper & Pine",
      "contact_email": "hi@paperandpine.com.au",
      "status": "waiting",
      "added_at": "2025-08-01T14:30:00.000Z"
    }
  ],
  "meta": { "count": 1, "event_id": 88 }
}

POST/api/v1/markets/:slug/events/:eventId/bookings/:bookingId/confirm

Confirm a pending booking. Triggers a confirmation email to the stallholder.

Path: slug, eventId, bookingId

{
  "data": { "booking_id": 201, "status": "confirmed" },
  "meta": { "count": 1 }
}

POST/api/v1/markets/:slug/events/:eventId/bookings/:bookingId/reject

Reject a pending booking. Triggers a rejection email to the stallholder.

Path: slug, eventId, bookingId

Body (optional): { "reason": "string" }

// Request body (optional)
{ "reason": "No space available for your category" }

// Response
{
  "data": { "booking_id": 201, "status": "rejected" },
  "meta": { "count": 1 }
}

POST/api/v1/markets/:slug/events/:eventId/bookings/:bookingId/cancel

Cancel a confirmed booking. Triggers a cancellation email and waitlist auto-notify if enabled.

Path: slug, eventId, bookingId

Body (optional): { "reason": "string" }

// Request body (optional)
{ "reason": "Market cancelled due to weather" }

// Response
{
  "data": { "booking_id": 201, "status": "cancelled" },
  "meta": { "count": 1 }
}

POST/api/v1/markets/:slug/waitlist/:entryId/notify

Notify a waiting stallholder that a spot is available. Sets a 48-hour response window.

Path: slug, entryId

{
  "data": { "entry_id": 9, "status": "notified" },
  "meta": { "count": 1 }
}

Error codes

400

Bad request — malformed body or missing required field

401

Unauthorised — missing or invalid API key

403

Forbidden — valid key but insufficient permissions or free plan

404

Not found — resource does not exist or does not belong to you

409

Conflict — resource is not in the expected status

429

Too many requests — rate limit of 60 req/min exceeded

Notes

API keys are scoped to your markets only
Write operations (confirm, reject, cancel, notify) trigger the same emails as manual actions in the dashboard
Cancellations trigger waitlist auto-notify if enabled for that market
All timestamps are ISO 8601 UTC

Authentication

All requests require an Authorization header with a Bearer token.

Keys are generated at /account/api (Pro plan required)

Rate limit: 60 requests per minute per key

Keys are scoped to your markets only

curl -H "Authorization: Bearer it_live_your_key_here" \ https://itineranttraders.com.au/api/v1/markets

Getting started

Generate an API key

Go to /account/api (Pro plan required) and create a key. Copy it — it is only shown once.

Make your first request

curl -H "Authorization: Bearer it_live_your_key_here" \
  https://itineranttraders.com.au/api/v1/markets

Handle the response

const res = await fetch(
  'https://itineranttraders.com.au/api/v1/markets',
  { headers: { Authorization: 'Bearer it_live_your_key_here' } }
);

const { data } = await res.json();

console.log(data); // array of your markets

Endpoints

GET/api/v1/markets

List all active markets belonging to your account.

{
  "data": [
    {
      "id": 12,
      "name": "Riverside Makers Market",
      "slug": "riverside-makers-market",
      "region": "VIC",
      "market_type": "Artisan"
    }
  ],
  "meta": { "count": 1 }
}

GET/api/v1/markets/:slug

Retrieve a single market by slug.

Path: slug — the market's URL slug

{
  "data": {
    "id": 12,
    "name": "Riverside Makers Market",
    "slug": "riverside-makers-market",
    "region": "VIC",
    "market_type": "Artisan",
    "booking_enabled": true
  },
  "meta": { "count": 1 }
}

GET/api/v1/markets/:slug/events

List upcoming scheduled events with confirmed and pending booking counts.

Path: slug — market slug

{
  "data": [
    {
      "id": 88,
      "starts_at": "2025-08-16T22:00:00.000Z",
      "ends_at": "2025-08-17T02:00:00.000Z",
      "status": "scheduled",
      "confirmed_count": 14,
      "pending_count": 3
    }
  ],
  "meta": { "count": 1 }
}

GET/api/v1/markets/:slug/events/:eventId/roster

List confirmed and pending bookings for a specific event.

Path: slug, eventId

{
  "data": [
    {
      "booking_id": 201,
      "trading_name": "Clover & Clay",
      "contact_email": "hello@cloverandclay.com.au",
      "status": "confirmed",
      "stall_number": "A4",
      "amount_cents": 4500,
      "approved_at": "2025-07-01T09:12:00.000Z"
    }
  ],
  "meta": { "count": 1 }
}

GET/api/v1/markets/:slug/stallholders

List all distinct stallholders who have ever booked at this market, with visit counts.

Path: slug

{
  "data": [
    {
      "business_entity_id": 55,
      "trading_name": "Clover & Clay",
      "contact_email": "hello@cloverandclay.com.au",
      "total_bookings": 6,
      "last_attended": "2025-07-19T22:00:00.000Z"
    }
  ],
  "meta": { "count": 1 }
}

GET/api/v1/markets/:slug/waitlist

List the waitlist for the market's next upcoming event.

Path: slug

{
  "data": [
    {
      "entry_id": 9,
      "trading_name": "Paper & Pine",
      "contact_email": "hi@paperandpine.com.au",
      "status": "waiting",
      "added_at": "2025-08-01T14:30:00.000Z"
    }
  ],
  "meta": { "count": 1, "event_id": 88 }
}

POST/api/v1/markets/:slug/events/:eventId/bookings/:bookingId/confirm

Confirm a pending booking. Triggers a confirmation email to the stallholder.

Path: slug, eventId, bookingId

{
  "data": { "booking_id": 201, "status": "confirmed" },
  "meta": { "count": 1 }
}

POST/api/v1/markets/:slug/events/:eventId/bookings/:bookingId/reject

Reject a pending booking. Triggers a rejection email to the stallholder.

Path: slug, eventId, bookingId

Body (optional): { "reason": "string" }

// Request body (optional)
{ "reason": "No space available for your category" }

// Response
{
  "data": { "booking_id": 201, "status": "rejected" },
  "meta": { "count": 1 }
}

POST/api/v1/markets/:slug/events/:eventId/bookings/:bookingId/cancel

Cancel a confirmed booking. Triggers a cancellation email and waitlist auto-notify if enabled.

Path: slug, eventId, bookingId

Body (optional): { "reason": "string" }

// Request body (optional)
{ "reason": "Market cancelled due to weather" }

// Response
{
  "data": { "booking_id": 201, "status": "cancelled" },
  "meta": { "count": 1 }
}

POST/api/v1/markets/:slug/waitlist/:entryId/notify

Notify a waiting stallholder that a spot is available. Sets a 48-hour response window.

Path: slug, entryId

{
  "data": { "entry_id": 9, "status": "notified" },
  "meta": { "count": 1 }
}

Error codes

400

Bad request — malformed body or missing required field

401

Unauthorised — missing or invalid API key

403

Forbidden — valid key but insufficient permissions or free plan

404

Not found — resource does not exist or does not belong to you

409

Conflict — resource is not in the expected status

429

Too many requests — rate limit of 60 req/min exceeded