Using as a Consumer

Channels provide a tailored view of item information designed for specific consumers.
While the overall data structure can remain consistent across different administrations, the expressions and configurations can vary per administration.

This flexibility ensures that the unique requirements of each administration are properly accommodated.

Example: Different Stock Messages per Administration

Imagine you have two administrations:

• Administration A wants to display more detailed stock messages:
  No stock, Few items left, and Plenty in stock.
• Administration B prefers a simpler approach:
  No stock or In stock.

Using channels, you can keep the same data structure for both administrations but configure the expressions so each administration gets its preferred stock messaging.

Keeping the channel in-sync

As the consumer application evolves, the channel structure will likely need to change as well.
We recommend managing the channel from within the consumer application to keep both aligned.

Channel Structure ≠ Channel Data

This refers to the channel structure — for example, which attributes are included — not the actual channel data exposed through those attributes.
Managing the data itself is typically handled by support or integration specialists.

There are two ways to manage the channel:

Manually

The channel is fully editable within the App, allowing you to manually update it to fit your specific needs.

This approach works especially well if you have only a few administrations using the consumer application — it's often the easiest way to start.

Programmatically through the API

You can also manage the channel and its attributes via the API. This approach allows you to:

• Keep the channel configuration in sync with your consumer application by integrating updates into your release process.
• Automatically create and configure channels when onboarding new customers.

This is ideal when you need consistent, automated, and scalable channel management.

Handling channel evaluation errors

Channel expressions are evaluated for each item or customer returned by the Public API. If an expression cannot be evaluated for a specific entity because the source data does not match the channel configuration, the response identifies the affected entity and property.

For single-entity endpoints, the API returns 422 Unprocessable Entity with a ProblemDetails response. The response extensions include:

Field	Description
propertyOutputName	The channel property output name that failed.
message	A human-readable explanation of the evaluation error.

For list and preview endpoints, one failing entity does not fail the complete response. Successfully evaluated entities still contain their data; failed entities are returned with empty data and an error object using the same fields as above. Consumers can skip the failed entity, report the error to a tenant administrator, and continue processing the rest of the response.

Looking up entities by a channel property

Consumers can look up a customer or item using a root-level scalar channel property instead of the platform's internal customer or item code. This is useful when an external system uses a different identifier.

The lookup property is evaluated with the same expression engine as the rest of the channel. For example, a customer channel can expose an external attribute as a scalar value:

{
  "OutputName": "ExternalId",
  "Expression": "firstOrDefault([Attributes.ExternalId])",
  "PropertyType": "Scalar"
}

The lookup request specifies the property output name and the value to match:

{
  "PropertyPath": "ExternalId",
  "Value": "ERP-CUSTOMER-123"
}

Lookups use exact, case-sensitive value comparison and only support scalar string, number, and boolean values. Object, array, nested-property, and null lookups are not supported.

The result is returned only when exactly one entity in the channel matches. A missing match returns 404 Not Found; multiple matches return 409 Conflict. If the property cannot be evaluated for a candidate, the lookup returns 422 Unprocessable Entity rather than treating the candidate as a missing match.

Item lookups can additionally include a customer code to preserve customer-group visibility rules. Lookup candidates are always restricted to the list configured for the channel.

Lookup expressions are evaluated in memory in configurable batches because channel expressions cannot be evaluated by the database. The lookup stops after the configured maximum candidate count (50,000 by default), but a request can still scan the complete channel list when no match is found. This endpoint is intended for occasional identifier resolution; high-volume lookup performance should be monitored separately.