Update to Mollie

{
  "description": "Activate this skill when a developer wants to upgrade their Mollie SDK to a newer version, or migrate an existing integration from a deprecated Mollie API to its replacement — most commonly migrating from the Orders API to the Payments API. This includes: updating @mollie/api-client, mollie-api-php, mollie-api-python, or mollie-api-typescript to a newer major version, resolving breaking changes after an upgrade, and moving off the Orders API (orderNumber, order lines, Shipments API, order cancellation) onto the Payments API (captures, release-authorization, unified refunds).\n",
  "included_files": [],
  "name": "mollie-upgrade",
  "skill_md_contents": "---\nname: mollie-upgrade\ndescription: >\n  Activate this skill when a developer wants to upgrade their Mollie SDK to a newer\n  version, or migrate an existing integration from a deprecated Mollie API to its\n  replacement — most commonly migrating from the Orders API to the Payments API.\n  This includes: updating @mollie/api-client, mollie-api-php, mollie-api-python, or\n  mollie-api-typescript to a newer major version, resolving breaking changes after an\n  upgrade, and moving off the Orders API (orderNumber, order lines, Shipments API,\n  order cancellation) onto the Payments API (captures, release-authorization,\n  unified refunds).\n---\n\n# Mollie Upgrade\n\nThis is a distinct workflow from `mollie-payments` — that skill builds new\nintegrations; this one changes existing, working code. Confirm current behavior\nwith tests before changing anything, and re-verify after.\n\n## Step 1 — Identify the type of upgrade\n\n> Are you updating your Mollie SDK to a newer version, or moving off the Orders API\n> to the Payments API?\n\nThese require different playbooks — ask before proceeding.\n\n---\n\n## Step 2A — SDK version upgrade\n\n1. **Detect the current version.**\n   ```bash\n   # Node.js\n   npm list @mollie/api-client\n   # TypeScript\n   npm list mollie-api-typescript\n   # PHP\n   composer show mollie/mollie-api-php\n   # Python\n   pip show mollie-api-python\n   ```\n2. **Find the latest supported version and read its changelog** before touching\n   code — do not upgrade blind. Check for a major version bump specifically; minor/\n   patch upgrades rarely have breaking changes, major ones usually do.\n3. **Identify breaking changes** relevant to this codebase — grep the existing\n   integration for methods/fields the changelog flags as renamed or removed, rather\n   than assuming nothing broke.\n4. **Apply the version bump and required code changes** together, not separately —\n   an upgraded dependency with unmigrated call sites will fail at runtime, not at\n   install time, for a dynamically-typed language.\n5. **Run the existing test suite.** If there isn't one covering the Mollie\n   integration, say so explicitly before declaring the upgrade done — this skill\n   should not report success on the basis of \"the code compiles.\"\n6. **Verify webhooks and payment flows manually in test mode** — create a test\n   payment, complete it, confirm the webhook still fires and fulfilment still\n   triggers, before recommending a live-mode deploy.\n\n---\n\n## Step 2B — Migrating from Orders API to Payments API\n\nMollie no longer recommends the Orders API. Payments API is simpler and gets new\nfeatures the Orders API doesn't. This is not a drop-in rename — several concepts\ndon't map 1:1.\n\n### Field and endpoint changes\n\n| Orders API | Payments API | Note |\n|---|---|---|\n| `orderNumber` | `description` | No dedicated order-number field |\n| `lines[].name` | `lines[].description` | |\n| Negative amounts on `physical`/`digital`/`shipping_fee`/`surcharge` lines | Not supported | Redesign any discount-via-negative-line logic |\n| `consumerDateOfBirth` | Removed | No replacement field |\n| `expiresAt` controlling authorization expiry | Removed | Authorization expiry is no longer configurable this way |\n\n### Authorize-then-capture behavior changed\n\nOrders auto-produced an `authorized` status for Klarna/Billie/Riverty. Payments\ncapture immediately by default — **you must explicitly set `captureMode: 'manual'`**\nto keep a hold-then-capture flow. Without this, funds are taken immediately where\nthe old integration expected a hold. See `<mollie-payments:references/operations/captures.md>`\nfor the Payments-API capture flow.\n\n### Fulfilment: Shipments API → Captures API\n\n- The Shipments API doesn't exist for standalone Payments — use the Captures API\n  instead.\n- Captures only work on `authorized`-state payments, are amount-based (not\n  line-based), and are asynchronous (status via webhook, not immediate).\n- **You cannot use the Captures API on a payment that is still part of an Order** —\n  fully migrate that transaction's flow, not just the capture call.\n\n### Cancellation changed\n\nOrders allowed cancelling individual lines or the whole order to release funds.\nPayments only support releasing the **full** remaining authorized amount via the\nrelease-authorization endpoint — there is no partial release. If the existing logic\ndoes partial-line cancellation, it has no direct equivalent; flag this to the\ndeveloper rather than silently approximating it.\n\n### Refunds consolidated\n\nOrders had two refund paths (via order lines, or via the underlying payment).\nPayments API has one — `<mollie-payments:references/operations/refunds.md>` — which\nalso works against legacy orders' underlying payments.\n\n### Migration steps, in order\n\n1. **Pre-migration gate: check for orders still in `authorized` status.** Those\n   can't use the Captures API directly — resolve them under the old flow first.\n   Do this before any of the steps below land in production, otherwise those\n   orders end up with the old shipment path gone and the new Captures path unable\n   to operate on them yet.\n2. Replace *create order* calls with *create payment*, adjusting the field\n   differences above.\n3. Add `captureMode: 'manual'` anywhere a hold-then-capture flow is required.\n4. Replace Shipments-API fulfilment logic with Captures-API calls — but only once a\n   given transaction is fully off the Orders flow.\n5. Replace order/line cancellation with the release-authorization endpoint; flag any\n   partial-cancellation logic that has no direct equivalent.\n6. Consolidate refund logic onto the single payment-refund endpoint.\n7. **Migrate stored references from Order IDs to Payment IDs.** Use `embed=payments`\n   on existing List/Get Order calls to find the underlying payment ID and confirm its\n   status matches the order's status before cutting over stored references. Run this\n   as a pre-deploy backfill, or ship it atomically with steps 2–6 in the same\n   release — not after. Steps 2–6 already make the codebase expect Payment IDs; any\n   lookup that runs between that deploy and a separately-completed backfill will fail\n   against a database that still holds Order IDs.\n8. **Webhook caveat**: payments created without a `webhookUrl` under the old Orders\n   flow will reference the Order ID in webhook payloads, not a Payment ID — account\n   for this if webhook handlers are being updated in the same pass.\n\n---\n\n## Step 3 — Produce a migration summary\n\nRegardless of which path was taken, end with a short summary covering: what version/\nAPI was migrated from and to, which breaking changes were found and how each was\nresolved, what was verified (tests run, manual test-mode checks performed), and\nanything flagged as needing a design decision rather than a mechanical fix (e.g.\npartial-cancellation logic with no equivalent). Don't mark the migration complete if\nverification was skipped — say so explicitly instead.\n"
}