API Reference
API Support
Start typing to search…

Custom Fields

Overview

Custom fields in Rackbeat allow you to extend the standard data structure by adding your own custom fields to various entities throughout the system. This powerful feature enables businesses to capture additional information specific to their operations while maintaining the flexibility to include these fields in PDFs and overview pages.

ℹ️

Premium subscription required

Custom fields are available exclusively on Premium subscription plans.


What Are Custom Fields?

Custom fields are user-defined data fields that can be added to enhance existing entities with additional information. These fields appear in company settings under the "Fields" section and can be configured to capture various types of data specific to your business needs.

Key Benefits:

  • Capture business-specific information not covered by standard fields
  • Include custom data in generated PDFs and reports
  • Display additional information on overview pages (products, orders, etc.)
  • Maintain data consistency across your organization

Field Types

Rackbeat supports four different types of custom fields:

1. Text Field

  • Purpose: Single-line text input
  • Use Cases: Short descriptions, reference numbers, codes
  • Validation: String length limits apply

2. Textarea Field

  • Purpose: Multi-line text input
  • Use Cases: Long descriptions, notes, specifications
  • Validation: Extended text content with line breaks

3. Checkbox Field

  • Purpose: Boolean true/false selection
  • Use Cases: Feature flags, yes/no questions, status indicators
  • Validation: Boolean values only

4. Dropdown Field

  • Purpose: Single selection from predefined options
  • Use Cases: Categories, statuses, predefined choices
  • Validation: Must match one of the configured options

Supported Entities

Custom fields can be added to the following entity types:

  • Products & BOMs - Enhance inventory items with additional specifications
  • Customers - Store customer-specific information and preferences
  • Suppliers - Track supplier details and requirements
  • Sales Documents - Add custom data to offers, orders and customer invoices
  • Purchasing Documents - Include additional information on purchase orders and supplier invoices

API for Field Management

List All Custom Fields

Retrieve all custom fields configured in your account:

GET /api/fields

Get Specific Field

Retrieve details for a specific custom field by its slug:

GET /api/fields/{slug}

Create New Field

Create a new custom field with specified type and configuration:

POST /api/fields

Update Field

Modify an existing custom field's configuration:

PUT /api/fields/{slug}
⚠️

Note that, if you want to update a dropdown field by adding a new option, then all the previous options should be included in the request buddy. Otherwise the previous options will be deleted and replaced with the new one.

Delete Field

Remove a custom field from your account:

DELETE /api/fields/{slug}

APIs to get Field Data

Entity-specific field access: There are three primary methods to retrieve custom field data.


Method 1: Dedicated Field Endpoints

Use these endpoints to retrieve only custom field data for specific entities:

Product / BoM (Lot) Custom Fields

Retrieve custom field values for a specific BoM (lot):

GET /api/lots/{lot_number}/fields

Retrieve custom field values for a specific product:

GET /api/products/{product_number}/fields

Supplier Custom Fields

Get custom field values associated with a specific supplier:

GET /api/suppliers/{supplier_number}/fields

Purchase Order Custom Fields

Get custom field values associated with a purchase order:

GET /api/purchase-orders/{purchaseOrder_number}/fields

Supplier Invoice Custom Fields

Get custom field values associated with a supplier invoice:

GET /api/supplier-invoices/{supplierInvoice_number}/fields

Customer Custom Fields

Get custom field values associated with a specific customer:

GET /api/customers/{customer_number}/fields

Offer Custom Fields

Get custom field values associated with an offer:

GET /api/orders/offers/{offer_number}/fields

Order Custom Fields

Get custom field values associated with an order:

GET /api/orders/{order_number}/fields

Customer Invoice Custom Fields

Get custom field values associated with a customer invoice.

GET api/customer-invoices/{customerInvoice_number}/fields

Method 2: Metadata Parameter (Recommended for Lists)

For better performance and convenience when retrieving multiple entities, use the metadata parameter with standard entity endpoints to retrieve both entity data and custom fields in a single request:

GET /api/products?fields=number,name,metadata
GET /api/customers?fields=number,name,metadata
GET /api/orders?fields=number,customer,metadata

Example Response:

{
  "products": [
    {
      "number": "ABC-123",
      "name": "Sample Product",
      "metadata": [
        {
          "id": 1,
          "label": "Product Category",
          "slug": "product-category",
          "value": "electronics"
        },
        {
          "id": 2,
          "label": "Warranty Period",
          "slug": "warranty-period",
          "value": "24 months"
        }
      ]
    }
  ]
}

The metadata approach returns all custom fields for each entity, including:

  • id: The custom field identifier
  • label: The display name of the field
  • slug: The programmatic identifier
  • value: The actual field value for this entity

Method 3: Expand Parameter (Best for Single Entities)

When retrieving a single entity, use the expand=field_values parameter to include custom field data:

GET /api/products/{number}?expand=field_values
GET /api/customers/{number}?expand=field_values
GET /api/orders/{number}?expand=field_values

Example Response (with dropdown and text field):

