How to Brief an Adobe Commerce Integration: Data, Events, Retries, and Acceptance Criteria

Who this lab is for, and what you will end up with

This guide is for IT leads, CTOs, operations managers, and project owners who need to brief an Adobe Commerce to ERP integration without jumping straight into implementation. The outcome is not a setup tutorial and not code: it is a completed brief, ready to review with internal engineers or external vendors.

The practical problem this brief solves is straightforward: it forces decisions on which data moves, who owns it, how events are handled, how retries and duplicates are treated, and what makes the project acceptable. The lab is designed to work with a spreadsheet or shared document, no production access, no credentials, and a simulated empty ERP as the baseline.

Adobe’s event documentation is useful here because it makes the integration model explicit: you configure an event provider, register events, define payload fields, and treat long-running work separately from the immediate response. In this guide, that becomes a practical brief-writing exercise rather than an installation recipe. The provider is treated as the event source, not automatically as the final receiver. (Configure Adobe Commerce, Use events and App Builder to Extend Adobe Commerce)

Result you should have at the end

A brief that contains:

• project objective and scope;
• data ownership and system of record;
• field mapping;
• event description and data contract;
• retry, duplicate, and reconciliation rules;
• acceptance test table;
• approval/signoff record.

Materials provided in this lab

• a complete sample CSV with three orders;
• a synthetic event envelope for one order;
• a completed field mapping table;
• a ready-to-copy signoff template.

Prerequisites

• a spreadsheet or document editor;
• no production access;
• no live customer data;
• no assumption that ERP is already configured;
• willingness to stop when scope, ownership, or retry rules are still unclear.

Provided sample data: the three simulated orders

Use the following CSV exactly as the working input for the lab. These are fictional examples only. Amounts are line totals only; VAT, discounts, and shipping are outside the scope of this exercise.

order_id,customer_ref,sku,qty,unit_price,line_total,currency,status
SIM-1042,C-07,TAZZA-BLU,2,12.00,24.00,EUR,confirmed
SIM-1043,C-08,BORSA-GRIGIA,1,30.00,30.00,EUR,confirmed
SIM-1044,C-09,TAZZA-BLU,3,12.00,36.00,EUR,confirmed

Synthetic event envelope for SIM-1042

This JSON is only for the exercise. It is not an Adobe-ready schema, not a verified endpoint payload, and not a promise of platform behavior.

{
  "event_id": "EVT-SIM-1042-01",
  "event_type": "order.confirmed",
  "timestamp": "2026-10-12T09:16:24Z",
  "order_id": "SIM-1042",
  "payload": {
    "customer_ref": "C-07",
    "sku": "TAZZA-BLU",
    "qty": 2,
    "unit_price": 12.00,
    "line_total": 24.00,
    "currency": "EUR",
    "status": "confirmed"
  }
}

1. Define objective and scope

Where to work: the first section of the brief.

What to write: one sentence for the project goal and one sentence for the exclusions.

Input to use: Adobe Commerce ↔ ERP, the three simulated orders, and an empty ERP baseline.

Paste-ready text:

Objective: define an integration between Adobe Commerce and ERP that creates confirmed ecommerce orders in ERP with clear rules for data, events, retries, duplicates, and acceptance.

Scope: this lab covers the three simulated orders SIM-1042, SIM-1043, and SIM-1044 and the Commerce → ERP order creation flow only.

Out of scope: catalog sync, invoicing, VAT, discounts, shipping, returns, ERP → Commerce stock updates, and any real production data.

What success looks like: anyone reading the brief can tell immediately that this is an order-integration project, not a generic e-commerce initiative.

If it does not match: stop here and rewrite scope. If the brief does not say what is in and what is out, the mapping and acceptance test sections will remain ambiguous.

2. Establish data ownership and system of record

Where to work: the section named “data ownership” or “master data”.

What to write: for each field, specify where it originates, where it lands, and who owns it in the process.

Fields to cover at minimum:

• order_id
• customer_ref
• sku
• qty
• unit_price
• line_total
• currency
• status

Completed example:

What success looks like: the brief states that, in this exercise, order data originates in Commerce and is transferred to ERP. Ownership is explicit, not implied.

If it does not match: if no system of record is written down, pause. The technical team will otherwise make assumptions, and the brief is not ready yet.

3. Fill in the field mapping

Where to work: the mapping table in the brief.

What to write: one row per important field, with direction, rule, and notes.

Completed mapping table:

What success looks like: a technical reviewer can see how each lab field becomes a destination field without guessing the transformation logic.

If it does not match: if any row is missing a destination or a rule, either complete it or declare it out of scope. Do not leave “TBD” rows in a brief that is meant to be reviewed.

4. Describe the event and the contract

Where to work: the section for event, payload, and delivery contract.

