When a Medusa purchase becomes a RealPage AP bill: keeping commerce and accounting in sync

The client problem

Checkout and property accounting describe the same purchase in different languages.

Medusa knows the buyer, seller, products, quantities, shipping, tax and payment journey. A property accounting system needs supplier codes, document numbers, properties, GL accounts, units, invoice dates and the state of the accounts-payable bill.

Exporting an order once does not close that gap.

After the bill enters RealPage, it continues to move. It may be posted, partially paid and eventually paid. The commerce platform needs those changes because buyers and operators should not see a purchase waiting for accounting when finance has already progressed it. At the same time, a temporary error on one document should not hide the state of every other bill in the synchronisation run.

That was the client problem behind the RealPage integration we built for a B2B procurement platform on Medusa.

We connected validated purchasing data to RealPage AP bills, then added a scheduled, organisation-scoped synchronisation that brings meaningful accounting states back into the order and purchase-order payment journey.

The integration starts before the API call

An accounting integration cannot repair missing business context at the final HTTP request.

If a marketplace order does not know which supplier code finance uses, which property incurred the cost or how a line is allocated across GL accounts and units, the RealPage adapter has nothing trustworthy to translate.

We therefore treat accounting as a continuation of the purchase lifecycle.

Line allocations remain connected to commerce lines. Seller accounting codes map marketplace suppliers to the identity expected by finance. Reviewed invoices and export batches preserve the document context. Only after those dimensions pass their business validation does the AP-bill integration become meaningful.

This produces a clean boundary: Medusa owns the purchasing truth; the accounting export translates an approved view of that truth; RealPage owns the downstream AP-bill state.

Give every supplier an accounting identity

A seller ID inside a marketplace is not automatically a vendor code inside the property accounting system.

The same supplier may be known by a specific accounting identifier established long before the commerce platform existed. Sending a storefront handle or internal database ID would create duplicate vendors, failed imports or bills attached to the wrong account.

The platform stores an explicit seller-to-accounting vendor-code mapping. That mapping is reviewed as business configuration rather than inferred from a company name.

This is a small piece of data with a large consequence. It lets the export say, “this commerce seller is that accounting vendor,” using an identifier both systems can treat as stable.

The same principle applies to properties and GL accounts. Integration quality depends on identity contracts, not fuzzy matching at the edge.

Export a reviewed accounting view, not the raw cart

A cart total is not an accounting bill.

Finance needs the commercial amounts separated and allocated in a way that can be reconciled. Merchandise, shipping and tax have different meanings. A line can be distributed across units or GL accounts according to the buyer’s allocation. Rounding must still resolve back to the order total.

The accounting utilities construct that reviewed view before RealPage synchronisation begins. The export retains identifiers for the order and document so the systems can refer to the same purchase later.

This is where many integrations become fragile: they send a convenient snapshot, then discover that nobody can explain how the accounting rows relate to the original order. We make that relationship part of the export contract.

When an AP bill is created or referenced in RealPage, the platform stores its document number with the corresponding export-order record.

Synchronise by organisation

RealPage credentials and accounting configuration belong to an organisation.

The scheduled job first identifies organisations that have completed exports with AP-bill documents still awaiting relevant state updates. It then runs the synchronisation separately for each organisation.

That scope matters for security and operations.

One organisation’s credentials must never be used to query another organisation’s documents. A failure in one connection should not stop the platform from processing unrelated organisations. Logs and run summaries should identify the organisation whose work was checked.

The workflow also acquires an organisation-level advisory lock. If another run is already processing that organisation, the second run skips rather than issuing overlapping state queries and competing updates.

The lock is not a marketing feature. Its business consequence is a synchronisation process with one active owner per organisation at a time.

Query only bills that can legitimately progress

Polling every historical order would be expensive and ambiguous.

The synchronisation selects a bounded business set. The accounting export must be completed. The organisation must have the integration enabled. The export item must have a RealPage document number. The related purchase-order payment must be in the validated state. The order’s accounting status must still be awaiting or exported.

Those conditions define the integration’s responsibility.

The job is not a general RealPage crawler. It follows bills that originated from the validated purchasing and export journey and have not yet reached their final commerce-side state.

This reduces noise and makes every queried document explainable: it is here because the platform exported it, knows its RealPage identity and expects an accounting transition.

Translate accounting states into commerce states

External systems often expose a richer or simply different status vocabulary.

For this AP-bill flow, the synchronisation recognises three important RealPage states:

• Posted means the bill has entered the accounting system and the Medusa order can move from awaiting to exported.
• Partially Paid remains exported and eligible for future polling because the financial lifecycle is still in progress.
• Paid moves the accounting state forward and triggers the buyer-payment confirmation workflow with RealPage as the confirmed source.

Other states are recorded as observed without inventing a transition the commerce platform does not understand.

That last rule is important. An integration should not convert every new provider string into a local success. Unknown states are information to retain and investigate, not permission to advance money-related workflow.

Keep accounting and payment as related but separate state machines

An AP bill being posted is not the same as the supplier having been paid.

The integration represents that distinction explicitly. Posted and partially paid establish that the bill has progressed into accounting. Only the paid state invokes the buyer-payment confirmation path.

