1. Customization and development

Using extended properties

Overview

Extended Properties (XP) enable data model customization in OrderCloud. This feature provides:

  • JSON-based property extension
  • Custom field addition
  • Complex data structures
  • List endpoint filtering

Implementation details

Constraints

  • 8000 byte size limit
  • Valid JSON structure
  • Consistent typing per object
  • Null default value

Data types

  • Numbers
  • Strings
  • Booleans
  • Arrays
  • Nested objects

Implementation examples

Basic property addition

Example: Adding user demographics

http
POST api.ordercloud.io/buyers/{buyerID}/users HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
Content-Type: application/json; charset=UTF-8
json
{
  "Username": "janesmith",
  "Password": "test12345",
  "FirstName": "Jane",
  "LastName": "Smith",
  "Email": "[email protected]",
  "Phone": "555-555-5555",
  "TermsAccepted": null,
  "Active": true,
  "xp": {
    "Gender": "Female",
    "Age": 26
  }
}

Nested object implementation

Example: Adding employment details

http
PUT https://api.ordercloud.io/buyers/{buyerID}/users/{userID} HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
Content-Type: application/json; charset=UTF-8
json
{
  "Username": "janesmith",
  "Password": "test12345",
  "FirstName": "Jane",
  "LastName": "Smith",
  "Email": "[email protected]",
  "Phone": "555-555-5555",
  "TermsAccepted": null,
  "Active": true,
  "xp": {
    "Gender": "Female",
    "Age": 26,
    "EmploymentDetails": {
      "Position": "Developer",
      "Department": "Tech"
    }
  }
}

Property modification

Example: Updating specific fields

http
PATCH https://api.ordercloud.io/buyers/newbuyer/users/userID HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
Content-Type: application/json; charset=UTF-8
json
{
  "xp": {
    "EmploymentDetails": {
      "Position": "Senior Developer",
      "Department": "Tech"
    }
  }
}

Property removal

Options:

  1. Update method (PUT):

    • Get current resource
    • Remove target property
    • Update entire object

  2. Null assignment:

    • Set property value to null
    • Maintain property existence

Example: Removing age property

http
PUT https://api.ordercloud.io/buyers/{buyerID}/users/{userID} HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
Content-Type: application/json; charset=UTF-8
json
{
  "Username": "janesmith",
  "Password": "test12345",
  "FirstName": "Jane",
  "LastName": "Smith",
  "Email": "[email protected]",
  "Phone": "555-555-5555",
  "TermsAccepted": null,
  "Active": true,
  "xp": {
    "Gender": "Female",
    "EmploymentDetails": {
      "Position": "Developer",
      "Department": "Tech"
    }
  }
}

Search capabilities

Index configuration

Requirements:

Exceptions:

  • Product XP
  • Submitted Order XP
  • Premium search enabled resources

Filter implementation

Example: Department filter

http
GET https://api.ordercloud.io/buyers/newbuyer/users?xp.EmploymentDetails.Department=Tech HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
Content-Type: application/json; charset=UTF-8

Features:

  • Dot notation for nested fields
  • Standard operators (=, <, >)
  • Advanced querying support

Using extended properties in custom eCommerce apps

Extended properties and schema-less development

OrderCloud's extended properties (XP) strategy aligns with modern development approaches to schema-less data management. This approach, similar to PostgreSQL's JSONB functionality discussed by Rob Conery in his blog post, provides flexibility in custom solution development.

OrderCloud's data model

Our platform combines:

  • 16+ years of B2B commerce and order management expertise
  • Complete access through our REST API
  • Flexible data model customization through extended properties

While our core data model is comprehensive, we recognize the need for customization. Extended properties allow you to add custom data points to any API resource. For example, while we might not have Product.YourSpecialDataPoint, you can use Product.xp.YourSpecialDataPoint.

Development benefits

Extended properties offer advantages over traditional platforms:

  • Rapid development without database migrations
  • Flexible data model customization
  • Reduced development time and complexity
  • No platform limitations on custom fields

Collaboration and improvement

The OrderCloud Portal enables:

  • Direct collaboration with our architects and developers
  • Submission of enhancement suggestions
  • Community-driven platform improvements
  • Feedback based on XP usage patterns

Best practices

Extended properties (XP) provide a mechanism for adding custom data points to OrderCloud objects that aren't natively supported in the platform's data models. While XP offers great flexibility, understanding its proper usage and limitations is crucial for building efficient applications.

Definition

Extended properties are more than just arbitrary JSON objects attached to OrderCloud models. They represent a purposeful way to extend the platform's data model with specific properties your application needs. Here's a simple example:

javascript
user.xp.FavoriteColor = "purple"

XP provides several key capabilities:

  • Flexible data storage for custom properties
  • Automatic property indexing for efficient queries
  • Advanced search capabilities (for example, you can quickly find all users whose favorite color is purple)

This functionality is highly optimized for adding and managing individual data points, but it's important to understand that XP is not designed for storing large, complex data structures.

Guidelines

1. Use native properties first

Extended properties should be used as a last resort, not a default solution. Before using XP:

  • Review all existing properties of the model you want to extend
  • Understand their purpose and behavior
  • Consider using writable IDs for external system integration

