Help Center

Getting Started Guides

Practical walkthroughs for the most common Guildhall workflows: creating events, joining communities, managing stores, and getting timezone/calendar behavior right.

Using the Store API

Using the Store API

Use this guide when you want to integrate your store website, automation tools, or internal systems with Guildhall.

1. Generate a store API token

  • Open My Store.
  • Go to Service API.
  • Create a token label you can recognize later (example: Website Scheduler).
  • Copy the token immediately when shown. It is only shown once.

2. Authentication and base path

  • Base path: /api/v1
  • Required header:
  • Authorization: Bearer YOUR_TOKEN
  • For JSON requests:
  • Content-Type: application/json

Recommended request headers:

Authorization: Bearer gh_store_xxxxx
Accept: application/json
Content-Type: application/json

3. Common endpoints for stores

These are the endpoints most stores use first.

Event management

  • GET /api/v1/events list events you can manage
  • POST /api/v1/events create an event (or upsert by external_source + external_uid)
  • GET /api/v1/events/<event_id> fetch one event with instances
  • PATCH /api/v1/events/<event_id> update event fields
  • DELETE /api/v1/events/<event_id> delete an event
  • GET /api/v1/events/<event_id>/instances list event instances

Invite-link operations

  • GET /api/v1/events/<event_id>/invite-links list store invite links for an event
  • POST /api/v1/events/<event_id>/invite-links create an invite link
  • POST /api/v1/events/<event_id>/invite-links/<invite_id>/revoke revoke an invite link

Instance attendance operations

  • GET /api/v1/events/<event_id>/instances/<instance_id>/attendance list attendance rows and summary
  • POST /api/v1/events/<event_id>/instances/<instance_id>/attendance create or update attendance row
  • DELETE /api/v1/events/<event_id>/instances/<instance_id>/attendance/<attendance_id> remove attendance row

4. Payload examples (expand/collapse)

POST /api/v1/events (Create event) payload 
{
  "title": "Friday Commander Night",
  "description": "Casual pods, all levels welcome.",
  "event_type": "in_person",
  "location_mode": "address",
  "location_address": "123 Main St, York, PA 17401",
  "zip_code": "17401",
  "timezone": "America/New_York",
  "start_datetime": "2026-03-06T19:00:00Z",
  "end_datetime": "2026-03-06T23:00:00Z",
  "recurrence_pattern": "weekly",
  "recurrence_until": "2026-06-30",
  "audience_scope": "public",
  "conversation_visibility": "attendees",
  "max_attendees": 40,
  "ticket_event_fee_cents": 500,
  "ticket_store_credit_cents": 500,
  "external_source": "store_site",
  "external_uid": "evt_2026_03_06_fri_commander"
}
POST /api/v1/events response (created/upserted) 
{
  "ok": true,
  "created": true,
  "event": {
    "id": "event_uuid",
    "title": "Friday Commander Night",
    "timezone": "America/New_York",
    "start_datetime": "2026-03-06T19:00:00",
    "end_datetime": "2026-03-06T23:00:00",
    "recurrence_pattern": "weekly",
    "instances": [
      {
        "id": "instance_uuid",
        "start_datetime": "2026-03-06T19:00:00",
        "end_datetime": "2026-03-06T23:00:00",
        "status": "scheduled",
        "source": "recurrence"
      }
    ]
  }
}
PATCH /api/v1/events/<event_id> payload (partial update) 
{
  "title": "Friday Commander Night - Competitive Pods",
  "max_attendees": 48,
  "ticket_event_fee_cents": 700,
  "ticket_store_credit_cents": 300
}
POST /api/v1/events/<event_id>/invite-links payload 
{
  "scope": "series",
  "custom_description": "Show this code at the register to join weekly commander nights.",
  "expires_at": "2026-04-01T23:59:59Z",
  "max_uses": 250
}
POST /api/v1/events/<event_id>/invite-links response 
{
  "ok": true,
  "invite_link": {
    "id": "invite_uuid",
    "event_id": "event_uuid",
    "scope": "series",
    "url": "https://your-domain/store-invites/token123",
    "expires_at": "2026-04-01T23:59:59",
    "max_uses": 250,
    "use_count": 0,
    "remaining_uses": 250,
    "status": "active",
    "is_active": true
  }
}
POST /api/v1/events/<event_id>/instances/<instance_id>/attendance payload (invite by email) 
{
  "invited_email": "player@example.com",
  "status": "invited",
  "send_email": true
}
POST /api/v1/events/<event_id>/instances/<instance_id>/attendance payload (mark going by user_id) 
{
  "user_id": "user_uuid",
  "status": "going"
}

5. cURL examples

List events 
curl -sS \
  -H "Authorization: Bearer $GUILDHALL_STORE_TOKEN" \
  -H "Accept: application/json" \
  "https://your-domain/api/v1/events?limit=50&offset=0&include_instances=true"
Create invite link for an event 
curl -sS -X POST \
  -H "Authorization: Bearer $GUILDHALL_STORE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scope":"event","max_uses":100}' \
  "https://your-domain/api/v1/events/$EVENT_ID/invite-links"

6. Validation and behavior notes

  • Datetimes should be ISO-8601 strings.
  • scope for invite links must be event or series.
  • Attendance upsert requires exactly one of user_id or invited_email.
  • For retries on POST, use idempotency patterns on your side and log X-Request-Id from responses.

7. Security and operations checklist

  • Rotate tokens on a schedule and when team access changes.
  • Use separate tokens per integration surface (website, automation, back office).
  • Revoke old tokens that are no longer in use.
  • Keep tokens server-side only (never in browser-exposed code).