Integrate an external promotion or loyalty engine

A promotion integration hands the discount decision to an external engine. In the architecture used by this guide, the engine holds the campaign rules, coupon inventory, and loyalty balances. commercetools holds the Cart, the Order, and the resulting prices.

The exact operations depend on the selected engine. This guide defines the following contract:

• Evaluation runs synchronously while the shopper is shopping. It sends the Cart to the engine, receives the discount effects, and applies them to the Cart. The evaluation endpoint must not consume a coupon, close a session, or award points.
• Redemption runs asynchronously after the Order exists. It performs the final operations supported by the engine, such as consuming a coupon, closing a session, or awarding loyalty points.

Define the promotion requirements

Promotion behavior follows marketing intent, and a wrong default either gives money away or blocks checkout. Document these decisions before you select or configure a Connector:

• Engine: identify the engine, the account environment, the credentials, and the evaluation and redemption endpoints it exposes.
• The capability gap: name the specific requirement that the built-in discounts cannot meet. The next section tests this answer.
• Discount ownership: decide whether the engine owns the Cart Discounts and Discount Codes on the Cart, or whether commercetools keeps that ownership and the engine covers only a carved-out case. A Cart cannot split it, for the reason given in Decide who owns discounts on the Cart. Product Discounts are decided separately, by the Project's DiscountCombinationMode.
• Coupon codes: decide whether a shopper types a code, where that code is stored, and how a rejected code reaches the storefront.
• Loyalty points and balances: decide what, if anything, is mirrored into commercetools for display, and confirm that the engine remains the system of record.
• Order lifecycle: decide whether a cancellation or a return rolls the redemption back and reclaims points. This determines which Messages the redemption application subscribes to.
• Redemption point: decide whether redemption happens when the Order is created or when payment is confirmed. Both are defensible and they carry different rollback duties.
• Failure policy: decide whether an engine outage drops discounts and lets the Cart proceed, or fails the Cart operation.
• Region, Project, and Stores: record these, along with any multi-currency, multi-Store, or business-to-business requirements such as Quotes.

Record any requirement that does not fit one of these lines as its own item rather than forcing it into a category. Cross-channel budgets shared with a point-of-sale system, marketplace sellers, and recurring Orders each change the design.

Rule out the built-in discounts first

commercetools provides built-in promotion capabilities. Rule them out before you plan a Connector, because a Connector adds cost, latency, and an availability dependency to Cart operations.

Continue past this gate when the requirement needs capabilities that belong to a promotion platform: unique code generation at scale, referral programs, loyalty points, tiers, or wallets, budgets shared across web and point-of-sale channels, per-customer targeting driven by a customer data platform, geofencing, or real-time campaign experimentation.

One further case justifies an engine even when the discount arithmetic is simple. If a marketing team already works in an engine daily and must author rules there, the requirement is the authoring surface rather than the calculation, and the built-in discounts do not satisfy it.

Record which case applies and why. An integration that restates behavior the platform already provides is the most expensive way to obtain it.

Decide who owns discounts on the Cart

• The engine owns discounts. Matching Cart Discounts are ignored, and Discount Codes cannot be added to Carts that carry engine discounts. This is the usual choice when a marketing team authors campaigns in the engine.
• commercetools owns discounts. The engine covers only a carved-out case on Carts that the built-in discounts leave alone. Keep the boundary explicit, because a Cart that receives an engine discount no longer receives matching Cart Discounts or Discount Codes.

The cited sources do not document a dedicated error for a mixed design. Enforce the ownership decision in your own configuration and code.

Choose a Connector path

GET https://connect.{region}.commercetools.com/connectors/search?integrationTypes=promotion&private=false

The promotions and loyalty category of the marketplace is crowded, and it lists partner-operated software-as-a-service products alongside deployable Connectors. A marketplace listing alone does not prove that an integration deploys through Connect. Confirm that a candidate publishes a Connect application before you plan around it.

