` — the signed-in member's access token. |
| `companyid` | Yes | Mongo ObjectId of the company the order belongs to. |
| `clientid` | Optional | Real-time client socket ID. When supplied, notifications include it. |
## Query parameters
The Order / Project ID to update. Pass this as a query string parameter.
## Request body fields
Updates the order title. Minimum 2 characters.
New status for the order. Must be one of: `Pending`, `Ongoing`, `Review`, `Completed`, `Cancelled`.
**Allowed transitions:**
* `Review` can only follow `Ongoing` or another `Review`. Jumping from `Pending` directly to `Review` returns a `400 ValidationError`.
* Orders already `Completed` or `Cancelled` cannot be updated.
* Clients cannot cancel an order that has moved past `Pending`.
Total budget figure. Must be `≥ 0`. Uses the order's existing currency unless `currency` is also provided.
Currency code for the budget. Examples: `USD`, `CAD`, `EUR`.
Number of units purchased for the package. Must be `≥ 1`.
ISO 8601 date string for the order's due date. Example: `"2025-12-31T00:00:00.000Z"`.
ISO 8601 date string for the project start date.
Internal notes visible to your team.
Client brief or project summary.
Complete list of project manager member IDs to assign to this order. New IDs are added to the team; removed IDs are deleted. Each ID must belong to a member with a `projectManager` role inside the same company.
**Required** when `status` is `Completed` or `Cancelled`. When `true`, all tasks in the order are marked done after the status change. When `false`, tasks remain in their current state.
Allowed only when `status` is `Completed` or `Cancelled`. When `true`, all outstanding client-requested tasks are rejected after the status update.
Required only for **subscription** orders when changing recurrence frequency. Pair with `repeatDuration`.
Required alongside `repeatCount` for subscription orders. One of: `day`, `week`, `month`, `year`.
Optional limit on recurring billing cycles. Defaults to `0` (no limit).
How each billing cycle is handled. One of: `createOrderWithTask`, `noChange`.
Zero or more file attachments. Files are appended to the order's system folder; existing files are never overwritten. Use `multipart/form-data` encoding and attach each file under the `files` field.
***
## Example request
```bash cURL (no files) theme={null}
curl --request PUT "https://api.agencyhandy.com/orders?pid=ORDER_ID_HERE" \
--header "Authorization: Bearer " \
--header "companyid: " \
--form "name=Website Redesign" \
--form "status=Review" \
--form "budget=12000" \
--form "currency=USD" \
--form "quantity=1" \
--form "assignedProjectManagers[]=PROJECT_MANAGER_ID" \
--form "notes=Scope finalized with client." \
--form "brief=Launch-ready design refresh."
```
```bash cURL (with file) theme={null}
curl --request PUT "https://api.agencyhandy.com/orders?pid=ORDER_ID_HERE" \
--header "Authorization: Bearer " \
--header "companyid: " \
--form "name=Website Redesign" \
--form "status=Review" \
--form "budget=12000" \
--form "repeatCount=3" \
--form "repeatDuration=month" \
--form "billingCycleEvent=createOrderWithTask" \
--form "files=@/path/to/creative-brief.pdf"
```
**Equivalent JSON payload** (convert to multipart form entries when sending files):
```json theme={null}
{
"name": "Website Redesign",
"status": "Review",
"budget": 12000,
"currency": "USD",
"quantity": 1,
"assignedProjectManagers": ["{{PROJECT_MANAGER_ID}}"],
"repeatCount": 3,
"repeatDuration": "month",
"billingCycleEvent": "createOrderWithTask",
"notes": "Scope finalized with client.",
"brief": "Launch-ready design refresh."
}
```
***
## Responses
| HTTP Status | Description |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `200 OK` | Update succeeded. |
| `400 ValidationError` | Invalid order ID, blocked status transition, or malformed payload. Response includes `fieldName` when relevant. |
| `403 PermissionError` | Caller is not an approved member, lacks the company role, the workspace subscription has expired, or a client attempted a forbidden cancel. |
| `500 Internal Server Error` | Unhandled exception — check server logs. |
### Success response
```json theme={null}
{
"message": "Project has been updated"
}
```
***
## Business rules and side effects
* **Status transitions** are restricted. `Review` can only follow `Ongoing` or another `Review`. Attempting `Pending → Review` returns `400 ValidationError`.
* Moving a status from `Pending` to `Ongoing`, `Review`, or `Completed` activates the order's file folder so uploaded files become accessible to the project team.
* Setting `status` to `Completed` or `Cancelled` **requires** `markTasksAsDone` to be explicitly set to `true` or `false`.
* Status changes to `Review`, `Completed`, or `Cancelled` automatically trigger client notifications:
* **Review** — notifies the client that review is needed.
* **Completed** — sends the `orderCompletion` notification to the client.
* **Cancelled** — sends the `orderCancellation` notification to the client.
* Every successful update fires an `ORDER.UPDATED` webhook event with the updated order document and attachment metadata, if you have an active webhook subscribed to that event.
# Accessing Your Portal
Source: https://docs.agencyhandy.com/client/accessing-portal
Set your password, log in to your AgencyHandy client portal, and reset your credentials if you ever get locked out.
You access your client portal through a web address provided by your agency. Because agencies can use their own custom domain and branding, your login page may look unique to your agency — but the steps below are the same everywhere.
## First-Time Login
When your agency adds you as a client, you'll receive an invitation by email.
Look for an email from your agency inviting you to your client portal. Click the **Accept Invitation** (or **Set Password**) button.
Choose a secure password and confirm it. This becomes your login credential going forward.
You'll be taken to your portal dashboard. Bookmark the login page so you can find it again easily.
Didn't get an invitation? Check your spam folder, then ask your agency contact to re-send it.
## Logging In Again
Return to the same portal web address your agency gave you, enter your email and password, and select **Log In**. If your agency has enabled Google sign-in, you can also continue with your Google account.
## Resetting Your Password
On the login screen, click the **Forgot password?** link.
Type the email address associated with your account and submit. You'll receive a reset link.
Open the email, click the link, and set a new password. You can now log in with it.
## Finding Your Way Around
Once logged in, your portal dashboard gives you quick access to everything on your account:
Your active and completed orders and their tasks.
Outstanding and paid invoices.
Proposals awaiting your review.
Open and past support tickets.
# Browsing & Ordering Services
Source: https://docs.agencyhandy.com/client/browse-and-order
Explore the services your agency offers, choose a package, apply coupons, and place an order from your client portal.
Your agency publishes its services in a catalog you can browse from your portal. You can compare packages, pick the one that fits, and order it yourself — no back-and-forth required.
## Browsing the Catalog
From your portal, open the **Services** (or **Catalog**) page to see everything your agency offers. Each service shows what's included, available packages, and pricing.
Some agencies organize services into groups (for example, *Design*, *Marketing*, *Development*). Use the group tabs or search to find what you need faster.
## Placing an Order
Click a service to see its full description, package options, and any add-ons.
If the service offers multiple packages (for example, *Basic*, *Standard*, *Premium*), select the one that fits your needs. Review what each tier includes.
Select optional add-ons if you'd like to expand the scope of your order.
If your agency gave you a coupon code, enter it at checkout to apply the discount.
Check the order summary and total, then place your order. Depending on your agency's setup, you may be asked to pay now or receive an invoice afterward.
Some services include a **setup fee** or a **trial period**, and some are billed as recurring subscriptions. These details are shown on the service page before you order.
## Completing an Order Form
Many services ask you to provide details before work begins — like brand assets, login access, or project requirements. If your order includes an order form, you'll be prompted to complete it at checkout or right after.
See [Files & Forms](/client/files-and-forms) for more on submitting information and uploading files.
## What Happens Next
Once your order is placed:
Your agency receives the order and begins setting up the work.
You can track each task as your agency works through your order.
# Credits
Source: https://docs.agencyhandy.com/client/credits
Purchase services and pay invoices using a prepaid credit balance: buy credits, track your balance, and manage credit requests.
Credits allow you to purchase services and pay invoices using a prepaid balance instead of making individual payments every time. You can purchase credits, track your available balance, view your transaction history, and use credits across the platform whenever credit payments are enabled by the agency.
## How credits work
Credits are purchased in advance and added to your account balance.
When you purchase a service or pay an invoice using credits:
* The required credits are deducted automatically.
* Your balance is updated instantly.
* The transaction is recorded in your credit history.
If the agency has disabled credit payments, credit-related features will not be available.
## Viewing your credit balance
When credit payments are enabled by the agency, your available credit balance is displayed in the top navigation bar.
![Credit balance widget in the client portal header]()
*Credit balance widget displayed in the client portal header*
### Accessing the Credits page
Click the credit balance widget to open the Credits page.
The Credits page provides:
* Available credit balance
* Transaction history
* Running balance
* Credit requests
* Buy Credits option
![Credits dashboard page]()
*Credits dashboard page*
## Purchasing credits
You can purchase additional credits at any time using the **Buy Credits** button.
Click the credit balance widget in the top navigation bar.
Select the **Buy Credits** button.
Choose a credit package from the available options.
Select your preferred payment method.
Follow the payment process to finalize your purchase.
![Buy Credits page showing available credit packages]()
*Buy Credits page showing available credit packages*
## Credit purchase methods
Different payment methods process credits differently.
### Instant credit purchases
Credits are added automatically after successful payment when using:
* Stripe
* PayPal
Once payment is confirmed, credits are added immediately, your balance is updated, and a transaction is recorded in your credit history.
### Manual credit purchases
Credits purchased using Bank Transfer or Cryptocurrency require agency approval before being added to your account.
After submitting payment:
1. A credit request is created.
2. The request is sent to the agency for review.
3. Credits are added only after the agency approves.
## Credit requests
Credit Requests allow you to track purchases that require agency approval.
Click the credit balance widget in the top navigation bar.
Click **Credit Requests** to see the status of your pending and past requests.
![Credit Requests page]()
*Credit Requests page*
**Request statuses:**
* **Pending**: your request has been submitted and is waiting for agency review.
* **Accepted**: the request has been approved and credits have been added to your balance.
* **Rejected**: the request has been declined and no credits have been added.
## Paying for services with credits
When credit payments are enabled and you have sufficient credits, you can purchase services using your credit balance.
Navigate to the service you want to purchase.
Start the checkout process for the service.
Choose the **Buy with Credit** option.
Confirm to finalize the purchase.
![Service checkout showing the Buy with Credit option]()
*Service checkout page showing the Buy with Credit option*
Once the purchase is completed, credits are deducted automatically, your balance is updated instantly, and the transaction appears in your credit history.
**When Buy with Credit is not available:**
The **Buy with Credit** option will not appear if:
* The agency has disabled credit payments.
* You do not have enough credits.
* The service is not eligible for credit payments.
## Paying invoices with credits
You can also use credits to pay outstanding invoices.
Navigate to the invoice you want to pay.
Select the **Pay Invoice** button.
Choose the **Pay with Credit** option.
Confirm to complete the payment.
![Invoice payment page showing the Pay with Credit option]()
*Invoice payment page showing the Pay with Credit option*
Once payment is completed, credits are deducted automatically, the invoice is marked as paid, your balance is updated, and the transaction appears in your credit history.
**When Pay with Credit is not available:**
The **Pay with Credit** option will not appear if:
* The agency has disabled credit payments.
* You do not have sufficient credits.
* The invoice amount exceeds your available balance.
## Understanding your credit history
All credit activity is recorded on your Credits page.
Each transaction includes:
* Date
* Transaction type
* Reference
* Credit amount
* Running balance
![Credit transaction history table]()
*Credit transaction history table*
**Transaction types:**
* **In**: credits added to your account (credit package purchases, approved credit requests).
* **Out**: credits deducted from your account (service purchases, invoice payments).
## Frequently Asked Questions
The agency has disabled credit payments for the workspace.
Credit payments may be disabled by the agency.
The agency may have disabled credit payments, you may not have enough credits, or the service may not support credit payments.
The agency may have disabled credit payments or your available credit balance may be insufficient.
Credits purchased through Stripe and PayPal are added immediately after successful payment. Credits purchased through Bank Transfer or Cryptocurrency are added after agency approval.
Yes. All credit purchases and deductions are available from the Credits page.
**In** indicates credits added to your account.
**Out** indicates credits deducted from your account.
No credits are added to your balance. You may contact the agency for more information regarding the request.
Yes. Credits can be used to purchase services and pay invoices whenever credit payments are enabled and sufficient credits are available.
# Files & Forms
Source: https://docs.agencyhandy.com/client/files-and-forms
Upload assets, complete intake and order forms, and download deliverables your agency shares through your client portal.
Sharing information and files with your agency happens directly in your portal — so everything stays organized and attached to the right order.
## Completing Forms
Your agency may ask you to fill out forms to collect the details they need to do their best work.
* **Order forms** appear when you place an order, gathering the specifics for that particular service.
* **Intake forms** collect general information about you or your business, often when you first start working together.
You'll be prompted to complete a form at checkout, or you'll receive a link to one from your agency.
Answer the questions and attach any files the form requests.
Send the form to your agency. They're notified and can start work with everything they need.
## Uploading Files
You can attach files wherever your agency needs them — most commonly inside a task or order.
Go to the [order or task](/client/orders-and-tasks) the file belongs to.
Use the **Upload** or attachment button, then select the file from your device.
Once attached, your agency can see and download it right away.
Keeping files attached to the relevant task means nothing gets lost in email and your agency always has the latest version.
## Downloading Deliverables
When your agency delivers completed work, you'll find it attached to the relevant task. Open the task, then preview or download the file. See [Tracking Orders & Tasks](/client/orders-and-tasks) for how to review and approve deliverables.
# Welcome to Your Client Portal
Source: https://docs.agencyhandy.com/client/introduction
Your AgencyHandy client portal is the single place to track your projects, approve proposals, pay invoices, share files, and get support from your agency.
Your agency uses **AgencyHandy** to manage the work it delivers for you. Through your own client portal, you get a transparent, real-time view of everything happening on your account — no more chasing email threads for status updates.
This guide walks you through everything you can do as a client.
## What You Can Do in the Portal
Explore the services your agency offers and place an order in a few clicks.
Follow the progress of your active orders and review tasks as they're delivered.
Read, accept, or reject proposals your agency sends you.
View your invoices and pay securely online.
Upload assets, complete intake forms, and download deliverables.
Raise a support ticket and message your agency directly.
## Getting Started
The first thing to do is access your portal. Your agency will send you an invitation email with a link to set your password and log in.
Learn how to log in and find your way around.
Your portal is hosted by your agency and may use their own branding and custom domain — so the colors, logo, and web address you see can differ from these screenshots.
# Invoices & Payments
Source: https://docs.agencyhandy.com/client/invoices-payments
View your invoices, pay securely online, manage subscriptions, and download receipts from your AgencyHandy client portal.
All billing happens in one place. From your portal you can see what you owe, pay invoices online, and keep copies for your records.
## Viewing Your Invoices
Open the **Invoices** page to see every invoice on your account and its status:
| Status | What it means |
| ----------- | -------------------------------------------------- |
| **Unpaid** | Payment is due. |
| **Paid** | Payment received — no action needed. |
| **Overdue** | Past its due date; please pay as soon as possible. |
Click any invoice to see a full breakdown of line items, taxes, discounts, and the total due.
## Paying an Invoice
Select the unpaid invoice you want to pay.
Click the **Pay Now** button to open the secure checkout.
Pay with the methods your agency has enabled — typically card (via Stripe), PayPal, or bank transfer.
Once payment succeeds, the invoice is marked **Paid** automatically and you'll get a confirmation.
The available payment methods depend on which gateways your agency has connected. If you don't see your preferred option, ask your agency.
## Subscriptions & Recurring Invoices
If you're on a recurring service, you'll receive invoices on a regular schedule (for example, monthly). Recurring invoices work the same way — open and pay each one as it arrives. Your agency can tell you the billing cycle for your subscription.
## Downloading & Printing
Need a copy for your records or accounting? Open any invoice and use the **Download** or **Print** option to save a PDF.
## Questions About a Charge?
If something on an invoice doesn't look right, open a support ticket and your agency will help sort it out.
# Tracking Orders & Tasks
Source: https://docs.agencyhandy.com/client/orders-and-tasks
Follow your active orders, review tasks as they're delivered, leave feedback on files, and request new work — all from your client portal.
Every order you place is broken down into **tasks** so you can see exactly what your agency is working on and how far along it is. This page explains how to stay on top of your projects.
## Viewing Your Orders
Open the **Orders** page in your portal to see all your orders. Each order shows its status, the service it's for, and the tasks within it.
| Status | What it means |
| ------------- | ----------------------------------------------------- |
| **Active** | Work is in progress. |
| **In Review** | Deliverables are ready for your feedback or approval. |
| **Completed** | The order is finished. |
| **Cancelled** | The order was cancelled. |
## Following Task Progress
Click into an order to see its tasks. Each task has a status that updates as your agency moves it through their workflow (for example, *To Do → In Progress → In Review → Done*).
Open any task to see its description, attached files, due date, and the full activity history.
## Reviewing Deliverables & Leaving Feedback
When your agency delivers a file for your review, you can respond right inside the task:
Click the task that contains the deliverable.
Preview or download the attached file to review the work.
Add a comment with your feedback, or approve the deliverable if you're happy with it. Your agency is notified right away.
## Requesting New Tasks
Depending on how your agency has set up your account, you may be able to request additional tasks within an order. Look for a **Request Task** (or **Add Task**) button on the order page, describe what you need, and submit it for your agency to review.
Whether you can create or request tasks depends on the permissions your agency has enabled for your portal.
## Next Steps
Upload assets your agency needs to complete your tasks.
Raise a support ticket if something doesn't look right.
# Reviewing Proposals
Source: https://docs.agencyhandy.com/client/proposals
Read proposals your agency sends, compare packages, and accept or reject them directly from your client portal.
Before starting a new engagement, your agency may send you a **proposal** outlining the scope, deliverables, and pricing. You can review and respond to it entirely within your portal.
## Finding Your Proposals
You'll usually receive an email when a new proposal is ready. You can also find all proposals on the **Proposals** page in your portal, each showing its status:
| Status | What it means |
| ------------ | ------------------------ |
| **Pending** | Waiting for your review. |
| **Accepted** | You've approved it. |
| **Rejected** | You've declined it. |
## Reviewing a Proposal
Click the proposal to read the full details — scope of work, deliverables, timelines, and pricing.
If the proposal includes more than one package option, review each one so you can choose the option that fits your needs and budget.
Not sure about something? Reach out to your agency contact or [open a support ticket](/client/support-tickets) before deciding.
## Accepting or Rejecting
Use the **Accept** or **Reject** button on the proposal.
When accepting a proposal with multiple packages, choose the package you want before confirming.
Your agency is notified instantly of your decision.
Accepting a proposal often kicks off the next step automatically — such as creating an order or generating an invoice. Your agency will let you know what to expect.
## After You Accept
Once an order is created, follow its progress here.
If an invoice is generated, you can pay it online.
# Getting Support
Source: https://docs.agencyhandy.com/client/support-tickets
Raise a support ticket, track its status, and message your agency directly from your client portal.
If you have a question, a problem, or a request that isn't tied to a specific task, the fastest way to reach your agency is by opening a **support ticket**. Every ticket is tracked in your portal so nothing slips through the cracks.
## Opening a Ticket
Open the **Support** or **Tickets** page in your portal.
Click **New Ticket** (or **Create Ticket**).
Give your ticket a clear subject and explain what you need. Attach screenshots or files if they help.
Send the ticket. Your agency is notified and will respond through the portal.
## Tracking Your Tickets
All your tickets appear on the Support page with their current status:
| Status | What it means |
| --------------- | ---------------------------------- |
| **Open** | Submitted and awaiting a response. |
| **In Progress** | Your agency is working on it. |
| **Resolved** | The issue has been addressed. |
Click any ticket to read the full conversation and add a reply.
## Replying to Your Agency
When your agency responds, you'll be notified. Open the ticket, read their reply, and add your own message to keep the conversation going — all in one thread.
For feedback on a specific deliverable, comment directly on the task instead — see [Tracking Orders & Tasks](/client/orders-and-tasks). Use tickets for everything else.
# Client Custom Fields: Track Extra Client Details
Source: https://docs.agencyhandy.com/crm/client-custom-fields
Create and manage custom fields for clients in Workspace Config so your team can capture contract terms, industry tags, preferred contact methods, and other client data beyond the default profile.
Client custom fields let you store extra information on each client profile — beyond name, email, company, and address. Define the fields once in **Workspace Config**, then fill them in on client profiles and keep them visible for the whole team.
Only **SuperAdmin** and **Admin** roles can create, edit, or delete custom field definitions. Team members with client access can fill in values on client profiles.
## Before you start
* Access to **Workspace Config** → **Custom Fields**
* A plan that includes CRM custom fields for your workspace
## How client custom fields work
1. An admin creates a **definition** (name + type) with **Belongs to = Client**.
2. That definition appears on every client profile in the workspace.
3. Your team (or Claude/Cursor via MCP) fills a **value** on each client.
4. Client and lead fields are separate catalogs. Reusing the name `Industry` on clients is fine even if leads already have `Industry` — they are two definitions with different ids.
## Create a client custom field
Go to **Workspace Config** → **Custom Fields**.
Click **Create Custom Field**.
In **Belongs to**, select **Client**. The field will appear only on client profiles (not on leads or tasks).
Enter a clear **name** (for example, `Contract renewal date` or `Preferred channel`). Choose a **type**:
| Type | Use for |
| ---------------------------- | -------------------------------- |
| **Text** | Free-form notes or short answers |
| **Number** | Seats, retainers, numeric scores |
| **Boolean** | Yes/no flags (for example, VIP) |
| **Dropdown (Single Select)** | One choice from a list |
| **Dropdown (Multi Select)** | Multiple choices from a list |
| **Attachment** | Contracts, NDAs, or other files |
For dropdown types, add the allowed **options**. Toggle **Required** if the field must be filled when creating or editing a client.
Click **Create**. The field appears in the Custom Fields list with belongs-to **Client**.
Mirror important lead fields on the client side when you regularly convert prospects. That makes conversion mapping smoother.
## Duplicate field names
AgencyHandy blocks a second **client** field with the same name (case and spacing ignored). Examples:
| You try to create | Existing client field | Result |
| ------------------- | --------------------- | --------------------------------------------------- |
| `VIP` | `VIP` | Not created — **Field already exists** |
| `vip` | `VIP` | Not created (same name after normalize) |
| `Preferred channel` | `preferred channel` | Not created |
| `VIP` | Lead field `VIP` only | **Allowed** — lead and client catalogs are separate |
If create is blocked for a duplicate, reuse the existing client field id from the list instead of creating another.
## Fill in values on a client
Go to **CRM** → **Clients** and open a client profile.
In the client profile, open the section that shows **Custom Fields** (often under primary information or a dedicated block).
Complete the fields your workspace defined, then save. Values stay on the profile for orders, billing, and team handoffs.
## Use with Claude or Cursor (MCP)
With [AgencyHandy MCP](/integrations/claude-cursor-mcp) (`agencyhandy-mcp@1.5+`):
1. List client definitions: `ah_custom_field_list` with type `client`.
2. Fill by **definition id** (`ah_custom_field_set_values` or `customFields` on `ah_client_create`).
3. To update an already-filled value, load the client with `ah_member_custom_fields` and prefer the existing value row id when present.
Example prompts:
* “List our client custom fields.”
* “Create client Ada Lovelace and set VIP to true.”
* “On client [ada@acme.com](mailto:ada@acme.com), set Preferred channel to Slack.”
## Carry fields over from a lead
When converting a lead to a client, you may be asked which **lead** custom fields to add or map onto the **client**.
1. Create matching **Client** custom fields first if they do not exist yet.
2. During conversion, select which lead fields to carry over.
3. Confirm values on the new client profile after conversion.
See [Lead Custom Fields](/crm/lead-custom-fields) for defining lead-side fields.
## Manage existing client fields
From **Workspace Config** → **Custom Fields**:
* **Search** or filter by name and belongs-to (**Client**)
* **Edit** the field name, options, or required setting
* **Delete** fields you no longer need (existing values on clients may be cleared — confirm before deleting)
## Import and lists
Client list views and CSV import focus on standard profile columns. Custom field definitions still live in **Workspace Config**; fill custom values on each profile (or after import) so data stays consistent.
## Related
* [Clients](/crm/clients) — create, import, export, and portal access
* [Lead Custom Fields](/crm/lead-custom-fields) — fields on prospects before conversion
* [Leads](/crm/leads) — pipeline and convert to client
* [Claude & Cursor MCP](/integrations/claude-cursor-mcp) — fill fields from AI tools
# Client Management: Profiles, Import, and Configuration
Source: https://docs.agencyhandy.com/crm/clients
Create and import client profiles in AgencyHandy, track orders and invoices, manage portal access, and organize clients with categories.
The Clients section of AgencyHandy's CRM is your centralized hub for every organization or individual that has moved past the prospect stage. Here you can create client profiles manually or in bulk, keep contact details current, track recent orders and invoices, segment clients into custom categories, and monitor portal access — all from one list view.
You need a **Super Admin** or **Admin** role to create, edit, import, or configure client profiles. Managers can view client details and activity logs.
## Creating a Client Profile
When you onboard a new client, AgencyHandy creates a portal account for them and sends a secure login invitation.
Log in to your AgencyHandy account, then click **CRM** in the left sidebar and select the **Clients** tab.
Click **+ Create Client** in the top-right corner. A form opens.
Fill in the client's details:
* **First Name / Last Name** *(mandatory)*
* **Email** *(mandatory — used to send the portal invitation)*
* **Company Name**
* **Phone Number**
* **Country, State, City, Zip Code**
* **Category** — assign an existing configuration category if applicable
Click **Create**. The profile is added to your client list immediately.
After you create the profile, the client receives an email containing a secure login URL. Clicking that URL activates their portal account and lets them log in for the first time.
## Importing Clients from CSV
If you're migrating from another platform or have a spreadsheet of existing clients, you can import them all at once.
From the Clients list, click the **Import** button at the top right.
Drag and drop your file onto the upload area, or click to browse and select it. AgencyHandy accepts CSV files containing the following fields:
* Client Name *(required)*
* Email *(required)*
* Company Name
* Country
* State
* City
* Zip Code
AgencyHandy automatically detects column names that match its field names. For any unmatched columns, use the dropdown menus to manually map them to the correct system fields.
Review the preview table to catch any formatting issues before the data is saved.
Click **Save**. A confirmation message appears once all records are imported successfully.
If your spreadsheet column headers match AgencyHandy's field names exactly (e.g., "email", "company name"), the mapper fills in automatically — no manual matching required.
## Exporting Clients
Back up your client database or share it with stakeholders by exporting to CSV or Excel.
From the Clients list, click the **Export** button at the top right.
Choose which columns to include — select **All Columns** for a complete export, or pick specific fields such as name, contact details, company, or address.
Select **CSV** or **XLSX** depending on your intended use.
Click **Export**. The file generates and downloads to your device. Store it securely to protect client data.
## Editing a Client Profile
In the Clients list, click the checkbox next to the client you want to update, or click directly on their name to open their profile.
Click the **Edit** button in the top-right corner of the client profile. An edit form appears.
Modify any fields — name, email, phone, address, company, or category.
Click **Update**. A confirmation message confirms the profile has been saved successfully.
## Searching, Sorting, and Filtering
The Clients list gives you several tools to find the right client quickly:
Type a client's name in the search bar to instantly filter the list.
Narrow the list to clients associated with a specific company.
Locate a client when you know their email address but not their name.
Show only active, inactive, or invited clients.
Sort the full client list A–Z or Z–A by name for quick reference.
Show only clients assigned to a specific configuration category.
## Tracking Client Activity
Inside each client profile you'll find tabs that give you a live picture of that client's engagement with your agency:
View a history of all orders placed by the client, including service name, package, status, and date. This gives you a quick snapshot of their purchasing history without leaving the CRM.
See all support or service tickets submitted by the client. Use this view to prioritize responses and ensure no request falls through the cracks.
Access a log of all invoices generated for the client, including payment status. This helps you monitor outstanding balances and invoice history in one place.
## Client Configuration (Categories)
Client Configuration lets you create color-coded categories to segment your client list — for example, *High Priority*, *Retainer*, or *On Hold*. Categories appear as filter options on the client list so you can instantly surface the right group.
From the Clients section, click the **Configuration** button.
Click **+ Create Category**.
* **Category Name** — a unique, descriptive label (e.g., *Enterprise Clients*)
* **Short Description** — a brief note explaining the category's purpose
* **Color** — choose a distinct color for quick visual recognition
Click **Create**. The category is now available to assign when editing client profiles.
Open any client profile, click **Edit**, select the **Category** field, and choose the relevant category. Click **Update** to save.
Use consistent color conventions across categories — for example, red for high-urgency clients and green for fully onboarded accounts — to make the list scannable at a glance.
## Client Activity Log
The Activity Log records every login and logout event for a client's portal account, giving you a clear audit trail of their engagement.
**To view the log:**
1. Go to **Clients** and open a specific client's profile.
2. Click the **Activity Log** tab in the top navigation bar of the profile.
3. Review the chronological list of authentication events.
**What the log shows:**
* Exact date and timestamp of each **login**
* Exact date and timestamp of each **logout**
* A running history of all authentication events
The log updates in real time and cannot be edited or deleted. Clients do not have access to their own activity log — it is for administrative and compliance visibility only.
At this stage, the activity log captures authentication events only (login and logout). Actions taken within the portal — such as viewing orders — are not yet logged here.
## Emailing a Client
You can send an email to any client directly from their profile without leaving AgencyHandy. Open the client's profile and use the **Email** option to compose your message. The **To** field is pre-filled with the client's email address.
## Client Impersonation
Admins can impersonate a client account to see exactly what the client sees in their portal — useful for troubleshooting access issues or walking a client through a process during a support call. Look for the **Impersonate** option inside the client's profile.
Use impersonation for support purposes only. Any actions taken while impersonating a client are performed on their behalf and will be reflected in their account.
## Company Accounts (B2B)
If you work with businesses rather than individuals, you can set a **Company Name** on any client profile to group contacts under the same organization. The Clients list can be filtered by company, making it easy to view all contacts at a given account together.
# Lead Custom Fields: Capture Extra Prospect Data
Source: https://docs.agencyhandy.com/crm/lead-custom-fields
Create and manage custom fields for leads in Workspace Config so your team can track industry, budget, referral source details, and other prospect data beyond the default CRM fields.
Lead custom fields let you store extra information on each prospect — beyond name, email, company, and the default CRM fields. Define the fields once in **Workspace Config**, then fill them in on every lead card.
Only **SuperAdmin** and **Admin** roles can create, edit, or delete custom field definitions. Team members with lead access can fill in values on lead profiles.
## Before you start
* Access to **Workspace Config** → **Custom Fields**
* A plan that includes CRM custom fields for your workspace
## How lead custom fields work
1. An admin creates a **definition** (name + type) with **Belongs to = Lead**.
2. That definition appears on every lead profile in the workspace.
3. Your team (or Claude/Cursor via MCP) fills a **value** on each lead.
4. Lead and client fields are separate catalogs. A lead field named `Industry` does **not** automatically create a client field with the same name.
## Create a lead custom field
Go to **Workspace Config** → **Custom Fields**.
Click **Create Custom Field**.
In **Belongs to**, select **Lead**. The field will appear only on lead profiles (not on clients or tasks).
Enter a clear **name** (for example, `Industry` or `Estimated budget`). Choose a **type**:
| Type | Use for |
| ---------------------------- | -------------------------------- |
| **Text** | Free-form notes or short answers |
| **Number** | Budgets, scores, quantities |
| **Boolean** | Yes/no flags |
| **Dropdown (Single Select)** | One choice from a list |
| **Dropdown (Multi Select)** | Multiple choices from a list |
| **Attachment** | Files related to the lead |
For dropdown types, add the allowed **options**. Toggle **Required** if the field must be filled when creating or editing a lead.
Click **Create**. The field appears in the Custom Fields list with belongs-to **Lead**.
Use names your sales team already uses in calls and spreadsheets. Consistent labels make filters and handoffs clearer.
## Duplicate field names
AgencyHandy blocks a second **lead** field with the same name (case and spacing ignored). Examples:
| You try to create | Existing lead field | Result |
| ----------------- | ---------------------------- | --------------------------------------------------- |
| `Industry` | `Industry` | Not created — **Field already exists** |
| `industry` | `Industry` | Not created (same name after normalize) |
| ` Budget ` | `budget` | Not created (whitespace normalized) |
| `Industry` | Client field `Industry` only | **Allowed** — lead and client catalogs are separate |
If create is blocked for a duplicate, use the existing field from the list (or via `ah_custom_field_list`) instead of creating another.
## Fill in values on a lead
Go to **CRM** → **Leads** and open a lead card.
In the lead detail view, open the **Custom Fields** section or tab.
Complete the fields your workspace defined, then save. Values stay with the lead through pipeline stages.
## Use with Claude or Cursor (MCP)
With [AgencyHandy MCP](/integrations/claude-cursor-mcp) (`agencyhandy-mcp@1.5+`):
1. List lead definitions: ask Claude to list lead custom fields (`ah_custom_field_list`, type `lead`).
2. Fill values by **definition id** — never invent ids.
3. Create a lead and set fields in one step, or set values on an existing lead.
4. To **update** a value later, open the member’s fields first (`ah_member_custom_fields`) and prefer the existing value row id when one is already filled.
Example prompts:
* “List our lead custom fields.”
* “Create a lead for Nora at Bright Studio and set Industry to Agency software.”
* “On lead [nora@brightstudio.com](mailto:nora@brightstudio.com), set Estimated budget to 12000.”
Admins can also create definitions from MCP (`ah_custom_field_create`). Duplicate names return in `notCreatedCustomFields` with reason **Field already exists**.
## Convert a lead that has custom fields
When you **Convert to Client**, AgencyHandy can prompt you to carry over lead custom fields that should also exist on the client.
* If matching **client** custom fields already exist, map or copy values during conversion.
* If a lead field has no client equivalent, create the client field first under **Workspace Config** → **Custom Fields** (belongs to **Client**), or skip that value.
See [Client Custom Fields](/crm/client-custom-fields) for defining client-side fields.
## Manage existing lead fields
From **Workspace Config** → **Custom Fields**:
* **Search** or filter by name and belongs-to (**Lead**)
* **Edit** the field name, options, or required setting
* **Delete** fields you no longer need (existing values on leads may be cleared — confirm before deleting)
## Related
* [Leads](/crm/leads) — pipeline, email, and conversion
* [Client Custom Fields](/crm/client-custom-fields) — fields that appear on client profiles
* [Clients](/crm/clients) — client list, import, and portal access
* [Claude & Cursor MCP](/integrations/claude-cursor-mcp) — fill fields from AI tools
# Manage Leads: Pipeline, Email, and Client Conversion
Source: https://docs.agencyhandy.com/crm/leads
Manage your sales pipeline with a Kanban board—track lead stages, filter by agent or source, send emails, and convert leads to clients.
The Leads section of AgencyHandy's CRM gives you a visual, drag-and-drop Kanban board to manage every prospect from first contact to signed client. Each lead lives on a card that travels through seven predefined pipeline stages, and you can filter, search, import, export, email, and convert leads without ever switching to another tool.
## Pipeline Stages
Every lead you create starts in the **New** stage and can be moved forward as your relationship develops:
| Stage | What it means |
| ----------------- | -------------------------------------- |
| **New** | Lead just entered the pipeline |
| **Contacted** | You've reached out at least once |
| **Qualified** | Lead meets your target-client criteria |
| **Working** | Active conversations underway |
| **Proposal Sent** | A formal proposal has been delivered |
| **Negotiation** | Terms are being discussed |
| **Client** | Ready to convert to a client account |
Moving a lead to the **Client** stage on the board does not automatically convert it — you still need to click **Convert to Client** inside the lead card to move it to the Clients tab.
## Creating a Lead
From the left sidebar, click **CRM**, then select the **Leads** tab. The Kanban board loads with all your existing pipeline stages.
Select the **+ Create Lead** button at the top right of the board. A creation form opens.
Complete the fields below. **Name** and **Email** are mandatory; everything else is optional but recommended for better filtering and reporting.
* **First Name / Last Name** *(mandatory)*
* **Email** *(mandatory)*
* **Company Name**
* **Category**
* **Status** — sets the initial Kanban stage (defaults to New)
* **Source** — e.g., Facebook, Website *(max 50 characters; text beyond this is truncated with a tooltip)*
* **Lead Value** — estimated deal worth
* **Phone Number**
* **Website**
* **Assigned Agent** — team member responsible for this lead
* **Last Interaction** — date of most recent contact
* **Address** — Country, State, City, Zip Code
* **Attachments** — PDFs, JPEGs, PNGs, and text files can be previewed directly in the lead modal; unsupported formats prompt a download instead
Click **Create**. The lead card appears in the **New** column on the Kanban board.
Upload PDF briefs or proposal documents as attachments so your team can review them without leaving the lead modal.
## Tracking Leads on the Kanban Board
Once leads exist on the board, you have several ways to work with them:
* **Drag and drop** — grab any lead card and drop it into a different stage column to reflect its current status.
* **Click a card** — opens the lead detail modal where you can edit all fields, view notes, check the activity log, send an email, or convert to a client.
* **Print lead details** — use the **Print** button in the top-right corner of the lead modal to generate a printable summary.
## Editing a Lead
Open any lead card and click **Edit** (or directly update the contact info or notes fields shown in the modal). Changes are saved immediately and recorded in the activity log.
If an email address already exists as both a client and a lead, that lead **cannot** be converted to a client. Resolve the duplicate before attempting conversion.
## Converting a Lead to a Client
Click the lead you want to promote on the Kanban board.
Select the **Convert to Client** button inside the lead modal.
A confirmation banner appears: *"Lead has moved to the Clients Tab."* The card disappears from the Kanban board, and all lead notes and history are preserved in the new client record.
## Filtering and Searching Leads
Use the toolbar above the Kanban board to narrow down what you see:
Type a name or email to instantly surface matching leads across all pipeline stages.
Filter the board to show only leads assigned to a specific team member.
Narrow by estimated deal size to prioritise high-value prospects.
Identify leads that haven't been touched recently and need follow-up.
View only leads from a particular channel, such as Website or Facebook.
## Emailing Leads
You can compose and send emails directly from the Kanban board or from inside a lead modal — no external email client required.
| Field | Details |
| --------------- | ------------------------------------------- |
| **To** | Pre-filled with the lead's email address |
| **Subject** | Mandatory; maximum 250 characters |
| **Body** | Rich text editor; maximum 10,000 characters |
| **Attachments** | Up to 5 files; total size limit 25 MB |
## Notes
Each lead includes a dedicated **Notes** section inside the detail modal. Notes are editable and deletable, and each note displays the name of the team member who wrote it along with a timestamp. Use notes to log call summaries, client preferences, or follow-up reminders that the whole team can see.
## Importing Leads
Bring an existing prospect list into AgencyHandy in bulk using a CSV or Excel file.
On the Leads board, click the **Import** button at the top right.
Drag and drop or browse for your CSV or Excel file. The file must include at minimum a **Name** and **Email** column.
The importer shows a column mapper. Match each column in your file to the corresponding AgencyHandy field. Optional mappable fields include: Source, Lead Value, Phone Number, Company Name, and Address.
Review the preview table to verify data accuracy, then click **Confirm** followed by **Save**. Your leads appear on the Kanban board immediately.
Leads with email addresses that already exist in your Clients tab will not be converted through the import — you must handle those duplicates manually.
## Exporting Leads
Export your pipeline data for reporting, backups, or integration with other tools.
Select the **Export** button from the Leads toolbar.
Select **All Columns** to export every field, or choose **Custom Columns** to pick only the data you need.
Choose **CSV** or **XLSX**, then click **Export**. The file downloads to your device.
## Activity Log
Every change made to a lead is automatically recorded in the **Activity Log** tab inside the lead modal.
The log captures:
* **User** — which team member made the change
* **Details** — what changed, for example *"Status changed from 'New' to 'Contacted'"*
* Attachment uploads, note additions, and field edits
Activity logs cannot be edited or deleted and are visible to admins and managers.
## Automated Reminders and Tasks
AgencyHandy sends automated notifications when a lead has been idle in any stage beyond a configurable number of days — for example, *"Follow up with \[Lead Name]."* Key actions such as sending a proposal can also automatically generate tasks in the task manager to keep your delivery process on track.
## Webhooks for Lead Events
AgencyHandy fires webhook events for the following lead actions, enabling you to connect external CRMs, automation tools, or data pipelines:
Fires when a new lead is created. Payload includes: lead ID, status, source, assigned agent, and timestamps.
Fires when any field on a lead is updated. Payload includes the same fields plus a summary of what changed.
Fires when a lead is deleted from the system. Payload includes the lead ID and deletion timestamp.
Configure webhooks in **Settings → Integrations → Webhooks** to start receiving real-time lead events in your external systems.
## Reporting Metrics
Track your pipeline health with built-in reporting metrics:
* Number of leads per stage
* Conversion rates from lead to client
* Average time a lead spends in each stage
* Best-performing agents by conversion volume
# Manage Files: Upload, Preview, and Get Client Feedback
Source: https://docs.agencyhandy.com/files/manage-files
Upload deliverables and reference assets to orders and tasks, share files with clients, and collect structured feedback — all inside AgencyHandy.
AgencyHandy gives every order and task its own file storage area, so deliverables, reference materials, and client feedback never get lost in email threads. You upload files directly to the task they belong to, share them with clients or teammates, and receive feedback as inline comments — all without leaving the platform. Files are preserved with a clear history, making version reviews and approvals straightforward.
## Supported file formats and limits
AgencyHandy accepts a wide range of file types to cover every deliverable your agency produces.
`pdf` `doc` `docx` `odt` `txt` `ppt` `pptx` `xls` `xlsx` `csv`
`jpg` `jpeg` `png` `gif` `webp` `svg` `ai`
`mp4` `mp3` `wav` `zip` `rar`
The maximum file size per upload is **1 GB**. Your total storage allowance depends on your plan: 100 GB (Freelancer), 2 TB (Team Starter), or 10 TB (Business Pro).
## Upload files to an order task
Files are attached at the task level, keeping deliverables organised and scoped to the exact piece of work they relate to.
Navigate to the relevant order, then click the task you want to attach files to. The task detail modal opens.
Scroll down inside the task modal to locate the **Attachment** section.
You have two options:
* **Click Upload** — a file picker opens so you can browse your local storage and select one or more files.
* **Drag and drop** — drag files from your desktop directly onto the Attachment area.
AgencyHandy uploads the files and displays them in the attachment list once the transfer is complete.
Once uploaded, you can share a file with specific team members or your client by setting access permissions from within the task. Shared files appear in the recipient's view of the task.
## View uploaded files
All files attached to a task are listed in the **Attachment** section of the task modal. Click any file to open a preview (for supported formats) or download it. Files are displayed with their name, upload date, and uploader, giving you a clear audit trail.
Need to find files across multiple orders quickly? Use the global **Files** section in the sidebar to browse all uploaded assets in a centralised view, filterable by project or upload date.
## File feedback workflow
The file feedback feature lets clients and team members leave comments directly on shared files, keeping all revision notes in one place rather than scattered across emails.
In the task's Attachment section, share the file with your client. They receive a notification (in-app and/or email, based on their notification settings) that a file is ready for their review.
The client opens the file from their portal. They can view the file and add a **feedback comment** to flag changes, ask questions, or give approval.
When the client adds a feedback comment, AgencyHandy sends a **File Feedback Comment Added** notification to the relevant team members. Clicking the notification takes you directly to the file and comment.
Review the client's comments, make the necessary changes, and upload the revised file to the same task. Add a reply comment to let the client know the revision is ready.
Once the client is satisfied, they can mark the file as approved. The approval status is recorded against the file for your records.
All file feedback comments are stored inside AgencyHandy and associated with the specific task and file, so you always have a full revision history available.
## Delete a file
To remove a file from a task, open the task modal, hover over the file in the Attachment section, and click the **delete icon**. Confirm the deletion when prompted. Deleting a file removes it permanently from the task — it cannot be recovered.
Deleting a file also removes any feedback comments attached to it. Make sure you no longer need the comments or the file before confirming deletion.
## Key benefits at a glance
| Capability | Details |
| ------------------------ | --------------------------------------------------------------------------- |
| **Centralised storage** | All files live inside AgencyHandy, no external drives or email attachments |
| **Version history** | Multiple files can coexist on a task so previous versions remain accessible |
| **Collaborative review** | Clients comment directly on files — no back-and-forth emails |
| **Access control** | Only users with the right permissions can view, upload, or delete files |
| **Broad format support** | 20+ file types accepted, up to 1 GB per file |
# Create Intake Forms to Collect Client Requirements
Source: https://docs.agencyhandy.com/forms/intake-forms
Create custom intake forms to gather every detail you need before starting a project — attached to services so clients fill them in right after ordering.
Before your team can start delivering, you need the full picture: goals, deadlines, brand guidelines, reference materials, and any other details that are unique to each client's project. Intake forms let you define exactly what information to collect and attach that form directly to a service — so the moment a client places an order, AgencyHandy prompts them to fill it in. No chasing emails, no incomplete briefs.
## Why intake forms matter
Without a structured intake process, important details get buried in email threads or simply never collected. An intake form:
* **Standardises briefing** — every project starts with the same quality of information.
* **Reduces back-and-forth** — you get what you need upfront, so work can begin immediately.
* **Sets expectations** — clients think through their requirements before the project kicks off, leading to clearer scope and fewer revision cycles.
* **Lives inside the order** — all responses are stored against the order in AgencyHandy, so your team always knows where to look.
## Two ways to create an intake form
You can build an intake form either while setting up a service, or independently from the **Forms** section and then attach it later.
This is the most direct route when you're setting up a new service and want the intake form ready from day one.
Navigate to **Services** and open an existing service or create a new one.
Inside the service settings, locate the **Intake Form** tab or section (sometimes labelled **Requirements**).
Click **Add Field** and choose the field type that best fits the information you need. See the [field type reference](#available-field-types) below for a full list.
Give each field a clear label and, if helpful, add placeholder text or helper instructions to guide the client's response. Mark the field **Required** if it must be completed before the form can be submitted.
Use the **Preview** option to see the form from the client's perspective, then click **Save** to attach it to the service.
Use this route when you want to build a library of reusable intake forms before assigning them to services.
In the sidebar, click **Forms**, then select **Intake Form**.
Click **Create New Intake Form** in the upper-right corner.
Give the form a descriptive name that reflects the service it will be attached to, for example "SEO Audit Brief" or "Logo Design Requirements".
Add fields from the component panel on the right. Configure labels, helper text, and required status for each field.
Preview the form, then click **Save** to store it in your form library.
Open the relevant service, go to its **Intake Form** settings, and select the saved form from the library to attach it.
## Available field types
| Field type | Character limit | Best used for |
| ------------------ | --------------- | ----------------------------------------------------------------- |
| **Short Answer** | 120 characters | Project names, quick labels, single-line responses |
| **Paragraph** | 500 characters | Open-ended briefs, background descriptions |
| **Formatted Text** | Flexible | Detailed specifications that benefit from bold, italics, or lists |
| Field type | Description |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| **Multiple Choice (Checkbox)** | Lets clients tick all options that apply — useful for selecting deliverable formats, target platforms, or style preferences |
| **Selection (Radio Button)** | Lets clients pick exactly one option — ideal for exclusive choices like preferred language or package tier |
| Field type | Description |
| --------------- | --------------------------------------------------------------------------------------- |
| **Date** | A date-picker for deadlines, launch dates, or event dates |
| **Attach File** | Allows clients to upload reference files such as logos, brand guides, or example assets |
| **Spreadsheet** | For bulk data inputs such as keyword lists, product catalogues, or location data |
## How clients fill out intake forms
After a client completes checkout on an order that has an intake form attached, AgencyHandy automatically presents the form as the next required step. Here's what happens:
1. The client sees a prompt to complete the intake form for their new order.
2. They work through each field, uploading any required files along the way.
3. Once every required field is filled in, they click **Submit**.
4. The responses are saved against the order in AgencyHandy and your team is notified.
If a client skips the intake form at checkout, they can return to it at any time from their client portal under the relevant order. You can also see whether the form has been completed from the order detail page in your dashboard.
## Tips for effective intake forms
Keep your intake form focused — only ask for information you will actually use. Long forms reduce completion rates. If you need a lot of detail, break the form into logical sections with clear headings.
* **Use helper text** on complex fields to explain exactly what format or level of detail you need.
* **Mark genuinely critical fields as Required** but avoid marking everything as required, or clients may feel overwhelmed.
* **Test the form yourself** from the client's perspective before attaching it to an active service — submit a test order and fill in the form to check the flow.
* **Update forms when your process changes** — you can edit an intake form at any time and the updated version will apply to all future orders.
# Create, Customize, and Share Order Forms with Clients
Source: https://docs.agencyhandy.com/forms/order-forms
Build branded order forms that let clients select services, add upsells, and pay — all on a single page. Share via link or embed in your client portal.
Order forms are the fastest way to turn a website visitor or lead into a paying client. Instead of sending separate service quotes and chasing payment links, you create one form that combines your service catalogue, optional upsells, project inputs, and checkout — so clients can browse, customise, and pay in a single flow. Once published, the form lives at a shareable public URL you can send directly or surface inside each client's portal.
## What you can include in an order form
Add your core services, optional upsell packages, and add-ons so clients can build their own order without a back-and-forth conversation.
Collect written briefs, deadlines, file uploads, spreadsheets, and more — directly on the order form before the client checks out.
Require clients to review and agree to your service terms as part of the purchase flow, protecting your agency legally.
Add a signature block so clients formally confirm their consent before the order is finalised.
## Create an order form
In the left-hand sidebar, click **Forms**, then select **Order Form** from the list.
Click **Create New Order** in the upper-right corner. A blank form builder opens.
Under the **Services** section of the form builder, click **Add Service** to attach one or more of your pre-configured services. For each service you can also:
* Click **Add Upsell** to offer an upgrade or complementary package clients can opt into.
* Click **Add-on** to include optional extras such as extended support or additional deliverables.
Services, upsells, and add-ons must be created in your **Services** catalogue before you can attach them to an order form.
In the **Project Input** section, click any field type to add it to the form. Available field types are:
| Field type | Best used for |
| ------------------------------ | -------------------------------------------- |
| **Short Answer** (120 chars) | Project titles, quick references |
| **Paragraph** | Open-ended briefs and descriptions |
| **Formatted Text** | Detailed specifications with rich formatting |
| **Multiple Choice (Checkbox)** | Selecting several applicable options |
| **Selection (Radio Button)** | Exclusive single-option choices |
| **Date** | Deadlines, go-live dates, event dates |
| **Attach File** | Design briefs, reference assets, brand files |
| **Spreadsheet** | Bulk data, keyword lists, product catalogues |
Drag fields up or down to reorder them. Mark any field as **Required** to prevent submission without it.
In the **Utility** section, add a **Terms & Conditions** block and/or a **Signature** field if you want clients to formally agree to your policies before completing the purchase.
Click **Preview Form** to see exactly what clients will see. Once you are satisfied, click **Save and Publish**. The form is now live and ready to share.
## Share your order form
After publishing, you have two main ways to get the form in front of clients.
Copy the public form URL from the order form's detail page and send it to clients via email, chat, or your website. No login is required for clients to access or submit the form.
Paste the link into your email signature or a "Get Started" button on your website so new leads can self-serve at any time.
You can surface the order form directly inside a client's portal so it appears under their **Forms** tab without any external link sharing. See the steps below.
### Display the order form in the client portal
Go to **Forms → Order Form**, find the form you want to display, click the **three-dot menu (⋯)**, and select **Share Form**.
In the **Share Public Form** modal, toggle on **Show this form in Client's Portal**.
Optionally enable **One client can submit multiple responses** if you want clients to be able to reorder or resubmit the form more than once.
Check the **Shared With** list to make sure the correct clients are included. Only those clients will see the form in their portal.
Click **Send** (to also notify clients by email) or simply close the modal — visibility is saved automatically.
Once enabled, the form appears under the **Forms** tab in each listed client's portal. Clients must be logged in to submit through the portal; no login is needed for public-link submissions.
## How clients experience the order form
When a client opens the order form link or visits it in their portal, they:
1. Browse the available services and select what they need.
2. Choose any upsells or add-ons they want to include.
3. Fill in the project input fields with their requirements.
4. Review and accept the Terms & Conditions (if included).
5. Add their digital signature (if required).
6. Complete payment to finalise the order.
All submitted data is captured immediately in AgencyHandy and a new order is created in your dashboard automatically.
## Important notes
Clients must complete all **Required** fields before they can submit the form. Label every field clearly so clients understand exactly what information you need.
* Keep field labels concise and jargon-free — your clients may not be familiar with your internal terminology.
* The Terms & Conditions and Signature fields provide legal protection for your agency; it is recommended to include them on any paid order form.
* You can edit a published form at any time; changes take effect immediately for anyone who opens the link after saving.
# AgencyHandy Dashboard Overview: Navigate Your Workspace
Source: https://docs.agencyhandy.com/getting-started/dashboard-overview
Tour the AgencyHandy main interface: explore Agency vs Client dashboards and every left sidebar section, from CRM and Orders to Settings.
Once you log in, AgencyHandy takes you to your main dashboard — the control center for everything your agency manages. The interface is clean and navigation-driven: a persistent left sidebar gives you instant access to every major feature, while the central panel updates to show the data relevant to whichever section you've selected. Everything you need to run your agency — from client relationships to invoices to task tracking — lives here.
## Two Dashboard Views
AgencyHandy provides two distinct dashboard perspectives depending on who is logged in. You can switch between them as needed.
The default view for agency owners, admins, and team members. Use it to get a real-time snapshot of your agency's operations — active orders, open tickets, outstanding invoices, task progress, and team workload — all from one central view. This is the dashboard you'll spend most of your time in.
A purpose-built portal your clients access when they log into AgencyHandy. Clients can monitor their active orders, review assigned tasks, check unpaid invoices, and raise support tickets — giving them full transparency into work you're delivering on their behalf.
The Agency Dashboard and Client Dashboard show the same underlying data but from different perspectives and with different permission levels. Clients only see data relevant to their own account; agency users see data across all clients.
## Left Sidebar Navigation
The left sidebar is your primary navigation panel. Each icon and label corresponds to a major feature area of AgencyHandy. Here's what each section does:
### CRM
Your client relationship management hub. Store and manage all client contact details, track communication history, and maintain a clear record of every account your agency works with. Use CRM as your single source of truth for who your clients are and where each relationship stands.
### Services
Define the services your agency offers and build your service catalog. When clients place orders, they select from the services you've published here. You can set pricing, descriptions, deliverables, and order intake forms for each service.
### Orders
Track every client order from placement through to completion. The Orders section gives you visibility into order status, associated tasks, client communications, and delivery timelines — so nothing falls through the gaps between a sale and its delivery.
### Proposals
Create, send, and manage proposals and contracts directly within AgencyHandy. Draft a proposal, attach pricing and scope, and send it to a client for review. Once accepted, proposals can be converted into active orders without any manual duplication.
### Invoices
Generate professional invoices tied to client orders or projects, track payment status, and give clients a clear view of what they owe. AgencyHandy handles the invoicing lifecycle from creation to settlement, reducing the back-and-forth that typically comes with billing.
### Tasks
Manage all work at the task level. Create tasks, assign them to team members, set due dates and priorities, and monitor completion status. Tasks connect directly to orders and services, so progress is always visible in context.
### Teams
Manage your team members from a central location. Invite new members, assign roles, and control what each person can access within the workspace. Use this section to keep your team roster up to date as your agency grows.
### Tickets
Handle client support requests and internal issue tracking through a built-in ticketing system. Clients can raise tickets from their portal, and your team can triage, respond to, and resolve them without switching to a separate helpdesk tool.
### Timesheet
Track time spent on client work and internal projects. Team members can log hours against specific tasks or orders, giving you accurate data for billing, capacity planning, and project profitability reporting.
### Forms
Build and manage custom forms to collect structured information from clients during onboarding, order intake, or any other point in your workflow. Forms created here can be attached to services, proposals, or sent directly to clients.
### Files
Store and organize all files related to your agency's work — deliverables, contracts, brand assets, and client documents — in one centralized location. Files can be scoped to specific clients or orders so everyone always knows where to find what they need.
### Settings
Configure every aspect of your AgencyHandy workspace. Manage your agency profile, branding, notification preferences, integrations, team permissions, billing, and more. Settings is also where you'll find workspace-level configuration that applies across all clients and team members.
## Quick Reference: Sidebar Sections at a Glance
| Section | Primary Use |
| ------------- | -------------------------------------------------- |
| **CRM** | Manage client contacts and account records |
| **Services** | Define and publish your agency's service catalog |
| **Orders** | Track and deliver client orders end to end |
| **Proposals** | Create, send, and manage proposals and contracts |
| **Invoices** | Generate invoices and monitor payment status |
| **Tasks** | Assign work, set deadlines, and track completion |
| **Teams** | Invite members, assign roles, control access |
| **Tickets** | Handle client support requests and internal issues |
| **Timesheet** | Log and review time spent on work |
| **Forms** | Build custom forms for client data collection |
| **Files** | Centralize documents and deliverables |
| **Settings** | Configure workspace, branding, and permissions |
## Getting Help
If you have questions while exploring the interface, click the **chat icon** in the bottom-right corner of any page to reach the AgencyHandy support team directly.
Haven't signed up yet? Get your workspace up and running in minutes.
Already have an account? Learn how to sign in and manage your session.
# Introduction to AgencyHandy: Your All-in-One Agency Hub
Source: https://docs.agencyhandy.com/getting-started/introduction
Discover what AgencyHandy is, who it's built for, and how it unifies client management, projects, invoicing, and team collaboration in one platform.
AgencyHandy is a comprehensive, all-in-one agency management platform that brings every corner of your agency operations under one roof. Instead of juggling a patchwork of disconnected tools, you get a single workspace to manage clients, deliver services, track projects, send invoices, collaborate with your team, and give clients a transparent portal — all without switching tabs.
## What AgencyHandy Does for You
Whether you run a growing marketing agency, work as an independent consultant, or manage a small team of freelancers, AgencyHandy is built to match the pace and complexity of modern agency work. It handles the operational heavy lifting so you can focus on delivering great work to your clients.
Keep all your client relationships organized in one place. Track contact details, communication history, and account status so nothing slips through the cracks.
Create polished proposals and contracts, send them directly to clients, and get them signed — all without leaving AgencyHandy.
Define your service catalog, accept client orders, and manage delivery workflows from a single, unified view.
Generate professional invoices, track payment status, and give clients visibility into what they owe — reducing back-and-forth email threads.
Break work down into tasks, assign them to team members, set deadlines, and monitor progress in real time.
Give every client their own login portal to track project progress, review tasks, approve deliverables, and communicate with your team.
Manage team members, define roles, and keep everyone aligned with shared visibility into orders, tasks, and timelines.
Centralize file storage, collect client information through custom forms, and handle support tickets without switching to a separate helpdesk tool.
## Who Is AgencyHandy For?
AgencyHandy is purpose-built for small to medium-sized agencies and service businesses. It's especially valuable for:
* **Marketing agencies** that need to manage client campaigns, track deliverables, and maintain clear communication across multiple accounts.
* **Freelancers** who want a professional way to manage projects, log time, collaborate with clients, and get paid promptly.
* **Consultants** who need to organize appointments, invoices, client information, and follow-ups in one structured space.
* **Web designers and developers** who juggle multiple client projects, need solid task tracking, and want seamless client collaboration.
* **Event planners** managing timelines, vendor communication, and client approvals across concurrent events.
* **Legal professionals** handling case management, client billing, and document organization.
If your work involves delivering services to clients and coordinating a team to do it, AgencyHandy is designed with you in mind.
## Why Choose AgencyHandy?
Most agencies accumulate a sprawl of separate tools — one for project management, another for invoicing, another for contracts, and yet another for client communication. Each tool means another subscription, another login, and another gap where information falls out of sync.
AgencyHandy closes those gaps by consolidating everything into a single platform:
* **Streamlined operations** — one platform replaces many, eliminating the chaos of multi-app management.
* **Cost efficiency** — reduce your software stack and the budget that comes with it.
* **Enhanced client transparency** — clients log into their own portal to track progress and stay informed, reducing status-update emails.
* **User-friendly interface** — an intuitive layout means your team is productive from day one, with a short learning curve.
* **Competitive edge** — offer clients a modern, transparent experience that sets your agency apart.
## Ready to Get Started?
Sign up for AgencyHandy in minutes and set up your agency workspace.
Learn your way around the main interface and everything it gives you access to.
# Log In to AgencyHandy: Access Your Agency Dashboard
Source: https://docs.agencyhandy.com/getting-started/log-in
Step-by-step guide to logging into AgencyHandy with your credentials or Google SSO, staying signed in, and resetting your password if you forget it.
Logging into AgencyHandy gives you immediate access to your agency's workspace — from pending orders and client communications to tasks, invoices, and team management. Every login is tied to your unique workspace name, so AgencyHandy can route you to the right account even if multiple agencies share the same email address.
You need a registered AgencyHandy account before you can log in. If you haven't created one yet, follow the [Sign Up](/getting-started/sign-up) guide first.
## Log In with Email and Password
Open [agencyhandy.com](https://www.agencyhandy.com/) in your browser, then click the **Sign In** button in the top navigation.
Type the **Workspace Name** you chose when you registered. This is the unique identifier for your agency — lowercase letters, numbers, and hyphens only. Click **Continue** to proceed to the credentials screen.
Not sure of your workspace name? Check the confirmation email you received when you signed up — it references your workspace URL.
Provide the **Email ID** and **Password** associated with your AgencyHandy account.
Tick the **Keep Log In** checkbox if you want AgencyHandy to remember your session on this device. With this option enabled, you won't need to enter your credentials again until you manually sign out.
Avoid enabling **Keep Log In** on shared or public computers. Anyone with access to that device will be able to open your workspace without entering a password.
Click the **Sign In** button. AgencyHandy authenticates your credentials and takes you directly to your Agency Dashboard.
## Log In with Google (SSO)
AgencyHandy supports Single Sign-On (SSO) via Google, letting you skip manual password entry entirely.
Navigate to [agencyhandy.com](https://www.agencyhandy.com/) and click **Sign In**.
On the login screen, click the **Continue with Google** button instead of entering your workspace name and password.
Google will prompt you to choose the account you want to use. Select the account whose email address matches your AgencyHandy account.
On your first Google login, you may be asked to grant AgencyHandy access to your basic profile information. Accept the permissions to continue.
AgencyHandy verifies your Google identity and redirects you to your Agency Dashboard automatically.
When you log in with Google, AgencyHandy checks whether the Google email address matches an existing account:
* **Email already exists** — AgencyHandy logs you into that account immediately.
* **Email does not exist** — AgencyHandy creates a new account using your Google profile details.
Once linked, your Google email becomes the primary login identity for that workspace. You can still log in with your email and password if you set one.
Your SSO session behaves like a standard login session. You can log out at any time, and re-authentication with Google is instant on your next visit.
* Use the **same email address** as your AgencyHandy account when authenticating with Google to ensure a seamless login.
* If you revoke AgencyHandy's access within your Google account settings, Google SSO login will be blocked. Use your email and password to regain access.
* Google authentication follows Google's own security protocols, including two-factor authentication if you have it enabled on your Google account.
* Password-based login remains available as an alternative at any time.
## Reset Your Password
If you forget your password, you can reset it directly from the login page without contacting support.
On the AgencyHandy login page, click the **Forgot Password** link below the password field.
Type the email address associated with your AgencyHandy account and submit the form. AgencyHandy will send a password reset email to that address.
Open the reset email in your inbox and copy the verification code provided.
Return to the AgencyHandy reset page, paste the code into the verification field, and click **Continue**.
Enter your new password in the **New Password** field and retype it in the **Confirm Password** field. Make sure the new password meets the same requirements as your original one:
* At least 8 characters
* At least one uppercase letter, one lowercase letter, one number, and one special character
* No spaces
Return to the login page, enter your workspace name and email, and sign in using your new password.
Reset emails occasionally land in spam or junk folders. If you don't see the email within a couple of minutes, check there before requesting another.
# Sign Up for AgencyHandy: Create Your Agency Workspace
Source: https://docs.agencyhandy.com/getting-started/sign-up
Learn how to register your AgencyHandy account, verify your email, configure your agency type, and land on your agency dashboard for the first time.
Signing up for AgencyHandy takes just a few minutes. You'll create your account, choose a unique workspace name that becomes your agency's sub-domain, verify your email address, and complete a short onboarding flow so the platform is tailored to your agency from the start.
Before you begin, make sure you have access to the email inbox you'll register with — you'll need it to verify your account during setup.
## Create Your Account
Open your browser and navigate to [app.agencyhandy.com/sign-up](https://app.agencyhandy.com/sign-up). On the homepage, click **Get Started for Free** to reach the registration form.
Complete all required fields in the sign-up form:
| Field | What to enter |
| ------------------ | ----------------------------------------------------- |
| **Email ID** | A valid email address you can access for verification |
| **First Name** | Your given name |
| **Last Name** | Your family name |
| **Password** | A strong password meeting the requirements below |
| **Workspace Name** | A unique identifier for your agency (see rules below) |
**Password requirements:**
* At least 8 characters long
* Contains at least one uppercase letter
* Contains at least one lowercase letter
* Contains at least one number
* Contains at least one special character (e.g. `!`, `@`, `#`)
* Must not contain spaces or whitespace
**Workspace name rules:**
* Lowercase letters and numbers only
* Hyphens (`-`) are allowed between characters
* Minimum 3 characters
* No spaces or uppercase letters
Choose your workspace name carefully — it becomes part of your agency's sub-domain and represents your brand. For example, a workspace named `bright-agency` will form the basis of your unique AgencyHandy URL.
Tick the checkbox to confirm you agree to AgencyHandy's **Data Privacy Policy**. You cannot proceed without accepting this.
Click the **Sign Up** button. AgencyHandy will create your account and immediately send a verification email to the address you provided.
Open the verification email in your inbox. It contains a unique verification code. Return to the AgencyHandy verification page, enter the code in the designated field, and click **Continue**.
If the email doesn't appear within a few minutes, check your spam or junk folder. If the verification code has expired, click **Resend Code** on the verification page to receive a fresh one.
Once AgencyHandy accepts the code, your account is confirmed and you'll see a success message.
After verification, a short onboarding questionnaire helps AgencyHandy tailor your experience:
1. **Agency type** — Select the category that best describes your agency (e.g., marketing, design, development, consulting).
2. **Agency usage** — Answer a brief question about how you intend to use AgencyHandy.
3. **Team size** — Choose the number of people currently on your team.
4. **Referral source** — Select how you heard about AgencyHandy.
Click **Next** after each screen to move through the flow.
After completing the onboarding steps, AgencyHandy redirects you to your **Company Home Dashboard**. Your workspace is now live and ready to use.
## Sign Up with Google
If you prefer not to create a separate password, you can register using your Google account instead.
On the sign-up page, click the **Continue with Google** button.
Choose the Google account you want to associate with AgencyHandy and grant the requested permissions.
AgencyHandy creates your account using your Google profile details. You'll still be guided through the agency type and team size onboarding steps before landing on your dashboard.
If you sign up with Google, use the **Continue with Google** button every time you log in — your Google email becomes your primary login identity.
## Important Notes
Your workspace name cannot be changed later without contacting support. Make sure it accurately represents your agency before you submit.
* Use a strong, unique password and store it in a password manager.
* The verification code sent to your email may expire after a short time. If it does, request a new one using **Resend Code**.
* The onboarding questions do not lock you into specific features — they simply personalise your initial dashboard view.
* Once you land on the dashboard, you can immediately start adding clients, creating services, and building your first proposal.
# Connect Claude and Cursor to run AgencyHandy with MCP
Source: https://docs.agencyhandy.com/integrations/claude-cursor-mcp
Set up AgencyHandy MCP so Claude or Cursor can brief you, assign work, investigate cash and delivery risk, and fill custom fields — in plain language.
AgencyHandy's MCP connection lets you talk to **Claude** or **Cursor** in plain language and have them run everyday work in your AgencyHandy workspace — without opening every screen yourself.
You stay in control. Claude and Cursor only act with the workspace API key you generate, and they ask you to confirm when a name matches more than one person.
You need a role that can open **Workspace Config** and manage **API keys** (typically **SuperAdmin** or **Admin**). You also need **Node.js 20+** on the machine where Claude Desktop or Cursor runs. Use `npx -y agencyhandy-mcp@1` (latest is **1.7.2+**: owner insights, advanced context packs, API builder context for leads/orders/tasks/invoices/forms, hardened URL/path checks).
## Requirements
| Requirement | Details |
| -------------------------------- | ------------------------------------------------------------ |
| **Node.js** | Version **20** or newer (`node -v` to check) |
| **Claude Desktop** or **Cursor** | One of these apps installed on your computer |
| **AgencyHandy workspace** | Access to **Workspace Config** → **API Key** |
| **MCP package** | `npx -y agencyhandy-mcp@1` (ships **1.7.2+** on the `1` tag) |
## Set up Claude or Cursor MCP
In AgencyHandy, open **Workspace Config** (company settings), then go to the **API Key** tab.
Create a new workspace API key (or use one you already saved). Copy the key when it appears — AgencyHandy cannot show the full key again later. Keys are **JWTs**; placeholders like `test-key` are rejected.
On the same **API Key** tab, use the Claude / Cursor MCP setup panel. Click **Copy MCP config** so the JSON includes your key and backend URL.
Paste the config into:
* **Cursor**: project or user `.mcp.json`
* **Claude Desktop**: `claude_desktop_config.json`
Keep the `npx -y agencyhandy-mcp@1` command and your API key as generated. The backend URL should be **https** (http is only allowed for localhost during local testing).
Fully quit and reopen **Cursor** or **Claude Desktop**. Then ask something simple, such as a Monday pulse or morning briefing for your workspace.
If Claude or Cursor cannot find the MCP server, confirm **Node.js 20+** is installed and that you restarted the app after saving the config. If the server exits immediately, check stderr for invalid URL/key messages — expired or placeholder keys fail fast.
## Example prompts
Ask like an owner: **spot the risk → dig into the record → take the next action**. Prefer full names or emails when assigning so the right person is selected.
### Owner / money / pipeline
| Goal | Example prompt |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Monday pulse** | “What’s on fire this morning — cash overdue, proposals going cold, and work that’s slipping?” |
| **Cash concentration** | “Who are our top 5 clients by open AR, and how much of that is past 30 / 60 / 90 days? Flag anyone who also looks churny.” |
| **Collect next** | “Pick the single best invoice to chase today (biggest \$ at risk that isn’t brand new), open full context, then send it if it’s ready.” |
| **Proposal triage** | “Which proposals are stale or expiring soon? For the worst one, summarize comments and tell me if we’re waiting on them or us.” |
| **Pipeline hygiene** | “List proposals waiting on clients longer than two weeks — which ones should I bump this week vs write off?” |
| **Lead quality mix** | “Segment leads by source and by Industry. Where are we getting volume but not converting status?” |
| **Churn watchlist** | “Which clients look at risk — overdue invoices *and* quiet orders? Give me a short watchlist with why each scored high.” |
| **At-risk deep dive** | “Take the highest churn-risk client: open their latest order and unpaid invoices, then tell me the one action that would reduce risk this week.” |
### Delivery / assignment
| Goal | Example prompt |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Smart assign** | “On the Acme website order, find the stuck task, recommend who should own it from the order team (not the busiest), then assign them.” |
| **Ticket load balance** | “For the Acme homepage redesign ticket, who on the team has capacity vs already overloaded on this order — recommend and assign.” |
| **Named assign** | “Assign the Acme homepage redesign ticket to Jordan Lee ([jordan@agency.com](mailto:jordan@agency.com)).” |
| **Order health** | “Full context on the Acme website order: open tasks, tickets, files, related invoices — what’s blocking delivery vs billing?” |
| **Proposal readiness** | “Summarize the Bright Studio proposal: status, comments, linked service — are they ready to accept or stuck on a question?” |
| **Invoice story** | “Explain INV-1042 end-to-end: amounts, due aging, linked order, and other open invoices for that client — should I nudge or escalate?” |
### CRM / custom fields / actions
| Goal | Example prompt |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Qualified lead in** | “Create lead Nora Patel at Bright Studio ([nora@brightstudio.com](mailto:nora@brightstudio.com)), set Industry to Agency software and Estimated budget to 12000.” |
| **VIP client in** | “Create client Ada Lovelace ([ada@acme.com](mailto:ada@acme.com)) and set VIP to true.” |
| **Enrich existing** | “On lead [nora@brightstudio.com](mailto:nora@brightstudio.com), set Estimated budget to 12000 — use the existing field id, don’t create a duplicate.” |
| **Close the loop** | “Mark INV-1042 paid, then refresh cash risk so I can see if that client drops off the top AR list.” |
## Advanced context packs
Claude should prefer these **context** tools instead of calling many small lookups. They return a short **summary**, **guidance**, and related sources.
| Context pack | What you get | Best for |
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| **Task** (`ah_task_context`) | Task details, comments, time entries, current assignees, **ranked people to assign** (order team / PM + workload on that order), linked order | “Who should do this?” / stuck delivery work |
| **Ticket** (`ah_ticket_context`) | Same assignment help for tickets/issues | Support or client-facing issues |
| **Order / project** (`ah_order_context` / `ah_project_context`) | Order summary, tasks, tickets, files, related invoices & subscriptions, prefix settings | Delivery health for one engagement |
| **Proposal** (`ah_proposal_context`) | Commercial summary, comment thread, public view, linked service | Negotiation / accept readiness |
| **Invoice** (`ah_invoice_context`) | Billing summary, public view, linked order, related invoices for the same client | Cash / overdue / billing questions |
## API builder context (for custom MCP tools)
If you build your **own** MCP tools against the AgencyHandy HTTP API (or Claude reads workspace resources), prefer the built-in resource **`ah://api-context`** (also inside **`ah://full-context`**). It documents path renames and easy mistakes for:
| Area | What to remember |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Leads** | No `/leads` route — use `/members` + `bulk-lead` / `isConvertedClient=false`. Never call `PUT /accounts/update` without `accountId` (that updates the API-key owner). |
| **Projects** | UI project = API `/orders` (not `/projects`). |
| **Tasks / tickets** | Board tickets are tasks with `type=issue`. Status **ObjectId** on lists, **name** on updates. |
| **Comments** | Task comments = `/comments`; proposal comments = `/quotation-comments`. Use `agencyComment` vs `clientComment` for visibility. |
| **Labels** | Company labels use `create-for-company` / `suggest-by-company`. |
| **Clients** | Live path is `/members` (not stale `/company/.../members` docs). |
| **Invoices** | Named permissions (`getInvoice`, …); resend and public routes differ from status PUT. |
| **Vouchers / forms / webhooks** | Admin CRUD vs public apply/respond/event-id rules — see `ah://api-context`. |
Shipped in **`agencyhandy-mcp@1.7.2+`**.
**Assignment flow (tasks & tickets)**
1. Ask for context on the task or ticket (include the order/project when you know it).
2. Claude reads `assignment.assignmentCandidates` and `assignment.advice`.
3. It assigns with a real member id from that list (or resolves a name you gave — it will not invent ids).
Passing the **order / project id** makes assignee suggestions much stronger (order team + PM + how many open items they already own on that order).
## Owner insights (workspace)
These tools scan recent lists and return **heuristic** owner dashboards (not a full data warehouse). Always drill into a real id from the result. Shipped in **`agencyhandy-mcp@1.7+`** (current **1.7.2**).
| Insight | Tool | What you get |
| --------------------- | ---------------------- | ---------------------------------------------------------------------------------------- |
| **Cash / AR risk** | `ah_cash_risk` | Aging buckets (0–7 … 90+), total due, top clients by amount owed |
| **Proposal pipeline** | `ah_proposal_pipeline` | Waiting-on-client, stale sent, expiring soon |
| **Lead segmentation** | `ah_lead_segments` | Counts by status & source; optional breakout by a lead custom field name (e.g. Industry) |
| **Client churn risk** | `ah_client_churn_risk` | Scored clients from overdue invoices + quiet orders (heuristic) |
| **Morning snapshot** | `ah_dashboard_digest` | Open invoices, overdue work, new leads |
## Lead and client custom fields (MCP)
Custom fields are workspace definitions under **Workspace Config** → **Custom Fields**. Lead fields and client fields are **separate** lists.
**Typical flow**
1. List definitions (`ah_custom_field_list` with type `lead` or `client`) — copy the real `_id`.
2. Fill values with `ah_custom_field_set_values`, or pass `customFields` when creating a lead/client.
3. To change a value later, load the person with `ah_member_custom_fields` and prefer an existing filled-value id when one is returned.
**Duplicate definitions**
* Within **leads**, names must be unique (case and spacing ignored). Creating `Industry` again returns **Field already exists** and does not add a second lead field.
* Within **clients**, the same rule applies.
* The same display name **can** exist once on leads **and** once on clients — different owners, different ids. Always pick the id for the owner you mean (`lead` vs `client`).
Never invent field ids. If a create is rejected as a duplicate, list fields and reuse the existing id.
## When two people share a name
If two teammates are both named Sara, Claude will ask which one you mean. It does **not** invent IDs or guess silently.
Always include a **full name** or **email** in the prompt when names might collide.
## What works now vs not yet
| Works now (`agencyhandy-mcp@1.7.2+`) | Not available from MCP yet |
| --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| Morning briefings and deep lookups (proposal, order, task, ticket, invoice context packs) | Replying in **client chat** from MCP |
| **Recommend who to assign** on tasks/tickets (ranked candidates + workload), then assign | Full BI / warehouse-grade reporting |
| **Cash risk**, **proposal pipeline aging**, **lead segments**, **client churn heuristics** | — |
| **API builder context** (`ah://api-context`) for leads, orders, tasks, comments, labels, clients, invoices, vouchers, forms | — |
| Investigate orders / proposals / invoices with linked records | — |
| Create leads and clients; list/create/fill **custom fields** | — |
| Send invoices and mark invoices paid | — |
MCP supports both reading your workspace and taking actions (create, assign, send, update) with your API key. Client chat replies are not exposed through MCP yet. Owner insights are sample-based heuristics — confirm before big decisions.
## Related
* Generate keys and copy config in-app under **Workspace Config** → **API Key**
* Package: [`agencyhandy-mcp`](https://www.npmjs.com/package/agencyhandy-mcp) on npm — use `npx -y agencyhandy-mcp@1` (latest **1.7.2**)
* [Lead Custom Fields](/crm/lead-custom-fields) · [Client Custom Fields](/crm/client-custom-fields)
# Bank Transfer, Crypto, and Wise Payment Methods Setup
Source: https://docs.agencyhandy.com/integrations/other-payments
Enable manual payment alternatives — bank wire transfer, cryptocurrency, and Wise — so clients who prefer non-card methods can pay your invoices.
AgencyHandy supports three manual payment methods in addition to Stripe and PayPal: **Bank Transfer**, **Crypto**, and **Wise**. Each is designed for a specific type of client or workflow. All three require you to manually mark an invoice as **Paid** after you receive the funds, since AgencyHandy cannot automatically confirm off-platform transfers.
Only **SuperAdmin** and **Admin** roles can enable or configure these payment methods.
## Bank Transfer
The Bank Transfer method lets you accept manual wire or ACH payments from clients. You provide your banking details through a rich-text editor, and AgencyHandy displays those instructions to clients during checkout and inside the invoice.
### Enable Bank Transfer
In the left sidebar, go to **Integrations → Bank Payment Method**.
Use the rich-text editor to enter your banking details. Include all fields your clients need to complete the transfer:
* **Recipient's Name**
* **Account Number**
* **Bank Name**
* **Routing Number**
* **Account Type** (e.g., Checking, Savings)
* **Bank Address**
You can also add memos, notes, or a support contact. There is no character limit, and the editor supports bold, underline, lists, links, and image formatting.
Toggle **Payment Screenshot is Required** if you want clients to upload a screenshot before their order is processed.
* **Enabled** — clients must upload a valid screenshot at checkout. No order is created until a file is uploaded.
* **Disabled** — clients can proceed without uploading proof. The order and invoice are created immediately.
Click **Update** to save your setup. Click **Cancel** to discard changes.
### Client experience
When a client selects Bank Transfer at checkout, they see your custom transfer instructions. If proof is required, a file-upload prompt appears and the order is held until they upload a screenshot.
After you receive the funds in your bank account, open the invoice in AgencyHandy and manually mark it as **Paid** to release the order.
Include a unique reference code in your instructions (e.g., the invoice number) so you can match incoming transfers to specific orders without confusion.
## Crypto Payment
The Crypto Payment method lets you accept cryptocurrency from clients using a wallet-based transfer. You configure your wallet details and instructions once; clients see them at checkout and in the invoice. Currently, **USDC** is the supported cryptocurrency.
### Enable Crypto Payment
In the left sidebar, go to **Integrations → Crypto Payment**. A wallet setup screen opens with a rich-text editor.
Fill in the following fields:
* **Cryptocurrency Type** — currently USDC is supported.
* **Wallet Address** — your public wallet address for receiving funds.
* **Network Type** — e.g., ERC-20, TRC-20.
* **Additional Instructions** — memo, tag, minimum amount, support contact, or any other guidance for your clients.
Toggle **Require Proof of Payment**:
* **Enabled** — clients must upload a file (e.g., a transaction screenshot) before the order and invoice are created.
* **Disabled** — an order and invoice are created as soon as the client selects crypto payment, without requiring proof.
Click **Save** to store your setup. You can edit or disconnect Crypto Payment at any time from the same screen.
### Client checkout flow
When a client selects Crypto at checkout:
1. An **Order** (status: *Pending*) and an **Invoice** (status: *Open*) are created.
2. The client is shown your wallet address and instructions.
3. If proof is required, a file-upload button appears. The client must upload their transaction screenshot before the order proceeds.
4. After the transfer is complete and you have verified the funds on-chain, open the invoice in AgencyHandy and mark it as **Paid**.
5. When an invoice is marked **Paid** and the order is *Pending*, the order status automatically updates to *Ongoing*.
Crypto Payment only appears at checkout if it is enabled in **Workspace Settings → Payment Methods** AND in the relevant **Service Group → Payment Availability** settings. Disabling it in Workspace Settings hides it everywhere, regardless of service-level settings.
If a service does not support USDC, the Crypto payment option is automatically hidden for that service. Make sure USDC is enabled in your service settings if you want clients to pay with crypto.
## Wise Payment
The Wise Payment method lets clients pay via a Wise payment link. You add the link once inside an invoice, and it is automatically included in all future subscription invoices. Wise is ideal for international clients who prefer bank-to-bank transfers with lower fees than traditional wire transfers.
### Add Wise as a payment method
In the left sidebar, click **Invoices**, then click **Create Invoice**.
Inside the invoice modal, scroll to the **Payment Methods** section. Click **Add Wise as a payment method**, then paste your Wise payment link into the input field.
Click **Save** or continue to finalize the invoice. Your Wise payment link is now embedded and visible to the client.
### How it works for clients
The Wise link appears as a clickable button on the client's invoice. The client opens the link, completes the transfer through their Wise account, and sends you confirmation. Because AgencyHandy does not receive automatic confirmation from Wise, you must manually mark the invoice as **Paid** after you receive the funds.
Wise **cannot** be used for automated upsell or marketplace payments. Only one Wise payment link can be added per invoice. Double-check the link before sending — an incorrect link means the client's payment goes to the wrong account.
### Platform behavior
* Once a Wise link is added, it automatically appears on all future **subscription** invoices unless you update or remove it.
* AgencyHandy does not perform any automatic currency conversion. The client transfers in whatever currency your Wise link is configured for.
* You are responsible for tracking payments and marking invoices as Paid after confirming receipt.
# Connect PayPal for Secure Client Payment Collection
Source: https://docs.agencyhandy.com/integrations/paypal
Link your PayPal account to AgencyHandy and let clients pay invoices using PayPal's trusted, globally recognized payment platform.
AgencyHandy's PayPal integration gives your clients a secure, familiar way to pay invoices without a credit card. PayPal supports a wide range of international currencies, making it especially useful for agencies with clients outside of their home country.
PayPal **cannot** be used for upsells due to platform-level currency and regional limitations. For upsell payments, use Stripe instead.
Only **SuperAdmin** and **Admin** roles can connect or manage the PayPal integration. You must have an active PayPal account before you start.
## Connect PayPal
Sign in to AgencyHandy, then go to **Integrations → PayPal Integration** in the left sidebar.
Click **Connect PayPal**. You are redirected to PayPal's login page.
Sign in to your PayPal account and review the permissions requested. Click **Allow** (or **Grant**) to authorize AgencyHandy to access your account.
After successful authorization, PayPal redirects you back to AgencyHandy. A confirmation message — **PayPal Connected** — appears on the integration card. Clients can now pay invoices using PayPal.
## How clients pay via PayPal
Once the integration is active, a **Pay with PayPal** button appears on any invoice you send. Your client clicks the button, logs in to their PayPal account (or pays as a guest depending on their region), and completes the payment. AgencyHandy updates the invoice status automatically when payment is confirmed by PayPal.
## Supported currencies
AgencyHandy supports the following currencies for PayPal payments:
| Region | Currencies |
| ------------------- | ------------------------------------------- |
| Americas | USD, CAD, BRL, MXN |
| Europe | EUR, GBP, CHF, NOK, SEK, DKK, PLN, CZK, HUF |
| Asia-Pacific | AUD, NZD, JPY, HKD, SGD, MYR, PHP, THB, TWD |
| Middle East / Other | ILS, CNY |
Some currencies have restrictions:
* **JPY** and a few others do not support decimal amounts — avoid fractional invoice totals.
* **BRL** is only available for Brazilian PayPal accounts. If your account is not based in Brazil, BRL payments are automatically converted to your primary currency.
* Certain currencies are only available for in-country accounts. Confirm your account's holding currency matches your invoice currency to prevent errors.
PayPal applies its own conversion fees and spreads when currency conversion occurs. These are not controlled by AgencyHandy.
## Test the integration
Before using PayPal for real client invoices, run a quick test:
1. Create a test invoice in AgencyHandy using a [supported currency](#supported-currencies).
2. Send the invoice to a secondary PayPal account you control.
3. Complete the payment from the secondary account.
4. Return to AgencyHandy and confirm the invoice status updated to **Paid** and that the funds appear in your PayPal account.
# How to Setup Credit in AgencyHandy
Source: https://docs.agencyhandy.com/integrations/setup-credit
Offer services through a prepaid credit system: create packages, set conversion rates, and let clients purchase and spend credits on services and invoices.
Credits enable you to offer services through a prepaid system. You create credit packages with a price, set conversion rates that define how many credits one unit of currency buys, and clients purchase credits in advance. When a client orders a service or pays an invoice, AgencyHandy converts the price into credits, deducts the required amount, and records every transaction in a complete audit trail.
## How credits work
The credit system has three components:
* **Credit packages**: bundles of credits that clients purchase (for example, 500 credits for \$50).
* **Conversion rates**: rules that convert a service's currency price into credits (for example, 1 USD = 10 credits).
* **Credit balance**: the credits available to a client to spend on services or invoices.
**Example:** A service costs \$3.51 and the conversion rate is 1 USD = 10 credits.
`$3.51 × 10 = 35.1 credits → rounded up to 36 credits`
AgencyHandy always rounds up to the nearest whole credit.
![Credit Page]()
*Credit Page*
## Enable credit payments
Before clients can purchase or use credits, you must turn the feature on.
In the left sidebar, go to **Credits**.
Enable the **Allow Credit Payment** toggle.
![Toggle to turn on credit payment]()
*Toggle to turn on credit payment*
**When enabled**, clients can:
* See their credit balance widget in the client portal.
* Access the Credits page and purchase packages.
* Submit credit requests.
* Use **Buy with Credit** during service checkout.
* Use **Pay with Credit** on invoices.
**When disabled**, the credit widget and all credit options are hidden from the client portal. Existing credit balances are preserved, and clients can still use other payment methods.
## Create credit packages
Credit packages are what clients purchase to load credits onto their account.
Navigate to **Credits → Settings → Credit Packages**.
Click **+ Package**.
Enter a package name, the number of credits included, the currency, and the price.
Click **Create**.
![Credit Package List View]()
*Credit Package List View*
![Create Credit Package]()
*Create Credit Package*
## Manage conversion rates
Conversion rates determine how many credits are required for a service based on its currency price. You can set a different rate per currency.
Navigate to **Credits → Settings → Conversion Rates**.
Click **+ Add Conversion Rate**.
Select a currency and enter the number of credits equivalent to one unit of that currency.
Click **Save**.
![Conversion List Page]()
*Conversion List Page*
![Add Conversion Rate Form]()
*Add Conversion Rate Form*
**Example rates:**
| Currency | Rate |
| -------- | ------------------ |
| USD | 1 USD = 10 credits |
| EUR | 1 EUR = 9 credits |
| GBP | 1 GBP = 12 credits |
Only one active conversion rate can exist per currency at any given time.
## Automatic vs manual credit purchases
How credits are added to a client's account depends on the payment method used.
**Automatic** (no approval needed):
* Stripe
* PayPal
Credits are added immediately after a successful payment.
**Manual** (requires agency approval):
* Bank Transfer
* Cryptocurrency
When a client pays via a manual method, a credit request is created. You must review and approve it before credits are added.
## Manage credit requests
Navigate to **Billing → Credits**.
Review the client name, payment amount, and number of credits requested.
Click **Accept** to add the credits, or **Reject** to decline.
![Credit Requests]()
*Credit Requests*
**Request statuses:**
* **Pending**: submitted and awaiting review.
* **Accepted**: approved; credits have been added to the client's balance.
* **Rejected**: declined; no credits were added.
## View client credits
Navigate to **Clients** and click on a client's name.
Select the **Credits** tab.
![Viewing Client Credit]()
*Viewing Client Credit*
The Credits tab shows the client's available balance, full transaction history, running balance, and transaction references.
## Understand credit transactions
Every credit activity is recorded in the client's transaction history.
**In**: credits added to the account:
* Credit package purchase
* Approved credit request
**Out**: credits deducted from the account:
* Service purchased using credits
* Invoice paid using credits
Each transaction shows the date, type, reference, credit amount, and running balance, providing a complete audit trail.
## Frequently Asked Questions
No. Clients cannot purchase credits while the **Allow Credit Payment** toggle is disabled.
Existing balances remain unchanged. Clients simply cannot access or use the Credits feature until it is enabled again.
Yes. Credits purchased through Stripe and PayPal are added automatically after successful payment.
Yes. These payment methods create a credit request that must be reviewed and approved by the agency.
Yes. Agencies can approve or reject any pending credit request.
Yes. Agencies can review a client's balance and transaction history from the **Credits** tab within the client profile.
**In** indicates credits added to the client's account.
**Out** indicates credits deducted from the client's account.
The agency may have disabled credit payments, or the client may not have sufficient credits available.
The agency may have disabled credit payments, or the client may not have sufficient credits available to cover the invoice amount.
# Connect Slack to Receive Real-Time AgencyHandy Alerts
Source: https://docs.agencyhandy.com/integrations/slack
Link your Slack workspace to AgencyHandy so order updates, task changes, and ticket alerts are posted to a Slack channel automatically.
AgencyHandy's Slack integration keeps your team in the loop without requiring anyone to switch between apps. Once connected, AgencyHandy posts automatic notifications to the Slack channel of your choice whenever tasks, orders, or other workspace activities change — so your team always knows what's happening in real time.
Only **SuperAdmin**, **Admin**, and **Manager** roles (with integration permissions) can connect or manage the Slack integration. You need Slack workspace admin rights to authorize the connection.
## Connect Slack
In the left sidebar, click **Integrations**.
Scroll to the **Slack** card and click **Connect**.
A Slack authorization window opens. If you are not already signed in to your Slack workspace, sign in now. Review the permissions AgencyHandy requests and click **Allow** to grant access.
After authorization, choose the Slack channel where you want AgencyHandy notifications to appear. Select a channel from the dropdown and click **Save** to confirm.
The Slack card updates to show **Connected**. AgencyHandy immediately begins posting notifications to the selected channel.
## What notifications are sent to Slack
AgencyHandy posts a Slack message whenever any of the following events occur:
| Category | Events that trigger a notification |
| -------------------- | --------------------------------------------- |
| **Tasks** | Task created, updated, assigned, or completed |
| **Orders** | Order created or status changed |
| **Comments** | New comment added to a task or order |
| **File attachments** | File or attachment added to a task |
| **Tickets** | Ticket created, assigned, or status changed |
Each Slack message includes:
* The **name** of the task, order, or ticket
* The **status change** or action that triggered the message
* A **link** back to the relevant item in AgencyHandy
When a file or attachment is added to a task, the Slack message also includes a preview of that attachment.
Choose a dedicated **#agency-handy-alerts** channel (or similar) to keep notifications organized and prevent them from cluttering your main team channels.
## Disconnect Slack
To stop notifications, return to **Integrations** and click **Disconnect** on the Slack card. All notifications stop immediately.
## Important notes
* **One workspace per connection** — you can only connect a single Slack workspace to each AgencyHandy workspace. To switch to a different Slack workspace, disconnect the current one and reconnect.
* **Channel visibility** — notifications are visible to everyone in the selected Slack channel. Make sure the channel is appropriate for the level of detail being shared (e.g., avoid posting client-sensitive order details to a public channel).
* **Re-authorization** — if your Slack token expires or permissions change, return to Integrations and reconnect to restore notifications.
# Connect Stripe to Accept Online Payments in AgencyHandy
Source: https://docs.agencyhandy.com/integrations/stripe
Link your Stripe account to AgencyHandy to send invoices and collect secure online payments from clients without leaving the platform.
AgencyHandy's Stripe integration lets you accept card payments directly from your clients through invoices you send inside the platform. Once connected, your clients see a familiar Stripe-hosted checkout, and payment status syncs back to AgencyHandy automatically — no manual reconciliation needed.
Only **SuperAdmin** and **Admin** roles can connect or manage the Stripe integration. You must also have a verified Stripe account with the appropriate permissions before starting.
## Connect Stripe
In the left sidebar, navigate to **Integrations → Stripe Integration**.
Click **Connect Stripe**. You are redirected to Stripe's authorization screen. Sign in to your Stripe account and click **Allow** to grant AgencyHandy access. Once approved, Stripe redirects you back to AgencyHandy automatically.
After the redirect, configure the following options:
* **Currency** — choose the default billing currency for your workspace.
* **Payment methods** — enable or disable card types (Visa, Mastercard, etc.) as supported by your Stripe account.
* **Billing preferences** — optionally set a tax rate, invoice prefix, or default payment terms and due dates.
Click **Save**. A confirmation banner appears when the integration is active. Stripe is now linked to your workspace and your clients can pay invoices online.
## Test the integration
Before sending live invoices, run a quick end-to-end test to confirm the connection is working correctly.
Create a draft invoice inside AgencyHandy and assign it a small amount.
Send the invoice to your own email address or to a team member who can help with the test.
Open the invoice link and complete the payment using a Stripe test card (e.g., `4242 4242 4242 4242`) if your Stripe account is in test mode, or a real card in live mode.
Return to AgencyHandy and confirm that the invoice status changed to **Paid**. If it did, your integration is working correctly.
## Manage your Stripe connection
Return to **Integrations → Stripe Integration** at any time to:
* **Update payment settings** — change currency, payment methods, or billing preferences.
* **Review connection status** — check whether Stripe is currently active.
* **Disconnect** — click **Disconnect** to unlink your Stripe account. Payment collection pauses immediately until you reconnect.
* **Reconnect** — click **Connect Stripe** again and reauthorize to restore the integration.
Disconnecting Stripe pauses payment collection for all outstanding invoices. Clients will not be able to pay online until you reconnect and re-authorize.
## Additional notes
AgencyHandy never stores your payment credentials. All payment data is handled exclusively by Stripe's secure infrastructure.
* **One account per workspace** — you can only connect a single Stripe account to each AgencyHandy workspace. To switch accounts, disconnect the current one first, then reconnect with the new account.
* **Live invoice status** — all invoices linked to Stripe continue to reflect real-time status updates received directly from Stripe.
* **Currency** — make sure the currency configured in AgencyHandy matches the currency enabled in your Stripe account to avoid payment errors.
# Webhook Management: Create, Test, and Authenticate
Source: https://docs.agencyhandy.com/integrations/webhooks
Set up webhooks in AgencyHandy to push real-time event data to external systems whenever orders, tasks, invoices, or other entities change.
Webhooks let AgencyHandy push data to your external systems the moment something changes — no polling required. When a configured event fires (for example, an order is updated or a ticket is created), AgencyHandy sends an HTTP POST request with a JSON payload to the endpoint URL you specify. This makes it easy to keep external tools like CRMs, billing systems, or custom dashboards synchronized with your AgencyHandy workspace in real time.
Business Pro plan workspaces support up to **30,000 webhook events** per billing period. Check your plan limits before setting up high-volume automations.
## Supported events
You can subscribe a webhook to any combination of the following events:
| Category | Events |
| ------------------- | ------------------------------------- |
| **Service** | Created, Updated, Deleted |
| **Order** | Created, Updated, Deleted |
| **Task** | Created, Assigned, Completed, Updated |
| **Invoice** | Status changed |
| **Client / User** | New client added, Client/user deleted |
| **Proposal** | Sent, Received, Accepted, Rejected |
| **Ticket** | Created, Assigned, Status changed |
| **Payment** | Received, Failed |
| **Service Package** | Created, Updated, Deleted |
## Create a webhook
In the left sidebar, go to **Integrations → Webhooks Management**.
Click the **Management** button to authenticate your webhook token. This token is used to sign outgoing payloads so you can verify they originated from AgencyHandy.
Click **Create New Webhook** to open the webhook configuration form.
In the **Endpoint URL** field, enter the URL of the external system that should receive the webhook data. This must be a publicly accessible **POST** endpoint.
Choose **JSON** as the content type. AgencyHandy sends all webhook payloads as `application/json`.
Choose every event that should trigger this webhook. You can select events from multiple categories — for example, **Order: Created** and **Invoice: Status changed** can both point to the same endpoint.
Toggle the **Active** radio button. When active, AgencyHandy delivers payloads for all selected events to your endpoint in real time.
Review your settings, then click **Save**. The webhook appears in the list and starts delivering events immediately.
## Test a webhook
After creating a webhook, send a test payload to confirm your endpoint is reachable and processing data correctly.
From the Webhooks Management list, click the webhook you want to test.
Click the **Test Event** button on the webhook detail page.
Choose a sample event from the list of events configured on this webhook (e.g., **Order: Created**).
Click **Send**. AgencyHandy posts a sample payload to your endpoint URL.
Check your external system to confirm the test payload arrived and was processed as expected. Back in AgencyHandy, click into the webhook to review its **history** — you can see the full request, the response your endpoint returned, and redeliver any past event if needed.
Use a tool like [Webhook.site](https://webhook.site) or [RequestBin](https://requestbin.com) as a temporary endpoint during setup to inspect the exact payload shape before wiring up your real system.
## Authenticate webhook payloads
Every outgoing webhook request from AgencyHandy includes a signature header that your endpoint can use to verify the payload is genuine and hasn't been tampered with.
### Signature header
```
x-ah-sig:
```
AgencyHandy adds this header to every webhook request. Extract the value from incoming requests and pass it to the verification endpoint.
### Verify a webhook signature
Send the following request to confirm a payload is authentic:
```
POST https://api.agencyhandy.com/api/v1/webhooks/verify-signature
Content-Type: application/json
```
The ID of the webhook that received the event. Find this on the webhook detail page in AgencyHandy.
The value of the `x-ah-sig` header from the incoming webhook request.
The webhook secret shown on the webhook detail page in AgencyHandy.
The raw JSON body received from AgencyHandy's webhook request.
```javascript JavaScript theme={null}
const url = 'https://api.agencyhandy.com/api/v1/webhooks/verify-signature';
const postData = {
webhookId: 'your_webhook_id',
signature: 'your_signature', // value of x-ah-sig header
secret: 'your_webhook_secret',
payload: {}, // the parsed JSON body from AgencyHandy
};
const response = await fetch(url, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(postData),
});
const data = await response.json();
console.log(data); // { "verification_status": "SUCCESS" }
```
```bash cURL theme={null}
curl -X POST https://api.agencyhandy.com/api/v1/webhooks/verify-signature \
-H "Content-Type: application/json" \
-d '{
"webhookId": "your_webhook_id",
"signature": "your_signature",
"secret": "your_webhook_secret",
"payload": {}
}'
```
**Responses**
`SUCCESS` when the signature is valid. `FAILED` when verification fails (HTTP 403).
```json Success (200) theme={null}
{
"verification_status": "SUCCESS"
}
```
```json Failure (403) theme={null}
{
"type": "PermissionError",
"status": 403,
"verification_status": "FAILED"
}
```
Keep your webhook secret confidential. Rotate it periodically and update your verification logic immediately after rotation. Never expose it in client-side code or public repositories.
## Important notes
* Your endpoint URL must be a **publicly accessible HTTPS POST** URL.
* If your endpoint is temporarily unavailable, check the webhook's history panel in AgencyHandy — you can **redeliver** any past event directly from there.
* Regularly monitor webhook activity to detect failed deliveries or unauthorized access attempts.
* Webhooks that fail repeatedly may be paused by AgencyHandy — review delivery logs to catch issues early.
# Create, Send, and Manage Client Invoices in AgencyHandy
Source: https://docs.agencyhandy.com/invoices/create-invoice
Step-by-step guide to creating an invoice in AgencyHandy — choose a client, set amounts, add notes, send to client, and configure payment reminders.
Creating an invoice in AgencyHandy is a straightforward process that ties your billing directly to clients and orders. You fill in the client, link the order, set amounts, add any notes, and send — all from a single form. Once sent, you can track payment status, set automated reminders, and download the invoice as a PDF at any time.
You must be a **Super Admin**, **Admin**, or **PM** to create invoices. At least one client must exist in your workspace before you can generate an invoice.
## Invoice Prefix Settings
Before you start creating invoices, consider configuring your invoice prefix. The prefix appears before every invoice number and helps identify invoices as belonging to your agency.
In the Invoice Dashboard, click the **Settings** button in the top-right corner.
Navigate to the **Invoice Prefix** field and enter the prefix you want (for example, `INV-` or your agency's initials).
Click **Save** to apply the prefix to all future invoices.
## Creating an Invoice
Click **Invoices** in the left sidebar to open the Invoice Dashboard.
Click **+ Create Invoice**. The invoice creation form will open.
Choose the client's name from the dropdown list. This is a required field. All Order IDs associated with that client will populate automatically in the next field.
To create a **Direct Invoice** (not linked to an order), you can leave the Order ID field empty or select **Independent Email** to invoice any email address outside your client list.
Select the specific Order ID you are billing for. This links the invoice to the correct order in the system. For direct invoices, skip this field.
Fill in the **Bill Payment Address**:
* Country, State, and City
* Zip code
* Street address (if applicable)
This address appears on the printed invoice for compliance and clarity.
Under **Order Details**, enter the following:
| Field | Description |
| ---------------------------------------- | -------------------------------------------- |
| **Currency** | The currency in which you want to be paid |
| **Order ID – Amount** | The monetary value associated with the order |
| **Discount (%)** and **Discount Amount** | Apply any applicable discounts |
| **Paid Amount** | Any amount the client has already paid |
| **Due Amount** | The outstanding balance remaining |
| **Total Amount** | The full payable amount for the order |
For **Direct Invoices**, click **Add Item** to add line items manually. Enter the item name, quantity, and price. You can add multiple items. Use **+ Tax Rates** to apply or create tax rates (inclusive or exclusive).
In the **Note** field, add any additional context for the client — for example, payment instructions, project references, or a personal message.
The right-side **Details** panel gives you a live summary of:
* Invoice status (Draft by default)
* Client name, company name, and address
* Bill payment address
* Service name and Order ID
* Created date and due date
* Total amount
Review everything carefully before proceeding.
* Click **Send to Client** to email the invoice immediately. The status changes from **Draft** to **Open** automatically.
* Click **Save as Draft** if you want to finalize it later.
The agency logo and address are added to the invoice automatically by the system — you don't need to enter them manually on each invoice.
## Invoice Status Transitions
Once an invoice is created, it follows a defined status flow. Only the agency can move an invoice between statuses.
```
Draft → Open (when sent to client)
Open → Paid (payment received)
Open → Void (invoice canceled)
Open → Uncollectable (debt written off)
```
Invoices can only be **edited** while they are in **Draft** status. Once an invoice is moved to Open, you cannot edit it. If you need to make changes, void the invoice and create a new one.
## Editing an Invoice
You can edit an invoice only while it is in **Draft** status.
In the Invoice Dashboard, find the draft invoice you want to edit. Click it or tick the checkbox next to it.
Select the **Edit** option from the action menu. The invoice form will open with all existing details pre-filled.
Update any fields — billing details, service descriptions, quantities, amounts, or payment terms.
Click **Save** to apply your changes.
## Sending an Invoice to a Client
If you saved the invoice as a draft and want to send it later:
In the Invoice Dashboard, locate the draft invoice you want to send.
Open the invoice and click the **Send Invoice** button. AgencyHandy delivers the invoice to the client's email address on file.
Check for the confirmation message to verify the invoice was sent successfully. The invoice status updates to **Open**.
If an invoice is in **Draft** status and you update the service name, the new name will be reflected in the invoice. Once the status changes to Open, Paid, Uncollectable, or Void, the service name on the invoice is locked and will not update.
## Downloading and Printing an Invoice
Both the agency and the client can download an invoice at any time.
Go to the Invoice Dashboard and select the invoice you want to download.
Click the **Download** or **Print** option from the invoice action menu.
Select **PDF** for downloading or choose your printer settings for a physical copy.
Save the file to your device or send it to the printer. After printing, archive the invoice or share it with stakeholders as needed.
## Setting Reminders on Invoices
The Invoice Reminder feature lets you automatically notify clients about upcoming, due, or overdue invoices so you get paid on time without manual follow-up.
Reminders only work on invoices that have an **Open** status and a set **due date**.
Click the **Settings** button at the top right of the Invoice Dashboard.
Scroll to the bottom of the **Template** section in the left panel, then click **Edit** to open the reminder configuration modal.
Select one of the following:
* **Sequenced Reminder** — creates a series of reminders at intervals you define
* **Don't Send Reminder** — disables reminders for the selected invoices
For each reminder in the sequence:
* Choose the **reminder template** (for example, "Upcoming Invoice Payment Reminder")
* Set the **remind date** — for example, 3 days before or after the due date
* Specify whether it triggers **before** or **after** the due date
Click **+ Add Another Reminder** to build a full reminder sequence. Click the **Delete** button next to any reminder to remove it.
Tick the checkbox to **apply these reminder settings to currently active invoices** if you want the new configuration to cover invoices already in Open status.
Click **Update** to save and activate the reminder schedule.
## Direct Invoices (Without an Order ID)
When you need to bill a client quickly without creating an order first, use the Direct Invoice workflow.
Go to **Invoices → Create Invoice**.
Select **Individual** or **Company** as the recipient type.
* Choose an **existing client** from the dropdown, or
* Select **Independent Email** to type any email address — even one not registered as a client
Skip the Order ID field. AgencyHandy creates a standalone invoice not linked to any order.
Click **Add Item** to add line items with names, quantities, and prices. Apply tax rates and discounts as needed. The total updates automatically.
Enter the bill payment address and add any notes for the client.
Click **Send Invoice** to deliver it immediately, or **Save as Draft** to review it first.
Direct Invoices are perfect for rush requests, consulting calls, or any work you need to bill for outside the normal order workflow. Payment tracking for standalone invoices must be managed manually.
# Invoice Management Overview for AgencyHandy Agencies
Source: https://docs.agencyhandy.com/invoices/overview
Explore AgencyHandy's invoicing system — billing, payment tracking, recurring invoices, statuses, direct invoices, and financial record exports.
AgencyHandy's invoice feature gives your agency a complete billing and payment management system inside the same platform you use to manage clients, orders, and projects. You can create professional invoices, send them to clients by email, track payment status in real time, automate recurring billing for subscription services, and export your financial records whenever you need them. Every invoice is tied to your agency's logo and address automatically, keeping your communications consistently on-brand.
## Who Can Create Invoices
Only users with the following roles can create and manage invoices:
* **Super Admin**
* **Admin**
* **Project Manager (PM)**
Clients can view and download invoices but cannot create or edit them.
## Invoice Dashboard
To open the Invoice Dashboard, click **Invoices** in the left sidebar. From here you can:
* Create, edit, and delete invoices
* Search invoices by **client name**, **order ID**, or **service name**
* Filter and sort the invoice list
* View invoice status at a glance
* Access invoice settings including prefix configuration
## What Invoices Do
Create and send professional invoices for any service or product you deliver to clients, with full control over amounts, discounts, and due dates.
Monitor whether invoices have been viewed, paid, or are overdue. The system automatically records paid dates and void dates as status changes occur.
Automate invoice generation for subscription-based services. AgencyHandy generates and delivers recurring invoices on each billing cycle without manual intervention.
Link invoices directly to orders and services so billing is always tied to the underlying work. Billable items can be added accurately to each invoice.
## Invoice Statuses
Every invoice moves through a defined lifecycle. Understanding these statuses helps you manage your receivables effectively.
| Status | Description |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Draft** | The invoice has been created but not finalized. You can edit any part of it. Once ready, finalize it by changing the status to Open. Draft invoices not tied to a subscription can be deleted. |
| **Open / Unpaid** | The invoice is finalized and awaiting payment. The agency sends this to the client, who can view and pay it. You can change an Open invoice to Paid, Void, or Uncollectable. |
| **Paid** | The invoice has been paid. The system records the paid date automatically when you mark an invoice as Paid. |
| **Void** | The invoice has been canceled. The system records the void date automatically. |
| **Uncollectable** | The client is unlikely to pay. Treat this as bad debt in your accounting process. |
When you send an invoice to a client using the **Send to Client** button, the status automatically changes from **Draft** to **Open**. Only the agency can change the status from Open to Paid, Void, or Uncollectable.
## Direct Invoices (Without an Order ID)
AgencyHandy supports **Direct Invoices** — invoices that are not linked to any existing order. This is useful for one-off billing, ad-hoc payments, or invoicing contacts who are not yet registered as clients in your system.
Key capabilities of Direct Invoices:
* Send invoices without selecting an Order ID
* Invoice any existing client or use **Independent Email** to send to any email address
* Add items, taxes, and discounts manually
* Send immediately or save as a draft
Use Direct Invoices when you need to bill a client quickly for work that doesn't have a formal order in AgencyHandy, such as rush projects, consulting calls, or out-of-scope work.
## Exporting Invoices
You can export your invoice list for use in external accounting tools or for record-keeping. The export includes all visible columns: invoice ID, client name, service, amounts, status, and dates. Access the export option from the Invoice Dashboard.
## Invoice Settings
Configure global invoice settings from the **Settings** button in the top-right corner of the Invoice Dashboard. This includes:
* **Invoice prefix** — customize the prefix that appears before every invoice number
* **Reminder templates** — set up automated payment reminders for open invoices
## Related Features
Step-by-step guide to creating, filling out, and sending an invoice.
How recurring billing works and how to manage subscription invoices.
Handle client billing questions through the support ticket system.
# Subscription Billing and Recurring Invoices in AgencyHandy
Source: https://docs.agencyhandy.com/invoices/subscriptions
How AgencyHandy handles recurring subscription billing — automated invoices, billing cycles, payment methods, cancellations, and Wise payment links.
AgencyHandy's subscription billing system lets you automate the entire recurring revenue workflow. When a client subscribes to a service, the platform creates a Subscription ID, generates orders, and issues invoices automatically on each billing cycle — whether that's daily, weekly, monthly, or yearly. You stay in control: you can view subscription details, monitor payment history, handle failed payments, and cancel subscriptions when needed, all from within AgencyHandy.
## How Subscription Billing Works
The subscription lifecycle in AgencyHandy follows six key stages.
Navigate to **Services** and click **Create New Service**. Select **Subscription** as the service type.
Define:
* **Billing Cycle** — Daily, Weekly, Monthly, or Yearly
* **Renewal Behavior** — Create New Order, Update Existing Order, or Keep Unchanged
* **Pricing & Payment Method** — PayPal, Stripe, or Manual
Click **Publish** to make the service available.
The client selects the subscription service, proceeds to checkout, and chooses a payment method.
AgencyHandy automatically:
* Creates a **Subscription ID**
* Generates an **Order**
* Issues an **Invoice**
For **PayPal or Stripe** payments, the invoice is marked **Paid** instantly. For **Manual Payment**, the invoice stays **Open** until the agency confirms receipt.
On each renewal date, AgencyHandy processes the payment automatically (for PayPal/Stripe) and generates the next invoice.
If payment succeeds, the invoice is marked **Paid**. If it fails:
* The invoice remains **Open**
* The client receives a **Failed Payment Notification**
* The agency receives an alert to retry or request updated payment details
Navigate to **Subscription Management** in the left sidebar to view all active and inactive subscriptions. Select any subscription to see its full details.
When you cancel a subscription, you can choose to:
* **Cancel completely** — stop all future billing and orders
* **Keep the last active order running** — let the client continue receiving service through the current period's deadline
To delete a service entirely, all active subscriptions on that service must be canceled first.
The system automatically sends:
* **Renewal Reminders** before the next billing date
* **Payment Confirmations** after successful charges
* **Failed Payment Alerts** to both the client and agency admins
## Subscription Details Page
The Subscription Details page gives you a complete picture of any individual subscription — from the service and package down to every invoice and event log entry.
### How to Access
1. Go to **Subscriptions** in the left sidebar
2. Click on any subscription from the list to open its detail page
### What You Can See
* **Service Name** and **Package Name**
* **Client Name**
* **Billing Cycle** (e.g., Monthly, Yearly)
* **Kick Off Date** and **End Date**
* Subscription **Status** (Active or Inactive)
* **Subscription Fee**
* **Total Number of Payments** made to date
* **Payment Method** (Stripe, PayPal, Wise, Manual Banking, etc.)
* **Next Payment Date**
* **Order ID**
* **Status** (e.g., Ongoing, Completed)
* **Kick Off Date** and **Due Date** for each order
* **Invoice ID**
* **Amount**
* **Status** (Open, Paid, etc.)
* **Payment Date** and **Due Date**
A chronological audit trail of all activities related to the subscription — status changes, payment events, cancellations, and more.
A single subscription can have multiple linked orders and invoices. Invoices tied to subscriptions update dynamically when payments are received.
## Wise Support for Manual Subscription Invoices
If you collect international payments, you can embed a **Wise payment link** directly into subscription invoices. This gives clients a convenient way to pay without needing to set up a bank transfer manually.
### Requirements
* An active AgencyHandy account
* An active **Wise account** with a valid payment link generated
### Steps to Add a Wise Link to an Invoice
Click **Invoices** in the left sidebar, then click **+ Create Invoice**.
Choose the client from the dropdown. All related Order IDs will appear. Select the relevant Order ID and enter the amount and any items being billed.
Add any applicable discount percentage, discount amount, paid amount, due amount, and VAT/tax details. Include billing address and notes as needed.
In the **Payment Method** section, select **Wise** as the payment option. Paste your Wise payment link into the provided field.
Click **Save** to finalize the invoice. The Wise payment link will appear in the invoice so the client can pay directly.
Always double-check your Wise payment link and invoice totals before saving. Verify that the order details, discounts, and tax information are accurate to avoid billing errors.
## Important Notes on Subscription Billing
Only **Super Admins** and **Admins** can cancel subscriptions. Clients cannot cancel their own subscriptions — they must request cancellation through the agency.
Once a subscription is created, its Subscription ID cannot be edited. This ensures consistent tracking throughout the subscription's lifetime.
When a payment fails, the invoice remains Open and a new order is created for the failed period. The subscription status stays **Active** until an admin manually retries the payment or cancels the subscription.
If a client pays outside of Stripe or PayPal (e.g., via bank transfer), the admin must manually mark the invoice as **Paid** in AgencyHandy. The system does not do this automatically for manual payments.
If a client starts a subscription checkout but does not complete payment, they remain in the system as a **Lead** until they successfully subscribe.
Due dates for subscription invoices are set automatically based on the billing cycle you configured (e.g., monthly invoices are due one month after the kick-off date).
# How to Create, Edit, and Delete Orders in AgencyHandy
Source: https://docs.agencyhandy.com/orders/create-order
Step-by-step guide to creating, editing, and deleting orders in AgencyHandy — including role requirements, form fields, and status transitions.
Creating an order in AgencyHandy gives you a structured workspace for delivering a service to a client. You fill in the key details upfront — client, service, pricing, dates, and a project brief — and everything else, from tasks to discussions, flows from that single record. This page walks you through creating an order from scratch, updating it after the fact, changing its status, and deleting it when it is no longer needed.
## Requirements
* You must be logged in to AgencyHandy.
* You must hold a **Super Admin**, **Admin**, or **Project Manager** role to create or edit orders.
* Only **Super Admins** and **Admins** can delete orders.
## Create a New Order
In the left sidebar of your AgencyHandy dashboard, click **Orders**.
Click **+ Create New Order** in the top-right corner. A form will appear.
Complete the fields in the form:
| Field | Required | Notes |
| ------------------- | -------- | ------------------------------------------------------------ |
| **Client** | ✅ | Select from your existing client list |
| **Service** | ✅ | Includes both published and unpublished services |
| **Project Manager** | ❌ | Optional; assign a PM to own the delivery |
| **Quantity** | ✅ | Number of units being ordered |
| **Price** | ✅ | Agreed budget for the order |
| **Kick-off Date** | ✅ | When work begins |
| **Due Date** | ✅ | Delivery deadline |
| **Order Brief** | ❌ | Instructions, requirements, or reference notes for your team |
| **Attachments** | ❌ | Supporting files relevant to the order |
If the selected service has add-ons linked to it, an **Add-On** section will appear in the form. Include any relevant add-ons before submitting.
Double-check all fields for accuracy — especially the client, service, price, and due date.
Click **Create** to finalize the order. You will receive a confirmation message once it is created successfully.
### What Happens After You Create an Order
* All Super Admins in your company automatically gain access to the new order.
* The client receives a notification that their order has been created.
* The order appears in the **Orders** list with a status of **Pending**.
## Edit or Update an Order
You can update an order at any point to correct details, adjust pricing, change the due date, or accommodate client requests.
You must be a **Super Admin**, **Admin**, or **Project Manager** to edit an order.
Navigate to **Orders** in the left sidebar.
Locate the order you want to update and tick the checkbox beside it.
An **Edit** button will appear in the top-right corner. Click it to open the order details in edit mode.
Update any fields that need to change — client details, service, pricing, dates, brief, or assigned PM.
Click **Update** to save. A confirmation message will confirm the update was successful.
## Change an Order's Status
Order status reflects where a piece of work stands in your delivery pipeline. AgencyHandy defines five fixed statuses — you cannot add or rename them.
| Status | Meaning |
| ------------- | ----------------------------------------- |
| **Pending** | Created, not yet started |
| **Ongoing** | Actively being worked on |
| **In Review** | Submitted for review; awaiting acceptance |
| **Complete** | Delivered and accepted |
| **Cancelled** | No longer active |
Only **Super Admins**, **Admins**, and **Project Managers** can change an order's status. Employees and clients cannot change status.
To update the status, open the order and use the status selector at the top of the order detail page. Select the new status from the dropdown and confirm.
## Delete an Order
Deleting an order permanently removes it from the system. Use this only when an order is truly obsolete — for example, if it was created in error or is a duplicate.
Order deletion is irreversible. Once you delete an order, it cannot be recovered. Proceed with caution.
Only **Super Admins** and **Admins** can delete orders.
Click **Orders** in the left sidebar.
Scroll or search for the order you want to remove from the list.
Click the **trash bin icon** associated with the order.
A confirmation prompt will appear. Confirm to permanently delete the order.
After deletion, review your remaining orders to ensure everything is in order. The deleted entry will no longer appear in any list or report.
## Adding Team Members to an Order
Super Admins, Admins, and PMs can add employees to an order at any time. When a team member is added, they receive an in-app notification. Assigned employees gain visibility into the order and its tasks, but they cannot manage the order itself (edit details, change status, or delete it).
# Orders Overview: Managing Client Work in AgencyHandy
Source: https://docs.agencyhandy.com/orders/overview
Understand how orders work in AgencyHandy — statuses, roles, order details, manual orders, and add-ons for unpublished services.
Orders are the operational backbone of AgencyHandy. An order represents a client's request for a service or product, and it acts as the central workspace where your team tracks progress, manages tasks, exchanges feedback, and delivers results. Whether a client places an order through your published service catalog or your team creates one manually, every order follows the same structured lifecycle that keeps your agency organized and your clients informed.
## What an Order Contains
Every order surfaces key information at a glance and gives team members a single place to coordinate work:
| Field | Description |
| ------------------------ | -------------------------------------------------------- |
| **Order ID** | Auto-generated unique identifier for each order |
| **Client** | The client the order belongs to |
| **Service** | The service being delivered |
| **Project Manager (PM)** | The team member responsible for delivery (optional) |
| **Budget** | Agreed price for the order |
| **Kick-off Date** | When work begins |
| **Due Date** | Deadline for order completion |
| **Order Brief** | Client instructions, notes, and attached reference files |
| **Tasks** | Discrete work items assigned to team members |
| **Discussions** | Threaded conversations between agency staff and clients |
## Order Statuses
Every order moves through a fixed set of statuses. You cannot add or rename these statuses.
Only Super Admins, Admins, and Project Managers can change an order's status.
| Status | What It Means |
| ------------- | --------------------------------------------------------------------------- |
| **Pending** | The order has been created and is awaiting work to begin |
| **Ongoing** | Active work is in progress |
| **In Review** | Deliverables have been submitted and are awaiting client or internal review |
| **Complete** | The order has been fully delivered and accepted |
| **Cancelled** | The order has been cancelled and is no longer active |
## Role-Based Access
Different roles in AgencyHandy have different capabilities within orders:
| Role | Can Create Orders | Can Edit Orders | Can Delete Orders | Can Change Status | Can Add Tasks | Can Add Team Members |
| ------------------------ | ----------------- | --------------- | ----------------- | ----------------- | ---------------- | -------------------- |
| **Super Admin** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| **Admin** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| **Project Manager (PM)** | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ |
| **Employee** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| **Client** | ❌ | ❌ | ❌ | ❌ | ✅ (request only) | ❌ |
Clients can send feedback and participate in discussions on orders. Employees assigned to an order can view and work on tasks but cannot manage the order itself.
## What You Can Do With Orders
AgencyHandy gives you a full toolkit for managing orders throughout their lifecycle:
* **Create orders** for clients — either from published services or manually for services still in development
* **Accept and reject** client-submitted orders, with the option to provide a reason when rejecting
* **View order details** including progress, assigned team members, kick-off and due dates, budget, and brief
* **Sort, filter, and search** across all orders by ID, status, client name, or other criteria
* **Add tasks** directly within an order to track and assign discrete units of work
* **Start discussions** to communicate with clients and team members in context
## Manual Orders for Unpublished Services
You are not limited to creating orders only for services you have published publicly. Super Admins and Admins can create manual orders for unpublished services — useful when a service is still under development, temporarily unavailable, or being offered to a specific client before its official launch.
When you open the order creation form, the **Service** dropdown shows both published and unpublished services, so you can select whichever applies. All other order fields and workflows behave the same as a standard order.
## Add-Ons in Manual Orders
When building a manual order, you can include **add-on services** to let clients receive customized packages beyond the core service. Add-ons must be created in advance and linked to the relevant service in the **Forms** section before they appear as an option in the order form.
The add-on selection only appears in the manual order form if at least one add-on has been connected to the selected service. If you do not see it, verify that your add-on is properly linked in the service configuration.
Once a service with linked add-ons is selected, you can include those add-ons before finalizing and submitting the order.
## Notifications
AgencyHandy automatically notifies the right people as orders move forward:
* When an order is created by a PM, Admin, or Super Admin, all Super Admins in your company gain access and the client receives a creation notification.
* When a team member is added to an order, that member receives a notification.
* When tasks are created within an order, the client receives a notification.
# Task Management: Creating and Tracking Work in Orders
Source: https://docs.agencyhandy.com/orders/tasks
Create, edit, and manage tasks inside orders — including time tracking, file feedback, client-requested tasks, and cross-order task visibility.
Tasks are the units of work that turn an order into a deliverable. Each task lives inside a specific order, can be assigned to a team member, and tracks its own status, timeline, attachments, and feedback thread. This page explains how to create and manage tasks, how clients can request tasks, how time tracking and file feedback work, and how to view tasks across all orders at once.
## Role Requirements
| Action | Who Can Do It |
| -------------------------------- | ----------------------------------------------------------------------- |
| Create tasks | Super Admin, Admin, Project Manager |
| Edit tasks | Super Admin, Admin, Project Manager |
| Delete tasks | Super Admin, Admin, Project Manager |
| View tasks in review / done | Super Admin, Admin, PM, Client |
| Send and reply to feedback | Super Admin, Admin, PM |
| Log time on tasks | All assigned users (Superadmins and Admins can log on behalf of others) |
| Request a task (client) | Client |
| Approve / reject requested tasks | Super Admin, Admin |
Employees assigned to an order can see tasks that are in **In Review** or **Done** status. Tasks in **In Progress** are not visible to employees.
## Create a Task
Navigate to **Orders** in the left sidebar and click the order where you want to add a task.
Inside the order, scroll to the **Tasks** section and click **+ Add New Task**. A task creation form will appear.
Complete the available fields:
| Field | Notes |
| -------------------------- | --------------------------------------------------------------------------------------------------- |
| **Task Name** | A clear, concise title for the work item |
| **Description** | Detailed context, requirements, or instructions |
| **Assignee** | The team member responsible for completing the task |
| **Label** | Categorical tag for organizing tasks (e.g., Design, Copy) |
| **Start Date** | When work on the task begins |
| **Due Date** | When the task must be completed |
| **Client Review Required** | Checkbox that requires the client to approve the task before it is marked Done — checked by default |
| **Attachments** | Reference files or supporting materials |
Click **Save** to create the task. The client receives an automatic notification that a new task has been added to their order.
The **Client Review Required** checkbox is enabled by default on every new task. If a task is purely internal and does not need client sign-off, you can uncheck it before saving.
## Task Statuses
Tasks move through the following statuses:
* **In Progress** — The task is being worked on (not visible to clients or employees)
* **In Review** — The task has been submitted for review; visible to clients
* **Done** — The task has been approved and completed
When a client or reviewer rejects a task from **In Review**, its status automatically reverts to **In Progress**.
## Task Modal and Activity Page
Clicking on any task opens the **Task Modal**, a full-detail view that serves as the task's activity hub. From here you can see and manage:
* Current status, assignee, start date, and due date
* Task description and any attached files
* All feedback threads and replies
* A complete activity log showing every update, comment, and status change on the task
Anyone who is part of the order — including clients, when client review is enabled — can access the task modal for tasks they have visibility on.
## Edit a Task
To update a task's details after it has been created, open the task modal and modify the relevant fields (name, description, assignee, dates, label, or attachments). Save your changes to apply the update. Only Super Admins, Admins, and PMs can edit tasks.
## Delete a Task
To delete a task, open it and use the delete option in the task's action menu. Deletion is permanent — all associated time logs and file versions are removed along with the task.
Deleting a task also removes all file versions and their associated feedback comments. This action cannot be undone.
## Time Tracking
AgencyHandy includes built-in time tracking so your team can log hours directly against tasks — no external tool required.
### Starting the Timer
Go to **Orders → Tasks** and open the task you want to track time on.
Click **Start Timer**. The timer begins running and displays the task name, real-time elapsed time, and total time logged.
Click **Pause Timer** to temporarily halt tracking, or **Stop Timer** to finalize the entry. When you stop, you will confirm the date, start time, end time, total duration, and an optional note.
You can only have one active timer running at a time. Starting a new timer automatically pauses any existing one.
If a task is marked **Done**, the timer is disabled. Reopen the task to re-enable time logging.
### Manual Time Entry
If you need to log time retroactively, click **Manual Time Entry** on the task and enter:
* **Date**
* **Start Time and End Time** (or a **Duration** in hours and minutes)
* **Notes** (optional)
Multiple users can log time against the same task simultaneously. Superadmins and Admins can create manual time entries on behalf of any user.
### Work Logs
Click the **Work Log** button next to the timer to see a full breakdown of all time entries on the task, including date, start/end times, total active time, and any notes. Admins and Superadmins can delete any entry; regular users can only delete their own.
### Timesheets
Navigate to **Timesheets** from the left sidebar for a cross-order view of all time logged. You can filter by task name, order ID, assignee, or date range (daily, weekly, monthly), and group results by team member, service name, or task name. You can also start a timer or add a manual entry directly from the Timesheets view.
## File Feedback
AgencyHandy's file feedback system lets you and your clients leave precise, visual comments on deliverables — directly inside tasks. It supports images, PDFs, videos, and live websites, with version control and threaded discussions built in.
### Uploading a File for Review
Open the task, click the **➕** icon in the **Attachments** section, and upload an image, PDF, video, or paste a live website URL.
### Leaving Feedback by File Type
**Images and PDFs**
Open the file and use the annotation toolbar (Arrow, Line, Rectangle, Highlight) to mark up specific areas. Select a region, type your comment, and choose whether to share it with your team, the client, or both. You can also undo or redo annotations and change annotation colors.
**Videos**
Open the video and pause it at the exact frame where your feedback applies. Type your comment — the video pauses automatically while you type. The feedback is timestamped to that moment. You can remove the timestamp to leave a general comment instead.
**Live Websites**
Add the site URL to the task using the **➕** button, then install the AgencyHandy browser extension. Open the site in **View Mode** (interactive) or switch to **Review Mode** to take a screenshot and annotate it with draw, text, or shape tools.
### Comment Actions
Each comment has a three-dot menu with options to:
* Edit the comment
* Copy the reply
* Delete the comment
* Restrict visibility to the internal team only
### Resolving Feedback
Click the **✓** button on a comment to mark it as **Resolved**. Resolved comments remain visible for reference and can be reopened. You receive a notification when a comment you left is resolved by someone else.
### File Versions
Click **Upload New Version** to add a revised file. Previous versions and their feedback are preserved and accessible from the version dropdown. When opening an older version, AgencyHandy notifies you that a newer version exists.
You can label each file as **Needs Review** or **Approved** to communicate review status at a glance.
Clients can only leave feedback on files if the **Client Review Required** checkbox is enabled on the task. File feedback is available only inside tasks or orders — not in the service catalog or profile images.
## Client-Requested Tasks
Clients can submit task requests from their portal, giving them a structured way to surface additional needs without bypassing your approval process.
### Client Workflow
The client clicks **Requests** in their Client Portal sidebar — or uses the **+ Request a Task** button directly inside an order.
The client provides:
* **Order** (mandatory — requests must be tied to an existing order)
* **Task Name** (mandatory)
* **Description** (optional)
* **Attachments** (optional — up to 1 GB; formats include PDF, DOCX, JPG, PNG, MP4, ZIP, and more)
* **Start and End Dates** (optional)
The client clicks **Request**. The task appears in their portal as **Pending** and your agency receives a notification.
### Agency Workflow
Click **Requests** in the Agency Portal sidebar. All pending requests appear in a list view. You can filter by client or order ID, sort alphabetically or by issue date, and use **Preferences** to show or hide columns.
Click a request to read the description and preview any attachments before making a decision.
Use the action buttons beside each request to approve or reject individually — or use the top-right bulk actions to approve or reject all requests at once.
* **Approved** requests become active tasks in the order and follow the normal task workflow.
* **Rejected** requests remain logged with a **Rejected** status and are not added to the order.
Clients cannot bypass the approval step. A request always requires agency action before it becomes a live task. Pending requests remain visible to both the client and the agency until a decision is made.
## All Tasks View
Beyond managing tasks inside individual orders, you can view tasks across every order from a single screen. Navigate to **Tasks** in the left sidebar to access the **All Tasks** page. From here you can:
* See every task you have visibility on, regardless of which order it belongs to
* Filter and sort by status, assignee, due date, or order
* Quickly identify overdue or at-risk items across your entire workload
This cross-order visibility is especially useful for Project Managers and Admins who need to balance team capacity and track delivery health at the agency level.
# Create and Send Proposals to Clients in AgencyHandy
Source: https://docs.agencyhandy.com/proposals/overview
Build, customize, and send professional proposals in AgencyHandy — covering service pricing, packages, client acceptance, and auto-order creation.
AgencyHandy's Proposal feature gives you a professional, end-to-end workflow for turning inquiries into active projects. You can build detailed proposals with services, packages, add-ons, taxes, and legal terms — then send them to clients or leads directly from the platform. Once a client accepts, AgencyHandy can automatically create an order and invoice, removing the manual back-and-forth that slows deals down.
Only **Super Admins** and **Admins** can create and send proposals. Project Managers (PMs) can view proposals but cannot send them.
## Proposal Dashboard
To open the Proposal Dashboard, click **Proposals** in the left sidebar. The dashboard lists all your sent and received proposals and shows:
* **Status** — Draft, Sent, Accepted, or Pending
* **Creation date**, **send date**, and **expiry date**
* **View status** — whether the client has opened the proposal
* Action menu to **edit**, **send**, **share**, or **delete** each proposal
You can search proposals by ID and filter or sort the list to find what you need quickly.
## Creating a Proposal
Click **Create Proposal** to open the proposal builder. It is organized into three sections: **Overview**, **Terms & Conditions**, and **Setup**.
### Overview
The Overview section is where you build the proposal's content and pricing.
#### Proposal & Client Information
Fill in the following fields at the top of the proposal:
* **Proposal Name** and **Proposal ID**
* **Client or Lead** — supports multiple email addresses; mark one as Primary
* **Company Name** and **Address** (country, state, city, zip, additional details)
* **Assignee**, **Send Date**, and **Expiry Date**
#### Content Blocks
Each content block uses an embedded editor so you can tailor the narrative to each client:
* **Introduction** — set the scene and context for the engagement
* **About Us** — highlight your agency's expertise
* **What You Get** — define the scope and deliverables clearly
* **Guarantee** — outline any assurances or commitments
#### Offerings — Services, Packages, Add-ons & Taxes
The Offerings section is where you configure pricing.
Add one or more services to the proposal. For each service, you can:
* Select a **pricing type**: One-time or Subscription
* Choose the **service currency** (different services can use different currencies in the same proposal)
Within each service, add existing packages or create new ones on the fly. For each package, define:
* Package name
* Quantity and pricing per unit
* Total amount
You can remove packages at any time before sending.
Attach optional add-ons to any service. Add-ons appear as extras that clients can see alongside the core service price. You can create new add-ons directly from the proposal builder without leaving the form.
Add one-time custom items with a defined quantity and unit price. Items are useful for ad-hoc costs like setup fees or one-off deliverables.
Apply existing tax rates or create new ones directly from the proposal. Select whether each tax is **Exclusive** (added on top of the price) or **Inclusive** (already included). Taxes are calculated per service.
### Terms & Conditions
Use the Terms & Conditions section to add proposal-specific legal language. Include cancellation policies, refund terms, usage rights, and any other conditions relevant to the engagement. This section helps ensure both parties understand their obligations before acceptance.
### Setup
The Setup section controls what happens after the proposal is sent.
Choose what AgencyHandy does when the proposal is accepted: **Do Nothing**, or **Create Order & Invoice** automatically.
Configure reminder notifications to nudge clients who haven't responded by the expiry date.
Add a password to the public proposal link so only the intended recipient can view it.
Allow clients to leave comments on the public proposal view for easier back-and-forth discussion.
## Sending a Proposal
At any point during creation, you can save the proposal as a **Draft** or **Preview** it. When it's ready, click **Send** to deliver it to the client or lead.
After sending:
* A public link is generated automatically
* The proposal status updates from **Draft** to **Sent**
* AgencyHandy tracks whether the client has viewed the proposal
From the proposal's action menu you can also re-send, download, share the public link, view comments, or delete the proposal.
## Sending a Proposal with a Specific Package
If you want to send a quick proposal tied directly to a specific service package, use the **Create Proposal** shortcut form:
Navigate to **Proposals** in the left sidebar and click **+ Create Proposal**.
Enter the **client's name** and select the **service**. If the service has multiple packages, they will appear automatically — select the appropriate one.
Optionally, assign a **Manager** to the proposal.
Write an **Order Brief** (required) describing what the client will receive. Attach any supporting files up to 1 GB.
Confirm the **pricing type** (one-time or subscription), set the **duration**, **quantity**, **budget**, and **currency**. Add any **Terms and Conditions** relevant to the proposal.
Click **Create** to finalize and send the proposal to the client. The proposal will appear in both your Sent list and the client's Received section.
Double-check the auto-filled pricing and duration before clicking Create. Once sent, the client can accept, reject, or download the proposal from their Received section.
## Proposal Status Lifecycle
| Status | Meaning |
| ------------ | ------------------------------------------------------------------------------------------------------- |
| **Draft** | The proposal has been created but not yet sent. |
| **Sent** | The proposal has been delivered to the client or lead. |
| **Pending** | The client has reviewed and sent the proposal back for discussion. |
| **Accepted** | Either party has formally accepted the proposal terms. An order is created automatically if configured. |
| **Rejected** | Either party has rejected the proposal. The sender receives a notification with the reason. |
## Accepting a Proposal
Either the agency or the client can accept a received proposal. When acceptance happens, AgencyHandy creates an order automatically (if configured in Setup).
Click **Proposals** in the sidebar, then select the **Received** tab.
Select the proposal you want to accept from the list and review its details.
Click the **Accept** button to formally accept the proposal. The status updates immediately and both parties are notified.
If the agency is the one accepting, Super Admins and Admins receive notifications. If the client accepts, AgencyHandy notifies the agency's Super Admin and Admin users.
## Rejecting a Proposal
If the proposed terms, pricing, or scope don't match your requirements, you can reject the proposal and provide a reason.
Navigate to **Proposals → Received**.
Choose the proposal you want to reject and review its details.
Click **Reject** and confirm your decision. The proposal sender receives a notification along with the reason you provided.
Rejected proposals **cannot be re-sent**. Both parties must create a new proposal to restart negotiations.
## Public Proposal View
When you send a proposal, clients receive a link to a public view where they can:
* Review all services, pricing, packages, and taxes
* Accept or reject the proposal
* Leave comments (if comments are enabled)
* Access the proposal securely with a password (if password protection is enabled)
## Additional Notes
You can add multiple email addresses to a single proposal and mark one as the Primary contact. Proposals work with both registered clients and unregistered leads.
When you configure the Setup section to "Create Order & Invoice" on acceptance, AgencyHandy automatically generates the linked order and invoice the moment a proposal is accepted — no manual steps required.
Every proposal includes a full activity trail. You can see when the proposal was created, sent, viewed, accepted, or rejected, all from within AgencyHandy.
# How to Create a Service with Packages, Tasks, and FAQs
Source: https://docs.agencyhandy.com/services/create-service
Step-by-step guide to building an AgencyHandy service: choose billing type, configure packages, set default tasks, add FAQs, and publish.
Creating a service in AgencyHandy is the first step to selling your agency's offerings through the platform. A single service can contain up to five pricing packages, automated default tasks that fire when an order is placed, FAQs to reduce pre-sales questions, a portfolio attachment for social proof, and an optional intake form — all configured in one place before you publish.
You need a **Super Admin** or **Admin** role to create services. Other roles require explicit service permissions to access this section.
Open **Services** from the left sidebar and click **+ Service** to start a new listing.
At the top of the page, select your billing model:
* **One-Time Service** — the client pays a single fee and receives the deliverable once. Best for projects with a clear scope: website builds, logo packages, audits, etc.
* **Subscription Service** — billing recurs automatically on the schedule you define. Best for retainers, ongoing content, managed services, or maintenance plans.
The service type is locked after you save. If you need a different billing model, create a new service.
Expand the **Service Details** section and fill in the following fields:
**Service Name** *(mandatory)*
This is how the service appears to clients everywhere in the platform — in the catalog, on invoices, and inside the order workspace. Make it clear and descriptive.
**Media Upload**
Upload one or more preview images to represent the service visually. High-quality images increase client trust and conversion rates.
**Service Description**
Write a thorough explanation of what the service includes, who it's for, and what clients can expect. Use this space to differentiate your offering.
**Tax Settings**
Choose whether tax is **inclusive** (already built into the price) or **exclusive** (added on top at checkout).
**Currency**
Set the currency for all packages in this service. All packages within a single service share the same currency.
Upload preview images in a 16:9 ratio for the best presentation in the client portal.
Expand **Package Details** and click **+ New Package** to add your first pricing tier. You can create up to **5 packages** per service.
For each package, configure the following:
**Package Name** *(mandatory)*
The name clients see, such as *Basic*, *Standard*, or *Premium*.
**Package Icon** *(optional)*
Select a built-in icon or upload a custom one. Uploaded icons must be **32 × 32 pixels**.
**Package Media** *(optional)*
Upload a cover image specific to this package. Accepted formats: PNG, JPG, JPEG. Maximum file size: **5 MB**. Maximum 1 file per package. Recommended ratio: **16:9**.
**Package Brief** *(optional)*
A one-line summary of this package's deliverables. Maximum **140 characters**.
**What's Included** *(mandatory)*
List the specific deliverables included in this package. You can add up to **15 line items** per package. Each bullet should describe one concrete deliverable (e.g., *"5 blog posts per month, up to 1,000 words each"*).
After creating multiple packages, drag them to reorder how they display to clients. Mark one as **Most Popular** to draw attention to your recommended tier.
Inside each package, set the core pricing fields and any optional controls:
**Amount** *(mandatory)*
The price a client pays for this package.
**Delivery Time** *(mandatory)*
The estimated number of days to deliver the service after purchase.
**Optional pricing controls:**
Apply a percentage or flat-amount reduction to this package's price. The discounted price displays to clients alongside the original price, creating an effective promotional effect.
Offer a free or reduced-price trial before the regular subscription billing begins. This option is only available on subscription-type services.
Cap the number of units a client can purchase in a single checkout session. Use this for limited-availability packages or services with capacity constraints.
Break down the total cost into individual line items — for example, showing *base price + setup fee + per-unit cost*. Each breakdown label supports a maximum of **20 characters**.
All required fields (Amount and Delivery Time) must be completed for every package before you can publish the service.
Every package includes a **Default Tasks** section. Tasks defined here automatically generate inside the order workspace the moment a client purchases this package — no manual setup needed after each sale.
Click **+ Add More** to open the task creation modal. For each task, you can configure:
| Field | Details |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Task Name** | Mandatory; maximum **160 characters** |
| **Description** | Detailed instructions for the assignee |
| **Assignee** | Team member responsible for completing this task |
| **Attachment** | Upload reference files; accepted formats: csv, odt, doc, docx, htm, html, pdf, ppt, pptx, txt, xls, xlsx, jpg, jpeg, png, gif, webp, svg, ai, mp4, mp3, wav, zip, rar; max file size **1 GB** per file |
| **Label** | Tag the task for filtering and reporting |
| **Status** | Initial status when the task is created |
| **Client Review** | Toggle on if this task requires client sign-off before it's considered complete |
Add as many tasks as needed to fully cover the delivery process for this package. Consistent default tasks ensure every order follows the same quality-controlled workflow.
Map your default tasks to your internal SOP. For example, a *Social Media Management* package might auto-generate tasks like *Content Calendar Draft*, *Client Approval*, *Schedule Posts*, and *Monthly Report*.
Expand the **Additional Information** section to add two optional but high-impact elements:
**Portfolio Attachment**
Link a portfolio category to this service so clients can browse relevant samples of your past work directly on the service listing. You can connect an existing portfolio category or create a new one from this screen.
**Frequently Asked Questions (FAQs)**
Click **+ Add** to insert a question-and-answer pair. Add as many FAQs as relevant — common topics include:
* Content originality and rights
* Revision and feedback process
* Scope boundaries and what's *not* included
* Timelines and communication cadence
* Payment and refund policies
Well-written FAQs reduce back-and-forth before purchase and help clients self-qualify.
An intake form collects the information you need from a client before work begins — for example, brand guidelines, access credentials, target audience, or project goals.
* Click **+ Create New Intake Form** to build a form from scratch, or select an existing form from the dropdown.
* If this service doesn't require an intake form, click **Skip** to bypass this section.
* Click **Update** to save your intake form selection and continue.
The intake form is optional but strongly recommended for services that require client-specific inputs before delivery can start.
At the bottom of the service editor:
1. Toggle **Publish this Service** to the ON position.
2. Click **Save** (or **Update Service** if editing an existing service).
Once published, the service becomes immediately visible to clients in the portal. If you leave the toggle off, the service is saved as a draft and only visible to your team.
Use draft mode to prepare a service in advance and publish it at launch time — useful for seasonal promotions or new offering announcements.
## Add-On Setup
Add-ons are optional extras that clients can select during checkout — for example, *Rush Delivery*, *Extra Revisions*, or a *Monthly Report*. They let you upsell complementary services without creating entirely new listings.
### Creating an Add-On
Go to **Services** in the sidebar, click the **down arrow** button next to the Services heading, and select **Add-Ons**.
Click **+ Add New Add-on** and fill in:
* **Add-on Name**
* **Description** — use the rich text editor to clearly explain what the add-on includes
* **Pricing Type** — choose *One-Time* or *Subscription*
* **Pricing details:**
* *One-time:* enter the amount and currency
* *Subscription:* set the billing interval (e.g., every 1 month), an optional billing cycle limit, the subscription fee, and currency
Toggle **Publish** ON, then click **Create**. Only published add-ons are visible when connecting them to order forms.
### Attaching an Add-On to an Order Form
Navigate to **Forms** and open the relevant order form.
Choose the service you want to attach the add-on to.
Select the **Add-ons** section from the left panel, then choose the add-ons you want to associate with this service.
Click **Save**. Clients will now see the selected add-ons as optional extras during checkout.
Add-ons must use the same currency as the service they're attached to. If currencies don't match, the add-on won't appear in the selection list.
### Subscription Add-On Billing Behavior
When the billing cycles of a service and a subscription add-on differ, AgencyHandy handles the overlap automatically:
Both the service and add-on are billed together for the service's duration. After the service ends, the add-on continues billing alone for its remaining cycles.
**Example:** Service runs for 4 cycles, add-on runs for 5 cycles → billed together for 4 cycles, add-on billed alone for 1 additional cycle.
Both the service and add-on are billed together for the add-on's duration. After the add-on ends, the service continues billing alone for its remaining cycles.
**Example:** Service runs for 5 cycles, add-on runs for 3 cycles → billed together for 3 cycles, service billed alone for 2 additional cycles.
## Editing a Service
After a service is published, you can update any field without interrupting existing orders.
1. Go to **Services** and find the service you want to update.
2. Click the **three-dot menu** (⋮) on the right side of the service row.
3. Select **Edit**. The service editor opens with all existing settings populated.
4. Make your changes — update the title, description, pricing, media, packages, tasks, or FAQs.
5. Click **Update Service** to save.
Changes to package pricing or delivery time take effect for **new orders only**. Existing orders are not retroactively affected.
## Field Reference
| Field | Limit |
| ------------------------------------------ | --------------------- |
| Packages per service | Up to 5 |
| Deliverables per package (What's Included) | Up to 15 |
| Package Brief | 140 characters |
| Package icon size | 32 × 32 px |
| Package media file size | 5 MB (PNG, JPG, JPEG) |
| Task name | 160 characters |
| Task attachment file size | 1 GB per file |
| Price breakdown label | 20 characters |
# Agency Services Overview: Catalog, Types, and Features
Source: https://docs.agencyhandy.com/services/overview
Learn how AgencyHandy services work: billing types, packages, add-ons, coupons, portfolios, intake forms, and client purchase options.
Services in AgencyHandy are the offerings you package, price, and sell to your clients — everything from a one-time website audit to a recurring monthly SEO retainer. The Services section acts as your agency's product catalog: you define what you sell, how it's priced and delivered, and what clients see when they browse and purchase. Everything from intake forms to portfolio samples to discount coupons lives here.
## Service Types
AgencyHandy supports two distinct billing models. You choose the type when you first create a service, and it determines how pricing, billing cycles, and checkout behavior work.
Clients pay a single flat fee to receive the service. Ideal for deliverables like logo design, website builds, audits, or any project with a clear start and end.
Billing repeats automatically on a schedule you define — weekly, monthly, annually, or custom. Ideal for retainers, ongoing content creation, managed services, or SaaS-style offerings.
The service type cannot be changed after the service is created. If you need to switch a service from one-time to subscription (or vice versa), you'll need to create a new service.
## Packages (Pricing Tiers)
Every service supports up to **five packages**, letting you offer tiered pricing — for example, Basic, Standard, and Premium — within a single service listing. Each package has its own name, price, delivery time, deliverables list, and default tasks. You can mark one package as **Most Popular** to highlight it visually in the client portal.
Packages are also drag-sortable, so you can control the order in which they appear to clients.
## Service Groups
You can organize services into groups to keep your catalog tidy as it grows. Groups act like folders in your service list, making it faster for both your team and your clients to find the right offering.
## Add-Ons
Add-ons are optional extras that clients can select during checkout alongside a primary service — think of them as upsell line items. You create add-ons separately under **Services → Add-Ons** and then attach them to an order form. Add-ons support both one-time and subscription billing, and each add-on is tracked as a separate order for clear delivery management.
Add-ons are a powerful way to increase average order value without creating entirely new service listings. Examples: *Rush Delivery*, *Extra Revision Round*, or *Monthly Performance Report*.
## Service Purchase Redirection
When a client completes a service purchase, you can configure where they land next. Options include redirecting to a custom URL (such as an onboarding page or a thank-you page) or staying within the AgencyHandy portal. Configure this per service to create a seamless post-purchase experience.
## Portfolio Attachment
Attach relevant portfolio categories to any service so clients browsing your catalog can see real examples of your past work. You can link an existing portfolio category or create a new one directly from the service editor. A strong portfolio builds trust and reduces pre-sales hesitation.
## Intake Forms
Attach an intake form to a service to automatically collect the information you need from a client before work begins — for example, brand guidelines, access credentials, or project goals. Intake forms appear during or after checkout and feed directly into the order workspace.
## User Reviews
Clients can leave reviews on services they've purchased, giving future buyers social proof and giving you feedback to improve your offerings. Reviews are visible on the service listing in the client portal.
## Coupons and Discounts
The Coupon System lets you create targeted discount codes to attract new clients or reward existing ones. Coupons support:
* **Percentage-based** discounts (e.g., 20% off) — up to 100%
* **Fixed-amount** discounts (e.g., \$50 off)
* **Service-specific** application — attach a coupon to one service or many
* **Usage limits** — control how many times a code can be redeemed in total or per customer
* **Expiration dates** — set a date after which the code no longer works
* **Duration options** — apply the discount forever, once, or for a set number of billing cycles
Clients enter coupon codes at checkout, and multiple valid coupons can be combined. Discounts appear in the order summary before the client confirms payment.
Deleting an active coupon immediately removes the discount from all future billing cycles on subscriptions that are using it. Notify affected clients before deleting, and wherever possible, time deletions to coincide with the end of a billing cycle.
## Managing Your Service Catalog
From the Services list you can:
* **Publish or unpublish** services — published services are visible to clients; unpublished ones are saved as drafts
* **Edit** any service to update pricing, descriptions, or packages
* **Delete** services you no longer offer
* **Duplicate** a service as a starting point for a similar offering (where available)
Step-by-step guide to building a service from scratch — including packages, default tasks, FAQs, and publishing.
How to create optional add-ons and attach them to your order forms for upselling at checkout.
## Who Can Manage Services
| Role | Permissions |
| --------------- | ------------------------------------------------------- |
| **Super Admin** | Full create, edit, publish, delete access |
| **Admin** | Full create, edit, publish, delete access |
| **Other roles** | Read-only unless granted service permissions explicitly |
# All Tasks — Centralized Task Management in AgencyHandy
Source: https://docs.agencyhandy.com/tasks/all-tasks
Use the All Tasks page for a real-time, role-filtered view of every task across ongoing and in-review orders — with search, filters, and sorting.
The All Tasks page in AgencyHandy gives you a single, centralized view of every task that belongs to active workflows across your agency. Rather than hunting through individual orders, you can see all relevant tasks in one place, filter them down by assignee, priority, or date, and make edits directly from the list. Visibility is automatically scoped to your role — Super Admins see everything, Managers see their assigned orders, and Employees see only their own tasks.
## Accessing the All Tasks Page
1. Log in to your AgencyHandy account.
2. Click **Tasks** in the left sidebar.
3. Select **All Tasks** to open the centralized task dashboard.
The All Tasks page only displays tasks from orders that are in **Ongoing** or **In Review** status. Tasks tied to orders in any other state (e.g., Completed, Pending) do not appear here.
## Task Visibility by Role
What you see on the All Tasks page depends entirely on your role.
| Role | What They See |
| ------------------------ | -------------------------------------------------------------------------------------- |
| **Super Admin / Admin** | All tasks across every order, team, and status |
| **Project Manager (PM)** | Only tasks from orders where they are assigned as the Manager |
| **Employee / Assignee** | Only tasks directly assigned to them — even if teammates are working on the same order |
If a PM cannot find a task they expect to see, confirm that they are assigned as the Manager on the relevant order. PMs do not see tasks unless they are the assigned Manager for that order.
## When Tasks Appear on This Page
Tasks show up on the All Tasks page when these conditions are met:
* Manual orders (one-time or subscription) are created
* Catalog orders via Stripe or manual payment methods are placed
* A proposal is accepted by the agency
* Client-requested tasks the agency has not yet accepted
* Trial orders the agency has not yet accepted
* Orders with pending status awaiting manual bank payment confirmation
## Searching, Filtering, and Sorting
The All Tasks page includes a full set of controls to help you find exactly what you need.
### Search
Use the search bar to locate tasks by name, assignee, or related order. Results update in real time as you type.
### Filters
Click **Filter → + Add Filter** to open the filter panel. You can combine multiple filters for precise results:
| Filter | What It Does |
| ----------------- | ----------------------------------------------------------------- |
| **Order ID** | Show tasks linked to a specific order number |
| **Assignee** | Show tasks assigned to a particular team member |
| **Status** | Filter by task progress: Pending, In Progress, Review, Done, etc. |
| **Priority** | Focus on High, Medium, or Low priority tasks |
| **Label** | Narrow down by task labels or categories |
| **Kick Off Date** | Show tasks starting on or after a specific date |
| **End Date** | Show tasks due by a specific date |
Filters are available only on the All Tasks page. They persist during your browser session but reset on page refresh. Filters affect only your view and do not change what other users see.
To clear all filters, click **Clear Filters** to return to the full, unfiltered list.
### Sorting
Sort the task list by:
* **Due date** — surface tasks that are coming up or already overdue
* **Priority** — bring the most critical tasks to the top
* **Creation time** — see recently added tasks first
### Breadcrumb Navigation
Use the breadcrumb trail at the top of the page to maintain context as you navigate between subtasks, task lists, and parent orders. This is especially helpful when drilling into a specific task and then needing to return to the broader list.
## Editing Tasks
You can modify tasks on the All Tasks page in two ways:
Click directly into an editable field within the task row — such as the status, assignee, or due date — and make your change without leaving the list view. This is the fastest option for quick updates.
Click on the task name to open the full task detail modal. From here you can update all task properties, add notes, view subtasks, and see the complete task history. Use this for more thorough edits or when you need context.
## Task Deletion Rules
Tasks on the All Tasks page are tied directly to their parent orders.
* When an **order is deleted**, all tasks associated with that order are **automatically and permanently removed** from the All Tasks page.
* This deletion affects all user roles — no one will be able to see those tasks after the order is deleted.
* **There is no recovery option** for tasks deleted through order deletion.
Deleting an order permanently removes all of its tasks. Make sure any important task history or deliverable records are saved elsewhere before deleting an order.
## Additional Notes
Changes to orders, task assignments, or task statuses reflect in real time on the All Tasks page. If a teammate updates a task while you have the page open, you'll see the change without needing to refresh.
Tasks submitted by clients do not appear on the All Tasks page until the agency explicitly accepts them. Until accepted, these tasks remain in a pending state and are not visible in the centralized view.
Tasks only appear for orders in Ongoing or In Review status. If an order moves to Completed or is paused, its tasks are no longer shown here. Navigate to the specific order to view tasks tied to orders outside these statuses.
# Time Tracking and Timesheet Management in AgencyHandy
Source: https://docs.agencyhandy.com/tasks/timesheet
Log time with a live timer or manual entry, filter work logs by task, member, or service, and export timesheet data as CSV or XLSX in AgencyHandy.
The Timesheet feature in AgencyHandy gives you a central panel for tracking every hour your team spends on tasks. You can start a live timer on any task, log time after the fact with a manual entry, and then slice and dice the data by date range, team member, or service. When you need to report on productivity or bill for time, you can export everything to CSV or XLSX in a few clicks. It's the essential tool for keeping your team accountable and your time-based billing accurate.
## Who Can Use Timesheet Features
| Feature | Super Admin | Admin | PM | Employee |
| --------------------- | :---------: | :---: | :-: | :------: |
| View own time logs | ✅ | ✅ | ✅ | ✅ |
| Log time for others | ✅ | ✅ | ✅ | ❌ |
| Edit time entries | ✅ | ✅ | ✅ | ❌ |
| Export timesheet data | ✅ | ✅ | ✅ | ❌ |
Tasks must exist before time can be tracked against them. Ensure tasks are created within orders before attempting to log time.
## Viewing the Timesheet
Click **Timesheet** in the main left sidebar. You'll see a table listing all time logs for your team.
Each row shows the date, team member, task name, service, time logged, and any notes attached to the entry.
## Adding a Time Entry
You have two options for logging time: a live timer for work in progress, or a manual entry for time you've already completed.
In the Timesheet view, find or select the task you're about to work on.
Click **Start Timer** to begin tracking time in real time. The timer runs until you stop it.
Click **Stop** when you finish the work. AgencyHandy automatically logs the elapsed time against the selected task.
Use the timer for ongoing work to ensure precise tracking. Manually rounding up or estimating time after the fact is less accurate than letting the timer run.
In the Timesheet panel, click **+ Add Entry**. A form will appear.
* **Task** — select the task this time applies to
* **Team Member** — assign the time to the correct person (Admins and Managers can log for others)
* **Time Spent** — enter the hours and minutes
* **Notes** — add any context about what was worked on
Click **Save** to record the entry. It will appear in the timesheet table immediately.
## Filtering by Date Range
Use the date filters to focus on a specific time period.
Click the date filter controls at the top right of the Timesheet panel.
Choose from preset ranges:
* **Daily** — today's logs only
* **Weekly** — the current week
* **Monthly** — the current month
For longer projects or historical reporting, select a **Custom** date range by entering a start and end date.
Click **Apply** to update the table with logs from the selected period.
Filter before exporting to generate focused reports. Exporting the full unfiltered timesheet can produce very large files for active agencies.
## Grouping Entries
Grouping rearranges how the timesheet rows are organized without removing any data. It helps you read and analyze the logs more quickly.
Click the **Group By** dropdown near the top of the Timesheet panel.
Choose from the following options:
| Group By Option | What It Shows |
| ----------------------- | ------------------------------------------------------------------------ |
| **Task Name** | All time entries grouped under each task |
| **Team Member** | All entries grouped under each person |
| **Service → Task Name** | Entries grouped by service, then broken down by task within each service |
Grouping is a visual-only change — it does not affect the underlying data or what gets exported. Exports always include all visible rows.
## Viewing Task Details from the Timesheet
In the timesheet table, click on any **Task Name**. AgencyHandy navigates you to that task's full detail page.
On the task detail page, you'll find the complete time log history, attached notes, assignees, status, and other task-level information. Use this view to investigate entries or verify what work was done.
## Exporting Timesheet Data
Export your timesheet for payroll, client billing reports, or external project management tools.
Use the date range filter to narrow the export to the period you need. This keeps the file focused and manageable.
Click the **Export** button at the top of the Timesheet panel.
Select either:
* **CSV** — for spreadsheet tools like Excel, Google Sheets, or data pipelines
* **XLSX** — for Excel-formatted workbooks with column formatting preserved
The file downloads to your device automatically. Each export includes all visible columns: date, team member, task name, service, time logged, and notes.
If the export does not trigger a download, your browser's **pop-up blocker** may be preventing the file from downloading. Disable pop-up blocking for AgencyHandy and try again.
## Additional Notes
The timer is best for active, real-time work. Manual entries are best when you forgot to start the timer or need to record time retroactively. Both methods produce identical log entries in the timesheet table.
Filters **reduce** what rows are shown in the table. Grouping **reorganizes** the rows that are already visible. You can apply both at the same time — filter to a date range, then group by team member to see each person's totals for that period.
Every export captures the current state of the visible table: date, user, task, service, time, and notes. If you've applied a group-by setting, the export reflects the grouping structure as well.
For long-running projects or quarterly reviews, use the custom date range option to pull historical timesheet data beyond the preset daily/weekly/monthly windows.
# Manage Your Agency Team Members and Roles in AgencyHandy
Source: https://docs.agencyhandy.com/teams/manage-team
Invite team members by email, assign roles and permissions, change roles for existing members, and remove users from your agency workspace in AgencyHandy.
AgencyHandy's Teams feature gives you a secure, organized way to build and manage your agency's workforce. You invite members by email, assign them a role that controls what they can see and do, and they receive a secure login link to complete onboarding. As your team evolves, you can update roles at any time or remove members to keep access tight and relevant.
## Accessing the Team Dashboard
Click **Teams** in the left sidebar to open the Team Dashboard. Here you see a list of all current team members along with their assigned roles. From this view you can invite new members, update roles, and remove people from the workspace.
## Roles in AgencyHandy
AgencyHandy has five default roles, each with preset permission levels. When you invite a team member, you assign one of these roles. You can change a member's role at any point after they join.
| Role | Typical Capabilities |
| ------------------------ | -------------------------------------------------------------------------------------- |
| **Super Admin** | Full access to everything — all settings, all data, all team management actions |
| **Admin** | Broad access including invoices, proposals, orders, team management, and settings |
| **Project Manager (PM)** | Manages orders assigned to them, views tasks for their orders, can invite team members |
| **Employee** | Limited to tasks directly assigned to them; no access to financial or admin sections |
Only **Super Admins** and **Admins** can change roles or delete team members. PMs can invite new members but cannot change or remove existing ones.
## Inviting a Team Member
Click **Teams** in the left sidebar.
Click the **+ Create Team** button. An invitation form will appear.
Type the email address of the person you want to invite. This is required.
Select the appropriate role from the dropdown. Choose carefully — this determines what the new member can access from their first login.
Click **Invite**. AgencyHandy sends the invited person an email with:
* A **secure login URL** to your agency's workspace
* A **computer-generated password** to use on first login
The invited team member follows the link in their email, logs in with the provided credentials, and completes the onboarding process. Once they log in, they are added to your agency workspace and can start collaborating immediately.
Ask the new team member to change their computer-generated password to something secure after their first login.
## Setting Roles for Team Members
You can assign or update roles in two ways: during the invitation, or after the member has already joined.
When you fill out the invitation form, select the role from the dropdown before clicking **Invite**. The role takes effect as soon as the member logs in for the first time.
1. Go to **Teams** in the left sidebar to open the Team Dashboard.
2. Find the team member whose role you want to change.
3. Click the **down arrow** button to the right of their name.
4. A list of default role names will appear. Select the new role.
5. The role updates immediately — no save step required.
Only **Super Admins** and **Admins** can change an existing team member's role.
## Role Permissions Summary
Use this table as a quick reference when deciding which role to assign.
| Feature | Super Admin | Admin | PM | Employee |
| -------------------------------- | :---------: | :---: | :------------------: | :-----------------: |
| Create & send proposals | ✅ | ✅ | ❌ | ❌ |
| Create & manage invoices | ✅ | ✅ | ✅ | ❌ |
| Manage all orders | ✅ | ✅ | Assigned only | ❌ |
| View all tasks | ✅ | ✅ | Assigned orders only | Assigned tasks only |
| Invite team members | ✅ | ✅ | ✅ | ❌ |
| Change roles / remove members | ✅ | ✅ | ❌ | ❌ |
| Access invoice & agency settings | ✅ | ✅ | ❌ | ❌ |
| Cancel subscriptions | ✅ | ✅ | ❌ | ❌ |
| Export timesheet data | ✅ | ✅ | ✅ | ❌ |
## Removing a Team Member
When someone leaves your agency or no longer needs access, remove them from the workspace to protect your data.
Navigate to **Teams** in the left sidebar.
Tick the checkbox next to the team member you want to remove. The **Delete** button will become active.
Click the **Delete** button. A confirmation modal will appear.
Confirm your decision. AgencyHandy immediately revokes the member's access to the workspace and all associated resources.
After removal, reassign any open tasks or orders the member was responsible for, and update relevant documentation and access permissions accordingly.
Removing a team member **cannot be undone**. Their access is revoked permanently. If you need to give the same person access again in the future, you must send a new invitation.
## Additional Notes
Every invitation is delivered through a secure login URL. The invited person uses this URL along with a computer-generated password to access the platform for the first time. This ensures that only the intended person gains access.
When you update a team member's role, the change applies instantly. There is no pending or confirmation step — the member's new permissions are active on their next page load.
An Employee can only see tasks that are directly assigned to them. A PM can only see tasks within orders where they are assigned as the Manager. Super Admins and Admins see everything. Keep this in mind when assigning roles to avoid confusion about missing tasks or orders.
# Support Tickets — Handle Client Inquiries in AgencyHandy
Source: https://docs.agencyhandy.com/tickets/support-tickets
Create, edit, and manage support tickets in AgencyHandy to track client inquiries, set priorities, assign statuses, and keep a full interaction history.
AgencyHandy's Ticket feature gives your agency a structured way to handle client inquiries, issues, and requests. Instead of letting questions get lost in emails or chat threads, every support request lives in a ticket with a subject, priority, assignee, and status — all searchable and trackable from one dashboard. Both your team and your clients can create tickets, and the full history of each ticket is preserved so nothing falls through the cracks.
## Accessing the Ticket Dashboard
Click **Tickets** in the left sidebar to open the Ticket Dashboard. From here you can:
* Create, edit, and delete tickets
* Search tickets by **subject**, **client name**, or **Order ID**
* View ticket status and priority at a glance
* Monitor all open, on-hold, and closed tickets across the agency
## What Tickets Do
Clients and agency team members can submit questions, issues, or requests through the ticketing system. Every submission is logged and tracked.
Assign tickets to team members, set priorities, and update statuses as work progresses toward resolution. Everyone stays informed.
Every ticket maintains a full history of actions, updates, and interactions. Review past communications at any time for context or audit purposes.
## Creating a Ticket
Both agency team members and clients can create tickets. The creation process is the same for both.
**Who can create tickets:** Super Admin, Admin, PM, and Client.
Click **Tickets** in the left sidebar.
Click the **+ Create Ticket** button. A form will appear.
Choose the client's name from the dropdown list. This links the ticket to the correct client profile.
Enter the **Order ID** to associate the ticket with a specific order. This is helpful for billing or project-related issues. You can also create a ticket without an Order ID for general inquiries.
Complete the following fields:
| Field | Description |
| ----------------- | -------------------------------------------------------- |
| **Subject** | A brief, descriptive title for the ticket |
| **Description** | A detailed explanation of the issue or request |
| **Assignee Name** | The team member responsible for resolving this ticket |
| **Priority** | Urgency level: Highest, High, Normal, Low, or Lowest |
| **Issued Date** | The date the ticket was created (recorded automatically) |
| **Status** | Current state: Open, Hold, or Close |
Click **Create** to save the ticket. It will appear in the Ticket Dashboard immediately.
## Ticket Statuses
Tickets move through three statuses as work progresses:
| Status | Meaning |
| --------- | -------------------------------------------------------------------------------- |
| **Open** | The ticket has been submitted and is actively being worked on |
| **Hold** | Work on the ticket is temporarily paused, typically waiting for more information |
| **Close** | The issue has been resolved and the ticket is archived for reference |
Use **Hold** status when you're waiting on a client response or an external dependency. This keeps the ticket visible without cluttering the active queue.
## Editing a Ticket
Agency team members can update ticket details at any time to reflect new information, priority changes, or resolution updates.
**Who can edit tickets:** Super Admin, Admin, and PM. Clients can create tickets but cannot edit them.
Only tickets created from the **agency side** can be edited. Tickets submitted by clients cannot be modified by the client after submission.
Navigate to **Tickets** in the left sidebar.
Tick the checkbox next to the ticket you want to edit. The **Edit Ticket** button will become active.
Click the **Edit Ticket** button. The ticket form will open with all existing details pre-filled.
Update any fields that need to change — the description, priority, assignee, status, or other details.
Click **Save** to apply your changes. The ticket is updated immediately in the dashboard.
If the change is significant — such as a priority escalation or assignee swap — notify the relevant team members so they can respond appropriately.
## Deleting a Ticket
Remove outdated or unnecessary tickets to keep the dashboard clean and relevant.
**Who can delete tickets:** Super Admin, Admin, and PM.
In the Ticket Dashboard, tick the checkbox next to the ticket you want to delete. The **Delete** button will activate.
Click **Delete**. A confirmation modal will appear.
Confirm your decision in the modal. The ticket is permanently removed from the system.
Check the ticket list or search for the ticket by subject or Order ID to confirm it no longer exists.
Deleting a ticket is **permanent and cannot be undone**. Before deleting, make sure any important communications or resolution notes from the ticket have been documented elsewhere.
## Searching and Filtering Tickets
Use the search bar at the top of the Ticket Dashboard to find tickets quickly. You can search by:
* **Subject** — the ticket title
* **Client name** — all tickets from a specific client
* **Order ID** — all tickets linked to a specific order
## Best Practices for Using Tickets
Agree on a priority scale with your team before you start creating tickets. If "High" means different things to different people, escalation workflows break down. Use Highest only for issues that block client deliverables.
Connecting a ticket to an Order ID makes it much easier to track which client issue is affecting which project. This also helps when reviewing past tickets for a specific order.
Once an issue is resolved, change the status to **Close** right away. Leaving tickets open after resolution inflates your active queue and makes it harder to spot genuine work in progress.
When you're waiting on a client or a third party, set the ticket to **Hold** rather than leaving it Open. This gives your team a clear signal that no action is needed until a response arrives.
# Customize Your AgencyHandy Workspace Color Schemes
Source: https://docs.agencyhandy.com/workspace/appearance
Apply your brand colors to the AgencyHandy sidebar and interface — primary color, background, text, and hover states — visible instantly to all users.
The Appearance settings give you full control over how your AgencyHandy workspace looks. You can align the platform's color scheme with your agency's brand identity by customizing the primary color, sidebar background, sidebar text color, and the hover highlight color for sidebar navigation items. Every change you save takes effect immediately across the entire workspace for all users — no page refresh required.
Only **Super Admins** and **Admins** can access and modify Appearance settings. If you don't see this option under **Workspace Config**, ask your Super Admin to review your role.
## Accessing Appearance Settings
From the left navigation menu, click **Workspace Config**.
Click **Appearance** (sometimes labeled **Visual Settings**) from the submenu.
***
## Customizing Each Visual Element
### Primary Color
The primary color is applied to buttons, active links, highlighted states, and key interface elements throughout the platform.
* Pick a color that reflects your core brand identity.
* This is the most impactful color setting because it appears everywhere in the UI.
### Sidebar Background Color
The sidebar background sets the base shade of the left navigation panel.
* Use a color that creates a clear visual separation between the sidebar and the main content area.
* Dark backgrounds with light text generally perform best for readability.
### Sidebar Text Color
The sidebar text color controls the label color for all navigation items in the left menu.
* Always choose a color that has strong contrast against your sidebar background color.
* Poor contrast makes links harder to read and reduces accessibility.
### Sidebar Hover Background Color
This color appears as the background highlight when a user moves their cursor over a sidebar navigation item.
* It signals interactivity and helps users understand which item they are about to click.
* Choose a color that is visibly distinct from both the default sidebar background and the active item color.
***
## Applying Your Color Choices
Click the color swatch next to any of the four appearance fields — Primary Color, Sidebar Background, Sidebar Text Color, or Sidebar Hover Background Color — to open the color picker.
Type your brand's exact hex code (e.g., `#3B5BDB`) directly into the input field, or use the visual picker to select a shade.
Review how the updated colors look in the sidebar and across the interface before saving.
When you're happy with the result, click **Save Changes**. The updated appearance is applied globally and instantly to all users in the workspace.
Keep a record of your brand's hex color codes somewhere accessible (a brand style guide or notes file). You'll want to reuse the exact same values consistently — especially if you ever need to reset and reconfigure your appearance settings.
***
## Resetting to Default Theme
If you want to remove all custom branding and restore the original AgencyHandy color scheme, click the **Reset Default Settings** button on the Appearance page.
Resetting to defaults permanently discards all custom color changes. This action cannot be undone. If you want to preserve your current settings, note down your hex codes before resetting.
***
## Color Contrast Best Practices
Good color contrast is not just a design preference — it directly affects readability and accessibility for your team and clients.
For normal body text, use a contrast ratio of at least **4.5:1** between text and background. For large text or icons, a ratio of **3:1** is acceptable. Use a tool like [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) to verify.
Don't pair colors like light grey text on white, or yellow text on white — these fail accessibility standards and strain the eyes over long sessions.
Hover colors should be noticeably different from both the resting state and the active state. If they look the same, users lose important visual feedback.
Use the same primary color here as on your website, proposals, and invoices. Consistency builds recognition and professionalism across all client touchpoints.
***
## Important Notes
* **Instant global effect:** All saved appearance changes are applied immediately across the entire workspace. Every logged-in user sees the update on their next navigation action.
* **One active theme:** There is no multi-theme support — one set of colors applies to the whole workspace for all roles.
* **Role restriction:** Only Super Admins and Admins can make appearance changes. Regular team members and clients cannot modify colors.
* **Reset is permanent:** The **Reset Default Settings** button cannot be undone, so use it only when you intentionally want to remove all custom colors.
# Connect a Custom Domain to Your AgencyHandy Workspace
Source: https://docs.agencyhandy.com/workspace/custom-domain
Link your own subdomain (e.g., portal.yourcompany.com) to AgencyHandy by adding a CNAME record at your DNS registrar — no coding required.
By default, your AgencyHandy workspace is accessible at a subdomain under `agencyhandy.com`. Connecting a custom domain lets you replace that default URL with your own branded address — for example, `portal.youragency.com` — giving clients a seamless, professional experience that reinforces your brand from the very first page they land on.
Only **Super Admins** and **Admins** can configure a custom domain. You must also own the domain and have access to its DNS settings at your registrar to complete this setup.
***
## How It Works
When you add a custom domain in AgencyHandy, the platform provides you with a **CNAME record**. You add that record to your domain's DNS settings at your registrar (GoDaddy, Namecheap, Cloudflare, etc.), and AgencyHandy verifies the connection once DNS has propagated.
***
## Step-by-Step Setup
Log in to your AgencyHandy account. Navigate to **Workspace Config** in the left sidebar, then click **Custom Domain**.
Click the **+ Add Custom Domain** button. In the input field that appears, enter the subdomain you want to use — for example, `portal.youragency.com`.
Do **not** use `www` as your subdomain (i.e., avoid `www.youragency.com`). The `www` prefix can cause configuration conflicts and prevents successful verification. Use a different subdomain such as `portal`, `client`, `app`, or `hub`.
After submitting your domain, AgencyHandy displays the DNS record you need to add:
| Field | Value |
| --------- | ---------------------------------- |
| **Type** | CNAME |
| **Name** | Your subdomain (e.g., `portal`) |
| **Value** | The target provided by AgencyHandy |
Copy these values carefully — you'll need them in the next step.
Log in to your domain registrar's dashboard (e.g., GoDaddy, Namecheap, Cloudflare). Navigate to the DNS management section for your domain and add the CNAME record using the Type, Name, and Value copied from AgencyHandy.
See the registrar-specific guidance below for Cloudflare.
Return to AgencyHandy and click **Save Domain**. The status will initially show as **Disconnected** — this is expected while DNS propagates.
DNS changes can take anywhere from a few minutes to **up to 48 hours** to propagate globally, depending on your registrar and TTL settings. Click **Refresh** periodically to check the connection status.
Once propagation is complete, the status changes to **Connected** ✅.
DNS propagation can take up to **48 hours**. If your domain still shows **Disconnected** after 48 hours, double-check that the CNAME record is correct and that no conflicting DNS records exist for the same subdomain.
***
## Cloudflare-Specific Instructions
If your domain is managed through Cloudflare, there is one critical setting you must configure correctly:
Open your [Cloudflare dashboard](https://dash.cloudflare.com) and click on the domain you are connecting to AgencyHandy.
Click the **DNS** tab in the top navigation of the domain settings panel.
Click **+ Add Record** and fill in the fields:
* **Type:** CNAME
* **Name:** Your subdomain (e.g., `portal`)
* **Target/Content:** The value provided by AgencyHandy
* **TTL:** Set to **2 minutes** (or the lowest available option) during initial setup
In the **Proxy status** column, make sure the toggle is set to **DNS only** (the cloud icon should appear grey, not orange).
If the Cloudflare proxy is **enabled** (orange cloud icon), the CNAME record will not resolve correctly and AgencyHandy cannot verify your domain. You must set it to **DNS Only** for the connection to work.
Review all values for accuracy and click **Save**.
Use [dnschecker.org](https://dnschecker.org) to monitor your CNAME record's propagation across different global regions. Look for green check marks across all regions before expecting AgencyHandy to confirm the connection.
***
## Monitoring Your Connection Status
After saving, return to **Workspace Config → Custom Domain** in AgencyHandy to track the status:
| Status | Meaning |
| ---------------- | ------------------------------------------------------------------------------------ |
| **Disconnected** | DNS record has not yet propagated or contains an error |
| **Connected** | Domain is verified and active — clients can access your workspace via the custom URL |
***
## Updating or Removing a Custom Domain
* **To update your domain:** Delete the existing entry and add the new domain using the same setup steps above.
* **To delete your domain:** Click the **Delete** button next to your domain in the Custom Domain panel and confirm the deletion. Your workspace will revert to the default AgencyHandy URL. You can re-add any domain at any time.
***
## Important Notes
* **Use a subdomain, not a root domain:** AgencyHandy custom domains require a subdomain (e.g., `portal.youragency.com`), not a root/apex domain (e.g., `youragency.com`).
* **Avoid `www`:** The `www` subdomain can cause issues during verification. Use a custom subdomain name instead.
* **Exact records required:** Enter the CNAME Type, Name, and Value exactly as shown in AgencyHandy. Any typo or missing character prevents the connection.
* **Cloudflare proxy must be off:** Always set Cloudflare records to **DNS Only** for AgencyHandy custom domain verification.
* **Admin-only access:** Only Super Admins and Admins can add, modify, or delete custom domain settings.
# Configure Outgoing Email, SMTP, and Email Templates
Source: https://docs.agencyhandy.com/workspace/email-setup
Configure a custom sender email address, connect an SMTP server, add DKIM/SPF records for deliverability, and customize email templates in AgencyHandy.
AgencyHandy's email setup lets you replace the default `noreply@agencyhandy.com` sender with your own branded email address, configure a dedicated SMTP server for reliable delivery, and customize the templates used for client notifications, invoices, proposals, and more. Setting this up properly ensures your emails reach clients' inboxes — not their spam folders — and that every message reflects your agency's identity.
Only **Super Admins** and **Admins** can configure email settings. Navigate to **Workspace Config → Email Setup** to access these options.
***
## Overview of Email Setup Components
Set the sender name and email address that clients see when they receive messages from your workspace.
Add DNS authentication records to prove your emails are legitimate and prevent them from being flagged as spam.
Connect your own mail server (e.g., Gmail, Outlook, or a custom domain server) to send all outgoing emails from AgencyHandy.
Customize the content, subject lines, and branding for every automated email AgencyHandy sends to clients.
***
## Part 1: Set Up a Custom Email Address
Before configuring your sender email, you need a registered domain with email hosting. Popular providers include Google Workspace, Microsoft 365, Zoho Mail, and Cloudflare Email Routing.
If you haven't already, register a domain with a registrar (e.g., GoDaddy, Namecheap, Cloudflare) and sign up for an email hosting provider. Make sure you can create and manage email addresses on that domain (e.g., `hello@youragency.com`).
Log in to AgencyHandy. Go to **Workspace Config** in the left navigation, then click **Email Setup**.
In the **Sender Name** field, type the name clients will see as the sender (e.g., `AgencyHandy Support` or your agency's name). In the **Sender Email** field, enter the custom email address (e.g., `hello@youragency.com`). Click **Save**.
AgencyHandy sends a verification link to the email address you entered. Open your email inbox, find the verification message, and click the link to confirm ownership.
After saving your sender email, AgencyHandy provides you with the DNS records you need to add:
* **SPF record** (TXT type) — authorizes AgencyHandy to send emails on behalf of your domain.
* **DKIM records** (3 CNAME records) — add cryptographic signatures to outgoing emails so receiving servers can verify authenticity.
* **DMARC record** — defines how recipient servers should handle emails that fail authentication checks.
Add all of these records to your domain's DNS settings at your registrar. For DKIM CNAME records, make sure **Proxy Status is disabled** if you use Cloudflare.
Return to the Email Setup page in AgencyHandy. Once all DNS records have propagated (this can take between 2 minutes and 2 hours), the email status updates from **Pending** to show a green checkmark ✅. Your custom email is now active.
Use [MXToolbox](https://mxtoolbox.com/DKIM.aspx) or [dmarcian's DKIM Validator](https://dmarcian.com/dkim-validator/) to verify your DKIM records are correctly configured. Refresh the Email Setup page periodically while waiting for propagation.
***
## Part 2: Configure DKIM & SPF (Standalone Setup)
If you need to generate or regenerate DKIM and SPF records independently, follow this path:
**Workspace Config → Emails → DKIM & SPF Setup → Generate DKIM and SPF records.**
Then add the records to your DNS:
| Record Type | DNS Type | What to Configure |
| ----------- | -------- | --------------------------------------------------------------------------------------- |
| SPF | TXT | Copy the **Name** and **Value** from AgencyHandy and add a new TXT record in your DNS |
| DKIM (×3) | CNAME | Copy each **Name** and **Value** pair; add 3 separate CNAME records with proxy disabled |
DKIM and SPF records can take anywhere from **2 minutes to 2 hours** to propagate. If the status still shows pending after 2 hours, verify that the records were entered without typos and that no conflicting records exist.
***
## Part 3: Set Up SMTP
SMTP (Simple Mail Transfer Protocol) lets you route all outgoing AgencyHandy emails through your own verified mail server, giving you more control over deliverability and branding.
You can use either a **Custom Domain Email** or an **SMTP Email Provider** — not both simultaneously. Switching between them is possible at any time, but you will need to re-enter your email configuration when switching back to a custom email.
Go to **Workspace Config → Email Setup**, then click **SMTP Server**.
If you already have a custom email configured, a confirmation popup appears asking if you want to switch. Click **Switch to SMTP** to proceed. This disables the existing custom email setup.
Fill in the required fields:
| Field | Example Value | Notes |
| --------- | -------------------- | ----------------------------------------- |
| Host Name | `smtp.gmail.com` | Your email provider's SMTP server address |
| User Name | `you@yourdomain.com` | Your full email address |
| Password | App password | Use an app-specific password (see below) |
| Port | `465` or `587` | 465 for SSL, 587 for TLS |
| Auto TLS | Toggle on/off | Optional — enables automatic TLS upgrade |
Click **Save** when done.
If you're using Gmail with 2-Factor Authentication enabled (required for app passwords):
1. Go to [myaccount.google.com/security](https://myaccount.google.com/security) and confirm 2-Step Verification is active.
2. Visit [myaccount.google.com/apppasswords](https://myaccount.google.com/apppasswords).
3. Click **Select app**, choose **Mail** (or enter a custom name), then click **Select device** and choose your setup.
4. Click **Create** — Google generates a 16-character app password.
5. Copy the password and paste it into the **Password** field in AgencyHandy's SMTP settings.
Use the **app password**, not your regular Google account password. Using your regular password will fail if 2FA is enabled and may trigger security alerts.
After saving, AgencyHandy displays a success message confirming *"SMTP is created successfully."* Your saved host, username, and port details appear on the SMTP settings page.
Click the **Test** button and enter a recipient email address. AgencyHandy sends a test email to that address. Check the inbox for the confirmation message: *"This is a confirmation that your email setup in Agency Handy is working properly."*
Only one SMTP configuration can be active per workspace at a time. Once SMTP is configured, all outgoing emails from AgencyHandy — invoices, proposals, task notifications — will be sent through your SMTP server.
***
## Part 4: Customize Email Templates
AgencyHandy includes pre-built templates for every automated email it sends. You can customize each one to match your brand tone and include relevant dynamic content.
**Available templates include:**
* Client Sign-up
* Send Proposal
* Task Review
* Send Invoice
* Invoice & Subscription Reminders
* Ticket Creation Notifications
Go to **Workspace Config → Emails**, then select **Email Template** from the submenu.
The full list of available templates is displayed. Click any template to open its configuration page.
Update the following as needed:
* **Sender Email:** Choose which configured email address sends this template.
* **Subject:** Write a clear, concise subject line.
* **Body:** Edit the message content to match your agency's tone and messaging.
* **Dynamic Variables:** Insert placeholders like `{{client_name}}`, `{{company_name}}`, or `{{invoice_id}}` to auto-populate client-specific data.
* **Social Media Links:** Add links to your agency's social profiles to encourage engagement.
Click **Send Test** to send a preview of the template to your inbox. Verify the formatting, content, and that all dynamic variables resolve correctly.
Click **Save Changes** to apply the updated template. The new version will be used for all future automated emails matching that template type.
***
## Important Notes
* **SMTP and custom email are mutually exclusive.** Only one method can be active at a time per workspace.
* **Re-enter email on switch.** If you switch from SMTP back to a custom email setup, you must re-enter your custom email credentials.
* **Incorrect SMTP credentials block all outgoing emails.** Double-check your hostname, port, username, and password if emails stop sending after an SMTP change.
* **DKIM/SPF propagation takes time.** Wait up to 2 hours and refresh the Email Setup page before concluding there is an error.
* **Dynamic variables are case-sensitive.** Use them exactly as shown in the template editor to ensure they populate correctly.
# Set Up Email to Ticket
Source: https://docs.agencyhandy.com/workspace/email-to-ticket
Automatically convert forwarded client emails into support tickets by connecting your support inbox to your AgencyHandy workspace forwarding address.
The **Email to Ticket** feature automatically converts client emails into support tickets. Once your support email is configured to forward incoming emails to your unique AgencyHandy forwarding address, every new email from a recognized client automatically creates a ticket in your workspace.
Only emails sent from existing client email addresses create tickets automatically.
***
## Accessing Email to Ticket
Log in to AgencyHandy. In the left navigation menu, click **Workspace Config**.
Click **Email to Ticket** from the Workspace Config submenu.
From this page, you can:
* Get your unique forwarding address.
* Configure email forwarding.
* Verify your forwarding setup.
* Enable automatic ticket creation.
* View setup instructions for different email providers.
![Email to Ticket settings page]()
*Email to Ticket settings page*
***
## Your workspace forwarding address
AgencyHandy generates a unique forwarding email address for every workspace. This address receives forwarded emails from your support inbox.
Click **Copy** to copy your workspace forwarding address.
Add this address as a forwarding destination in your email provider.
Complete the forwarding verification process required by your provider.
Once verification is complete, enable **Auto-create Ticket**.
![Workspace forwarding address with Copy button]()
*Workspace forwarding address with Copy button*
Your forwarding address is unique to your workspace and remains the same unless you regenerate it.
***
## Setting up email forwarding
AgencyHandy does not access your mailbox. Email forwarding is configured entirely within your email provider.
The Email to Ticket page includes setup guides for:
* Gmail
* Outlook / Microsoft 365
* Zoho Mail
* cPanel / Hosting
* Other providers that support email forwarding
Select your email provider on the Email to Ticket page to view the appropriate setup instructions.
***
## Gmail setup
If you use Gmail, follow these steps.
In Gmail, go to **Settings → See all settings → Forwarding and POP/IMAP**.
![Gmail Forwarding and POP/IMAP settings tab]()
*Gmail Forwarding and POP/IMAP settings tab*
Click **Add a forwarding address** and paste the forwarding address you copied from AgencyHandy. Google sends a confirmation email to verify the forwarding address. Return to AgencyHandy after saving the forwarding address.
![Gmail Add a forwarding address dialog]()
*Gmail Add a forwarding address dialog*
Return to **Workspace Config → Email to Ticket** and click **I've added the address in Gmail**. AgencyHandy waits for Google's confirmation email and automatically detects the confirmation link or verification code when it arrives, usually within one to two minutes. Once verification is complete, the forwarding setup is ready.
![Verifying the forwarding address in AgencyHandy]()
*Verifying the forwarding address in AgencyHandy*
In Gmail:
* Enable **Forward a copy of incoming mail**.
* Select your AgencyHandy forwarding address.
* Save your changes.
All future emails received by your support inbox are now forwarded to AgencyHandy.
![Gmail Forward a copy of incoming mail option]()
*Gmail Forward a copy of incoming mail option*
***
## Auto-create Ticket
After forwarding has been verified, enable the **Auto-create Ticket** toggle.
When enabled:
* Every forwarded email from an existing client automatically creates a new support ticket.
* Clients are matched using their email address.
* A success message confirms that Email to Ticket is active.
![Auto-create Ticket toggle enabled]()
*Auto-create Ticket toggle enabled*
Keep this option disabled until forwarding verification has been completed.
***
## Confirmation helper
For supported email providers, AgencyHandy includes a confirmation helper. After adding the forwarding address in your email provider:
1. Return to the Email to Ticket page.
2. Click the confirmation button, such as **I've added the address in Gmail**.
3. Wait while AgencyHandy checks for the provider's verification email.
4. Once detected, AgencyHandy automatically completes the verification process.
This removes the need to manually retrieve the verification email or confirmation code.
***
## Refresh verification status
If verification is taking longer than expected, click **Refresh** to check for newly received confirmation emails.
***
## How Email to Ticket works
Once Email to Ticket is configured:
1. A client sends an email to your support email address.
2. Your email provider automatically forwards a copy of the email to your AgencyHandy forwarding address.
3. AgencyHandy verifies the sender's email address.
4. If the sender matches an existing client in your workspace, a new ticket is automatically created.
***
## Notes
* Only emails from existing client email addresses create tickets automatically.
* Emails from unknown senders are ignored.
* Each workspace has its own unique forwarding address.
* AgencyHandy only receives forwarded copies of emails. It does not access your mailbox directly.
* Email reply threading is planned for a future release.
# Configure Your AgencyHandy Workspace General Settings
Source: https://docs.agencyhandy.com/workspace/general-settings
Set your workspace name, upload logos, add your agency address, and select the correct timezone to personalize your AgencyHandy workspace.
The General Settings page is the first place you'll visit after signing in to AgencyHandy. It lets you establish your agency's identity on the platform — from your logo and workspace name to your physical address and timezone. Every change you make here applies globally across the workspace for all users.
Only **Super Admins** and **Admins** can access and modify Workspace Config settings. If you don't see the **Workspace Config** option in the left navigation, contact your Super Admin to adjust your role permissions.
## Accessing General Settings
Log in to your AgencyHandy account. In the left navigation menu, click **Workspace Config**.
Click **General Settings** from the Workspace Config submenu. The General Settings panel opens on the right.
***
## Uploading Your Workspace Logo
AgencyHandy supports three distinct logo types, each displayed in a different part of the interface:
| Logo Type | Dimensions | Where It Appears |
| -------------- | ----------- | ---------------------------------------------- |
| Circle Logo | 32 × 32 px | Profile areas and compact UI elements |
| Favicon Logo | 16 × 16 px | Browser tab icon |
| Rectangle Logo | 142 × 36 px | Sidebar header (replaces circle logo when set) |
**Supported formats:** PNG, JPG, SVG
Under the logo section, click the **Upload Logo** button for the logo type you want to set.
Browse to the image on your device. Make sure the file matches the required dimensions and is in a supported format.
The logo preview updates immediately. Repeat for each logo type as needed.
Uploading a **Rectangle Logo** will replace the Circle Logo in the sidebar and automatically hide the workspace name text next to it. The rectangle logo also becomes the primary logo used in all other contexts where a logo is displayed — even if a circle logo is also uploaded.
***
## Setting Your Workspace Name and Address
### Workspace Name
Enter your agency's name in the **Workspace Name** field. This name:
* Appears throughout the platform for identification.
* Is used in the default AgencyHandy subdomain (e.g., `yourname.agencyhandy.com`).
Changing your workspace name updates your default subdomain immediately. If you share the default subdomain link with clients, they will need the updated URL. Consider setting up a [custom domain](/workspace/custom-domain) to avoid this issue.
### Workspace Address
Enter your agency's full physical address in the **Workspace Address** field. This address is used for official representation on invoices and client-facing documents, so ensure it is accurate and current.
***
## Selecting Your Timezone
Scroll to the **Time Zone** field and click the dropdown to expand the timezone list.
Select the timezone that matches your agency's primary operating location. All task deadlines, scheduled notifications, calendar events, and timestamps across the workspace are based on this setting.
An incorrect timezone setting causes scheduling errors for tasks, meetings, and invoice due dates. Double-check this setting before inviting your team or clients.
***
## Saving Your Changes
After filling in or updating any fields, click **Save Changes** at the bottom of the General Settings panel. All updates are applied globally and are immediately visible to every user in the workspace.
***
## Danger Zone: Deleting Your Workspace
At the bottom of the General Settings panel, there is a **Danger Zone** section containing the **Delete Workspace** button.
Deleting your workspace is **permanent and irreversible**. All data — including clients, orders, invoices, projects, and configurations — will be permanently erased. There is no recovery option. Only proceed if you are absolutely certain.
***
## Best Practices
Upload logos at the exact recommended pixel dimensions to prevent stretching, cropping, or blurry display across the platform.
Update your logo and address whenever your agency rebrands or changes location to keep all documents and client-facing pages accurate.
Configure your timezone before creating services, tasks, or scheduling anything to ensure all timestamps align correctly from the start.
Only grant Super Admin or Admin roles to personnel who genuinely need to modify workspace configurations, to prevent accidental changes.
# Customize Client Portals, Access Controls, and Tax Rates
Source: https://docs.agencyhandy.com/workspace/portals
Brand your client sign-in and sign-up pages, control sidebar visibility by role, and configure tax rates for invoices and checkout in AgencyHandy.
AgencyHandy gives you deep control over what your clients see and experience — from the very first page they land on when signing in, to which sections of the platform they can navigate after logging in. This page covers four interconnected configuration areas: the **Sign-in Portal**, the **Sign-up Portal**, **Sidebar & Access controls**, and **Tax Rates**. Together, these settings let you create a polished, role-appropriate experience for every user in your workspace.
All settings on this page require **Super Admin** or **Admin** access. Navigate to **Workspace Config** in the left sidebar to access each section.
***
## Sign-in Portal
The Sign-in Portal is the login page your clients and team members see when they access your AgencyHandy workspace. Customizing it ensures the first impression clients have is fully on-brand — complete with your agency's imagery, headline, and messaging.
### What You Can Customize
| Element | Description | Limit |
| ----------- | ----------------------------------------------------- | ------------------------- |
| **Heading** | The main title displayed at the top of the login page | Max 120 characters |
| **Image** | A branded photo or illustration shown on the page | PNG, JPG, JPEG — max 5 MB |
| **Subtext** | A short message below the login fields | Max 300 characters |
### Steps to Customize the Sign-in Portal
Go to **Workspace Config** in the left navigation, then select **Sign-in Portal** from the submenu.
Type your desired heading in the **Heading** field. Keep it concise and relevant — for example, *"Welcome back to \[Agency Name]"* or *"Your Client Portal."* The maximum length is 120 characters.
Click the upload area or drag and drop an image file (PNG, JPG, or JPEG, maximum 5 MB) to add a visual element to the sign-in page. This image typically appears alongside the login form.
Use a high-quality image that represents your agency — a photo of your team, a clean brand illustration, or a professional background. Ensure the file size is under 5 MB to avoid upload errors.
In the **Subtext** field, write a brief message to appear below the login fields — for example, a welcome note, support contact, or a short tagline. Keep it under 300 characters.
Review the sign-in page layout using the preview. Once you're satisfied, click **Save** (or **Update**) to apply the changes. Changes take effect immediately.
### Resetting to Defaults
Click **Reset Default Settings** on the Sign-in Portal page to remove all customizations and restore the original AgencyHandy sign-in page.
Resetting to defaults is irreversible. All custom headings, images, and subtext will be permanently removed. Click **Cancel** if you are not sure — unsaved changes are discarded and the current saved settings remain intact.
### Best Practices
* Keep the heading short and welcoming — clients see it before they log in, so make it reassuring.
* Use a professional image that represents your agency. Avoid generic stock photos that feel disconnected from your brand.
* Preview on different screen sizes before saving to ensure the image and text layout looks correct.
* If the image fails to upload, confirm it meets the format (PNG, JPG, JPEG) and size (under 5 MB) requirements.
## Sign-up Portal
The Sign-up Portal is the registration page new clients land on when they create an account in your workspace. Customizing it creates a consistent branded experience from the very first interaction a prospective client has with your agency's platform.
### What You Can Customize
| Element | Description | Limit |
| ----------- | ------------------------------------------------------- | ------------------------- |
| **Heading** | The main title displayed at the top of the sign-up page | Max 120 characters |
| **Image** | A branded photo or illustration shown on the page | PNG, JPG, JPEG — max 5 MB |
| **Subtext** | A short message below the registration fields | Max 300 characters |
### Steps to Customize the Sign-up Portal
Go to **Workspace Config** in the left navigation, then select **Sign-up Portal** from the submenu.
Type a heading in the **Heading** field that welcomes new clients. For example, *"Get started with \[Agency Name]"* or *"Create your client account."* Maximum 120 characters.
Click the upload area or drag and drop an image file (PNG, JPG, or JPEG, maximum 5 MB). This image is displayed on the sign-up page alongside the registration form.
Use the same visual style and color palette on both your Sign-in and Sign-up portal images to create a cohesive experience across the two pages.
Write a short supporting message in the **Subtext** field — for example, instructions on what to expect after signing up, or a brief value proposition. Maximum 300 characters.
Review the sign-up page using the preview option. Click **Save** (or **Update**) to apply changes immediately.
### Resetting to Defaults
Click **Reset Default Settings** on the Sign-up Portal page to remove all customizations and restore the original AgencyHandy sign-up page.
This action cannot be undone. All custom heading, image, and subtext configurations will be permanently erased.
### Best Practices
* Match the tone of the sign-up heading to your overall client communication style — professional, friendly, or both.
* Keep subtext focused: tell new clients what happens after they register (e.g., *"Once you sign up, our team will send you a welcome email within 24 hours."*).
* Test the sign-up flow yourself after saving changes to confirm the page looks and behaves as expected.
## Sidebar & Access Controls
The Sidebar & Access settings let you control exactly what each user role can see in the left navigation menu. You can rename menu items to match your agency's terminology, swap out default icons for custom ones, and toggle the visibility of any menu section per role. The result is a cleaner, purpose-built interface for every person who logs in.
### Roles You Can Configure
* Client
* Super Admin
* Admin
* Manager
* Assignee
* Custom (any custom roles you've created under Roles & Permissions)
### Steps to Customize Sidebar Menu Items
Go to **Workspace Config**, then select **Sidebar & Access** from the settings menu.
Click the **Customize** button at the top of the panel. The full list of current sidebar menu items appears under the **Main** category.
Click on any menu item's text field and type the new label. For example, rename "Dashboard" to "Overview" or "CRM" to "Contacts." Click **Save** to apply the new name.
Click the icon next to a menu item name. A popup opens with a set of icon options — select one from the library, or upload a custom 32×32 px image to use your own branded icon. Click **Save** to apply.
### Steps to Configure Role-Based Visibility
Click the **Edit Access** button (next to the **Customize** button). You'll see tabs for each available role.
Click the tab for the role you want to configure — for example, **Client**.
For each menu item listed, use the toggle to show or hide it for the selected role. For example, you might hide **Invoices** and **Subscriptions** from Clients while keeping them visible to Admins and Managers.
Click **Save**. The updated visibility settings take effect immediately — users see the changes on their next page navigation or after logging back in.
Click **Reset to Default** on any role's tab to restore the original visibility settings for that role.
A clean, minimal sidebar improves the client experience. Showing clients only what they need — such as **Dashboard**, **Orders**, and **Messages** — reduces confusion and prevents them from stumbling across internal-only sections.
### Example Role Configurations
| Role | Recommended Visible Sections |
| ----------- | ------------------------------------------------- |
| Client | Dashboard, Orders, Messages, Invoices (if needed) |
| Manager | CRM, Projects, Timesheet, Tasks |
| Assignee | Dashboard, Tasks, Projects, Messages |
| Super Admin | All sections (no restrictions) |
### Important Notes
* **Changes are instant:** Role visibility updates reflect immediately after users refresh or log back in.
* **Most permissive role wins:** If a user holds multiple roles, the role with the broadest access takes precedence.
* **Custom icons:** Upload 32×32 px images to match your agency's brand visuals in the sidebar.
* **Naming consistency:** Use clear, consistent naming conventions your whole team understands — avoid abbreviations or internal jargon that new team members won't recognize.
## Tax Rates
The Tax Rates feature lets you create, manage, and apply tax configurations across your services, subscriptions, and invoices. You can set up multiple tax types — VAT, GST, Sales Tax, and others — with country-specific and state-specific rates, support for both inclusive and exclusive pricing models, and automatic application at checkout based on client location.
Only **Super Admins** and **Admins** can create, edit, or delete tax configurations.
### Tax Concepts at a Glance
| Concept | Definition |
| ------------- | --------------------------------------------------------------------------------------------------- |
| **Exclusive** | Tax is added on top of the listed price at checkout (e.g., $100 + 10% tax = $110 total) |
| **Inclusive** | Tax is already included in the price shown to the customer (e.g., \$110 total already includes tax) |
| **Tax ID** | Your agency's business tax identification number, shown on invoices |
### Step 1: Create a Tax Rate
Go to **Workspace Config**, then click the **Tax Rates** tab.
Click the **+ New Tax** button. A form appears.
Complete the following fields:
* **Title / Tax Type** *(required)*: Enter a descriptive name, e.g., Standard VAT, Reduced GST, or US Sales Tax. Maximum 255 characters.
* **Tax ID** *(optional)*: Your agency's business tax identification number. Maximum 20 characters.
* **Home Country**: Select the primary country this tax applies to.
* **Home Country General Tax Rate %** *(optional)*: The default rate for your home country.
* **Country-Specific Rates** *(optional)*: Add per-country rates with optional state, ZIP code, and percentage. This is useful for agencies serving clients in multiple tax jurisdictions.
Toggle the tax to **Active** to make it immediately available for use in services and invoices. Set it to **Inactive** to save the configuration without applying it to new purchases yet.
Click **Save**. The tax appears in your Tax Rates list and is now available to link to services.
You can support up to 4 decimal places in tax rate percentages. A 0% tax rate is valid — use it for zero-rated items or compliance scenarios where tax must be listed but amounts to zero.
### Step 2: Link Taxes to Services
Navigate to **Services** and create a new service or edit an existing one.
Proceed to Step 3 (Additional Info) of the service setup wizard.
Click **Add Tax** and select one or more tax types from your configured list. Choose whether taxes apply as **inclusive** or **exclusive** for this service. This setting applies to all linked taxes on the service, including setup fees and add-ons.
### Step 3: How Taxes Are Applied
Taxes can be applied **automatically during checkout** or **manually on invoices**:
**Automatic (Checkout)**
* Taxes linked to a service are automatically calculated based on the client's billing location.
* The client must provide their country, state, and ZIP code at checkout for location-based tax to apply.
* For Stripe India accounts, full location information (country, state, ZIP) is mandatory.
**Manual (Invoice)**
* When creating an invoice manually, click **Add Taxes** to choose which taxes to apply.
* Billing address fields populate automatically.
* **Only exclusive taxes** can be applied to manual invoices — inclusive taxes are not supported in this flow.
### Invoice Tax Display
Every invoice that includes a tax shows the following details:
* **Tax Name** — the label you entered (e.g., VAT, GST)
* **Tax Percentage** — the applied rate (e.g., 15%)
* **Tax Amount** — the calculated amount charged
### Managing Existing Tax Rates
* **Edit a tax:** Click the tax entry in the list to update its title, rate, or country rules. Updates apply to future invoices and purchases only.
* **Delete a tax:** Deleted taxes no longer apply to new purchases or subscriptions, but existing invoices that included them are unaffected.
* **Deactivate a tax:** Set a tax to **Inactive** to stop applying it to new purchases without deleting the configuration.
### Important Notes
* **Coupon discounts apply before tax:** When a client uses a discount coupon, the tax is calculated on the discounted price, not the original price.
* **Multiple taxes per service:** You can attach more than one tax to a single service (e.g., VAT + GST simultaneously).
* **Tax applies to add-ons and setup fees:** If your service has a setup fee or add-ons, tax is applied to those amounts as well.
* **Client location is prefilled:** If a client has a billing country and state saved in their profile, those fields are pre-populated at checkout. However, editing the location during checkout does **not** update the client's profile.
* **ZIP code-based state detection:** For U.S. clients, the system can automatically detect the state from the ZIP code and apply the correct regional tax if configured.