The payment workflow receives the order, the RealPage document number and the external state that caused the confirmation. That gives the transition provenance instead of changing a generic boolean.

This separation matters for account-term purchasing. Unlike an instant card authorisation, the commercial order can exist while finance validates, posts and later settles the bill. The storefront and operational dashboards need to communicate that journey without calling every intermediate state “paid.”

Medusa’s extensible payment and workflow boundaries let us model the client’s terms rather than pretending RealPage behaves like a card processor.

Contain failures at the document level

Batch integrations fail unevenly.

One RealPage response can succeed for most document numbers while a subset fails. A bill can contain an unexpected state. A database update can fail for one order after other candidates were checked.

The synchronisation keeps per-item results. Documents returned in a failed provider batch are counted and logged without being treated as successful. During application, each candidate has its own error boundary, so one failure increments the failed count while the loop continues with the remaining bills.

The result reports how many bills were checked, moved to exported, confirmed paid or failed.

This gives operators a useful answer. They can see that most of the run progressed and isolate the documents that need attention, instead of receiving one red “RealPage sync failed” message for the entire portfolio.

Failure isolation is not permission to ignore errors. It makes errors actionable.

Persist what the external system actually said

Even when a state does not trigger a local transition, the platform records the last RealPage state and the time it was checked.

For posted or paid milestones, the relevant timestamps are retained. The order metadata carries the commerce-facing accounting status, while the export-order record preserves synchronisation detail.

This creates a trace between an external observation and a local change.

An operator can distinguish a bill that has never been checked from one that RealPage returned in an unrecognised state. The next scheduled run can continue from durable facts rather than from process memory.

Persisted observations also make support conversations clearer: “RealPage returned Partially Paid at this check” is much more useful than “the sync should have run.”

Protect credentials as server-side infrastructure

RealPage API keys and passwords are not ordinary organisation profile fields.

The credential module encrypts sensitive values at rest and decrypts them only for server-side consumers. Browser-facing routes return a safe shape: identifiers and configuration metadata, plus booleans indicating whether each secret has been set. They never return the raw keys or password.

When a user edits non-secret fields without entering a new secret, empty write-only inputs are removed so they do not overwrite stored credentials. Ownership checks ensure a credential ID belongs to the caller’s organisation before it can be retrieved or updated.

The UI can also test a connection without saving a new raw credential set first. The server uses the accounting API and returns a bounded success or failure message.

This is the correct trust boundary: the browser can manage configuration, but only the server can possess and use the secrets.

Make scheduling visible

A scheduled integration becomes frustrating when users do not know whether it is active or when it will run again.

The AP-bill synchronisation is a named scheduled job with a configured interval. It emits organisation-level summaries and per-failure logs. The storefront includes a synchronisation countdown so finance users can understand the next expected check.

That visibility reduces unnecessary manual retries. It also makes the system’s promise concrete: accounting state is reconciled on a cadence, not magically in real time.

If the business later requires webhook-driven updates, the same state-transition contract can receive another trigger. The current scheduler remains a reliable reconciliation path.

Why we integrated RealPage through Medusa

The client’s purchase journey already lived in Medusa: sellers, properties, lines, allocations, invoice validation, purchase-order payments and orders.

Building a detached integration service would require duplicating that context or reducing it to a thin export. By extending the Medusa platform, the adapter can act at the boundary where a validated commerce purchase becomes accounting data and where a paid AP bill becomes a buyer-payment confirmation.

Medusa supplies the commerce and workflow foundations. The custom accounting modules supply the property, GL, vendor-code and RealPage contracts the client needs.

This is exactly why platform choice is architectural. We chose a foundation we could extend far enough to connect ecommerce operations with a specialised property-accounting system without rebuilding the purchasing lifecycle around the integration.

A practical AP-bill integration checklist

Before connecting commerce to property accounting, define these contracts.

1. Supplier identity: which stable vendor code links the two systems?
2. Property and allocation context: where do GL accounts, units and quantities come from?
3. Export readiness: which business validations must pass before a bill can be sent?
4. Document identity: which number lets both systems refer to the same AP bill?
5. Credential ownership: which organisation owns the connection and how are secrets masked?
6. Candidate scope: which bills should the reconciliation job query?
7. State translation: what do Posted, Partially Paid and Paid mean locally?
8. Payment authority: which external state is allowed to confirm the buyer payment?
9. Failure isolation: can one bad document be retried without hiding successful work?
10. Operational evidence: where are last state, last check, milestones and run counts visible?

These contracts turn an API connection into an operable accounting capability.

The outcome: one purchase, two systems, one explainable journey

The integration does not pretend Medusa and RealPage are the same system.

It gives each one a clear responsibility and preserves the identifiers and transitions that connect them. Commerce validates the purchase and builds the accounting view. RealPage advances the AP bill. The synchronisation brings back only the states that matter to the buyer-payment lifecycle, with document-level errors kept visible and contained.

That is how WeAreSouk approaches enterprise commerce integration: start from the business transition, protect the identity and security boundaries, and make every asynchronous state change explainable to an operator.

If your Medusa purchase journey ends in a manual accounting export—or your AP bills progress without the commerce platform knowing—we can map the hand-off and build a controlled, observable integration around your finance system.