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.
• Enter a recognizable token label such as Website Scheduler.
• Click Generate Token.
• Copy the token immediately when shown. It is displayed 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

Event management

• GET /api/v1/events list events you can manage
• POST /api/v1/events create an event, or upsert by external identity
• 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
• DELETE /api/v1/events/<event_id>/instances/<instance_id>/attendance/<attendance_id> remove attendance

4. Attendance targets and verified-email claiming

Guildhall supports two attendance target types for a single event instance:

• user_id: attach attendance directly to an existing Guildhall account
• invited_email: attach attendance to an email address even if that person does not have an account yet

This lets stores record attendance for walk-ins, counter signups, or league participants before they register.

Important behavior:

• The attendance request must include exactly one of user_id or invited_email.
• invited_email rows can use going, not_going, or invited.
• If a Guildhall account later verifies that same email address, Guildhall can claim the matching email attendance rows into that user account.
• If the account exists but the email is not verified yet, the email-backed attendance stays as an email row until verification happens.
• Once claimed, the user can manage that attendance through the normal Guildhall RSVP flows.

For attendee display:

• users with accounts show their Guildhall display name or username
• unmatched email attendees are shown as masked email addresses in non-manager views

5. Payload examples

{
  "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"
}

{
  "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
}

{
  "user_id": "user_uuid",
  "status": "going"
}

{
  "invited_email": "player@example.com",
  "status": "going",
  "send_email": false
}

{
  "id": "attendance_uuid",
  "event_id": "event_uuid",
  "event_instance_id": "instance_uuid",
  "status": "going",
  "target_type": "email",
  "user_id": null,
  "user": null,
  "invited_email": "player@example.com",
  "added_by_id": "store_owner_uuid"
}

6. cURL examples

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"

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"

curl -sS -X POST \
  -H "Authorization: Bearer $GUILDHALL_STORE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"invited_email":"player@example.com","status":"going","send_email":false}' \
  "https://your-domain/api/v1/events/$EVENT_ID/instances/$INSTANCE_ID/attendance"

7. Validation and behavior notes

• Datetimes should be ISO-8601 strings.
• Invite-link scope must be event or series.
• Attendance upsert requires exactly one of user_id or invited_email.
• status must be going, not_going, or invited.
• invited_email must be a valid email address.
• send_email is optional for email-backed attendance and defaults to true.
• Email-backed attendance is counted for attendance totals immediately based on its status, even before an account exists.
• Email-backed attendance only converts into a user-owned attendance row after that user verifies the matching email address.
• Tokens should stay server-side and never ship to browser code.

8. Recommended store workflow

• If you already know the person’s Guildhall account, use user_id.
• If they do not have an account yet, send invited_email and the correct status.
• Use send_email: false for in-person counter workflows where you do not want an email sent immediately.
• Do not create duplicate person records in your own system just because Guildhall has not linked the attendance row yet.
• Expect claim timing to depend on email verification, not just account creation.

9. Security and operations checklist

• Use separate tokens for each integration surface.
• Rotate tokens when staff access changes.
• Revoke old tokens that are no longer needed.
• Log request identifiers on your side if you need to troubleshoot retries.