{
  "product": {
    "number": "97891866890023",
    "urlfriendly_number": "97891866890023",
    "type": "product",
    "name": "Sample Product",
    "recommended_cost_price": 0,
    "stock_quantity": 0,
    "in_order_quantity": 0,
    "available_quantity": 0,
    "purchased_quantity": 0,
    "used_in_production_quantity": 0,
     //
     // Abbreviated for readability
     //
    "created_at": "2022-07-05T14:21:01+02:00",
    "updated_at": "2022-07-05T14:22:50+02:00",
    "field_values": {
      "1": {
        "value": "electronics",
        "label": "Electronics"
      },
      "2": {
        "value": "24 months warranty",
        "label": "24 months warranty"
      },
      "3": {
        "value": "true",
        "label": "YES"
      }
    }
  }
}

Understanding the response:

  • Field 1 (dropdown - Product Category): value = "electronics" (stored option value), label = "Electronics" (display text)
  • Field 2 (text - Warranty Info): value = "24 months warranty" (user input), label = "24 months warranty" (same as value)
  • Field 3 (dropdown - Certified): value = "true" (stored option value), label = "YES" (display text for the option)

Key characteristics of theexpand approach:

  • Returns field data as an object keyed by field IDs
  • Only includes fields that have values (empty fields are omitted)
  • For dropdown fields, value contains the option value, label contains the display text
  • More compact response for single entity requests
⚠️

Be aware that the expand approach does not work if you also use additional filtering e.g. by specifying which fields should be returned. So a query like api/products/{number}?expand=field_values&fields=number,name will NOT work.


Method Comparison

  • Metadata: Always returns all fields (even empty ones), best for lists and comprehensive data
  • Expand: Only returns fields with values, best for single entity requests
  • Dedicated endpoints: Custom fields only, useful when entity data isn't needed
🤓

Which method to choose when?

  • Use dedicated field endpoints when you don't need entity data
  • Choose metadata when you need all fields (including empty ones) for consistency
  • Choose expand when you only care about fields that have values

Field Configuration

Required Parameters

When creating custom fields, you'll need to specify:

  • name - The display name for the field
  • type - One of: text, textarea, checkbox, dropdown
  • available_for - Entity type where this field applies

Available For Categories

The available_for parameter determines which entity can use the field:

  • item - Products and BoMs (lots)
  • customer - Customer records
  • supplier - Supplier records
  • sales - Sales documents (offers, orders, invoices)
  • purchasing - Purchase orders and related documents

Dropdown Configuration

For dropdown fields, additional configuration is required:

{
  "type": "dropdown",
  "options": [
    {"value": "option1", "label": "Option 1"},
    {"value": "option2", "label": "Option 2"}
  ]
}

Data Validation

Field-Level Validation

  • Text fields: Length restrictions and character validation
  • Textarea fields: Extended content with newline support
  • Checkbox fields: Boolean value validation
  • Dropdown fields: Value must match configured options

Best Practices

1. Plan Your Field Structure

  • Design fields based on actual business requirements
  • Consider how fields will be used in reports and PDFs
  • Avoid creating redundant fields that duplicate existing data

2. Use Appropriate Field Types

  • Choose text for short, single-line inputs
  • Use textarea for longer descriptions or notes
  • Select checkbox for binary choices
  • Implement dropdown for standardized options

3. Consider Field Naming

  • Use clear, descriptive field names
  • Maintain consistent naming conventions
  • Avoid special characters that might cause issues

4. Manage Field Dependencies

  • Understand which entities will use each field
  • Consider the impact of field changes on existing data
  • Plan for field migrations if business requirements change

5. Integration with Layouts

  • Custom fields can be included in PDF layouts

6. API Performance Optimization

  • For lists: Use the metadata parameter approach when retrieving multiple entities with custom fields
  • For single entities: Use the expand=field_values parameter for more compact responses
  • For custom fields only: Use dedicated field endpoints when you don't need entity data
  • Choose metadata when you need all fields (including empty ones) for consistency
  • Choose expand when you only care about fields that have values

Example Implementation

Creating a Custom Field

POST /api/fields
{
  "name": "Product Category",
  "type": "dropdown",
  "available_for": "item",
  "options": [
    {"value": "electronics", "label": "Electronics"},
    {"value": "clothing", "label": "Clothing"},
    {"value": "books", "label": "Books"}
  ]
}

Setting Field Values

When creating or updating entities with custom fields, include field values in your requests:

PUT /api/products/{product_number}
{
    "name": "Sample Product",
    "custom_fields": [
        {
            "id":3,
            "value": "The field value"
        }
    ]
}

Error Handling

Common Validation Errors

  • Invalid field type: Ensure the field type is one of the supported options
  • Missing required options: Dropdown fields must include option configurations
  • Invalid entity assignment: Verify the available_for value is correct
  • Value validation failures: Field values must match the expected format

Response Codes

  • 200 - Successful field operation
  • 422 - Validation error (check field configuration)
  • 403 - Permission denied (Premium subscription required)
  • 404 - Field or entity not found

Limitations

Premium Feature Restriction

  • Custom fields are only available on Premium subscription plans
  • Attempts to use custom fields on non-Premium accounts will result in access errors

Technical Limitations

  • Field name length is restricted to 40 characters
  • Text field character limit is 1000 characters