Locations

Create a new location for the merchant. The location will be linked to the same company as the user's current active location.

Hierarchy Options:

• Standalone (default): Independent location with no parent
• Parent: Set isRootCompany: true to mark as a parent/root location
• Child: Provide parentLocationId to create as a child of another location

Payout Account: A payout account will be created with the specified PSP (STRIPE or ADYEN). For Adyen, billingEmail is required.

Required Fields:

• name: Location name (1-255 characters)
• address: Street address
• city: City name
• country: Country code (e.g., SE, NO)
• psp: Payment Service Provider (STRIPE or ADYEN)

Permissions: 🟢 locations.create

Get detailed information about a specific location, including its feature toggles.

Features: By default, the response includes all available features and their status for this location. Set includeFeatures=false to exclude features from the response.

Response includes:

• Location details (name, address, timezone, currency, etc.)
• Feature toggles with enabled status and optional metadata
• Hierarchy information if applicable

Permissions: 🔵 locations.read

Quick check if a specific feature is enabled for a location.

Use cases:

• Feature gating in UI components
• Conditional logic based on feature availability
• Quick feature checks without fetching full location data

Permissions: 🔵 locations.read

Get the location hierarchy tree starting from a specific location. Returns the location and all its descendants in a tree structure.

Permissions: 🔵 locations.read

Get opening hours for a location including weekly schedule, exceptions, and current open/closed status

Update or create opening hours for a location. This replaces the entire schedule.

Permissions: 🟠 schedules.update

Remove opening hours for a location (makes it always open)

Permissions: 🔴 schedules.delete

Get pickup settings and exceptional sale times for a location.

Response includes:

• pickupSettings: Configuration for time slot selection (enabled, days in advance)
• exceptionalSaleTimes: Special dates with modified hours or closures (holidays, events, etc.)

Use cases:

• Displaying time slot picker in checkout flow
• Determining if pickup time selection is available
• Showing modified hours for upcoming dates

Permissions: 🔵 locations.read

Get all active QR codes (tables) for a location.

Response includes:

• Array of QR codes with uuid and name
• Only active QR codes are returned
• Sorted alphabetically by name

Use cases:

• Displaying table selection in storefront
• Managing table orders
• QR code scanning for dine-in orders

Permissions: 🔵 locations.read

Set or change the parent location for a location. This updates the location hierarchy and refreshes the materialized access view.

Permissions: 🟠 locations.update

Update settings for a specific location. Supports partial updates - only provided fields will be updated.

Supported fields:

• phone: Phone number (set to null to clear)
• website: Website URL (set to null to clear, max 248 chars)
• description: Location description (set to null to clear, max 1000 chars)
• pickupInformation: Pickup information text
• context: Location context JSON (features, configuration, etc.)
• isItemCommentAllowed: Whether item comments are allowed
• orderPlacements: Order placement configuration per channel
• paymentFlow: Default payment flow (open_tab or pay_upfront, set to null to clear)
• defaultPreparationTimeSeconds: Default preparation time
• takeawayEnabled: Whether takeaway is enabled
• autoacceptMinutesBeforePickup: Minutes before pickup for auto-accept
• pickupTimeEnabled: Whether time slot selection is enabled
• pickupDaysInAdvanceAllowed: Days in advance for pickup time selection

Permissions: 🟠 locations.update

Get comprehensive storefront data for a location by its ID.

Response includes:

• Location details (name, address, coordinates, contact info)
• Current sale status and times
• Opening hours (weekly hours, exceptions, schedule ID)
• Theme and branding configuration
• Feature flags and settings
• Loyalty program information
• Extended waiting time (if set)

This returns the same enriched data as the slug-based endpoint, but uses the numeric location ID.

Permissions: 🔵 locations.read

Returns the location's voucher provider type and a ready-to-render display name.

Behavior:

• voucher_provider='trivec' → providerDisplayName: 'Trivec' (hardcoded, never leaks voucherService)
• voucher_provider='custom' with valid displayName → providerDisplayName: <settings.displayName>
• voucher_provider='custom' with displayName containing the forbidden third-party vendor substring (case-insensitive) → providerDisplayName: null
• No integration_configs row OR voucher_provider IS NULL → { voucherProvider: 'karma', providerDisplayName: null }

Permissions: 🔵 locations.read

Upserts integration_configs.voucher_provider and settings in a single transaction.

Body is a tagged union by provider:

• { provider: 'karma' } — switch back to native Karma vouchers (no settings)
• { provider: 'trivec' } — enable Trivec; credentials are provisioned out-of-band, never via merchant PUT (CRED-02)
• { provider: 'custom', settings: {...} } — configure a custom HTTP voucher provider

Server-side behaviour:

• Custom provider secrets are AES-256-CBC encrypted server-side; plaintext is expected in the request body over HTTPS.
• Requests containing the forbidden third-party vendor substring (case-insensitive) in any string value are rejected with 400 before reaching the DB.
• In-flight voucher reservations or a non-empty DLQ block provider switches with 409 to prevent double-spend.

Permissions: 🟠 locations.update

Calls Trivec /voucher/services via integrations-service using the currently-saved config.

Behaviour:

• Persists last_tested_at and last_test_reachable on integration_configs.
• Non-Trivec providers return 400 INVALID_PROVIDER_FOR_TEST.
• Does not emit platform_events (D-08).

Permissions: 🟠 locations.update

Get comprehensive location information by its URL slug.

Response includes:

• Location details (name, address, coordinates, contact info)
• Current sale status and times
• Opening hours (weekly hours, exceptions, schedule ID)
• Theme and branding configuration
• Feature flags and settings (discounts, scan-to-tab, split items, etc.)
• Loyalty program information
• Extended waiting time (if set)

This is the primary endpoint for storefront applications to fetch location data. The slug is the URL-friendly identifier for the location (e.g., "joes-pizza").

Permissions: 🔵 locations.read

Broadcast when a schedule rule for a location changes — lets storefronts and clients refresh open/closed status.

This is an outbound webhook event. Karma POSTs this payload to the URL you registered via POST /api/v1/webhooks/subscriptions. Your endpoint should respond 2xx within 30 seconds to acknowledge delivery.