1. Customization & 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
If you have suggestions for improving this article, let us know!