Transaction Body Fields (SuiteBuilder)
Comprehensive guide to creating and configuring custom transaction body fields that appear at the header level of sales orders, invoices, purchase orders, and other transactions.
Overview
Transaction body fields are header-level fields that apply to the entire transaction. They capture data that is consistent across all line items on a transaction.
TRANSACTION BODY FIELD PLACEMENT
═══════════════════════════════════════════════════════════════════════════════
SALES ORDER #SO-001
┌─────────────────────────────────────────────────────────────────────────────┐
│ HEADER (Body Fields) │
│ ───────────────────── │
│ Customer: ABC Corp Date: 2026-02-03 │
│ PO Number: PO-12345 Ship Via: UPS Ground │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ CUSTOM BODY FIELDS │ │
│ │ Project: PRJ-001 Delivery Priority: Rush │ │
│ │ Department: Sales Approval Status: Approved │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────────────────┤
│ ITEMS SUBLIST (Line Fields apply here) │
│ ───────────────────── │
│ Line │ Item │ Qty │ Rate │ Amount │ (custom line fields...) │
│ 1 │ Widget-A │ 10 │ $25.00 │ $250.00 │ │
│ 2 │ Widget-B │ 5 │ $50.00 │ $250.00 │ │
├─────────────────────────────────────────────────────────────────────────────┤
│ TOTALS │
│ Subtotal: $500.00 Tax: $40.00 Total: $540.00 │
└─────────────────────────────────────────────────────────────────────────────┘
Creating Transaction Body Fields
Navigation
Customization → Lists, Records, & Fields → Transaction Body Fields → New
Configuration Options
TRANSACTION BODY FIELD CONFIGURATION
═══════════════════════════════════════════════════════════════════════════════
┌─────────────────────────────────────────────────────────────────────────────┐
│ BASIC SETTINGS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Label*: [Delivery Priority ] │
│ ID*: [custbody_delivery_priority ] │
│ Type: [List/Record ▾] │
│ List/Record: [Priority Level List ▾] │
│ │
│ Description: [Indicates shipping urgency for │
│ warehouse prioritization ] │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ APPLIES TO (Transaction Types) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ SALES PURCHASE │
│ ☑ Sales Order ☑ Purchase Order │
│ ☑ Item Fulfillment ☑ Item Receipt │
│ ☐ Invoice ☐ Vendor Bill │
│ ☐ Cash Sale ☐ Vendor Credit │
│ ☐ Credit Memo │
│ │
│ INVENTORY FINANCIAL │
│ ☑ Transfer Order ☐ Journal Entry │
│ ☐ Inventory Adjustment ☐ Deposit │
│ ☐ Work Order ☐ Check │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ VALIDATION & DEFAULTING │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ☐ Mandatory Require value on save │
│ ☐ Unique Value No duplicates across transactions │
│ │
│ Default Value: [Standard ▾] │
│ │
│ Help Text: [Select shipping priority level ] │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Common Transaction Body Field Use Cases
Classification Fields
| Field Purpose | Type | Example |
|---|---|---|
| Project Tracking | List/Record | Project, Job, Contract |
| Department | List/Record | Department Override |
| Approval | List | Approval Status, Approval Level |
| Category | List | Order Type, Transaction Category |
| Priority | List | Delivery Priority, Processing Priority |
Compliance & Reference Fields
| Field Purpose | Type | Example |
|---|---|---|
| External Reference | Text | Customer PO, External ID |
| Compliance | List/Checkbox | Export License, Hazmat Declaration |
| Tax/Duty | List/Text | Incoterms, Tax Exemption Reason |
| Legal | Document | Contract Attachment, Authorization |
Process & Workflow Fields
| Field Purpose | Type | Example |
|---|---|---|
| Status | List | Processing Status, Review Status |
| Assignment | List/Record | Assigned To, Reviewer |
| Dates | Date | Expected Ship Date, Required Date |
| Notes | Text Area | Special Instructions, Internal Notes |
Integration Fields
| Field Purpose | Type | Example |
|---|---|---|
| External System | Text | ERP Order ID, WMS Reference |
| Sync Status | List | Integration Status |
| Timestamps | Date/Time | Sync Date, Export Date |
Field Flow Between Transactions
Transaction body fields automatically flow through the createdfrom relationship:
BODY FIELD FLOW (CREATEDFROM)
═══════════════════════════════════════════════════════════════════════════════
Sales Order #SO-001 Item Fulfillment #IF-001
┌─────────────────────────────────┐ ┌─────────────────────────────────┐
│ custbody_project: PRJ-100 │──▶│ custbody_project: PRJ-100 │
│ custbody_priority: Rush │ │ custbody_priority: Rush │
│ custbody_instructions: Handle │ │ custbody_instructions: Handle │
│ with care │ │ with care │
└─────────────────────────────────┘ └─────────────────────────────────┘
│
▼
Invoice #INV-001
┌─────────────────────────────────┐
│ custbody_project: PRJ-100 │
│ custbody_priority: Rush │
│ custbody_instructions: Handle │
│ with care │
└─────────────────────────────────┘
Field Flow Rules:
1. Field must "Apply To" BOTH source and target transaction types
2. Values copy automatically when creating from source
3. Values can be modified on child after copy
4. Scripts can override during creation
Sourcing from Entity and Item
Body fields can source default values from the entity or other sources:
BODY FIELD SOURCING
═══════════════════════════════════════════════════════════════════════════════
Customer Record Sales Order
┌─────────────────────────────────┐ ┌─────────────────────────────────┐
│ Customer: ABC Corp │ │ Customer: ABC Corp │
│ │ │ │
│ custentity_default_project: │──▶│ custbody_project: PRJ-100 │
│ PRJ-100 │ │ (Auto-populated) │
│ │ │ │
│ custentity_default_priority: │──▶│ custbody_priority: Standard │
│ Standard │ │ (Auto-populated) │
└─────────────────────────────────┘ └─────────────────────────────────┘
Configuration:
1. Create entity field on Customer
2. Create body field on Transaction
3. Set body field to "Source From: Customer"
4. Select source field (e.g., custentity_default_project)
5. When customer selected, value auto-populates
Subtab Placement
Transaction body fields can be placed on specific subtabs:
BODY FIELD SUBTAB PLACEMENT
═══════════════════════════════════════════════════════════════════════════════
Sales Order Form Layout:
┌─────────────────────────────────────────────────────────────────────────────┐
│ [Main] [Shipping] [Billing] [Custom Info] [Related Records] │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Main Tab: │
│ • Customer, Date, PO Number (standard) │
│ • custbody_order_type (custom) │
│ • custbody_priority (custom) │
│ │
│ Shipping Tab: │
│ • Ship To, Ship Via, Ship Date (standard) │
│ • custbody_delivery_instructions (custom) │
│ • custbody_carrier_account (custom) │
│ │
│ Custom Info Tab: │
│ • custbody_project │
│ • custbody_campaign_source │
│ • custbody_approval_status │
│ • custbody_internal_notes │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Configuration:
Use Form Customization to place fields on specific subtabs
Display Type Options
| Display Type | UI Behavior | Use Case |
|---|---|---|
| Normal | Editable input field | Standard data entry |
| Disabled | Visible, not editable | Calculated or system-set values |
| Hidden | Not visible on form | Script-only or integration fields |
| Inline Text | Display text only | Read-only reference display |
| Hyperlink | Clickable link | URL references |
Role-Based Field Access
BODY FIELD ACCESS BY ROLE
═══════════════════════════════════════════════════════════════════════════════
Field: Discount Override (custbody_discount_override)
Role Access Configuration:
┌─────────────────────────────────────────────────────────────────────────────┐
│ Role Form Access Field Visibility │
├─────────────────────────────────────────────────────────────────────────────┤
│ Administrator Full Edit │
│ Sales Manager Full Edit │
│ Sales Representative Standard Form View (Disabled) │
│ Warehouse Limited Form Hidden │
│ Accounts Receivable AR Form View (Disabled) │
└─────────────────────────────────────────────────────────────────────────────┘
Implementation Options:
1. Create different forms per role with field show/hide
2. Use field-level access controls
3. Set display type to Disabled for view-only
Reporting and Search Usage
Saved Search Criteria
-- Transaction search with body fields
SELECT
t.tranid AS document_number,
t.type,
t.trandate,
c.companyname AS customer,
t.total,
BUILTIN.DF(t.custbody_project) AS project,
BUILTIN.DF(t.custbody_priority) AS priority,
t.custbody_instructions AS instructions
FROM
transaction t
JOIN customer c ON t.entity = c.id
WHERE
t.type = 'SalesOrd'
AND t.custbody_priority = 3 -- Rush priority ID
AND t.trandate >= TO_DATE('2026-01-01', 'YYYY-MM-DD')
SuiteScript Access
// Reading body fields
var salesOrder = record.load({
type: 'salesorder',
id: orderId
});
var project = salesOrder.getValue('custbody_project');
var priority = salesOrder.getValue('custbody_priority');
var instructions = salesOrder.getValue('custbody_instructions');
// Setting body fields
salesOrder.setValue('custbody_priority', 1);
salesOrder.setValue('custbody_instructions', 'Handle with care');
salesOrder.save();
Best Practices
Naming Conventions
| Element | Convention | Example |
|---|---|---|
| Field ID | custbody_[prefix]_[name] | custbody_wh_priority |
| Prefix | Department/module (2-4 chars) | wh, fin, ops |
| Name | Descriptive, snake_case | delivery_priority |
Design Checklist
| Consideration | Recommendation |
|---|---|
| Applies To | Select only transaction types that need the field |
| Flow | Ensure field applies to all linked transaction types |
| Sourcing | Auto-populate from entity when possible |
| Placement | Group related fields on same subtab |
| Display | Use Disabled for calculated/sourced values |
| Mandatory | Only require if truly essential |
| Default | Set defaults to reduce data entry |
Performance Tips
| Consideration | Impact |
|---|---|
| Fewer applies-to | Faster form loading |
| Avoid Too Many | >30 custom body fields slows forms |
| Source Simple | Complex sourcing adds load time |
| Script Wisely | Heavy scripts on fieldChanged slow UI |