For example, if you're integrating with a back-office system, use order.ID directly instead of creating order.xp.ExternalSystemID. Remember that XP properties lack the validation, behavior, and referential integrity that native properties provide.

2. Data size limits

OrderCloud imposes size limits on XP data to ensure optimal performance. When using XP:

  • Avoid storing large text content like blog posts or extensive descriptions
  • Use native fields like Product.Description for content requiring full-text or natural language search
  • Focus on small, discrete data points that complement the native data model
  • Consider external storage solutions for larger content needs

These limitations help maintain system performance and ensure XP remains efficient for its intended purpose.

3. Object structure

While XP supports arbitrarily deep objects, it's optimized for simple name/value pairs. When structuring your XP data:

  • Use straightforward, flat property structures when possible
  • Limit nested objects to cases where hierarchy adds clear value
  • Keep object structures consistent across similar items

Here's an example of acceptable nesting for geographic coordinates:

javascript
address.xp.Coordinates = {
  Latitude: value,
  Longitude: value
}

This structure makes sense because latitude and longitude are inherently related properties that form a single logical unit.

4. List management

Lists in XP require careful consideration because they can grow unpredictably. When using lists:

  • Choose lists only when you can reasonably predict their maximum size
  • Use simple value arrays rather than object arrays
  • Verify that the native data model doesn't already provide a suitable list structure

Here's an example of an appropriate list usage:

javascript
user.xp.PetNames = ["Max", "Bella"]

This works because:

  • The list has a natural size limit (number of pets is typically small)
  • It uses simple string values
  • The information is specific to the user

5. Avoid duplicate data

Storing repeated lookup data in XP can lead to maintenance issues and increased storage costs. Consider this problematic approach:

javascript
order.xp.Category = {
  ID: "xyz123",
  Name: "Category Name",
  Description: "Long description..."
}

This practice creates several problems:

  • Redundant storage of the same data across multiple orders
  • Difficulty in updating information (requires changes to all instances)
  • Increased data storage costs
  • Potential for inconsistency

A better approach is to store only the reference:

javascript
order.xp.CategoryID = "xyz123"

This solution:

  • Maintains data integrity
  • Reduces storage requirements
  • Makes updates simpler
  • Follows proper data normalization practices

6. Configuration data

Most applications require some form of global configuration data. Before storing this in XP, consider:

  • Does the data change frequently?
  • Do you need a UI for managing the configuration?
  • Is the data specific to individual resources?

For static or rarely changing configuration:

  • Store in front-end code (e.g., JSON configuration files)
  • Use environment variables
  • Implement external configuration services

Only use XP for configuration when:

  • The data changes frequently
  • You need a UI for configuration management
  • The configuration is specific to individual resources

7. Security considerations

XP data is visible to anyone with access to the parent object. Therefore:

Never store sensitive information in XP, including:

  • Passwords
  • Credit card numbers
  • Personal identification numbers
  • Authentication tokens
  • Encryption keys

Storing credit card information in XP is not only a security risk but also violates OrderCloud's terms and conditions. For sensitive data:

  • Use appropriate secure storage solutions
  • Implement proper encryption
  • Follow industry security standards
  • Consider tokenization for sensitive references

Implementation examples

The following examples demonstrate proper XP usage patterns, from basic properties to more complex structures. Each example follows the guidelines outlined above.

Basic property

javascript
// Add single property
user.xp.Department = "Sales"

// Add multiple properties
user.xp = {
  Department: "Sales",
  EmployeeID: "E123",
  StartDate: "2025-01-15"
}

Nested data

javascript
// Location data
address.xp.GeoLocation = {
  Latitude: 44.9778,
  Longitude: -93.2650,
  Accuracy: "high"
}

// Contact preferences
user.xp.Communication = {
  PreferredMethod: "email",
  OptIn: true,
  Frequency: "weekly"
}

List handling

javascript
// Simple list
product.xp.Tags = ["new", "featured", "sale"]

// Structured list (use sparingly)
user.xp.Certifications = [
  {
    Name: "Security+",
    ExpiryDate: "2026-12-31"
  }
]

External storage options

Remember that OrderCloud is not a complete solution by itself. Just as you build custom front-ends to create useful applications, you may need additional back-end services for complex data requirements. Modern cloud platforms offer excellent options for handling data needs that exceed XP's scope:

  • Firebase: Google's real-time database and backend services
  • DynamoDB: Amazon's fast and flexible NoSQL database
  • DocumentDB: Microsoft's globally distributed database service

These services excel at handling complex data structures, large datasets, and specialized querying needs that fall outside XP's intended use.

Support

OrderCloud's success depends on your application's success. We provide several support options to help you make the most of XP and other features:

  • Free support resources and documentation
  • Paid support packages for enterprise needs
  • Early development guidance to ensure proper architecture

We encourage you to reach out during the early stages of development when architectural decisions have the most impact. Our team can help you determine the best way to use XP within your application's context.

XP exemplifies our flexibility over features philosophy, providing powerful customization capabilities while maintaining clear boundaries and purpose. Understanding these boundaries helps you build scalable, maintainable applications that make the most of OrderCloud's capabilities.

If you have suggestions for improving this article, let us know!