Custom Fields

The CustomFieldsSchema Object

Custom Fields are platform-defined fields that can be added to existing entities and contain information unique to a business. This feature is currently only supported for Netsuite.

There are three key parts of Rutter's Custom Fields feature:

  1. 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. The entity_type can be any of the core endpoints for accounting automation workflows, including bills, invoices, and expenses.

  2. To fetch the values of the custom fields for a given entity, use the expands=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.

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

descriptionstringRequired

The description of this field.

keystringRequired

The platform key of this field.

namestringRequired

The name of this field.

requiredbooleanRequired

Whether this field is required for this entity type.

typeenumRequired

The type of this field.

One ofboolean, select, string, number, or multiselect.
optionsarrayRequired
Show options attributes
defaultnullableRequired

The default value for the field if any.

Endpoints
GET
/accounting/:entityType/custom_fields
POST
/accounting/:entityType

Custom Field Schema

GEThttps://production.rutterapi.com/versioned/accounting/:entityType/custom_fields

Request Parameters

    entityTypeenumpathRequired

    The supported entity types for which we can fetch the custom field schema.

    One ofbills, expenses, invoices, invoice_payments, or journal_entries.
    access_tokenstringqueryRequired

    The access token of the connection.

    force_fetchenumquery

    Force a response even if the underlying connection hasn't finished the initial sync.

    One oftrue or false.
    platform_fieldsenumquery

    Include fields that are platform defined (or unlocked through a platform defined process) vs. only those that are user defined.

    One oftrue or false.

Response Body

    custom_fieldsobjectRequired
    Show custom_fields attributes
Support by integration
  • Netsuite
    Netsuite
Example Response Body
JSON
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

POSThttps://production.rutterapi.com/versioned/accounting/:entityType

Currently, we support posting transactions with custom_fields on bills, expenses, invoices, invoice_payments, and journal_entries.

Request Parameters

    access_tokenstringqueryRequired

    The access token of the connection.

Request Body

    other_entity_fieldsstringRequired

    Other fields for this entity.

    custom_fieldsobject

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

    Show custom_fields attributes
    line_itemsarrayRequired
    Show line_items attributes

Response Body

    other_entity_fieldsstringRequired

    Other fields for this entity.

    line_itemsarrayRequired
    Show line_items attributes
    platform_dataobjectRequired

    Platform data for this entity. You can get this on any endpoint by using the platform_data=true query parameter.

Support by integration
  • Netsuite
    Netsuite
Example Request Body
JSON
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
}
Example Response Body
JSON
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?expands=platform_data

The expands=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.

Contact support
Previous
Currencies
Next
Customers