X-Company header that scopes every query to the authenticated company. Public endpoints (/2023-11/company, /2023-11/shops, /2023-11/plans) are unauthenticated.
Base URL https://api.genuka.com · Auth Authorization: Bearer <token> + X-Company: <companyId> · Getting Started
Endpoints at a glance
Company
GET /2023-11/admin/company
Returns the full company profile for the authenticated user’s active company.
200 OK):
401— Missing or invalid bearer token.403— User does not have access to this company.
PUT /2023-11/admin/company
Update company profile fields. All fields are optional (partial update).
Request body
200 OK): Returns the raw company model (direct Eloquent serialization — not wrapped in FullCompanyResource):
401— Unauthenticated.422— Validation errors.
GET /2023-11/admin/company/app-shortcuts
Returns the array of app shortcuts stored on the company’s metadata.
200 OK):
401— Unauthenticated.
GET /2023-11/admin/company/document-number
Generate the next sequential document number for a given document type.
Query parameters
200 OK):
401— Unauthenticated.422—typeis missing or not a validDocumentTypeenum value.
POST /2023-11/admin/company/medias
Queue an asynchronous job to import a media file from S3 into the company’s media library.
Request body
202 Accepted):
401— Unauthenticated.422—keyorcollectionNamemissing.500— S3 or queue error.
PATCH /2023-11/admin/company/metadata
Update only the metadata field of the company.
Request body
200 OK): Returns the raw company model (direct Eloquent serialization):
401— Unauthenticated.
GET /2023-11/admin/company/onboarding
Returns the company’s onboarding record.
200 OK):
401— Unauthenticated.
GET /2023-11/admin/company/variables
Returns the template variables stored in the company’s metadata.
200 OK):
401— Unauthenticated.
GET /2023-11/admin/company/wallets
Returns paginated AI token wallet transactions for the company.
Query parameters
200 OK):
401— Unauthenticated.422— User is not linked to a company.
GET /2023-11/admin/company/website
Returns the company’s main domain record.
200 OK):
401— Unauthenticated.
Public Company Endpoints
GET /2023-11/company
Public endpoint. Returns the company identified by the X-Company header (or companyId query param) with storefront data.
Query parameters
200 OK):
404— Company not found (bothcompanyIdanddomainabsent or not matching).
GET /2023-11/company/filters
Public endpoint. Returns the storefront filter configuration for the company.
Query parameters
200 OK):
404— Company not found.500— Unexpected server error.
GET /2023-11/company/from-domain
Public endpoint. Resolves a company by a custom domain name (cached for 4 weeks).
Query parameters
200 OK): Same shape as GET /2023-11/company — the PublicCompanyResource transformation is applied:
404— Domain not registered to any company.
Settings
GET /2023-11/admin/settings
Returns the company’s settings as a flat key-value map. Users with company.* permission receive all settings; users with treasury_accounts.* permission receive only cash_control.* settings.
200 OK):
401— Unauthenticated.403— User lacks bothcompany.*andtreasury_accounts.*permissions.
PUT /2023-11/admin/settings
Update one or more company settings. Requires company.* permission for non–cash-control settings; treasury_accounts.* is sufficient for cash_control.* settings only.
Request body
200 OK): Returns the updated settings map (filtered by the caller’s permission level):
401— Unauthenticated.403— User lacks required permissions, or tried to update non–cash-control keys withoutcompany.*.422—settingsfield missing or not an array.
Variables
GET /2023-11/admin/variables
Alias for GET /2023-11/admin/company/variables. Returns the company template variables.
200 OK):
401— Unauthenticated.
PUT /2023-11/admin/variables
Replace the company’s template variables. Also syncs custom fields from the variable definitions and mirrors revenue settings to the company_settings table.
Request body
200 OK): Returns the updated variables object (the variables key stored in company.metadata):
401— Unauthenticated.
Shops
GET /2023-11/admin/shops
List shops belonging to the authenticated company. Non-admin users only see shops they are assigned to.
Query parameters
200 OK):
401— Unauthenticated.
POST /2023-11/admin/shops
Create a new shop.
Request body
200 OK):
401— Unauthenticated.500— Database transaction failure.
GET /2023-11/admin/shops/{shop}
Get details for a specific shop. The authenticated user must have the shop assigned.
Path parameters
200 OK):
401— Unauthenticated.403— User is not assigned to this shop.404— Shop not found.
PUT /2023-11/admin/shops/{shop}
Update a shop. All fields are optional (partial update). The authenticated user must be assigned to the shop.
Path parameters
Request body
200 OK):
401— Unauthenticated.403— User not assigned to this shop.404— Shop not found.500— Database transaction failure.
DELETE /2023-11/admin/shops/{shop}
Permanently delete a shop (force-delete, no soft-delete).
Path parameters
204 No Content):
401— Unauthenticated.403— User not assigned to this shop.404— Shop not found.500— Database transaction failure.
Public Shop Endpoints
GET /2023-11/shops
Public endpoint. List shops (scoped to the current company via X-Company or companyId).
Query parameters
200 OK):
GET /2023-11/shops/count
Public endpoint. Returns the total number of shops across all companies.
200 OK):
GET /2023-11/shops/handle/{shop}
Public endpoint. Get a shop by its slug. If companyId query param is provided, scopes to that company.
Path parameters
Query parameters
200 OK):
404— Shop not found for this company.
GET /2023-11/shops/{shop}
Public endpoint. Get a shop by its ULID.
Path parameters
200 OK):
404— Shop not found.
Roles
GET /2023-11/admin/roles
List all roles for the current company (excluding the superadmin role). Includes permission count and user count.
Query parameters
200 OK):
401— Unauthenticated.
POST /2023-11/admin/roles
Create a custom role for the company. Non-admin actors cannot assign permissions beyond their own.
Request body
200 OK):
401— Unauthenticated.422— Validation failure (name taken, invalid permissions, reserved name).
GET /2023-11/admin/roles/permissions/catalog
Returns all available permission values grouped by domain.
200 OK):
PUT /2023-11/admin/roles/assign/{user}
Assign a role to a user within the current company. Non-admin actors cannot assign a role that grants permissions they do not themselves hold.
Path parameters
Request body
200 OK):
401— Unauthenticated.403— Actor lacks permission to assign this role (privilege escalation prevention).404— Role or user not found / user does not belong to this company.422—role_idmissing or invalid.
GET /2023-11/admin/roles/{role}
Get a single role with its permissions and user count.
Path parameters
200 OK):
401— Unauthenticated.404— Role not found or belongs to a different company.
PUT /2023-11/admin/roles/{role}
Update a role. System roles (is_system = true) cannot have their name changed.
Path parameters
Request body
200 OK):
401— Unauthenticated.404— Role not found.422— Attempting to rename a system role, or invalid permissions.
DELETE /2023-11/admin/roles/{role}
Delete a custom role. Blocked if is_system = true or if the role is assigned to any users.
Path parameters
200 OK):
401— Unauthenticated.404— Role not found.422— Role is a system role or still assigned to users.
Onboarding
GET /2023-11/admin/onboarding
Returns entity counts for all onboarding tasks (products, customers, orders, users, and many more).
200 OK):
401— Unauthenticated.
POST /2023-11/admin/onboarding/start
Start a new onboarding flow for the company. If one already exists it is returned unchanged.
Request body: None. This endpoint requires no request body.
200 OK):
401— Unauthenticated.
PUT /2023-11/admin/onboarding/{onboarding}
Advance or update onboarding progress. All body fields except step are stored in metadata.
Path parameters
Request body
200 OK): Returns the OnboardingResource — metadata keys are extracted to the top level:
401— Unauthenticated.404— Onboarding record not found.
Subscriptions
GET /2023-11/admin/subscriptions
List legacy subscriptions for the company. Supports filtering and pagination.
Query parameters
200 OK):
401— Unauthenticated.
Genuka Subscriptions
GET /2023-11/admin/genuka/subscriptions
List Genuka platform subscriptions for the company.
Query parameters
200 OK):
401— Unauthenticated.
POST /2023-11/admin/genuka/subscriptions
Create a new Genuka subscription. Handled by NewSubscriptionProcess.
Request body
200 OK): Returns the new GenukaSubscriptionResource:
401— Unauthenticated.422— Invalid plan or payment data.
POST /2023-11/admin/genuka/subscriptions/renew
Renew the active Genuka subscription via mobile money or card. Only company admins may call this.
Request body
200 OK):
401— Unauthenticated.403— User is not a company admin.422— No associated company, or payment/Stripe error.
GET /2023-11/admin/genuka/subscriptions/renewal-reminder
Returns whether the company’s subscription needs renewal and the reminder level to display.
200 OK):
GET /2023-11/admin/genuka/subscriptions/{subscription}
Get a single Genuka subscription record.
Path parameters
200 OK): Returns a GenukaSubscriptionResource. Note: the controller show method body is currently a stub and returns an empty response — the shape below reflects what would be returned once implemented.
401— Unauthenticated.404— Subscription not found.
PUT /2023-11/admin/genuka/subscriptions/{subscription}
Update a Genuka subscription record.
Path parameters
Request body
200 OK): Note — the controller update method body is currently a stub and returns an empty response. The shape below reflects the expected output once implemented.
401— Unauthenticated.404— Subscription not found.
DELETE /2023-11/admin/genuka/subscriptions/{subscription}
Delete a Genuka subscription record.
Path parameters
200 OK): Note — the controller destroy method body is currently a stub and returns an empty response. The expected response once implemented:
401— Unauthenticated.404— Subscription not found.
Plans (Public)
GET /2023-11/plans
Public endpoint. Returns all available Genuka plans.
200 OK):
GET /2023-11/plans/{plan}
Public endpoint. Get a specific plan by its lookup_key.
Path parameters
200 OK):
404— Plan not found.
Search
GET /2023-11/admin/search
Generate a scoped Meilisearch tenant token valid for 12 hours. The token is automatically filtered to the authenticated company (and optionally a specific shop via X-Shop header).
Headers
200 OK):
400—X-Companyheader missing.401— Unauthenticated.500— Meilisearch configuration incomplete or token generation error.
POST /2023-11/admin/search
Server-side multi-index full-text search across all company data in Meilisearch. Returns up to limit hits per index.
Request body
Default indexes searched:
products, orders, customers, suppliers, supplierproducts, deliveries, pages, pickup_locations, payments, bill_of_materials, articles, document_number_formats, templates, campaigns, stock_movements, taxes, webhooks, calendar_events, addresses.
200 OK):
400—companyIdmissing (derived fromX-Companyheader).401— Unauthenticated.
Enums
GET /2023-11/enums/notification-events
Public endpoint. Returns all notification event enum values with their labels and descriptions.
200 OK):
Mobile Sync
GET /2023-11/admin/sync/pull
Pull entity changes from the server since the given cursor timestamp. Designed for offline-first mobile apps.
Query parameters
200 OK):
401— Unauthenticated.422— Validation failure on query params.
POST /2023-11/admin/sync/push
Push local operations (creates, updates, deletes) from mobile to the server. Up to 50 operations per request.
Request body
200 OK):
401— Unauthenticated.422— Validation failure (missing fields, invalid entity type or operation).500— Server-side processing error.
Users
GET /2023-11/admin/users
List users belonging to the current company.
Query parameters
200 OK):
401— Unauthenticated.
POST /2023-11/admin/users
Create a new user and attach them to the company, or invite an existing user to join. If the email already exists in the system, an invitation is sent and code: "INVITATION_SENT" is returned.
Request body
201 Created for new user / 200 OK for invitation):
400— Business rule violation (e.g. user already in company).401— Unauthenticated.422— Validation failure.
GET /2023-11/admin/users/invitations/pending
List all pending invitations for the current company.
200 OK):
401— Unauthenticated.
DELETE /2023-11/admin/users/invitations/{user}
Cancel a pending invitation for a user.
Path parameters
200 OK):
401— Unauthenticated.404— No pending invitation found for this user in this company.
POST /2023-11/admin/users/invitations/{user}/resend
Resend an invitation email to the specified user. Generates a new invitation token and resets the expiry clock (7-day window).
Path parameters
Request body: None. The user to reinvite is identified solely by the
{user} path parameter.
200 OK):
401— Unauthenticated.404— No pending invitation found for this user.
PUT /2023-11/admin/users/metadata
Update arbitrary metadata key-value pairs for the authenticated user. Any key from the request body (except metadata and anonymous) is merged into the user’s metadata object.
Request body
200 OK): Returns the updated UserResource:
401— Unauthenticated.
GET /2023-11/admin/users/stats
Returns aggregated dashboard statistics for the authenticated user over a date range. Each metric includes daily values for the period, a total, a comparison against the previous equal-length period, and a percentage change.
Query parameters
200 OK): Returns an array of three metric objects — Total sales, Orders, and Services performed:
401— Unauthenticated.
GET /2023-11/admin/users/{user}
Get a single user’s details. A user may always fetch their own record. Admins may fetch any user in the same company.
Path parameters
Query parameters
200 OK): Returns a UserResource (same shape as list item):
401— Unauthenticated.403— Non-admin trying to view another user, or target is in a different company.404— User not found.
PUT /2023-11/admin/users/{user}
Update a user’s profile, role, permissions, and shop assignments.
Path parameters
Request body
200 OK): Returns the updated UserResource:
400/403— Business rule violation (not in the same company, etc.).401— Unauthenticated.422— Validation failure.
DELETE /2023-11/admin/users/{user}
Delete or detach a user. Requires admin role. If the user belongs to multiple companies, they are only detached from the current company. If they belong to only one company, the user record is soft-deleted. The last admin in a company cannot be removed.
Path parameters
200 OK):
401— Unauthenticated.403— Caller is not an admin.500— Cannot remove last admin, or database transaction failure.