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.

Permission required

To set up the NetSuite integration, your account must have the following role enabled:

• Role: Company Admin

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.

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:

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 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 — 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

The project chart template includes fringe-bucket rows (Total Fringes, Employer Taxes, Platform) that do not auto-populate from your COA. Add these to your project chart and map each to the corresponding GL account:

• Employer Taxes → typically mapped to employer payroll tax payable account

• Platform → typically mapped to platform/processing fee expense account

• Fringes → typically mapped to benefits or fringe benefit expense account

⚠️ If fringe lines are left unmapped, the resulting Bills will include lines without a GL destination and Acumatica may reject the push.

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).

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.

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.

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

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

1. Find the failure. Go to Company Settings → Integration push history. Locate the payroll row and check the Sync Status column — a status of "Failed" means the push didn't go through.

2. Read the error message. Click the row to view the specific error and timestamp. This tells you which validation failed (for example, missing dimension, invalid GL account, unmapped chart line).

3. Check the likely causes, in order:

   • Is a Chart Template assigned to the project? Go to Project Settings → Cost tracking and confirm a chart is selected under Enable accounting chart. No chart assigned means any coding is accepted, which can cause downstream mapping gaps.

   • Does the fringe mapping exist? Go to Project Settings → Project Charts and confirm fringe-bucket rows (Total Fringes, Employer Taxes, Platform) are mapped to GL accounts, not left blank.

   • Are dimension overrides missing? Check Company Settings → Integrations Settings → Edit → Override project dimensions to confirm required dimensions (Project, Location, Department, Item, Task) are set for this project.

4. Fix and re-sync. Once the gap is corrected, use the Retry Sync button on the payroll row and confirm Sync Status updates to "Synced" within ~15 seconds.

Common connection errors

Have Wrapbook run its connection test first. If authentication fails, work through these in order before validating with a real bill.

Need help?

Contact the Wrapbook Support Team 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.