Choose the first path that satisfies the requirements:

1. Configure an existing deployable Connector when its evaluation, coupon handling, loyalty, redemption, rollback, and regional capabilities fit.
2. Prove whether configuration closes a gap before forking. Promotion Connectors commonly expose the effect-to-action mapping, the attributes forwarded to the engine, the Custom Field that holds the coupon code, the Tax Category used for discount Line Items, and the Order States that trigger redemption as configuration.
3. Fork an existing Connector when the gap is genuine and the source is available. Add only the missing behavior and deploy the result as an Organization Connector.
4. Build both applications when no Connector exists for the engine, which is the usual case for a promotion service that you operate.

Assess a public Connector before you adopt it

Two promotion integrations publish their source under an MIT license. Both need the same checks as any inherited codebase. The following external observations were verified on 2026-09-10 at the linked commits. Re-check them at the current commit, because they change independently of this guide.

Design the two applications

Separate evaluation from redemption

In the contract used by this guide, evaluating a Cart and redeeming a promotion are different engine operations with different consequences.

Evaluation answers the question of what this Cart would cost. The evaluation operation must not consume a coupon, close a session, or award points. It runs many times during a shopping session, including for Carts that are never ordered.

Redemption records that the promotion was used. Configure it to perform the final operations that the selected engine supports, such as consuming a coupon, closing a session, or awarding points.

This separation prevents abandoned Carts from consuming coupons or awarding points. It also ensures that engine reporting can distinguish a price evaluation from a completed redemption when the engine provides that distinction.

The two jobs therefore become two Connect applications:

• A service application registered as a Cart API Extension, which evaluates.
• An event application driven by a Subscription, which redeems.

The evaluator receives the Cart as it will be after the triggering change, and the actions it returns are applied within that same operation. The hash it compares in step 3 was written by the previous evaluation, and the discounts it returns in step 6 are not yet persisted when it builds the response.

A backend-for-frontend can evaluate instead of an API Extension, by applying the Cart change, calling the engine with the returned Cart, and writing the discounts in a second update. That removes the engine from the platform's synchronous path, at the cost of guaranteeing that every client reaches the Cart through that backend. Any client that bypasses it produces an undiscounted Cart. Use an API Extension when discounts must apply regardless of which client changes the Cart.

Apply engine discounts to the Cart

Three mechanisms can put an engine's discount on a Cart. Choose one deliberately, because the choice reaches the storefront.

Choose this mechanism only when a visible per-code line is a requirement, or when an existing storefront already handles it.

Size the catalog against those distinctions rather than a single ceiling, and confirm high code volumes with commercetools support. This mechanism suits a small, slow-changing campaign set.

When you use Direct Discounts, map the engine's effects onto the value and target vocabulary:

Five details in that mapping cause defects that are hard to attribute:

• A relative value is a permyriad, one ten-thousandth. A 10% discount is 1000. An engine value of 10 forwarded without conversion produces a 0.1% discount, which looks like a rounding fault rather than a mapping fault.
• The shipping target's discriminator is shipping, although its type is named CartDiscountShippingCostTarget. A draft that sends shippingCost is rejected.
• Multi-buy targets accept a percentage only. An engine effect expressed as a fixed amount for a quantity, such as three items for a set price, maps to pattern, which accepts an amount, a fixed price, or a percentage. A lineItems target is not a substitute, because it discounts the matching Line Items as a whole and cannot express the trigger and discounted quantities.
• A giftLineItem value must not carry a target, and it references a Product and Variant in the Project. An unpublished Product still produces a Gift Line Item, so that case needs no guard. Guard instead against a Product that does not exist, and against a supplyChannel without the InventorySupply role or a distributionChannel without the ProductDistribution role. Decide in advance whether an unmatched gift effect is dropped with a log entry or treated as a failure.
• Set DirectDiscounts replaces the whole array. Always send the complete current set. A response that sends only the changed entry removes the others. Sending an empty array removes all Direct Discounts and recalculates the affected prices.

