Key concepts
These are the words and ideas you’ll see again and again across Hilal Software. Once you know them, the rest of the app is easy to navigate.
Organization
An organization is the top-level container that owns everything you see in Hilal — your Amazon connections, your inventory, your campaigns, your team, your subscription. Most users have one organization. Agencies and operators with multiple brands have several and switch between them with the org switcher in the sidebar.
When you sign up, an organization is created for you automatically. You can rename it, add a logo, and set the billing address from Settings → Organization.
Member
A member is a person you’ve invited into your organization. Each member has an email address, a name, and a role.
Role
A role determines what a member can do. Hilal uses three roles:
- Owner — the person who created (or now owns) the organization. Can do anything, including delete the organization or transfer ownership. There must always be exactly one Owner.
- Admin — can do everything except destroy the organization. Manages members, billing, integrations, and all data.
- Member — can do everything an Admin can do minus the org-administration items: no member invites, no billing changes, no integration changes.
Beyond roles, individual permissions can be toggled per member for very specific cases (e.g., “this VA shouldn’t see the Finances section”). See Team & permissions.
Permissions: server-side and client-side
Hilal uses a two-layer permission model:
- Server-side is the source of truth. Every API call and Server Action checks the caller’s role and permissions before doing anything. You can’t bypass it from the browser.
- Client-side is for UI gating. The browser fetches a flat list of the current user’s permissions and uses it to hide or show menu items, buttons, and pages. It’s a usability layer — never the security boundary.
What this means for you: if a member doesn’t have permission to do something, the button disappears. If they somehow trigger the API anyway, the server still rejects it.
Marketplace
A marketplace is one of Amazon’s 15+ regional storefronts (US, CA, MX, BR, UK, DE, FR, IT, ES, NL, JP, AU, SG, etc.). You select which marketplaces your organization sells in from Settings → Marketplaces, and the entire app — dashboard, inventory, ads, finances — scopes its data to those marketplaces.
Marketplaces are grouped into three regions:
- North America (NA) — US, CA, MX, BR
- Europe (EU) — UK, DE, FR, IT, ES, NL, etc.
- Far East (FE) — JP, AU, SG, etc.
Region grouping matters for the Ads API: each region is a separate Ads connection.
Amazon Seller Partner API connection (SP-API)
The SP-API connection is the OAuth grant that lets Hilal read your Seller account — orders, inventory, fees, returns, and reports. One connection covers your entire seller account across regions.
If the connection expires or is revoked, every section that depends on Seller data shows a “reconnect Amazon” banner. See Connection status & troubleshooting.
Amazon Advertising API connection (Ads API)
The Ads API connection is the OAuth grant that lets Hilal read and write your Amazon Ads campaigns. Unlike SP-API, Ads is per-region: a North American ads connection and a European ads connection are independent. You can have any combination — only NA, only EU, NA + EU, all three, or none.
Subscription
Your subscription is the Hilal plan you’re paying for: Free, Basic, Premium, or Enterprise. Each plan unlocks a different feature set, marketplace count, member count, and AI usage allowance.
On top of the base plan you can buy add-ons — for example, additional AI usage, extra members, or a higher campaign limit. Add-ons stack on top of your base plan and renew on the same cycle.
See Plans, usage & pricing for the breakdown.
Feature gating
Most features in Hilal are gated by subscription tier. The middleware checks your tier on every request and either lets the page render, redirects to an upgrade prompt, or returns a 403 from the API. The dashboard surfaces an “upgrade required” banner whenever you click into a feature your plan doesn’t include.
Worktree-style isolation (under the hood)
You won’t see this in the UI, but it’s worth knowing: long-running operations (large data syncs, AI workflows) run in isolated worktrees so they can’t conflict with your day-to-day work. Most users never need to think about it.