Choose between schema extensions and Managed API Extensions based on your requirements.
To add custom logic around your Project's data, use schema extensions or Managed API Extensions. Schema extensions shape what clients read through the Experience API. Managed API Extensions approve, modify, or block a write before it is persisted. Managed API Extensions use the commercetools API Extensions mechanism; the Commerce Integration Layer hosts and registers the handler. They differ in where they run and which consumers they affect, so choose the one that matches your requirement.
Schema extensions
Use a schema extension when you want to:
- Add a new query, type, or a field on an entity such as
Product. - Compute a value from data the Commerce Integration Layer already owns, or from fields your extensions expose (with
@requires). - Call an external service and return the result as part of the graph.
- Shape or enrich what a storefront reads.
- Add a mutation for a flow that doesn't intersect commercetools, for example, one that only calls an external service, or where you don't need transactional (pre-persist) semantics on the commercetools operation.
Because it runs at the edge, a schema extension only affects traffic that goes through the Commerce Integration Layer. It's the right tool for anything a client reads, but it is not a platform-wide guarantee. For more information, see Managed API Extensions.
Schema extensions aren't limited to reads. A mutation on your extension subgraph can run your own logic by calling an external service, orchestrating a multi-step flow, or wrapping a commercetools write. Because it runs at the edge rather than inside the commercetools write, it's a good fit when the flow doesn't touch commercetools at all, or when you don't need the all-or-nothing, pre-persist guarantees of a Managed API Extension on the commercetools operation. When you do need those guarantees (a rule enforced on every write, or transaction semantics tied to the commercetools write) use a Managed API Extension instead.
Managed API Extensions
Use a Managed API Extension when you want to:
- Enforce a rule on a cart, order, customer, or other write, and reject it if it doesn't hold.
- Stamp or correct a field as part of the write (for example, a computed custom field).
- Have that logic apply to every write to the resource, no matter which client made it.
Unlike a schema extension, a Managed API Extension applies to all consumers, including the storefront, the Merchant Center, a direct API client, or any other channel, because it runs inside the commercetools write itself. When a rule must hold platform-wide, this is the mechanism.
Decision guide
To help you decide which extension type to use, work through these in order and stop at the first that fits:
- Can you model it with built-in commercetools features? Before writing any custom logic, check whether an existing commercetools data model or product feature already covers the requirement. Built-in modeling has the lowest cost and best time-to-value.
- Is it data a client reads? Add, compute, or shape it with a schema extension.
- Must a rule hold for every write, across all clients? Use a Managed API Extension. This is the only mechanism that can validate or change a resource as part of the write, for all consumers.
- Do you only need to react after the fact? Use a Subscription.
Prefer Managed API Extensions for input preparation to ensure logic applies to all clients. Use schema extensions for input preparation only if a field is immutable once set, or to avoid commercetools validation rejection.