{
  "actions": [
    {
      "action": "setDirectDiscounts",
      "discounts": [
        {
          "value": { "type": "relative", "permyriad": 1000 },
          "target": { "type": "lineItems", "predicate": "1=1" }
        },
        {
          "value": { "type": "relative", "permyriad": 10000 },
          "target": { "type": "shipping" }
        }
      ]
    },
    {
      "action": "setCustomField",
      "name": "promotionResult",
      "value": "{\"status\":\"accepted\",\"campaign\":\"SPRING10\"}"
    },
    {
      "action": "setCustomField",
      "name": "promotionHash",
      "value": "9f2c1ae6b0d4"
    }
  ]
}

Two price modes silently deactivate Cart Discounts for the item that carries them, and a Direct Discount is a Cart Discount applied to one Cart, so an engine effect targeting such an item produces no reduction and no error:

• A LineItem with the ExternalTotal LineItemPriceMode, despite a matching CartDiscountLineItemsTarget or MultiBuyLineItemsTarget.
• A CustomLineItem with the External CustomLineItemPriceMode, despite a matching CartDiscountCustomLineItemsTarget, MultiBuyCustomLineItemsTarget, or CartDiscountPatternTarget.

Target the Cart total for Carts that carry externally priced items, which is common in quoted and business-to-business flows.

Store the coupon code and its result

• The entered code, written by the storefront or backend.
• The evaluation result for that code, written by the evaluator, carrying acceptance or a rejection reason that the storefront can display.
• The promotion hash from the last evaluation, described in Skip unchanged evaluations.

Add a field for engine-supplied campaign messaging when the storefront renders prompts such as progress toward a threshold.

The deployment scripts own three resources: the Extension, the Subscription, and the Type. Give all three stable keys, and hold the scripts to this contract:

• postDeploy fetches by key and updates, rather than creating unconditionally. With a stable key an unconditional create does not duplicate the resource, it fails the redeployment because the key is taken. Duplicates appear only when a script generates a fresh key each run, which leaves a second Extension evaluating every Cart or a second Subscription redelivering every Order.
• postDeploy reads the Type before writing it, so that a redeployment does not remove fields that already exist.
• preUndeploy deletes the Extension and the Subscription. An undeployed Connector that leaves them registered points the platform at an endpoint that no longer answers, which fails every Cart write.
• preUndeploy leaves the Type in place. Custom Field data on existing Carts depends on it.

Configure the Connector and scopes

deployAs:
  - name: promotion-evaluator
    applicationType: service
    endpoint: /promotions
    scripts:
      postDeploy: npm run connector:post-deploy
      preUndeploy: npm run connector:pre-undeploy
    configuration:
      standardConfiguration:
        - key: ENGINE_BASE_URL
          description: Base URL of the promotion engine
          required: true
        - key: ENGINE_TIMEOUT_MS
          description: Outbound engine deadline, below the Extension timeout
          required: true
        - key: COUPON_CODE_FIELD
          description: Cart Custom Field holding the entered coupon code
          required: true
        - key: EVALUATION_HASH_FIELD
          description: Cart Custom Field holding the last successful promotion hash
          required: true
        - key: FAILURE_MODE
          description: Behavior on engine error or timeout, fail-open or fail-closed
          required: true
        - key: ATTRIBUTE_MAPPING
          description: Cart and Customer attributes forwarded to the engine
          required: true
        - key: DISCOUNT_TAX_CATEGORY_ID
          description: Tax Category for discount Custom Line Items, unused with Direct Discounts
          required: false
      securedConfiguration:
        - key: ENGINE_API_KEY
          description: API key for the promotion engine
          required: true
  - name: redemption-syncer
    applicationType: event
    endpoint: /redemptions
    scripts:
      postDeploy: npm run connector:post-deploy
      preUndeploy: npm run connector:pre-undeploy
    configuration:
      standardConfiguration:
        - key: ENGINE_BASE_URL
          description: Base URL of the promotion engine
          required: true
        - key: ENGINE_TIMEOUT_MS
          description: Outbound engine deadline, below the 10-second acknowledgment window
          required: true
        - key: ROLLBACK_ORDER_STATES
          description: Order State keys that trigger a rollback
          required: false
      securedConfiguration:
        - key: ENGINE_API_KEY
          description: API key for the promotion engine
          required: true
