Custom Fields
The CustomField Object
Custom Fields are platform-defined fields that can be added to existing entities and contain information unique to a business.
There are three key parts of Rutter's Custom Fields feature:
GET /{entity_type}/custom_fields
outputs a structured schema defining all of the custom fields associated with that entity and the metadata for each custom field. Theentity_type
can be any of the core endpoints for accounting automation workflows, includingbills
,invoices
, andexpenses
.To fetch the values of the custom fields for a given entity, use the
expand=platform_data
query parameter on a GET request. This will output the platform response for a connection and if available, it will also include the custom fields for that entity.To make POST requests with custom fields, simply include the custom field names (key) and values in the POST body request in the
custom_fields
field, alongside any other fields from Rutter's universal data model. Rutter will correctly map all of the relevant to fields to the appropriate objects for write operations. See below for an example, where we will read from the response in the GET call and pass in values in the POST call.
Properties
description
stringThe description of this field.
key
stringThe platform key of this field.
name
stringThe name of this field.
required
booleanWhether this field is required for this entity type.
type
enumThe type of this field.
options
arrayoptions
attributesdefault
nullableThe default value for the field if any.
Custom Field Schema
Request Parameters
entityType
enumpathRequiredThe supported entity types for which we can fetch the custom field schema.
access_token
stringqueryRequiredThe access token of the connection.
platform_fields
enumqueryOptionalInclude fields that are platform defined (or unlocked through a platform defined process) vs. only those that are user defined. Supported for NetSuite.
force_fetch
enumqueryOptionalUsed to force a response even if the underlying connection has not finished its initial sync.
Response Body
- QuickBooks
- QuickBooks Desktop
- NetSuite
- Zoho Books
1{
2 "custom_fields": {
3 "entity": [
4 {
5 "description": "This is a mandatory field. Netsuite Type: text",
6 "key": "custbodymandatoryfield",
7 "name": "Rutter Mandatory Field",
8 "required": false,
9 "type": "string",
10 "options": [],
11 "default": "Default Value"
12 },
13 {
14 "description": "This is an select field. Netsuite Type: select",
15 "key": "custbodyemployees",
16 "name": "Rutter Enum List Record",
17 "required": false,
18 "type": "select",
19 "options": [
20 {
21 "text": "Bill",
22 "value": "4"
23 },
24 {
25 "text": "Rutter Engineering",
26 "value": "3"
27 },
28 {
29 "text": "Rutter User",
30 "value": "6"
31 }
32 ],
33 "default": null
34 }
35 ],
36 "entity.line_items": [
37 {
38 "description": "Please check if this is an out going order. Netsuite Type: checkbox",
39 "key": "custcoloutgoingboolean",
40 "name": "Outgoing order field",
41 "required": true,
42 "type": "boolean",
43 "options": [],
44 "default": false
45 },
46 {
47 "description": "Please describe the invoice more. Netsuite Type: text",
48 "key": "custcoldescription",
49 "name": "Custom Description",
50 "required": false,
51 "type": "string",
52 "options": [],
53 "default": null
54 }
55 ]
56 }
57}
Custom Fields
Supported Custom Fields by Platform
➖ Not supported by Rutter at this time. ❌ Not supported by platform.
Entity Type | NetSuite | ZohoBooks | QuickBooks Desktop | QuickBooks Online | Xero |
---|---|---|---|---|---|
ACCOUNTS | ➖ | ➖ | ➖ | ➖ | ➖ |
CLASSES | ➖ | ➖ | ➖ | ➖ | ➖ |
CURRENCIES | ➖ | ➖ | ➖ | ➖ | ➖ |
DEPARTMENTS | ➖ | ➖ | ➖ | ➖ | ➖ |
SUBSIDIARIES | ➖ | ➖ | ➖ | ➖ | ➖ |
ITEMS | ➖ | ➖ | ✅ | ➖ | ➖ |
BILLS | ✅ | ✅ | ➖ | ➖ | ✅ |
BILL_CREDIT_MEMOS | ✅ | ➖ | ➖ | ❌ | ✅ |
BILL_PAYMENTS | ✅ | ➖ | ➖ | ➖ | ➖ |
CUSTOMERS | ✅ | ➖ | ➖ | ➖ | ➖ |
EXPENSES | ✅ | ✅ | ➖ | ❌ | ✅ |
INVOICES | ✅ | ➖ | ✅ | ✅ | ✅ |
INVOICE_PAYMENTS | ✅ | ➖ | ➖ | ➖ | ➖ |
INVOICE_CREDIT_MEMOS | ✅ | ➖ | ➖ | ✅ | ✅ |
JOURNAL_ENTRIES | ✅ | ✅ | ➖ | ➖ | ✅ |
LOCATIONS | ✅ | ➖ | ➖ | ➖ | ➖ |
PURCHASE_ORDERS | ➖ | ➖ | ➖ | ✅ | ➖ |
SALES_ORDERS | ➖ | ➖ | ➖ | ➖ | ✅ |
VENDORS | ✅ | ➖ | ➖ | ➖ | ➖ |
Request Parameters
entityType
enumpathRequiredThe supported entity types for which we can fetch the custom field schema.
access_token
stringqueryRequiredThe access token of the connection.
Request Body
other_entity_fields
stringOther fields for this entity.
custom_fields
objectOptionalCustom fields on the entity. Note: for field type 'select', please use the values from options presented through 'GET /accounting/:entityType/custom_fields' endpoint. For field type 'boolean', please pass in a boolean value.
custom_fields
attributesline_items
arrayline_items
attributesResponse Body
- QuickBooks Desktop
- NetSuite
- Zoho Books
1{
2 "other_entity_fields": "Other entity values",
3 "custom_fields": {
4 "custom_field_key": "Custom field value"
5 },
6 "line_items": [
7 {
8 "other_line_item_fields": "Other line item values",
9 "custom_fields": {
10 "line_item_custom_field_key": "Line item custom field value"
11 }
12 }
13 ]
14}
1{
2 "other_entity_fields": "Other entity values",
3 "line_items": [
4 {
5 "other_line_item_fields": "Other line item values"
6 }
7 ],
8 "platform_data": {
9 "custom_field_key": "custom field value",
10 "other_platform_fields": "Platform fields",
11 "sublist_key": [
12 {
13 "line_item_custom_field_key": "Line item custom field value",
14 "other_sublist_fields": "Sublist fields"
15 }
16 ]
17 }
18}
Examples
Here's an example with the entity type invoices
. Note: you can replace invoices
with any of the other supported entity types specified in the "GET Custom Fields Schema" section (Request Parameters > entityType).
1. To get the custom field schema, use GET /accounting/invoices/custom_fields
Here's an example response for the custom field schema endpoint:
1{
2 "custom_fields": {
3 "invoice": [
4 {
5 "key": "custbody_customname",
6 "name": "Custom Order Name",
7 "type": "string",
8 "description": "This is a mandatory field. Netsuite Type: text",
9 "required": true,
10 "default": null,
11 "options": []
12 },
13 {
14 "key": "custbody_secondarycurrency",
15 "name": "Second Currency",
16 "type": "select",
17 "description": "This is a select field. Netsuite Type: select",
18 "required": false,
19 "default": null,
20 "options": [
21 {
22 "value": "2",
23 "text": "British pound"
24 },
25 {
26 "value": "3",
27 "text": "Canadian Dollar"
28 },
29 {
30 "value": "4",
31 "text": "Euro"
32 },
33 {
34 "value": "1",
35 "text": "USA"
36 }
37 ]
38 }
39 ],
40 "invoice.line_items": [
41 {
42 "key": "custcol_reminderformat",
43 "name": "Custom Line Item Reminder Format",
44 "type": "select",
45 "description": "Please select the correct reminder format for the customer. Netsuite Type: select",
46 "required": false,
47 "default": null,
48 "options": [
49 {
50 "value": "1",
51 "text": "Mail"
52 },
53 {
54 "value": "2",
55 "text": "Email"
56 },
57 {
58 "value": "3",
59 "text": "SMS"
60 },
61 {
62 "value": "4",
63 "text": "Phone"
64 }
65 ]
66 },
67 {
68 "key": "custcol_reviewed",
69 "name": "Custom Review",
70 "type": "boolean",
71 "description": "Please click if this order has been manually reviewed. Netsuite Type: checkbox",
72 "required": false,
73 "default": false,
74 "options": []
75 }
76 ]
77 }
78}
2. To see the custom field values for a certain entity record you could call GET /accounting/invoices?expand=platform_data
The expand=platform_data
query parameter would allow you to see the raw platform response from Netsuite. Here's an example response (note: the custom field key/values):
1{
2 "invoice": {
3 "id": "11423fb5-e84c-44ec-964f-ab0ffd60e647",
4 "platform_id": "21156",
5 "document_number": "50",
6 "customer_id": "77507585-aeb0-46a2-8667-e56ac1e9126e",
7 "subsidiary_id": "00b4187f-80d6-4e6e-bca0-4674b5b1bab0",
8 "issue_date": "2023-01-02T08:00:00.000Z",
9 "due_date": "2023-01-02T08:00:00.000Z",
10 "currency_code": "USD",
11 "account_id": "2267d1db-958f-404e-805a-2751a1199ec2",
12 "line_items": [
13 {
14 "id": null,
15 "platform_id": "11",
16 "description": "A Rutter Shirt",
17 "unit_amount": "2",
18 "quantity": 1,
19 "discount_amount": null,
20 "sub_total": "2",
21 "tax_amount": null,
22 "amount": "2",
23 "discount_percentage": null,
24 "tax_rate_id": null,
25 "item_id": "60d96f07-d474-4978-8422-6d5ec479e2c1",
26 "account_id": "15f844d2-0b04-4b8b-a253-261cf9bbd1fd"
27 },
28 {
29 "id": null,
30 "platform_id": "5",
31 "description": "A Second Rutter Shirt",
32 "unit_amount": "2",
33 "quantity": 2,
34 "discount_amount": null,
35 "sub_total": "4",
36 "tax_amount": null,
37 "amount": "4",
38 "discount_percentage": null,
39 "tax_rate_id": null,
40 "item_id": "c012dc49-3d06-4fc3-9ac3-7a883233d01a",
41 "account_id": "15f844d2-0b04-4b8b-a253-261cf9bbd1fd"
42 }
43 ],
44 "status": "open",
45 "total_discount": null,
46 "sub_total": "6",
47 "tax_amount": null,
48 "total_amount": "6",
49 "amount_due": "6",
50 "linked_payments": [],
51 "memo": null,
52 "created_at": "2023-06-01T13:56:00.000Z",
53 "updated_at": "2023-06-01T13:56:00.000Z",
54 "platform_data": {
55 "id": "21156",
56
57 // omitting other data
58
59 "custbody_customname": "Awesome Test Demo Product",
60 "custbody_secondarycurrency": "3",
61
62 "item": [
63 {
64 "id": "21156_1",
65
66 // omitting other data
67
68 "custcol_reminderformat": "2",
69 "custcol_reviewed": true,
70 },
71 {
72 "id": "21156_4",
73
74 // omitting other data
75
76 "custcol_reminderformat": "4",
77 "custcol_reviewed": false,
78 }
79 ],
80 }
81 }
82}
3. To post with custom fields, you would call POST /accounting/invoices
with the custom fields information
Here's an example:
1{
2 "invoice": {
3 "account_id": "6d58a5ba-a8c0-42c5-890d-efd2e659b4d4",
4 "customer_id": "77507585-aeb0-46a2-8667-e56ac1e9126e",
5 "due_date": "2023-01-02T02:34:56.000Z",
6 "issue_date": "2023-01-02T02:34:56.000Z",
7 "currency_code": "USD",
8 "memo": "Rutter Demo Invoice with Custom Fields",
9 "custom_fields": {
10 "custbody_customname": "Awesome Test Demo Product",
11 "custbody_secondarycurrency": "3"
12 },
13 "line_items": [
14 {
15 "total_amount": 2,
16 "description": "A Rutter Shirt",
17 "item": {
18 "id": "60d96f07-d474-4978-8422-6d5ec479e2c1",
19 "quantity": 1,
20 "unit_amount": 2
21 },
22 "custom_fields": {
23 "custcol_reminderformat": "2"
24 }
25 },
26 {
27 "total_amount": 4,
28 "description": "A Second Rutter Shirt",
29 "item": {
30 "id": "c012dc49-3d06-4fc3-9ac3-7a883233d01a",
31 "quantity": 2,
32 "unit_amount": 2
33 },
34 "custom_fields": {
35 "custcol_reminderformat": "4",
36 "custcol_reviewed": true
37 }
38 }
39 ]
40 }
41}
Have questions?
Contact support for personalized guidance.