What to write: event name, event identifier, timestamp format, minimum payload, and a note that this is an exercise artifact.

Adobe’s documentation is useful here because it frames events as something you explicitly configure: provider, registrations, payload fields, and identifiers are all part of the setup. In the brief, the provider should be described as the event source, not automatically as the final receiver. Also, do not imply that a single event ID is enough to guarantee end-to-end delivery. The brief should name the persistent record, confirmation behavior, and error handling as separate concerns. (Configure Adobe Commerce, Use events and App Builder to Extend Adobe Commerce)

Paste-ready text:

Business event: order.confirmed.

Synthetic example: EVT-SIM-1042-01.

Timestamp: ISO 8601 format.

Minimum payload: order_id, customer_ref, sku, qty, unit_price, line_total, currency, status.

Note: this is an exercise event envelope, not an Adobe-ready schema and not a verified configuration.

What success looks like: the reviewer knows which event to monitor, what data to expect, and where the brief ends and technical implementation begins.

If it does not match: if the brief suggests that the provider alone guarantees delivery, rewrite it. The document must describe the process, not make unsupported promises.

5. Define retries, duplicates, and reconciliation

Where to work: the error-handling section.

What to write: a clear rule set that prevents duplicate orders and explains what happens when the outcome is uncertain.

Paste-ready text:

The project requires idempotency: the same operation must not create a new order.

Each request must be tied to a persistent key or persistent registry so that a replay can be recognized as an operational duplicate rather than a new business intent.

Retries are allowed only for transient errors and must be limited by project rules; definitive failures or unclear outcomes must go to a tracked error queue or an exception state.

If the outcome is uncertain, reconciliation happens first; only then does the team decide whether to retry, discard, or escalate for human review.

A single event identifier is not enough, by itself, to guarantee uniqueness in ERP.

What success looks like: the brief clearly separates retry, duplicate, and new order.

If it does not match: if there is no persistent key, registry, or error queue, the project risks duplicating orders or losing traceability. In that case the brief is incomplete.

6. Prepare the acceptance test table

Where to work: the bottom of the brief, in the acceptance or validation section.

What to write: a test input, an expected outcome, and a note for each scenario.

Completed acceptance table:

What success looks like: the brief is testable without running production systems. Each line has one observable outcome.

If it does not match: if the table uses vague phrases like “works fine” or “to be checked,” it is not an acceptance table. Replace narrative language with observable outcomes.

7. Collect approval and close the brief

Where to work: the final section with signoff or approval.

What to write: roles, verification performed, final status, and open questions.

Completed signoff template:

What success looks like: the brief ends in a decision point: approved, needs correction, or needs more detail.

If it does not match: if someone signs off without checking mapping, error handling, or acceptance tests, the signoff is incomplete. A justified “do not approve” is better than a generic approval.

Normal case and error case

Normal case

Order SIM-1042 arrives with every field present, maps to external_order_id, customer_code, item_code, quantity, unit_price, line_amount, currency, and order_status, and creates one ERP record. The brief should say that a replay of the event must not generate a second order.

Error or missing-data case

Order SIM-1043 arrives with a missing sku. The correct brief does not say “try anyway”; it defines a tracked rejection or a review queue, with no partial ERP record. If the project fills the field with a made-up value, the brief needs revision.

Troubleshooting

• The mapping is too short: add the fields the ERP truly needs, or explicitly declare them out of scope.
• Retry is described too vaguely: specify that retry is for transient failures only, and that uncertain outcomes require reconciliation first.
• The provider is confused with the receiver: rewrite the event section and state clearly that the provider is the event source, while receipt may happen later in the flow.
• Acceptance criteria are not observable: every test row needs an input and a single expected outcome.
• The brief says “success” without criteria: replace the generic wording with record counts, error handling rules, or reconciliation steps.

Final repeatable check

Before you send the brief to a vendor or internal team, verify these five conditions:

1. the objective is written in one sentence;
2. the scope says clearly what is in and what is out;
3. the mapping includes every required field;
4. retries, duplicates, and reconciliation are unambiguous;
5. the acceptance table has observable outcomes and the signoff identifies who approves and what remains open.

If even one of these is missing, the document is not ready for technical review.

Why this approach matters

Adobe Commerce integrations fail most often when teams skip the brief and jump directly to implementation. Adobe’s event model makes the lesson clear: events are configured, registered, and processed in a structured way, and deferred work is a separate design decision. That is why the best output from this lab is not a diagram or a ticket, but a brief that forces agreement before build work begins. (Configure Adobe Commerce, Use events and App Builder to Extend Adobe Commerce)

Sources

• https://developer.adobe.com/commerce/extensibility/events/configure-commerce
• https://developer.adobe.com/commerce/extensibility/events/tutorial/