Example scope & report

# Medusa: a recoverable supplier import

Plan and implement one custom workflow with explicit retry and compensation rules

[← All services](/services)

Public reference: Medusa. Independent example based on public documentation. Not commissioned by or affiliated with Medusa.

[Download all 7 reports (PDF) ↓](/examples/upserto-example-reports.pdf)[Download Markdown ↓](/examples/backend-delivery.md)

## Decision brief

Recommended next decision

| Question | Recommendation |
| --- | --- |
| Decision | Give each supplier row a stable identity and each workflow step a recovery rule. |
| Why it matters | A repeat import or lost adapter response can leave duplicate or partly synchronized products. |
| Acceptance | An operator can recover a failed batch and explain the outcome of every accepted row. |
| Scope boundary | One custom Medusa workflow and external catalog adapter; product mapping is agreed with the commerce owner. |

## The proposed engagement

Proposed brief: a commerce team using Medusa needs to import supplier products and synchronize an external catalog. Upserto would implement one custom workflow: validate an approved batch, update the intended product records, call the external catalog adapter and expose the completion or recovery decision. The scope includes partial failure and repeated execution, not just a successful import.

Inputs required. Supplier schema; product mapping; deployed Medusa version; catalog API contract; representative redacted files.

## System boundary and assumptions

Medusa documents durable workflows, step compensation and configurable retries. These are building blocks; the customer still needs rules for external effects and business identity. The proposed slice covers a customer-owned import module and one catalog adapter. It excludes a full commerce migration, pricing rules and payment capture. No Medusa installation or supplier data was inspected for this proposal.

## How Upserto would approach it

Define batch identity and row identity before writing steps. Separate validation from changes. For each external call, specify whether a repeat is idempotent, compensatable or requires manual reconciliation. Review version-specific workflow retry settings. Agree batch size, concurrency and a representative workload before quoting capacity.

## What the team would receive

- A custom Medusa workflow and one catalog adapter.

- Batch-state and compensation rules with focused integration tests.

- Operator status output, retry guidance and configuration notes.

Separate forward progress from compensationA supplier import needs a recovery decision for each completed step. An ambiguous external result must be reconciled before retry or compensation.Solid: forward execution · Dashed: failure recovery

Read the diagram- Validate input before changing products or calling the external catalog.

- Record the information needed to restore or correct each completed step.

- After an ambiguous external call, confirm remote state before compensating local changes.

## Starting point and proposed change

Items to inspect in the customer integration, the proposed control and the evidence needed for acceptance.

Design comparison

| Control | Inspect first | Proposed change | Acceptance evidence |
| --- | --- | --- | --- |
| Repeat identity | Review how rows are matched on repeated imports. | Stable source identity and recorded adapter references. | Repeat and lost-response fixtures do not duplicate records. |
| Compensation | Review whether all failures use the same rollback. | Step-specific restore, compensate or reconcile decision. | Partial failure produces the intended recovery state. |
| Execution bounds | Review unbounded waiting and concurrency. | Agreed timeouts, batch limit and operator status. | A stuck adapter has a visible terminal or owned recovery decision. |

## Decisions and approval owners

Decisions to agree before implementation

| Decision | Proposed default | Approval owner |
| --- | --- | --- |
| Compensation | Choose restore, corrective action or reconciliation per step rather than one blanket rollback. | Commerce + backend owners |
| Execution limits | Agree batch size, timeouts and concurrency after a representative fixture run. | Backend + operations owners |

## Review questions and implementation risks

P1 Resolve before releasing the affected workflow, or record an explicit acceptance decision. P2 Assign an owner and an agreed follow-up milestone; do not leave the item unowned.

### BE-01 · P1 · Can the catalog call be repeated safely?

A catalog service may accept a request before its response is lost. Retrying the whole import without a stable row key can repeat an external effect.

Proposed approach. Use supplier/batch/row identity and confirm the adapter’s idempotency behavior. Reconcile ambiguous writes before repeating them.

### BE-02 · P1 · Does compensation match the business effect?

Deleting a local record is not a universal reversal. An external catalog change may already be consumed, and an existing product may need restoration rather than deletion.

Proposed approach. Specify compensation input for each step. Distinguish newly created and updated objects; document irreversible effects and the manual correction path.

### BE-03 · P2 · Can an import wait forever or overload workers?

Retry counts, waiting-step behavior and batch size affect how an operator observes progress. The actual workload and SDK version determine the configuration.

Proposed approach. Set explicit retry/timeout rules for the chosen version and expose batch progress. Measure an agreed workload before increasing concurrency.

## Example technical output

Proposed workflow contract

```text
workflow: supplier_catalog_import
identity: supplier + batch + row_key
steps:
  - validate_input
  - apply_product_change
  - sync_external_catalog
  - publish_batch_result
external_timeout: reconcile_before_repeat
compensation: defined_per_step
execution_result: TO_VERIFY
```

## Delivery plan and ownership

Proposed action plan

| Priority | Review item | Accountable role | Acceptance gate |
| --- | --- | --- | --- |
| P1 | BE-01 | Backend + catalog owner | A repeated row and a lost adapter response do not create unintended duplicate records. |
| P1 | BE-02 | Commerce backend owner | A failure after the external step leaves a documented, reviewable state with no blind deletion. |
| P2 | BE-03 | Backend + operations | A stuck adapter reaches the defined timeout/recovery state and does not block unrelated batches. |

## Acceptance checks

Run these checks before accepting the proposed changes.

Acceptance checks

| Scenario | Required evidence / expected behavior | Status |
| --- | --- | --- |
| Same batch is submitted twice | Stable row identity prevents unintended duplicate products | To verify |
| Catalog accepts then connection is lost | Remote state is reconciled before repeat | To verify |
| Failure after an update | Compensation restores the intended prior state or records a correction task | To verify |
| Catalog never completes | Timeout/recovery state is visible; unrelated work can proceed | To verify |

## Rollout and recovery

Build and verify in an isolated Medusa environment with approved fixture data. Start with a limited supplier and batch size. Keep new imports independently stoppable while existing batches remain inspectable. Release only after the team agrees which failures can be retried automatically and which require a person.

## Handover and limits

Deliver the workflow, adapter, mapping specification, fixture results and operator guide. Estimates for throughput or infrastructure would follow a representative workload test; this proposal includes no measured performance claim.

## Access and evidence handling

Controls for the agreed engagement

| Area | Required control |
| --- | --- |
| Access | Use an isolated Medusa environment and approved supplier fixtures before live imports. |
| Evidence | Retain row identity and adapter references; redact supplier credentials and unnecessary commercial fields. |
| Release | Agree an import stop control and the operator responsible for unresolved batches. |

## Public documentation used

The sources below establish product capabilities and API contracts. The implementation choices above are Upserto’s proposed approach for a customer integration.

- [Medusa: Workflows ↗](https://docs.medusajs.com/learn/fundamentals/workflows)Defines custom steps and execution from routes, subscribers and jobs.

- [Medusa: Compensation function ↗](https://docs.medusajs.com/learn/fundamentals/workflows/compensation-function)Documents step rollback inputs and compensation.

- [Medusa: Retry failed steps ↗](https://docs.medusajs.com/learn/fundamentals/workflows/retry-failed-steps)Documents retries, waiting steps and version-specific limits.

Discuss the same kind of work for your system, with an agreed scope and acceptance criteria.

[Explore Backend and API development ↗](/services/backend-api-development)[Discuss a similar scope ↗](/contact)

Contact: [hello@upserto.com](mailto:hello@upserto.com)