Mixins

Mixins let you extend business resources with custom properties by defining JSON schemas, hosting them, and referencing them in resource metadata for flexible, schema-driven data enrichment.

Mixins are custom properties that you can use to describe your business resources in more details. Mixins can be applied to most objects in the Emporix API. Learn more about mixin schemas in Schema Service.

APIs that support mixins

The following APIs and services support mixins in their data models:

Core entities (with Schema Service support)

These entities support mixin schema creation through the Schema Service API:

• Cart - Cart Service

• Category - Category Tree Service

• Company - Client Management Service

• Coupon - Coupon Service

• Custom Entities and Custom Instances

• Customer - Customer Service / Customer Management Service

• Customer Address - Customer Service

• Order - Order Service

• Price List - Price Service

• Product - Product Service

• Quote - Quote Service

• Return - Returns Service

• Site - Site Settings Service

• Vendor - Vendor Service

Additional mixin support

These services accept mixins in their API requests and responses, but require manually created JSON schemas (not supported through Schema Service schema creation):

• Availability - Availability Service

• Customer and Item Assignments - Customer Segments Service

• Customer Segments - Customer Segments Service

• Groups - IAM Service (supports mixins field directly, without metadata.mixins)

• Locations - Vendor Service

• Locations and Contact Assignment - Client Management Service

• Prices - Price Service

• Returns - Returns Service

• Shopping List - Shopping List Service

Note: For services that don't support schema creation through the Schema Service API, you need to manually create and host your JSON schema, then reference it in the metadata.mixins field when using mixins with those APIs. See the Schema Service tutorial for details on creating references with manually defined JSON schemas.

Schemas

To apply a mixin to a resource, you need to define the mixin schema in the form of a JSON Schema object. Mixin schemas need to be uploaded to a hosting service and then referenced in a resource's mixin metadata.

Here's an example of a JSON schema that defines custom delivery options for customers:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Mixin schema for delivery options.",
  "properties": {
    "packaging": {
      "type": ["string", "null"],
      "description": "Delivery packaging."
    },
    "hint": {
      "type": ["string", "null"],
      "description": "Additional information from the customer."
    },
    "substituteProduct": {
      "type": ["boolean"],
      "default": false,
      "description": "Flag indicating whether products that are out of stock can be substituted."
    }
  }
}

Usage example

Here's an example of custom delivery options applied inside a Customer object with the schema referenced in mixin metadata:

{
  "mixins": {
    "deliveryOptions": {
      "packaging": "Paper",
      "hint": "If we are not home, the package can be left in front of the door.",
      "substituteProduct": true
    }
  },
  "metadata": {
    "mixinMetadata": {
      "mixins": {
        "deliveryOptions": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/deliveryOptionsMixIn.v6.json"
      }
    }
  }
}

How to add mixins to an object

The procedure below presents applying mixins to a Customer object.

1. Define your mixin schema.

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Mixin schema for delivery options.",
  "properties": {
    "packaging": {
      "type": ["string", "null"],
      "description": "Delivery packaging."
    },
    "hint": {
      "type": ["string", "null"],
      "description": "Additional information from the customer."
    },
    "substituteProduct": {
      "type": ["boolean"],
      "default": false,
      "description": "Flag indicating whether products that are out of stock can be substituted."
    }
  }
}

1. Upload your schema to a hosting service and save its URL.

2. Update an object with mixins and the mixin schema.

curl -i -X PATCH \
  'https://api.emporix.io/customer/{tenant}/customers/{customerNumber}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "contactEmail": "[email protected]",
    "active": true,
    "mixins": {
      "deliveryOptions": {
        "packaging": "Paper",
        "hint": "If we are not home, the package can be left in front of the door.",
        "substituteProduct": true
      }
    },
    "metadata": {
      "mixins": {
        "deliveryOptions": "{{schemaURL}}"
      }
    }
  }