--- title: "Set up Acumatica in Wrapbook" slug: "set-up-acumatica-in-wrapbook" updated: 2026-11-18T19:41:19Z published: 2026-11-18T19:41:19Z canonical: "help.wrapbook.com/set-up-acumatica-in-wrapbook" --- > ## Documentation Index > Fetch the complete documentation index at: https://help.wrapbook.com/llms.txt > Use this file to discover all available pages before exploring further. # Set up Acumatica in Wrapbook ## Overview This guide walks you through connecting your Acumatica instance to Wrapbook so payroll data flows automatically into your General Ledger. When you issue a payroll in Wrapbook, the integration pushes a **Bill** to Acumatica for your AP team to review and post. **Setup time:** Approximately 30–45 minutes once you have the prerequisites ready and your Acumatica admin available. **Who this is for:** Company Admins at production companies using Acumatica as their accounting system. > [!NOTE] > Permission required > > To set up the Acumatica integration, your account must have one of the following [roles](/v1/docs/roles-permissions) enabled: > > - Role: Company Admin > - Custom role with: Company settings/Accounting settings — Full access ### What flows from Wrapbook to Acumatica Each time you issue a payroll in Wrapbook, a **Bill** is pushed to Acumatica approximately 1–2 minutes after issuance. In Acumatica, the Bill appears in the **Processing** state. State names can be customized in your tenant, so your label may differ. Your AP team reviews and posts the Bill. Each Bill includes: - **Vendor:** default vendor configured (e.g., Wrapbook) - **Bill number:** the Wrapbook payroll display ID (e.g., `Payroll-00748134`) - **Document date:** the payroll's issue date - **Lines:** one line per pay type per worker, plus fringes (Employer Taxes, Workers' Comp, Platform Fees, etc.) broken out and consolidated by category ### What flows from Acumatica to Wrapbook Wrapbook reads the following from Acumatica to populate your mapping configuration. This is **read-only** — Wrapbook never writes back to your Acumatica dimensions data: The integration passes the following Acumatica dimensions on Bill lines: **Required:** - **Account** (GL account) — Typically set as default for production expense account at company level - **Vendor** — Vendor record used on all Bills. Create the record before setup and select it as the default vendor. **Optional (configurable per project):** - **Cost codes** — departmental allocation or cost center tracking - **Projects** — project or job costing; synced from your Acumatica project list - **Project tasks** — task-level or phase coding within a project; only if Projects enabled - **Subaccounts** — GL sub-account segment for detail-level coding - **Bank accounts** — payroll disbursement account coding - **Branches** — multi-branch or multi-location accounting; synced from your entity structure **You can set defaults at the company level and override them per project.** ### Limitations ⚠️ **Custom Segments and Custom Fields are not supported.** Only the standard dimensions above are passed. If your account requires an unsupported field on Bills, ask your Acumatica administrator to make it optional before setup. ## Before you start The setup steps in Step 1 are performed in your Acumatica instance and require familiarity with your Acumatica system. If you need help creating users, configuring permissions, generating API credentials, or understanding your system's configuration, contact your Acumatica system administrator or [support team](https://www.acumatica.com/support/). Have the following ready before beginning setup: - **Project chart template** — start from the Wrapbook template or a blank template (i.e., line numbers & sections) - **A vendor record for Wrapbook in Acumatica** (`"Wrapbook"`). Create one manually if it doesn't exist — the integration does not auto-create vendors. - **Dimension requirements** — know which of Cost code, Project task, Subaccount, Project, and Bank account your GL accounts require on transaction lines. ⚠️ **Confirm your tenant before you start.** Check the tenant selector in the top bar or look for CompanyID= in the browser URL. The role and Connected Application you create are scoped by your login tenant. Never create these objects in the System tenant (Tenant ID 1). ## Step 1: Acumatica Setup ### A: Create the Integration Role **Screen:** User Roles (SM201005) 1. Navigate to **System → User Security → User Roles** or paste `SM201005` into the Acumatica search bar 2. The screen typically opens with a blank record in insert mode. Type directly into the **Role Name** field: - **Role Name:** `Wrapbook Integration` - **Role Description:** (optional) `API service account for Wrapbook AP bill import` 3. Leave **Guest Role** unchecked 4. Click **Save** The role has no access to anything at this point — that's expected. You'll grant access in Step 2. ### B: Grant Access Rights by Workspace and Form **Screen:** Access Rights by Role (SM201025) ⚠️ **Critical conceptual note:** Acumatica permissions are **screen-based, not entity-based**. There is no "Bills: Create, View, Edit" object. Instead, you set one access level on the Bills and Adjustments form. The access rights tree is organized by **workspace**, not by accounting module (e.g., you'll find Payables and Finance, not "Accounts Payable" or "General Ledger"). **Procedure:** 1. Navigate to **Access Rights by Role** or paste `SM201025` into the search bar 2. In the **Role Name** field at the top, select `Wrapbook Integration` 3. In the left tree, select a workspace name (do NOT expand the tree into individual tabs/fields) 4. The right pane fills with forms in that workspace; set the access level for each form using the dropdown 5. **Click Save before moving to the next workspace** — changes are discarded if you switch without saving **Permission matrix by workspace:** | Workspace | Form | Screen ID | Access Level | Why | | --- | --- | --- | --- | --- | | **Payables** | Bills and Adjustments | AP301000 | **Insert** | Wrapbook creates AP bills | | **Payables** | Suppliers/Vendors | AP303000 | **View Only** | Resolve vendor records on bills | | **Configuration** | Branches | CS102000 | **View Only** | Branch assignment on bills | | **Configuration** | Departments | EP201500 | **View Only** | Department coding (optional) | | **Finance** | Chart of Accounts | GL202500 | **View Only** | GL account validation | | **Finance** | Subaccounts | GL203000 | **View Only** | Subaccount segment of GL key | | **Projects** | Projects | PM301000 | **View Only** | Project coding | | **Projects** | Project Tasks | PM302000 | **View Only** | Task coding on bill lines | **Important notes:** - **Vendors vs Suppliers terminology:** Some tenants label vendors as suppliers. If you see "Suppliers" instead of "Vendors", it's the same form (AP303000). Verify by the form screen ID or nearby entries like "Supplier Locations". - **Watch for duplicate form names:** The Projects workspace may show two entries named "Projects" — use the access rights dropdown options to tell them apart. Data entry forms show graduated options (Revoked, View Only, Edit, Insert, Delete); reports show only Revoked and Granted. Select only the data entry form. - **Do NOT set permissions on the workspace row itself** — this applies the level to every form in the workspace. Set values only on individual form rows. - **Do NOT expand the tree** — everything you need is in the right pane once the workspace is selected. ### C: Create the API User Account **Screen:** Users (SM201010) 1. Navigate to **System → User Security → Users** or paste `SM201010` into the search bar 2. Click **+** to add a new user 3. Fill in the form: - **Login:** `Wrapbook_` (e.g., `Wrapbook_ABC123`) - **Email:** Use a monitored internal address (not personal), since Acumatica sends password expiry and lockout notices here - **First Name:** `Wrapbook` - **Last Name:** `Integration` 4. **Set a password** — generate a long random string (32+ characters) and store it immediately in your password manager 5. Check **Active** 6. **IMPORTANT — Uncheck "Force User to Change Password on Next Login"** if present — a service account cannot complete an interactive password change, and this checkbox breaks the integration on first connection 7. **Consider checking "Password Never Expires"** — otherwise, set a calendar reminder to rotate the password before expiry, because an expired service account password fails silently on Wrapbook's side 8. Click **Save** ⚠️ Do not reuse an existing named user account, and do not use the admin account for this purpose. ### D: Assign the Role to the API User **Screen:** Users (SM201010) Still on the Users screen with your new account open: 1. Go to the **Roles** tab 2. Check the box next to `Wrapbook Integration` 3. Click **Save** **Verify before moving on:** Reopen Access Rights by Role (SM201025), select `Wrapbook Integration`, and confirm all eight forms from Step 2 carry the levels you set and nothing else was granted. ### E: Create the Connected Application (OAuth 2.0) **Screen:** Connected Applications (SM303010) ⚠️ **Confirm your tenant before you start.** Check the tenant selector in the top bar or look for CompanyID= in the browser URL. The connected application is branded with the tenant you're signed into when you create it. Creating one in the wrong tenant produces credentials that silently read and write the wrong company's data. 1. Navigate to **Integration → Connected Applications** or paste `SM303010` into the search bar 2. Click **+** for a new record 3. Fill in the form: - **Client Name:** `Wrapbook Integration - ` (e.g., `Wrapbook Integration - ABC123`) - **Active:** checked - **Flow:** `Resource Owner Password Credentials` - **Plug-In:** `No Plug-In` 4. Click **Save** 5. Scroll to the **Secrets** section and click **Add Shared Secret** - Give it a description like `Wrapbook prod` (for tracking) 6. **Copy the Client ID and Client Secret immediately** — Acumatica displays them only once and cannot be retrieved afterward ⚠️ **Copy the entire Client ID including the @TenantName suffix.** That suffix is what routes API requests to the correct company. Do NOT trim it or hand-edit it. Verify the suffix names your intended tenant (compare against the Tenants list if unsure). Store all three values securely (password manager alongside credentials from Step 3): - Client ID (full, with @TenantName) - Client Secret - Username and password from Step 3 ### F: Confirm the Web Service Endpoint Version **Screen:** Web Service Endpoints (SM207060) 1. Navigate to **System → Customization → Web Service Endpoints** or paste `SM207060` into the search bar 2. Look at the **Endpoint Name** and **Endpoint Version** columns 3. Find the rows named **Default** (there may be several, representing different versions of the same endpoint) 4. **Use the highest Default version** unless Wrapbook specifies otherwise 5. Note both the endpoint name and version in the format: `Default/` (e.g., `Default/24.200.001`) ⚠️ **Do NOT infer a version from the highest number on screen** — endpoint versions are numbered independently per endpoint. A non-Default endpoint with a higher version number does not mean a newer Default exists. Ask Wrapbook to confirm which version they require before finalizing. **Ignore non-Default endpoints** — entries like MANUFACTURING, eCommerce, and GLConsolidation are specialized and do not expose what Wrapbook needs. Their presence signals that other integrations are already using this instance's API connection pool. ## Step 2: Connect Wrapbook to Acumatica 1. In Wrapbook, go to **Company Settings → Accounting → Integrations** 2. Click **Connect** next to Acumatica 3. Enter the following: | Wrapbook field | Value | Where it comes from | | --- | --- | --- | | **Site URL** | `https:// .acumatica.com` | Your Acumatica login URL (no path or query string) | | **Client ID** | Full GUID with @TenantName suffix | Step 1.E | | **Client Secret** | Client secret generated | Step 1.E | | **Username** | `Wrapbook_` | Step 1.C | | **Password** | User Password | Step 1.C (the password you generated) | | **Branch ID** (optional) | — | From Branches (CS102000) if tenant has multiple branches; leave blank to use account default | | **Web Service Endpoint** | `Default/` | Step 6 (format as Name/Version, e.g., `Default/24.200.001`) | Wrapbook will validate the credentials and fetch your reference data from Acumatica (this takes 2–5 minutes). ### Set company-level defaults After connecting, configure your company defaults: - **Default vendor:** select Wrapbook from the vendor list (the vendor record you created in Acumatica before setup) - **Default GL/expense account code** — this is the fallback account inherited by all projects - **Enable dimensions:** Under **Company Settings → Integrations Settings → Edit Dimensions**, select which optional dimensions apply to your GL accounts: Cost code, Project task, Subaccount, Project, Bank account ### Confirm data pulled correctly Wrapbook fetches your Chart of Accounts, Vendors, Cost Codes, Projects, Project Tasks, Subaccounts, and Bank Accounts from Acumatica. This typically appears in your mapping UI within 5 minutes. **Confirm all lists are populated before moving to the next step.** If any list is empty, it's almost always a role permission issue — verify the API user has Insert or View access on the corresponding form. ## Step 3: Configure your Chart Mapping Before configuring individual projects, set up your [Project Chart Template](/v1/docs/production-accounting-settings#chart-of-accounts) — this is done once and reused across projects. ### A. Select the Chart of Accounts 1. Go to **Company Settings → Project chart templates → Edit** 2. Select an AICP or custom chart already mapped at the company level - Each chart line maps to a single GL account - Any other dimensions are applied separately at push time based on the project or company defaults; they are not configured at the individual line level ### B. Map fringe lines Fringe costs are mapped on the chart’s *Fringe mapping rules* tab. For instructions, see [Map fringe costs with fringe mapping rules](/v1/docs/map-fringe-costs-with-fringe-mapping-rules). If the chart previously used fringe-line mappings, Wrapbook carried those mappings over to the *Fringe mapping rules* tab. ## Step 4: Configure each project After the company-level connection is set up, each Wrapbook project needs the following confirmed before its first payroll sync. ### A. Assign the Chart Template (optional) Go to **Project Settings → Cost tracking**, enable **Accounting chart**, and select a Chart Template from the dropdown. Use **Manage chart** to review or adjust the chart's line-level mappings if needed. ### B. Set project-level dimension overrides (optional) Go to **Company Settings → Integrations Settings → Edit** to override project dimensions using the Feature Dimension Management functionality. Each dimension can be overridden at the project level under the **Override project dimensions** section. If not overridden, dimensions inherit the company-level defaults. ### C. Verify timecard coding is complete The auto-push fires approximately 1–2 minutes after payroll issuance with no manual review step. Make sure all timecards are fully coded before issuing your first payroll. **How coding gaps affect the push depends on the field type:** - **Required fields (GL account and Vendor):** If either is missing, the push will fail entirely — you'll see a "Failed" status in Integration push history. - **Dimensions (Cost Code, Project, Project Task, Subaccount):** Behavior depends on how each dimension is configured in Acumatica. If a dimension is marked required in Acumatica, a missing value will cause the push to fail. If it's optional, the bill will sync but that dimension will be left uncoded on the line. See **Troubleshoot a failed push**, below, if a payroll doesn't sync after issuance. ## Field Mapping: Wrapbook Payroll → Acumatica Bill This table shows how Wrapbook payroll data maps to fields on the Acumatica AP Bill (Bills and Adjustments form). | Wrapbook Source | Acumatica Bill Field | Notes | | --- | --- | --- | | **Payroll ID** | Bill No. | Wrapbook payroll ID appears in the Bill no. field for reference | | **Payroll Issue Date** | Document Date | The date the payroll was issued in Wrapbook | | **Vendor** | Vendor | Must exist in Acumatica (AP303000); Wrapbook does not auto-create vendors. Set a default in Company Settings or override per project. | | **Default GL Account** | Account (header) | The default account from company settings. Individual line items may override this based on dimension mapping. | | **Branch** | Branch | Defaults to the API user's default branch if not specified | | **Currency** | Currency (header) | Inherited from the company; Wrapbook does not currently support multi-currency payroll | **Dimensions:** When enabled in **Company Settings → Integrations Settings → Edit Dimensions**, the corresponding Acumatica master records (Cost Codes, Projects, Project Tasks, Subaccounts, Branches, Bank Accounts) are synced to Wrapbook and mapped to Bill line fields automatically. ## Line-Item Mapping: Payroll Line Types → Acumatica Bill Lines Each Wrapbook payroll creates multiple lines on the Acumatica Bill. Below shows how different payroll components appear as separate Bill line items. | Payroll Component | Bill Line | GL Account Source | Amount | Description (Bill Transaction Field) | | --- | --- | --- | --- | --- | | **Base wages** | Wages | From company default or project chart | Gross wages (before taxes/fringes) | Employee name, job title, hourly rate (if applicable), # of days worked | | **Overtime wages** | Overtime | From project chart (if configured separately) | Gross OT wages | Same description pattern as base wages | | **Regular reimbursements** | Reimbursements | From project chart (reimbursement account) | Total reimbursement amount | Employee name, job title (e.g., "Darrick Stracke, Property Master Loan Out...") | | **Employer taxes** | Employer Taxes | From project chart (tax account) | Calculated tax amount | Aggregate FICA, FUTA, SUTA by payroll | | **Benefits/Fringes** | Fringes | From project chart (fringe account) | Fringe cost total | Aggregate cost (health, 401k, workers comp, etc.) | | **Platform fees** | Platform Fee | From company default or override | Wrapbook platform fee | "Wrapbook Platform Fees - [Project]" | ## After go-live: Dimensions data sync ### Initial sync on connection When you enter credentials in Step 2, Wrapbook immediately fetches your Chart of Accounts, Vendors, Cost Codes, Projects, Project Tasks, Subaccounts, Bank Accounts, and Branches. This data appears in your mapping UI within 2–5 minutes. ### Ongoing data refresh Wrapbook syncs dimensions data from Acumatica every **24 hours** from the time of initial connection. | Object | Direction | Frequency | Notes | | --- | --- | --- | --- | | Chart of Accounts | Acumatica → Wrapbook | 24 hours | — | | Projects | Acumatica → Wrapbook | 24 hours | — | | Cost Codes | Acumatica → Wrapbook | 24 hours | — | | Project Tasks | Acumatica → Wrapbook | 24 hours | — | | Subaccounts | Acumatica → Wrapbook | 24 hours | — | | Bank Accounts | Acumatica → Wrapbook | 24 hours | — | | Branches | Acumatica → Wrapbook | 24 hours | — | | AP Bills (payroll) | Wrapbook → Acumatica | Real-time | Pushed 1–2 minutes after payroll issuance | ### Manual refresh If you need data to update immediately (for example, you just added a GL account in Acumatica): 1. Go to **Company settings → Integrations settings → Edit** 2. Click **Refresh Connection** 3. Updated lists appear within 2–5 minutes. ⚠️ **Adding new GL accounts or dimensions before mapping a new project?** Use the manual refresh button. ## Viewing sync status and syncing payrolls ### Check sync status After a payroll is issued, you can confirm whether the push to Acumatica succeeded: 1. Go to **Company Settings → Integration push history** 2. Find the payroll row and look at the **Sync Status** column | Status | Meaning | | --- | --- | | Sync complete | Bill pushed successfully to Acumatica | | Failed | Push attempt failed — click the row to view the error message | | Pending | Push is in progress or hasn't been attempted yet — wait a few seconds and refresh | | (empty) | The integration was not connected when the payroll was issued — no push was attempted | ### Manually re-sync a payroll If a payroll missed the auto-push (for example, the integration was not yet set up at the time of issuance): 1. Go to **Company Settings → Integration push history** 2. Find the payroll you want to re-sync and click **Retry Sync** 3. Wrapbook re-attempts the push immediately 4. Check **Sync Status** after ~15 seconds to confirm it succeeded ## Deleting the integration ⚠️ **This action is permanent.** Only disconnect if you're certain you won't reconnect. 1. Go to **Company settings → Accounting → Integrations → Manage** 2. Click **Delete** next to Acumatica and confirm **What happens when you delete:** - The connection is removed - All configuration is deleted: company defaults, project overrides, field mappings, dimension settings - Dimensions data is cached in Wrapbook but no longer synced from Acumatica - Payroll issuance in Wrapbook continues to work, but no Bills will sync to Acumatica ## Troubleshooting ### Troubleshoot a failed push **Understand a failed payroll push** When Wrapbook cannot send a payroll transaction to Acumatica, the payroll push shows **Failed**. You can review a plain-language explanation before correcting the issue and retrying the sync. **Review the failure** 1. Open the failed payroll push 2. Click **Why did this fail?** 3. Review the explanation in the drawer 4. Review each cause listed in the drawer The explanation summarizes the accounting-system error in plain language. It may identify a missing or incorrect mapping for the chart of accounts, project, department, account, class, customer, location, project task, or cost code. The drawer may show more than one cause. Review every listed cause because you may need to correct settings in more than one place. **Correct the issue** If the drawer includes an action link, click the link to open the relevant settings area. Depending on the cause, the link may open the *Dimensions* grid in *Integration Settings* or *Cost Tracking* in *Project Settings*. If no action link appears, use the cause description to identify the setting that needs attention. Some corrections require a Company Admin, an Acumatica administrator, or a change in Acumatica. **Retry the payroll sync** 1. Correct each issue listed in the drawer 2. Return to the failed payroll push 3. Click **Retry Sync** 4. Review the new sync status After you click **Retry Sync**, the push changes to **Pending** and then to **Success** or **Failed**. If you retry before correcting the underlying issue, the push may fail again for the same reason. **Permissions** You must have access to the [company-level accounting features](/v1/docs/roles-permissions) to review the explanation and correct settings in Wrapbook. Some corrections may also require an *Acumatica administrator*. ### Common connection errors Have Wrapbook run its connection test first. If authentication fails, work through these in order before validating with a real bill. | Symptom | Cause | Fix | | --- | --- | --- | | `invalid_client` on token request | Client ID or Client Secret is wrong, or the Connected Application is inactive | Re-check Step 5. Verify the Client ID includes the full @TenantName suffix. If unsure, generate a new Shared Secret and copy both values again from the Secrets tab. Confirm the Connected Application is marked Active. | | `invalid_grant` on token request | Username or password is wrong; account is inactive; or "Force User to Change Password on Next Login" is checked | Return to Step 3. Verify username and password exactly. Confirm the account is marked Active. **UNCHECK "Force User to Change Password on Next Login"** if it's checked. If you rotated the password, update Wrapbook with the new value. | | **HTTP 403 naming a specific screen** (e.g., `Access denied to form AP301000`) | The role lacks access rights to that form | Return to Step 2 (Access Rights by Role). Use the search bar to find the form. Set the access level to Insert (for Bills and Adjustments) or View Only (for all others). Save before moving to the next workspace. | | **HTTP 401 after working previously** | Password expired or account locked out | Rotate the password in Users (SM201010). Update Wrapbook with the new value. If the account is locked, ask an admin to unlock it. Review the account's password policy if rotations are happening too frequently. | | **Fields rejected as unknown on POST** (e.g., "Unknown field") | Endpoint version mismatch | Confirm the version from Step 6 matches what Wrapbook is calling. Ask Wrapbook which endpoint version they're using and verify it against SM207060. | | **Intermittent failures under load only** | API connection limit reached | Acumatica limits concurrent API connections separately from named user seats. Review the License Monitoring Console (SM207015) to check API usage. You may need to upgrade the license or reduce connection pool usage. | | **Bills post to the correct company but wrong branch** | Branch ID was left blank, falling back to the account's default | Either set Branch ID explicitly in Step 7 (from Branches / CS102000), or verify the account's default branch is correct in Users (SM201010). | | **Data appears in wrong company** | Connected Application was created while signed into the wrong tenant | Check the @TenantName suffix on the Client ID. If it names the wrong tenant, recreate the Connected Application while signed into the correct tenant. Copy the new Client ID and update Wrapbook. | | **Access rights look unchanged after setting them** | The workspace node was changed without clicking Save first | Redo the entire workspace and click Save before selecting another workspace node. Changes are discarded without warning if you navigate away. | | **Bill fails to push after successful connection** | Missing additional form permissions beyond the base eight (e.g., Tax zones, Payment methods, Attachments) | Identify the missing form name. Return to Step 2 (SM201025), add the form to the role's access rights at View Only (or Insert if creating records), and Save. Use Wrapbook's Retry Sync button on the failed payroll to re-push immediately. | ## Need help? Contact the [Wrapbook Support Team](/v1/docs/how-to-get-help-using-wrapbook) or reach out to your Customer Success Manager if you run into setup issues or have questions about how your specific Acumatica configuration works with the integration. Original and detailed book of record for all accounting transactions arranged by departmental account codes that occurs throughout the lifetime of a production. (Accounts Payable) Cash disbursements through the payment of vendor invoices and other payables (General Ledger) Original and detailed book of record for all accounting transactions arranged by departmental account codes that occurs throughout the lifetime of a production. The master list of all the accounts used to track production costs, expenses, assets, liabilities, and income. These also can be referred to as Cost Accounts. In commercials, typically AICP line numbers are utilized in its stead. (Open Authorization) OAuth is a secure way for apps and websites to access your information from another service without asking for your password. It lets you sign in or share limited data safely by granting permission through a trusted provider, like Google or Apple. For example, when you click *Sign in with Google* you're using OAuth. Google confirms who you are, and the app gets access without ever seeing your password. Association of Independent Commercial Producers: Association of producers that handles collective bargaining The additional employer's cost of hiring labor over and above salary; includes statutory charges such as payroll taxes as well as benefits negotiated under a collective bargaining agreement. Legal document used to record employee's hours worked each week. A loan-out corporation is a company set up as a separate legal entity, usually for an actor, recording artist, or other individual, for the purposes of using the loan-out company's corporate legal protection. Paid via EIN (Employer Identification Number), with no tax deduction Acronym for Federal Insurance Contributions Act; the employer's and employee's matching contributions to the Social Security Act.