Terminal
Terminal/Skill
Walks through upgrading a Mollie SDK to a new major version or moving an integration from the Orders API to the Payments API.
By Mollie
Works with
npx skills add mollie/ai --skill mollie-upgradeThis is a distinct workflow from mollie-payments — that skill builds new
integrations; this one changes existing, working code. Confirm current behavior
with tests before changing anything, and re-verify after.
Are you updating your Mollie SDK to a newer version, or moving off the Orders API to the Payments API?
These require different playbooks — ask before proceeding.
# Node.js
npm list @mollie/api-client
# TypeScript
npm list mollie-api-typescript
# PHP
composer show mollie/mollie-api-php
# Python
pip show mollie-api-python
Mollie no longer recommends the Orders API. Payments API is simpler and gets new features the Orders API doesn't. This is not a drop-in rename — several concepts don't map 1:1.
| Orders API | Payments API | Note |
|---|---|---|
orderNumber | description | No dedicated order-number field |
lines[].name | lines[].description | |
Negative amounts on physical/digital/shipping_fee/surcharge lines | Not supported | Redesign any discount-via-negative-line logic |
consumerDateOfBirth | Removed | No replacement field |
expiresAt controlling authorization expiry | Removed | Authorization expiry is no longer configurable this way |
Orders auto-produced an authorized status for Klarna/Billie/Riverty. Payments
capture immediately by default — you must explicitly set captureMode: 'manual'
to keep a hold-then-capture flow. Without this, funds are taken immediately where
the old integration expected a hold. See <mollie-payments:references/operations/captures.md>
for the Payments-API capture flow.
authorized-state payments, are amount-based (not
line-based), and are asynchronous (status via webhook, not immediate).Orders allowed cancelling individual lines or the whole order to release funds. Payments only support releasing the full remaining authorized amount via the release-authorization endpoint — there is no partial release. If the existing logic does partial-line cancellation, it has no direct equivalent; flag this to the developer rather than silently approximating it.
Orders had two refund paths (via order lines, or via the underlying payment).
Payments API has one — <mollie-payments:references/operations/refunds.md> — which
also works against legacy orders' underlying payments.
authorized status. Those
can't use the Captures API directly — resolve them under the old flow first.
Do this before any of the steps below land in production, otherwise those
orders end up with the old shipment path gone and the new Captures path unable
to operate on them yet.captureMode: 'manual' anywhere a hold-then-capture flow is required.embed=payments
on existing List/Get Order calls to find the underlying payment ID and confirm its
status matches the order's status before cutting over stored references. Run this
as a pre-deploy backfill, or ship it atomically with steps 2–6 in the same
release — not after. Steps 2–6 already make the codebase expect Payment IDs; any
lookup that runs between that deploy and a separately-completed backfill will fail
against a database that still holds Order IDs.webhookUrl under the old Orders
flow will reference the Order ID in webhook payloads, not a Payment ID — account
for this if webhook handlers are being updated in the same pass.Regardless of which path was taken, end with a short summary covering: what version/ API was migrated from and to, which breaking changes were found and how each was resolved, what was verified (tests run, manual test-mode checks performed), and anything flagged as needing a design decision rather than a mechanical fix (e.g. partial-cancellation logic with no equivalent). Don't mark the migration complete if verification was skipped — say so explicitly instead.