> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monk.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Acumatica
> Monk integration with Acumatica Cloud ERP
# Acumatica
Monk follows up on overdue Acumatica invoices and keeps customer replies,
payment promises, and collection history together. Your team can see who has
promised to pay and which conversations need attention.
You continue to issue invoices and record payments in Acumatica. The
connection is read-only and refreshes every hour. Monk never writes back to
your ERP.
## How it works in practice
A customer receives a reminder for one overdue invoice and replies with a
payment date. Monk records the promised date and pauses reminders based on
your team's settings. A colleague can see the commitment alongside the
invoice without searching the inbox.
Once your team records full payment in Acumatica, the next completed sync
marks the invoice as paid in Monk and stops reminders for it. If the customer
disputes the invoice, Monk pauses reminders and flags the conversation for
review.
## What stays in Acumatica and what happens in Monk
Acumatica lets you configure dunning levels by customer class. If your team
also tracks payment promises and follow-up dates in inboxes or spreadsheets,
Monk keeps those commitments and customer replies alongside the relevant
invoices.
| In Acumatica | In Monk |
| ------------------------------------------------ | ---------------------------------------------------------------- |
| Creating, releasing, and correcting AR documents | Following up on overdue invoices, per customer or customer group |
| Recording payments, credit memos, and write-offs | Tracking payments and the remaining balance on each invoice |
| Maintaining customer accounts and contacts | Using those contacts for collection reminders |
Credit limits, payment terms, and credit holds stay in Acumatica, along with
the general ledger, month-end close, and statutory reporting. Monk reports
aging and DSO for the invoices it imports.
Reminders go to the contacts already on the Acumatica customer account: every
active contact with an email address, plus the account email when no contact
carries it. Recipients are reviewed with you during onboarding.
## Requirements and scope
* **Acumatica 2026 R1 or later**, Acumatica-hosted or self-hosted, reachable
over public HTTPS. Monk reads the `Default` endpoint at version `25.200.001`.
* **One tenant, one company, one branch per Monk org.** The tenant is part of
the client ID. Connect additional Monk orgs for additional tenants, and agree
the branch with your Monk contact if receivables sit across several.
* **Single currency.** Monk currently supports tenants that invoice in one
currency, matching your Monk organization's currency. Multi-currency support
is planned. If your tenant invoices in multiple currencies, talk to your
Monk representative about your requirements.
* **Hourly refresh, plus on demand.** Monk reads what changed since the last
run every hour, and **Refresh now** starts a run immediately. Reminders use
the balance from the latest refresh, so after posting a large batch of
payments, refresh before reminders go out.
* **History.** The first refresh reads customers, contacts, credit memos,
payments, and applications in full, and invoices changed in the last 12
months. The import start date agreed during onboarding decides which of those
become invoices in Monk.
* **One API user licence slot.** Monk signs in as a dedicated Acumatica user,
which holds one API user slot while connected.
* **Customer hierarchy.** Monk reads the **Parent Account** on a customer and
links the child to its parent once both exist in Monk. Reminders go to each
customer's own contacts, parent or child.
## Setting up Acumatica
**Setup is done together with Monk.** Steps 1 and 2 use standard Acumatica
forms and need no customization project or installed component. Connecting,
the first sync, checking the imported invoices against Acumatica, and
switching on invoice import and follow-ups are done with a Monk engineer.
Agree the import start date and the refresh-token setting with your Monk
contact before you register the Connected Application.
Steps 1 and 2 are done by your Acumatica administrator; step 3 by a Monk user
who can manage integrations. Before you start, open **Integrations → Acumatica**
in Monk and copy the **Redirect URI** shown there; step 2 needs it.
Create a role on **User Roles** (SM201005), for example `MONK-API-READ`,
then on **Access Rights by Role** (SM201025) give it **View Only** on four
forms and leave every other form revoked:
* Customers (AR303000), under Receivables
* Invoices and Memos (AR301000), under Receivables
* Payments and Applications (AR302000), under Receivables
* Contacts (CR302000), under Marketing
On **Users** (SM201010), create a dedicated user with only that role. It
signs in to a browser once, during consent, so it must be a regular user
rather than Acumatica's API-only user type. Check **License Monitoring
Console** (SM604000) for a free API user slot if other integrations already
use the API. If the user later loses access to one of these forms,
refreshes stop at that read until access is restored.
On **Connected Applications** (SM303010):
* Set **Flow** to **Authorization Code**.
* On the **Redirect URIs** tab, paste the redirect URI copied from Monk.
* On the **Secrets** tab, add a **Shared Secret** and copy it when it is
shown; Acumatica does not display it again.
* Under **Refresh Tokens**, choose a mode other than No Refresh Tokens.
With sliding expiration the connection stays alive while Monk keeps
syncing, up to any absolute cap you set; with absolute expiration an
administrator re-authorizes on that schedule.
* Save. Acumatica generates the client ID as `@`, where the
suffix is the tenant you were signed in to. Monk needs the whole value.
In **Integrations → Acumatica**, enter the instance URL (the site root only,
for example `https://erp.example.com/Instance`, never a screen URL), the
full client ID, and the client secret, then click **Save and authorize**.
Monk sends you to your instance: sign in as the dedicated user (sign out of
Acumatica first, or use a private window) and approve the two permissions,
**Access to Web Services API** and **Offline Access**.
The authorization link expires after ten minutes and is bound to the Monk
user who started it. If it expires, click **Authorize in Acumatica** on the
Monk page to try again; your Acumatica settings and secret are unaffected.
If Monk should read one branch only, set it under **Instance settings**
right after connecting and before the first refresh. Once data has synced,
the branch is fixed.
## Supported entities
| Monk entity | Acumatica entity | Acumatica form |
| ------------------- | -------------------------------------- | ------------------------------------ |
| Customer | Customer, including its parent account | Customers (AR303000) |
| Customer contacts | Contact | Contacts (CR302000) |
| Invoice and lines | AR invoice, debit memo, overdue charge | Invoices and Memos (AR301000) |
| Credit memo | AR credit memo | Invoices and Memos (AR301000) |
| Payment | AR payment, prepayment | Payments and Applications (AR302000) |
| Payment application | AR application, including write-offs | Payments and Applications (AR302000) |
## How Acumatica documents map to Monk
Each sync records the payments, credit memos, and write-offs applied to
invoices already in Monk. Their balances reflect those applications. When
Acumatica shows an invoice closed or with a zero balance, Monk marks it paid.
```mermaid theme={null}
flowchart LR
P["Payment applied"] --> S["Invoice balance in Monk"]
C["Credit memo applied"] --> S
W["Write-off
(separate document, or
entered on the payment)"] --> S
S -->|"Fully covered"| D["Paid
Reminders stop"]
S -->|"Balance remains"| O["Open
Reminders continue"]
```
| In Acumatica | In Monk |
| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| A payment covers part of an invoice | An allocation for the paid amount; the invoice stays open for the remainder |
| One payment is applied to several invoices | Each invoice gets its own allocation, read from the application records |
| A balance is written off with a separate write-off document | A non-cash settlement; the invoice closes without counting the amount as cash |
| A write-off amount is entered while applying a payment | The same non-cash settlement; only the cash portion counts as cash received |
| A released invoice is reversed with a credit memo (cancellation) | The invoice shows as paid by the credit memo and reminders stop |
| An invoice is on hold, on credit hold, or not yet released | Not imported; it appears once released |
| A payment is applied without the invoice record changing | Picked up anyway: applications are read on their own, not inferred from the invoice |
| A customer has a parent account | Linked to the parent once both exist in Monk; reminders still go to the customer's contacts |
| A contact is inactive or has no email address | Not imported as a recipient |
| The API user loses access to one of the four forms | The refresh stops at that read; nothing partial reaches Monk until access is restored |
| Acumatica returns a truncated or malformed page | The refresh fails instead of importing an empty page |
| The instance publishes `Default` at a version other than `25.200.001` | Talk to your Monk contact before connecting; the integration is validated against `25.200.001` |
## Authentication and connection
* Your Acumatica administrator registers a **Connected Application**
(SM303010) with the Authorization Code flow. Monk requests two scopes, shown
on the consent screen as **Access to Web Services API** and **Offline
Access**, and acts as the Acumatica user who approves them.
* Monk stores your instance URL, tenant, client ID, shared secret, and the
access and refresh tokens encrypted at rest, and rotates refresh tokens
automatically.
* The instance address is validated when you connect and each time Monk
requests a token: public HTTPS only, no private or internal hosts. Reads use
the validated address and never follow a redirect to another host.
* If the grant is revoked or a token refresh is refused, the connection shows
**Authorization needed** with an **Authorize in Acumatica** button. To be
emailed when that happens, turn on **Integration reconnect required** under
Settings → Notifications in Monk and add recipients.
* **To revoke access at the source**, open the Connected Application in
Acumatica and click **Revoke Access**, which removes the tokens Monk holds,
and delete its shared secret so no new token can be requested.
* **Disconnect** in Monk stops reads and archives the connection with its
settings so the same instance can be reconnected later. Imported customers
and invoices stay in Monk with the balances from the last refresh, and
nothing is revoked inside Acumatica. Disconnect does not by itself stop
follow-ups on those invoices, so ask your Monk contact to switch off
follow-ups at the same time.
## Configuration and sync
* **Instance and tenant:** your Acumatica site URL and Connected Application
credentials.
* **Endpoint version:** leave blank. Monk reads the `Default` endpoint at
version `25.200.001`, which Acumatica 2026 R1 and later builds publish, and
the integration is validated against that version. If **Web Service
Endpoints** (SM207060) shows `Default` at another version, talk to your Monk
contact before connecting.
* **Branch:** the branch Monk's reads run under. Leave blank to use the
dedicated user's default branch. Fixed once data has synced.
* **Licence tier:** leave blank unless you are sure of it. Blank means Monk
reads at its slowest pace, one request at a time and at most 50 a minute.
Acumatica enforces its per-minute API limit by delaying requests, so a tier
set higher than your licence allows shows up as slower screens for your own
users rather than as an error in Monk. Set it to the tier shown in **License
Monitoring Console** (SM604000) only when you want the first read to go
faster.
* **Import start date, automatic import, and follow-ups:** how far back Monk
imports invoices, whether new documents import automatically, and whether
Monk follows up on Acumatica invoices at all. All three are switched on with
your Monk contact during onboarding, and off the same way. Invoices and their
payments are imported together, so a partially paid invoice never appears
with its full balance.
* **Refresh behavior:** a truncated or malformed response from Acumatica fails
the refresh instead of importing an empty page, so a bad read never
overwrites correct balances. A daily check calls your instance with the
stored grant, so a revoked grant or an instance Monk cannot read is reported
as **Authorization needed** and emailed to the recipients you set.
**Refresh now** reports that a refresh started; a first refresh can take
several minutes.
## Frequently asked questions
**How do our customers pay?**
They keep using your existing payment methods. Monk reminders include a PDF
copy of the invoice but no payment link. Your team records payments in
Acumatica as usual.
**Can we keep sending Acumatica dunning letters while we use Monk?**
You can, but the two do not know about each other. Prepare Dunning Letters
(AR521000) reads Acumatica and Monk sends its own reminders on its own schedule,
so a customer covered by both receives both. When piloting, choose the customers
Monk follows up on and exclude them from your Acumatica dunning run.
**Do credit limits, credit holds, or customer classes affect what Monk sends?**
An invoice on credit hold is not imported until it is released. Credit limits
and customer classes stay in Acumatica; you configure each customer's
reminder sequence in Monk.
**Can we test the integration in an Acumatica sandbox before connecting production?**
Yes. You can test the integration in an Acumatica sandbox before connecting
production. Let your Monk representative know before you start so we can
plan both connections and validate the workflows you need.
Production requires a new connection, and any data imported from the sandbox
stays in Monk. Planning ahead helps us keep test data separate from your
production receivables.