inheritAs:
  apiClient:
    scopes:
      - manage_extensions
      - manage_subscriptions
      - manage_types
      - view_orders

• manage_extensions for the script that registers the Cart API Extension.
• manage_subscriptions for the script that registers the Subscription.
• view_orders for the application that fetches the Order. This scope is broader than its name suggests, because it also grants read access to Carts, Associate Carts, Associate Orders, and Zones. Use the Store-scoped variant where a Store boundary applies.
• manage_types only when a deployment script creates the Cart Type.

Register the Extension destination so that its URL matches the route the application serves. Connect exposes the deployed service base URL for this purpose, and a handler mounted at the root can use it unchanged. When the handler is mounted on a path, append that path to the destination. A destination that does not match the served route causes every platform call to reach a route that does not exist.

Implement the evaluator

Condition the trigger

Under a carved-out design, where commercetools keeps ownership for most Carts, the condition must also select only the engine-owned Carts. Test whatever marks the carve-out, such as the Store, the Customer Group, or a Custom Field the storefront sets. Without that restriction the evaluator runs for Carts that carry platform-owned Discount Codes, and returning Set DirectDiscounts for one of them breaks the exclusivity rule and fails the Cart operation.

Skip unchanged evaluations

Hash the promotion-relevant fields of the Cart and store the result in a Custom Field. When the next evaluation computes the same hash, return an empty action list without calling the engine.

Include every field the engine's rules can match on: Line Items with their quantities and prices, the Customer and Customer Group, the Store, the currency and country, the Shipping Method, and the entered coupon code. A hash that omits a field the engine reads serves one segment's discount to another and produces a discount that is wrong rather than absent.

A Cart hash cannot see the engine. Campaign activation, a time window opening or closing, a coupon redeemed on another channel, a shared budget being consumed, and a loyalty tier change all move the engine's answer while the Cart stays identical, so an unconditional skip leaves a stale discount in place until an unrelated Cart change breaks the hash. Three rules keep the skip safe:

• Bound it. Store an evaluation timestamp, or the decision or campaign-set version token the engine returns, next to the hash. Call the engine anyway once the entry is older than a configured lifetime, or when the token no longer matches.
• Bypass it on coupon actions. A shopper who submits or removes a code expects a fresh answer.
• Write it only on success. The stored value records the Cart that the current discounts were calculated from. A hash written alongside an empty discount array holds the Cart at no discounts. Leaving the previous value untouched is not enough either, because a freshness-triggered failure leaves a hash that still matches the Cart; the failure branch must clear the hash or mark its entry stale so that the next evaluation retries.

The hash is a cost control, not a correctness mechanism. It does not replace idempotency on the engine side.

Choose a failure policy

A percentage sent in the wrong unit is the opposite failure. The draft is well formed, the Cart write succeeds, and the shopper silently receives a discount a hundredth of the intended size. No guard catches it, so cover unit conversion with a test instead.

The platform makes one attempt. An API Extension is not retried within an API call, although later API calls reach it again.

Reject a coupon without failing the Cart update

Understand what re-triggers the evaluator

Two behaviors are commonly confused, and only one of them is a loop.

Sequence against other Extensions

commercetools triggers all API Extensions registered for the same resource and action concurrently. If a Project runs both a promotion Extension and a tax Extension on the Cart, discounts must be applied before tax is calculated, because tax is calculated on discounted amounts. When the two Extensions run concurrently, the tax calculator can evaluate the Cart state that precedes the discount.

