> ## Documentation Index
> Fetch the complete documentation index at: https://help.billpal.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Automate documents with rules
> Categorize, tag, exclude, or flag documents for review automatically.
A rule says once what should happen to certain documents. Billpal then applies it to every new document that matches. For example: every incoming invoice from Slack and Notion gets the Software account, counts as a subscription, and gets the tag "SaaS".
A rule has two parts:
* **When:** the conditions a document has to meet
* **Then:** the changes Billpal makes to that document
Only admins can create and edit rules. Members see every rule and can open it, but can't change it.
## Create a rule
Click **Rules** in the navigation, then **Add new**.
Under **Rule name**, describe what the rule does, for example "Categorize software subscriptions". You'll see the name in the list and under **Activity**.
**When** always starts with **Direction**: **Incoming** for documents you receive from suppliers, or **Outgoing** for documents you send to customers. Each rule covers exactly one direction.
Click **Add condition** and pick a field, for example **Supplier** or **Amount**. A document only matches if every condition is true.
Under **Then**, click **Add action** and pick what should happen to matching documents.
Click **Create rule**. Billpal then asks whether the rule should also apply to documents already in the workspace.
## Conditions
You can use each field once per rule, and every condition has to be true. If a rule should apply to "A or B", use **is any of** or **contains any of**. If that doesn't fit, create two rules.
| Field | What Billpal checks | Comparisons |
| - | - | - |
| **Document** | All the text: content, names and addresses of both sides, document and reference numbers, VAT IDs, line items, and file name | contains any of, contains all of, contains none of |
| **Line items** | Only the line item descriptions | contains any of, contains all of, contains none of |
| **Supplier** | A supplier from **Contacts**. Or the name or address on the document, or whether the supplier's VAT ID is on it | is, is not, is any of, is not any of, is known, is unknown. For name and address: contains … For Tax ID: Known, Unknown |
| **Customer** | Same as Supplier, for the customer | same as Supplier |
| **Amount** | The document total, optionally only in certain currencies | equals, is greater than, is less than, is between |
| **Source** | How the document arrived: upload, email, WhatsApp, or portal. Optionally only through certain mailboxes, WhatsApp accounts, or portals | is |
| **Category** | The account on the line items | is any of, is not any of |
| **Type** | Invoice, receipt, credit note, or reminder | is, is not, is any of, is not any of |
For **Keywords** on Document, Line items, name, and address, type each one and press Enter, up to 10 per condition. Upper and lower case don't matter. A keyword also matches inside a word: "pro" finds "Pro plan" but also "product" and "approval". So don't make keywords too short.
For **Amount**, Billpal compares without the sign. If you pick only currencies and no amount, every document in those currencies matches.
## Changes
You can use each action once per rule.
| Action | What it does |
| - | - |
| **Add a tag** | Adds one or more tags. You can create new tags right in the rule. |
| **Category** | Sets the account. It applies to every line item on the document. |
| **Create a note** | Adds a note to the document. If you mention someone with @, they get a notification. Turn on **Review needed** to also put the document in Review. |
| **Supplier** or **Customer** | Assigns the document to a specific contact. |
| **Exclude** | Sets the document to Excluded, so it isn't in any export. |
| **Payment method** | Sets the payment method, for example PayPal or American Express. |
| **Payment status** | Sets Paid, Unpaid, Partially paid, or Refunded. With Paid, Billpal uses the document date as the payment date if none is set. With Unpaid, Billpal clears the payment date. |
| **Subscription** | Marks matching documents as recurring (**Subscription**) or as **One-off**. |
## When a rule runs
* **New documents:** While a rule is on, Billpal checks every new document right after reading it.
* **Side confirmed:** When someone sets whether your company is the supplier or the customer on a document, Billpal checks the rules for that document again. So rules also apply to documents that started out in Review.
* **Existing documents:** only if you choose it when saving.
### Apply to existing documents
After you save, Billpal asks, for example, "Also apply to 12 existing documents?". The count only includes documents the rule would actually change.
* **Only new documents:** The rule applies from now on. Existing documents stay as they are.
* **Apply to 12 documents:** Billpal applies the rule to those documents in the background.
Billpal asks for a new rule and whenever you've edited the conditions or changes. Renaming or reordering doesn't trigger it.
Two things never change: Billpal doesn't touch exported documents, so nothing drifts from what's already in your books. And anything someone changed by hand on a document stays too.
## Order and manual edits
In the list under **Rules**, drag a rule up or down. The order decides when two rules want to set the same field:
* **Same field:** If two matching rules set different accounts, for example, the higher rule wins. The lower one skips that change.
* **Tags and notes:** These add up from every matching rule. Billpal leaves out duplicates.
* **Manual edits win:** If someone changed a field on the document by hand, no rule overwrites it, not even on a later run.
## See and undo what a rule did
In **Activity**, on the **Rules** tab, you see when a rule was created or changed and what it changed on which document. To undo a single change, click **Undo rule action**.
## Manage rules
* **Turn on and off:** With the switch in the list. A rule that's off doesn't run. When you turn it back on, it applies to new documents from then on.
* **Edit:** In the rule's menu. Members see **View** here.
* **Duplicate:** Creates a copy you can adjust. Handy for similar rules with a different supplier or account.
* **Delete rule:** The rule stops running. Its past activity stays in the history.
## Examples
### Categorize software subscriptions
* **When:** Direction Incoming, Supplier is any of Slack, Notion
* **Then:** Category Software, Subscription, Add a tag "SaaS"
### Approval from 1,000
* **When:** Direction Incoming, Amount is greater than 1,000, currency EUR
* **Then:** Create a note "Please approve", mention the approver with @, and turn on **Review needed**
The approver gets a notification, and the document stays in Review until they close it with **Done**.
### Keep personal purchases out
* **When:** Direction Incoming, Customer, Address contains any of "5 Sample Street"
* **Then:** Exclude, Add a tag "Personal"
Documents addressed to your home stay out of every export and are still easy to find.
## Related pages
How documents end up in Review and how to close it.
The suppliers and customers rules refer to.
What happens to excluded documents in an export.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.