• An Extension declares at most 5 direct dependencies.
• A chain runs at most 3 levels deep.
• Circular dependencies are rejected.
• Cumulative execution time must stay inside the 60-second limit the platform enforces for an API request. Two chained Extensions that each call an external service consume a large share of that budget.

Keep the mapping testable

Keep the Cart-to-request and effects-to-actions mapping in pure functions with no network calls, so that the whole evaluation can be asserted without a deployment, a Cart, or a token.

Implement the redemption application

Decide when redemption happens

Two redemption points are defensible, and the choice changes what the application subscribes to and what it must roll back.

Choose one and implement it. Drifting between the two produces both sets of failure modes and neither set of guarantees.

Subscribe to the right Messages

Redeem idempotently

For each delivery, complete this sequence:

1. Validate the delivery and its Message type, and acknowledge deliveries that this application does not act on.
2. Fetch the current Order by resource.id rather than treating the delivery payload as the current resource.
3. Decide from the Order you fetched. Skip redemption for an Order that is already canceled, and skip a rollback for an Order that was never redeemed.
4. Redeem in the engine, keyed on a stable identifier derived from the Order ID, so that reprocessing the same Order does not create a second redemption.
5. Treat a response of already redeemed from the engine as success rather than an error to retry.
6. Record the outcome for that Order, so that a later delivery for the same Order can be recognized as already handled.
7. Acknowledge only after the engine call succeeded, was already complete, or failed permanently and was recorded for an operator.

Never redeem from a Cart. Only an Order is a purchase, and redeeming at evaluation time consumes coupons and awards points for Carts that are abandoned.

Do not treat commercetools as the ledger for points or balances. Mirroring a balance onto a Customer Custom Field for display is reasonable. Reading that mirror back as authoritative is not, because it diverges from the engine silently.

Roll back on cancellation or return

When rollback is in scope, release the redemption and reclaim the points on the transitions the merchant designates. Drive those transitions from configured lists of Order and State keys rather than from names written into the code, because State keys differ between Projects.

Keep the engine session stable

An engine tracks a session and a profile. Use the Cart ID as the session key and the Customer ID, or a stable anonymous identifier, as the profile key, and carry the same session key into the redemption call so that the engine can tie the redemption to the evaluations that preceded it.

The documented merge rules do not specify whether Cart-level Custom Fields transfer to the surviving Cart. Do not rely on an implicit transfer of the entered coupon code or promotion hash. Test the selected sign-in mode, explicitly re-apply required values to the surviving Cart, re-evaluate under its ID, and close or re-key the abandoned engine session.

Test the applications

Run these tests without a deployed Connector and without engine credentials. Mock the outbound boundary and assert on what the code decided: which endpoint it called, what it sent, and what it did with the answer.

Test the following evaluator behavior:

• Each engine effect type maps to the expected value and target, including permyriad conversion and the shipping discriminator.
• The response replaces the complete Direct Discount array rather than sending a delta.
• A successful response uses 200 or 201, and no code path returns 202.
• An invalid coupon produces a 200 response with a rejection in the Custom Field, and a Set DirectDiscounts action carrying the complete remaining set, usually an empty array, so that a discount from a previously accepted code is removed.
• A Cart with no Custom Fields Type assigned receives the Type before the first Set CustomField action, rather than failing.
• An unchanged promotion hash returns an empty action list and makes no engine call, while a change to any hashed field causes a fresh evaluation.
• An expired freshness entry and a submitted coupon code both bypass the skip and call the engine, and a failed evaluation clears the stored hash or marks it stale so that the next update retries.
• An engine error and an engine timeout both follow the chosen failure policy.
• A large Cart stays within the Extension action limit.
• A gift effect for a Product that is absent from the catalog follows the decision you recorded, rather than throwing.

Test the following redemption and deployment behavior:

• The handler validates the delivery envelope, acknowledges Messages it does not act on, and fetches the Order by resource.id.
• Redeeming the same Order twice produces one redemption and one point award, and a response of already redeemed is treated as success.
• A cancellation delivered before the OrderCreated delivery for the same Order leaves that Order unredeemed.
• An engine call that passes the outbound deadline records a pending redemption and completes on retry without a second redemption.
• A Cart that never becomes an Order produces no redemption.
• Configured cancellation and return transitions produce the expected rollback.
• Running the deployment scripts more than once leaves one API Extension, one Subscription, and one Cart Type registered, with the Type's existing fields intact.
• The undeploy script removes the API Extension and the Subscription, so that no platform call is left pointing at the removed endpoint.

Verify and operate the integration

Verify in a non-production Project against an engine test environment, and confirm that a real campaign matches your test Cart before concluding that anything is broken. Work through these checks:

1. Verify configuration: confirm that the deployment scripts registered the API Extension against the evaluator endpoint, created the Cart Type, and created the Subscription with the Messages and the destination the redemption application consumes. A Subscription is configured with a destination rather than pointed at an application URL, so check the destination and the application's consumption of it as separate steps. Confirm that the engine credentials are not present in standard configuration or in logs.
2. Verify evaluation: add a priced Line Item that an active campaign matches, then read the Cart. totalPrice has moved, and the discount is visible in the form the chosen mechanism produces. For Direct Discounts, directDiscounts lists the values and targets you sent, while the effect on prices appears in discountedPricePerQuantity on the affected Line Items for item targets, and in discountOnTotalPrice for a Cart-total target. For negative Custom Line Items, look for the added line. For engine-managed Discount Codes, check discountCodes and discountedPricePerQuantity.
3. Verify coupon handling: enter a valid code and confirm both a discount and an acceptance result. Enter an invalid code and confirm that the Cart update succeeds and carries a rejection reason. The acceptance and rejection results live in the Custom Fields only where the evaluator owns the code; for engine-managed Discount Codes, read the platform's own DiscountCodeState instead.
4. Verify call reduction: repeat an update that changes nothing the engine reads and confirm that no engine call occurred. Then change a hashed field and confirm that a fresh evaluation ran.
5. Verify redemption: place an Order, confirm that the application acknowledged the Message, and confirm through the engine's API that the effects you configured for the selected engine occurred, such as the coupon being consumed, the session being closed, or the points being awarded. Where the engine distinguishes a redemption from an evaluation, confirm that the redemption is recorded as one.
6. Verify redelivery: deliver the same Order Message twice and confirm exactly one redemption and one point award.
7. Verify the abandoned Cart: evaluate a Cart with a points-earning promotion and abandon it. The engine shows no redemption and no points.
8. Verify the failure policy: make the engine unavailable. Under fail-open, the Cart update still succeeds without discounts, and the next successful evaluation restores them.
9. Verify sign-in: sign in with an anonymous Cart that already carries an evaluated session and an entered code, and confirm that the code, the discounts, and the engine attribution land where you decided they should.
10. Verify rollback: where it is in scope, cancel an Order and confirm one rollback in the engine, then repeat for a return.

Monitor evaluation latency, engine errors and timeouts, the ratio of skipped to executed evaluations, Subscription health, and redelivery counts. Use the Cart ID and the Order ID as the trace keys that both applications share, because a Subscription delivery does not carry the correlation ID of the API Extension request that preceded it. Log that correlation ID in the evaluator for the synchronous path, and propagate it to the redemption application only if the evaluator persists it somewhere the Order-driven flow can read.

Diagnose common failures

Several correct behaviors in this domain read as defects. Engine-side symptoms assume that the selected engine exposes the campaign, reporting, idempotency, and session capabilities configured for this guide. Adapt those checks to the selected engine.