askell-mcp 0.4.16 → 0.4.18

package/README.md

@@ -173,10 +173,12 @@ Typical agent workflow:
 
 ## API notes (short)
 
-- **v1** — legacy paths like `/customers/`, `/subscriptions/` (no `/v2` prefix)
+- **v1** — legacy paths like `/customers/`, `/subscriptions/` (no `/v2` prefix). Contracts-only accounts refuse new legacy subscriptions (`400`, `code: legacy_subscriptions_disabled`). A subscription whose billing moved to a contract refuses cancel/activate/set_expiry/PATCH (`code: subscription_managed_by_contract`, follow `v2_endpoint`).
 - **v2** — current model: catalogs, quotes, checkouts, contracts, billing runs, coupons/promotion codes, fulfillment orders under `/v2/`
+- **v2 contract changes** — `reference` (max 128, no commas) on create/patch/list filter. Item update `apply_at=now|period_end`; cancel a scheduled change with `POST .../scheduled-changes/{id}/cancel/`. Move the billing anchor with `POST .../change-anchor/`, not PATCH. PATCH accepts only `metadata`, `reference`, `payment_processor_override` — ignore the description's `delivery_address` / accounting fields; they are not on `V2SubscriptionContractPatch`.
+- **v2 refunds** — billing-run charges are not Payments. `POST /v2/billing-runs/{id}/refund/` (full amount, no body). `202` means still `succeeded`; do not resend immediately. `POST /payments/{uuid}/refund/` is one-off only. `payment.*` may carry `billing_run_id`.
 - **v2 discounts** — catalog CRUD `/v2/coupons/` + `/v2/promotion-codes/` (coupon = definition, promotion code = what the customer types). Contract: `GET/POST /v2/subscription-contracts/{id}/discount|apply-code|remove-discount` (one active). Quotes take `promotion_code` and, for an existing buyer, `customer` (id) so combo discounts + promo restrictions apply. First-period totals already include coupon + combo; `quote.recurring_*` include combo but not the coupon (`discount.recurring_final_amount` while the coupon is active). Recurring `finalize` needs a verified payment method even when due-now is 0. Not the v1 `discount` 0–100 field.
-- **v2 fulfillment** — `GET /v2/fulfillment-orders/` for backfill; `POST .../{id}/fulfill/` (optional tracking body) and `POST .../{id}/cancel/` mark shipped/cancelled. Same body as `fulfillment_order.*` webhooks.
+- **v2 fulfillment** — `GET /v2/fulfillment-orders/` for backfill; `POST .../{id}/fulfill/` (optional tracking body) and `POST .../{id}/cancel/` mark shipped/cancelled. Webhooks: `fulfillment_order.created`, `shipment_booked` (extra `shipment_id`), `fulfilled`, `cancelled`. Same body as `GET`.
 - Paths use **trailing slashes**
 - Prefer **v2** for new integrations; v1 remains for existing ones
 - Docs: [docs.askell.is](https://docs.askell.is/) · OpenAPI: [v1](https://askell.is/api/swagger/swagger.json) · [v2](https://askell.is/api/swagger/v2/swagger.json)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "askell-mcp",
-  "version": "0.4.16",
+  "version": "0.4.18",
   "mcpName": "io.github.Neschadin/askell-mcp",
   "description": "MCP server for the Askell payment and subscription API (Bun + stdio)",
   "author": "Neschadin Oleksandr",
@@ -67,7 +67,7 @@
     "typescript": "7.0.2"
   },
   "dependencies": {
-    "@modelcontextprotocol/server": "2.1.0",
+    "@modelcontextprotocol/server": "2.2.0",
     "zod": "4.6.5"
   }
 }

package/spec/openapi-v1.json

@@ -431,11 +431,18 @@
             "description": "Successful operation"
           },
           "400": {
-            "description": "Invalid status value",
+            "description": "Invalid request, or the account uses subscription contracts only and no longer creates legacy subscriptions (`code: legacy_subscriptions_disabled`). Create a subscription contract with `POST /api/v2/subscription-contracts/` instead. The guard error also carries `status: error` on this endpoint.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/inline_response_400"
+                  "anyOf": [
+                    {
+                      "$ref": "#/components/schemas/inline_response_400"
+                    },
+                    {
+                      "$ref": "#/components/schemas/LegacySubscriptionGuardError"
+                    }
+                  ]
                 }
               }
             }
@@ -727,11 +734,18 @@
             }
           },
           "400": {
-            "description": "Invalid status value",
+            "description": "Invalid request, or the account uses subscription contracts only and no longer creates legacy subscriptions (`code: legacy_subscriptions_disabled`). Create a subscription contract with `POST /api/v2/subscription-contracts/` instead. On that refusal the customer is neither created nor updated.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/inline_response_400"
+                  "anyOf": [
+                    {
+                      "$ref": "#/components/schemas/inline_response_400"
+                    },
+                    {
+                      "$ref": "#/components/schemas/LegacySubscriptionGuardError"
+                    }
+                  ]
                 }
               }
             }
@@ -812,6 +826,25 @@
                 }
               }
             }
+          },
+          "400": {
+            "description": "The request failed validation, or the subscription's billing is managed by a subscription contract (`code: subscription_managed_by_contract`). Manage the contract through `/api/v2/subscription-contracts/{id}/` instead.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "anyOf": [
+                    {
+                      "type": "object",
+                      "description": "Field validation errors, keyed by field name.",
+                      "additionalProperties": true
+                    },
+                    {
+                      "$ref": "#/components/schemas/LegacySubscriptionGuardError"
+                    }
+                  ]
+                }
+              }
+            }
           }
         },
         "security": [
@@ -852,11 +885,18 @@
             }
           },
           "400": {
-            "description": "Invalid status value",
+            "description": "The subscription is not active, or its billing is managed by a subscription contract (`code: subscription_managed_by_contract`, whatever the legacy state). Cancel the contract with `POST /api/v2/subscription-contracts/{id}/cancel/` instead (see `v2_endpoint`).",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/inline_response_400"
+                  "anyOf": [
+                    {
+                      "$ref": "#/components/schemas/inline_response_400"
+                    },
+                    {
+                      "$ref": "#/components/schemas/LegacySubscriptionGuardError"
+                    }
+                  ]
                 }
               }
             }
@@ -900,11 +940,18 @@
             }
           },
           "400": {
-            "description": "Invalid status value",
+            "description": "The subscription is already active, expired or over its plan's subscription limit, or the account no longer reactivates legacy subscriptions. Or its billing is managed by a subscription contract (`code: subscription_managed_by_contract`, whatever the legacy state): manage the contract through `/api/v2/subscription-contracts/{id}/` instead (see `v2_endpoint`).",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/inline_response_400"
+                  "anyOf": [
+                    {
+                      "$ref": "#/components/schemas/inline_response_400"
+                    },
+                    {
+                      "$ref": "#/components/schemas/LegacySubscriptionGuardError"
+                    }
+                  ]
                 }
               }
             }
@@ -952,11 +999,18 @@
             }
           },
           "400": {
-            "description": "Invalid status value",
+            "description": "Invalid date or subscription state, or the subscription's billing is managed by a subscription contract (`code: subscription_managed_by_contract`). Manage the contract through `/api/v2/subscription-contracts/{id}/` instead.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/inline_response_400"
+                  "anyOf": [
+                    {
+                      "$ref": "#/components/schemas/inline_response_400"
+                    },
+                    {
+                      "$ref": "#/components/schemas/LegacySubscriptionGuardError"
+                    }
+                  ]
                 }
               }
             }
@@ -975,7 +1029,7 @@
           "Checkout"
         ],
         "summary": "Create a hosted checkout card form",
-        "description": "Creates a hosted checkout and returns a `checkout_url` that should be rendered in an iframe. The hosted page collects card details, handles 3D Secure when required, and posts completion messages to the embedding page. The resulting `token` is a reference to a payment method that can be added to a customer after checkout status becomes `tokencreated`.\n\nCreate a checkout either for a `plan` or directly for an account `payment_processor`. When using `payment_processor`, `currency` is required. To capture only the card details, set `capture_only` to `true`; this value is optional and defaults to `false`.\n\nIf supplied, `allowed_origin` must be an origin only, for example `https://merchant.example`, with no path, query string, or credentials. It controls the single parent page origin allowed to frame this checkout and receive checkout postMessage notifications. If omitted, all checkout origins configured for the account are allowed to frame the checkout.",
+        "description": "Creates a hosted checkout and returns a `checkout_url` that should be rendered in an iframe. The hosted page collects card details, handles 3D Secure when required, and posts completion messages to the embedding page. The resulting `token` is a reference to a payment method that can be added to a customer after checkout status becomes `tokencreated`.\n\nCreate a checkout either for a `plan` or directly for an account `payment_processor`. When using `payment_processor`, `currency` is required. A `plan` checkout completes into a legacy subscription, so on an account that uses subscription contracts only it is refused with 400 and `code: legacy_subscriptions_disabled`; a checkout for a `payment_processor` still works there. To capture only the card details, set `capture_only` to `true`; this value is optional and defaults to `false`.\n\nIf supplied, `allowed_origin` must be an origin only, for example `https://merchant.example`, with no path, query string, or credentials. It controls the single parent page origin allowed to frame this checkout and receive checkout postMessage notifications. If omitted, all checkout origins configured for the account are allowed to frame the checkout.",
         "requestBody": {
           "$ref": "#/components/requestBodies/CheckoutCreate"
         },
@@ -991,11 +1045,18 @@
             }
           },
           "400": {
-            "description": "Invalid status value",
+            "description": "Invalid request, or a checkout for a `plan` on an account that uses subscription contracts only (`code: legacy_subscriptions_disabled`). Checkouts without a `plan` are not affected.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/inline_response_400"
+                  "anyOf": [
+                    {
+                      "$ref": "#/components/schemas/inline_response_400"
+                    },
+                    {
+                      "$ref": "#/components/schemas/LegacySubscriptionGuardError"
+                    }
+                  ]
                 }
               }
             }
@@ -1359,7 +1420,7 @@
           }
         ],
         "summary": "Refund a settled Payment",
-        "description": "If a Payment is in the settled state and the payment processor supports refunds, you can refund it. Requires a secret key.",
+        "description": "If a Payment is in the settled state and the payment processor supports refunds, you can refund it. Requires a secret key. Charges made by V2 billing runs are not Payments: the transaction uuid a V2 `payment.*` webhook carries is answered with a 400 whose body names the run (`billing_run_id`) and points to `POST /api/v2/billing-runs/{billingRunId}/refund/`, which refunds it.",
         "responses": {
           "200": {
             "description": "Successful operation",
@@ -2590,6 +2651,47 @@
           }
         }
       },
+      "LegacySubscriptionGuardError": {
+        "type": "object",
+        "description": "Returned with HTTP 400 when the legacy API refuses work that subscription contracts now own. Match on `code` rather than on the message.",
+        "required": [
+          "error",
+          "code",
+          "v2_endpoint"
+        ],
+        "properties": {
+          "error": {
+            "type": "string",
+            "description": "What was refused and what to use instead, in English.",
+            "example": "This account uses subscription contracts and no longer creates legacy subscriptions. Use POST /api/v2/subscription-contracts/ instead."
+          },
+          "code": {
+            "type": "string",
+            "enum": [
+              "legacy_subscriptions_disabled",
+              "subscription_managed_by_contract"
+            ],
+            "description": "`legacy_subscriptions_disabled`: the account's subscription model is `contracts`, so legacy subscriptions are no longer created. `subscription_managed_by_contract`: the subscription was migrated to a subscription contract (its `billing_managed_by` is `subscription_contract`), which must be cancelled or changed through the V2 API instead.",
+            "example": "legacy_subscriptions_disabled"
+          },
+          "migrated_to_contract_id": {
+            "type": "integer",
+            "nullable": true,
+            "description": "The subscription contract that bills the subscription. Only present with `subscription_managed_by_contract`.",
+            "example": 123
+          },
+          "v2_endpoint": {
+            "type": "string",
+            "description": "The V2 endpoint to use instead: `/api/v2/subscription-contracts/` to create, `/api/v2/subscription-contracts/{id}/cancel/` to cancel, `/api/v2/subscription-contracts/{id}/` for other changes.",
+            "example": "/api/v2/subscription-contracts/"
+          },
+          "status": {
+            "type": "string",
+            "description": "Only on `POST /customers/{customerReference}/subscriptions/add/`, matching that endpoint's other errors.",
+            "example": "error"
+          }
+        }
+      },
       "inline_response_400": {
         "type": "object",
         "properties": {

package/spec/openapi-v2.json

@@ -619,6 +619,14 @@
             },
             "description": "Filter by customer reference."
           },
+          {
+            "in": "query",
+            "name": "reference",
+            "schema": {
+              "type": "string"
+            },
+            "description": "Filter by contract reference (exact match)."
+          },
           {
             "$ref": "#/components/parameters/PageSizeFilter"
           }
@@ -699,7 +707,7 @@
           "V2 Subscription Contracts"
         ],
         "summary": "Partially update a V2 subscription contract",
-        "description": "Restricted patch endpoint. Only `metadata` and `payment_processor_override` may be updated. Requires a secret key.",
+        "description": "Restricted patch endpoint. Only `metadata`, `reference`, `payment_processor_override`, `delivery_address`, `accounting_department` and `accounting_cost_center` may be updated. Requires a secret key.",
         "parameters": [
           {
             "$ref": "#/components/parameters/V2ContractId"
@@ -739,7 +747,7 @@
           "V2 Subscription Contracts"
         ],
         "summary": "Preview a V2 subscription contract proration",
-        "description": "Previews the proration impact of updating an existing V2 subscription contract item. Requires a secret key.",
+        "description": "Previews the proration impact of updating an existing V2 subscription contract item. With `operation=update_item`, `apply_at` selects when the change takes effect: `now` (default) prorates from `effective_at`, which must not be in the future (a future value returns a 400 with code `future_effective_at_not_supported`); `period_end` previews a change scheduled for the item's next renewal (nothing due now, no lines, `next_billing_estimate` at the new values, and `scheduled_for`). An immediate change to a price with a different billing interval credits the unused current period, charges a full new period from `effective_at` and restarts the item's billing period (single-item contracts only, settled with `invoice_now`). update_item previews also return `next_billing_at_after_change` and `billing_cadence_after_change`. Requires a secret key.",
         "parameters": [
           {
             "$ref": "#/components/parameters/V2ContractId"
@@ -786,7 +794,7 @@
           "V2 Subscription Contracts"
         ],
         "summary": "Update a V2 subscription contract item with proration",
-        "description": "Executes a prorated update for an existing V2 subscription contract item. Requires a secret key.",
+        "description": "Updates an existing V2 subscription contract item. With `apply_at=now` (default) the change applies immediately and `effective_at` only positions the proration window, so it must not be in the future (a future value returns a 400 with code `future_effective_at_not_supported`). With `apply_at=period_end` nothing is changed or charged now: the change is stored as a scheduled change (returned in `scheduled_change`, with `change_id` null) and applied to the item when its next renewal billing run is created. `effective_at`, `settlement_behavior` and `include_pending_adjustments` cannot be combined with `period_end`. An item with a pending scheduled change rejects further updates with a 409 (`scheduled_change_exists`) until it is canceled. An immediate billing-interval change with an amount due only switches the item once its proration run is collected (`applies_on_payment: true`, item `pending_interval_change`); meanwhile other changes to the item return a 409 (`pending_interval_change`). Requires a secret key.",
         "parameters": [
           {
             "$ref": "#/components/parameters/V2ContractId"
@@ -818,6 +826,70 @@
           },
           "404": {
             "$ref": "#/components/responses/V2NotFound"
+          },
+          "409": {
+            "$ref": "#/components/responses/V2ProrationConflict"
+          }
+        },
+        "security": [
+          {
+            "Secret-Api-Key": []
+          }
+        ]
+      }
+    },
+    "/v2/subscription-contracts/{contractId}/scheduled-changes/{scheduledChangeId}/cancel/": {
+      "post": {
+        "tags": [
+          "V2 Subscription Contracts"
+        ],
+        "summary": "Cancel a scheduled V2 subscription contract item change",
+        "description": "Cancels an item change scheduled with `apply_at=period_end` that has not been applied yet; the item then renews at its current values. Canceling an already canceled change replays (`replayed: true`); an applied or failed change returns a 409 with code `scheduled_change_not_cancelable`. Requires a secret key.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/V2ContractId"
+          },
+          {
+            "name": "scheduledChangeId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "reason": {
+                    "type": "string",
+                    "nullable": true
+                  }
+                }
+              }
+            }
+          },
+          "required": false
+        },
+        "responses": {
+          "200": {
+            "description": "Successful operation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/V2SubscriptionContractScheduledChangeCancelResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/V2NotFound"
+          },
+          "409": {
+            "$ref": "#/components/responses/V2ProrationConflict"
           }
         },
         "security": [
@@ -865,6 +937,9 @@
           },
           "404": {
             "$ref": "#/components/responses/V2NotFound"
+          },
+          "409": {
+            "$ref": "#/components/responses/V2ProrationConflict"
           }
         },
         "security": [
@@ -912,6 +987,59 @@
           },
           "404": {
             "$ref": "#/components/responses/V2NotFound"
+          },
+          "409": {
+            "$ref": "#/components/responses/V2ProrationConflict"
+          }
+        },
+        "security": [
+          {
+            "Secret-Api-Key": []
+          }
+        ]
+      }
+    },
+    "/v2/subscription-contracts/{contractId}/change-anchor/": {
+      "post": {
+        "tags": [
+          "V2 Subscription Contracts"
+        ],
+        "summary": "Change the billing anchor of a V2 subscription contract with proration",
+        "description": "Moves the next renewal of an active V2 subscription contract, and of all its active items, to new_billing_anchor_at. With proration, the unused part of the paid period is credited and the stretch from effective_at to the new anchor is charged, on the next invoice at the new date (next_invoice) or in a proration billing run now (invoice_now). Does not extend service entitlements. While an immediate billing-interval change on an item awaits its payment (item `pending_interval_change`) it returns a 409 (`pending_interval_change`); an interval change whose payment failed is abandoned, so a later retry of its charge no longer applies it. Requires a secret key.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/V2ContractId"
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/V2SubscriptionContractChangeAnchor"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Successful operation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/V2SubscriptionContractItemUpdateResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/V2ValidationError"
+          },
+          "404": {
+            "$ref": "#/components/responses/V2NotFound"
+          },
+          "409": {
+            "$ref": "#/components/responses/V2ProrationConflict"
           }
         },
         "security": [
@@ -1681,6 +1809,39 @@
         ]
       }
     },
+    "/v2/billing-runs/{billingRunId}/refund/": {
+      "post": {
+        "tags": [
+          "V2 Billing Runs"
+        ],
+        "summary": "Refund a V2 billing run",
+        "description": "Refunds the charge a succeeded V2 billing run settled. Full refunds only: the whole settled amount of the run's transaction is returned to the payment method it was charged to; partial refunds are not supported. Only runs in the `succeeded` state with a settled transaction can be refunded, and the payment processor must support refunds. No request body. Requires a secret key (public keys and legacy tokens are rejected).\n\n**200** — the processor refunded the charge and the returned run is `refunded` (with the refund recorded under `metadata.transaction_refund`); a `billing_run.changed` webhook is sent.\n\n**202** — the refund is not reflected on the returned run yet, which is still `succeeded`. Either the processor accepted the refund but has not completed it (for example Teya answering PENDING), or the processor refunded the charge and the run is still being updated. The request is recorded under `metadata.refund_requests`. Wait for the `billing_run.changed` webhook, or re-read the run, to see it move to `refunded`. Do not treat a 202 as a failure and do not immediately resend the request.\n\n**400** — the run is not `succeeded`, has no settled transaction (for example a zero-amount run, or a charge already refunded), its payment processor does not support refunds, or the processor did not complete the refund.\n\nConcurrent refund requests for the same run are serialized, and a request made after an earlier one refunded the charge gets a 400 while the run is `refunded`. If a request gets no response (for example a timeout), read the run with `GET /api/v2/billing-runs/{billingRunId}/` and check its `state` and `metadata.refund_requests` before sending the request again.\n\nThe `billing_run_id` in `payment.*` webhook payloads identifies the run to refund.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/V2BillingRunId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/V2BillingRun"
+          },
+          "202": {
+            "$ref": "#/components/responses/V2BillingRunRefundPending"
+          },
+          "400": {
+            "$ref": "#/components/responses/V2ValidationError"
+          },
+          "404": {
+            "$ref": "#/components/responses/V2NotFound"
+          }
+        },
+        "security": [
+          {
+            "Secret-Api-Key": []
+          }
+        ]
+      }
+    },
     "/v2/fulfillment-orders/": {
       "get": {
         "tags": [
@@ -3011,6 +3172,12 @@
               "metadata": {
                 "$ref": "#/components/schemas/V2Metadata"
               },
+              "reference": {
+                "type": "string",
+                "nullable": true,
+                "maxLength": 128,
+                "description": "The contract's reference in an external system, such as the seller's order number. Must not contain commas. Surrounding whitespace is trimmed and a blank value means no reference."
+              },
               "initial_billing_mode": {
                 "type": "string",
                 "enum": [
@@ -3029,7 +3196,18 @@
         "type": "object",
         "properties": {
           "metadata": {
-            "$ref": "#/components/schemas/V2Metadata"
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/V2Metadata"
+              }
+            ],
+            "description": "Replaces the integration's metadata keys. Keys Askell uses itself (`askell_source`, `billing_anchor_mode`, `activation_failure`, `email_markers`, `copied_legacy_pauses`, `copied_legacy_extra_data`, `migration_source`, `migration_cadence_mode`, `legacy_subscription_ids`, `seed`) keep their current values on the contract; any of them in the request are ignored."
+          },
+          "reference": {
+            "type": "string",
+            "nullable": true,
+            "maxLength": 128,
+            "description": "The contract's reference in an external system. Must not contain commas. `null` or a blank value clears it."
           },
           "payment_processor_override": {
             "type": "integer",
@@ -3288,7 +3466,8 @@
                   "pause",
                   "resume",
                   "cancel",
-                  "restart"
+                  "restart",
+                  "change_anchor"
                 ],
                 "default": "update_item"
               },
@@ -3335,6 +3514,21 @@
                 "format": "date-time",
                 "nullable": true,
                 "description": "Only applies to pause."
+              },
+              "new_billing_anchor_at": {
+                "type": "string",
+                "format": "date-time",
+                "nullable": true,
+                "description": "Only applies to change_anchor, where it is required."
+              },
+              "apply_at": {
+                "type": "string",
+                "enum": [
+                  "now",
+                  "period_end"
+                ],
+                "default": "now",
+                "description": "Only applies to update_item. `now` changes the item immediately with proration; `period_end` schedules the change for the item's next renewal (cannot be combined with `effective_at`, `settlement_behavior` or `include_pending_adjustments`)."
               }
             }
           }
@@ -3419,6 +3613,49 @@
           }
         ]
       },
+      "V2SubscriptionContractChangeAnchor": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/V2SubscriptionContractChangeCommon"
+          },
+          {
+            "type": "object",
+            "required": [
+              "new_billing_anchor_at"
+            ],
+            "properties": {
+              "operation": {
+                "type": "string",
+                "enum": [
+                  "change_anchor"
+                ],
+                "default": "change_anchor"
+              },
+              "new_billing_anchor_at": {
+                "type": "string",
+                "format": "date-time",
+                "description": "The contract's new next renewal time. Must be after effective_at and, with proration, no more than one billing period after it."
+              },
+              "settlement_behavior": {
+                "type": "string",
+                "enum": [
+                  "next_invoice",
+                  "invoice_now"
+                ],
+                "nullable": true,
+                "description": "Defaults to invoice_now with always_invoice proration, otherwise next_invoice. Ignored when proration_behavior is none."
+              },
+              "idempotency_key": {
+                "type": "string",
+                "nullable": true
+              },
+              "preview_token": {
+                "type": "string"
+              }
+            }
+          }
+        ]
+      },
       "V2SubscriptionContractItemUpdate": {
         "allOf": [
           {
@@ -3459,6 +3696,15 @@
                 "nullable": true,
                 "description": "Fixed per-unit amount for the item, used instead of the catalog price. Omitting the field keeps the item's current override; an explicit null clears it so the item reverts to the catalog price."
               },
+              "apply_at": {
+                "type": "string",
+                "enum": [
+                  "now",
+                  "period_end"
+                ],
+                "default": "now",
+                "description": "`now` changes the item immediately with proration; `period_end` keeps the current price until the item's current service period ends and applies the change at the next renewal, with no refund or charge now."
+              },
               "idempotency_key": {
                 "type": "string",
                 "nullable": true
@@ -3613,6 +3859,155 @@
           },
           "preview_token": {
             "type": "string"
+          },
+          "apply_at": {
+            "type": "string",
+            "enum": [
+              "now",
+              "period_end"
+            ],
+            "description": "update_item only."
+          },
+          "scheduled_for": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true,
+            "description": "update_item only. When a period_end change takes effect (the item's current service period end); null for now."
+          },
+          "next_billing_at_after_change": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true,
+            "description": "update_item only. The item's next billing once the change is in effect. For an immediate billing-interval change this is the end of the new period; for period_end it is the renewal the change applies at."
+          },
+          "billing_cadence_after_change": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/V2SubscriptionContractBillingCadence"
+              }
+            ],
+            "nullable": true,
+            "description": "update_item only. The contract's billing cadence after the change."
+          },
+          "applies_on_payment": {
+            "type": "boolean",
+            "description": "update_item only. True for an immediate billing-interval change with an amount due: the item switches only once that charge is collected."
+          }
+        }
+      },
+      "V2SubscriptionContractScheduledChange": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "integer"
+          },
+          "contract_item": {
+            "type": "integer"
+          },
+          "operation": {
+            "type": "string",
+            "enum": [
+              "update_item"
+            ]
+          },
+          "state": {
+            "type": "string",
+            "enum": [
+              "scheduled",
+              "applied",
+              "canceled",
+              "failed"
+            ]
+          },
+          "scheduled_for": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "price_id": {
+            "type": "integer"
+          },
+          "price": {
+            "$ref": "#/components/schemas/V2CatalogPrice"
+          },
+          "product": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "integer"
+              },
+              "name": {
+                "type": "string"
+              },
+              "reference": {
+                "type": "string",
+                "nullable": true
+              }
+            }
+          },
+          "quantity": {
+            "type": "integer"
+          },
+          "discount_percent": {
+            "type": "string",
+            "format": "decimal",
+            "nullable": true
+          },
+          "unit_amount_override": {
+            "type": "string",
+            "format": "decimal",
+            "nullable": true
+          },
+          "from_price_id": {
+            "type": "integer",
+            "nullable": true
+          },
+          "from_quantity": {
+            "type": "integer",
+            "nullable": true
+          },
+          "reason": {
+            "type": "string",
+            "nullable": true
+          },
+          "applied_at": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+          },
+          "canceled_at": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+          },
+          "applied_change_id": {
+            "type": "integer",
+            "nullable": true
+          },
+          "billing_run_id": {
+            "type": "integer",
+            "nullable": true
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "V2SubscriptionContractScheduledChangeCancelResponse": {
+        "type": "object",
+        "properties": {
+          "scheduled_change": {
+            "$ref": "#/components/schemas/V2SubscriptionContractScheduledChange"
+          },
+          "replayed": {
+            "type": "boolean"
+          },
+          "contract": {
+            "$ref": "#/components/schemas/V2SubscriptionContract"
           }
         }
       },
@@ -3620,7 +4015,21 @@
         "type": "object",
         "properties": {
           "change_id": {
-            "type": "integer"
+            "type": "integer",
+            "nullable": true,
+            "description": "Null when the change was scheduled with apply_at=period_end."
+          },
+          "scheduled_change": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/V2SubscriptionContractScheduledChange"
+              }
+            ],
+            "nullable": true
+          },
+          "applies_on_payment": {
+            "type": "boolean",
+            "description": "True when an immediate billing-interval change waits for `billing_run_id` to be collected; until then the item keeps its current price and shows the change in `pending_interval_change`."
           },
           "billing_run_id": {
             "type": "integer",
@@ -3632,6 +4041,13 @@
               "type": "integer"
             }
           },
+          "consumed_pending_adjustment_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer"
+            },
+            "description": "Earlier pending adjustment lines this change pulled into its invoice_now billing run with include_pending_adjustments; empty otherwise."
+          },
           "replayed": {
             "type": "boolean"
           },
@@ -3668,7 +4084,12 @@
                 "type": "string"
               },
               "metadata": {
-                "$ref": "#/components/schemas/V2Metadata"
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/V2Metadata"
+                  }
+                ],
+                "description": "Stored on the checkout and copied to the created contract's `metadata` when the checkout is finalized. In a checkout session the session's own metadata wins on a shared key, and the sales channel's `metadata_policy.frontend_allowed_keys` limits the keys the browser may send (with no such list any key is accepted, and an empty list accepts none). Keys Askell uses itself (`askell_source`, `billing_anchor_mode`, `activation_failure`, `email_markers`, `copied_legacy_pauses`, `copied_legacy_extra_data`, `migration_source`, `migration_cadence_mode`, `legacy_subscription_ids`, `seed`) are not copied."
               },
               "delivery_address": {
                 "$ref": "#/components/schemas/V2Address",
@@ -4001,7 +4422,12 @@
             "description": "Seller customer reference. If an existing customer has this reference, the session is bound to that customer."
           },
           "metadata": {
-            "$ref": "#/components/schemas/V2Metadata"
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/V2Metadata"
+              }
+            ],
+            "description": "Server-side session metadata. Returned by the session GET and copied to the created contract's `metadata` when the session's checkout is finalized; on a key the browser also sends, this value wins. Keys Askell uses itself (`askell_source`, `billing_anchor_mode`, `activation_failure`, `email_markers`, `copied_legacy_pauses`, `copied_legacy_extra_data`, `migration_source`, `migration_cadence_mode`, `legacy_subscription_ids`, `seed`) are not copied."
           },
           "theme": {
             "$ref": "#/components/schemas/V2Metadata",
@@ -4902,6 +5328,59 @@
           },
           "metadata": {
             "$ref": "#/components/schemas/V2Metadata"
+          },
+          "scheduled_change": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/V2SubscriptionContractScheduledChange"
+              }
+            ],
+            "nullable": true,
+            "description": "The item's pending change scheduled for its next renewal, if any."
+          },
+          "pending_interval_change": {
+            "type": "object",
+            "nullable": true,
+            "description": "An immediate billing-interval change waiting for its charge to be collected; the item switches when the billing run succeeds.",
+            "properties": {
+              "change_id": {
+                "type": "integer"
+              },
+              "billing_run_id": {
+                "type": "integer",
+                "nullable": true
+              },
+              "status": {
+                "type": "string",
+                "enum": [
+                  "awaiting_payment"
+                ]
+              },
+              "price_id": {
+                "type": "integer"
+              },
+              "quantity": {
+                "type": "integer"
+              },
+              "discount_percent": {
+                "type": "string",
+                "format": "decimal",
+                "nullable": true
+              },
+              "unit_amount_override": {
+                "type": "string",
+                "format": "decimal",
+                "nullable": true
+              },
+              "effective_at": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "next_billing_at": {
+                "type": "string",
+                "format": "date-time"
+              }
+            }
           }
         }
       },
@@ -5478,7 +5957,8 @@
             "type": "string"
           },
           "customer_name": {
-            "type": "string"
+            "type": "string",
+            "description": "The customer's first and last name, whichever are set; empty when the customer has neither."
           },
           "customer_email": {
             "type": "string",
@@ -5758,6 +6238,12 @@
           "customer_reference": {
             "type": "string"
           },
+          "reference": {
+            "type": "string",
+            "nullable": true,
+            "maxLength": 128,
+            "description": "The contract's reference in an external system, such as the seller's order number. V2 payment pages set it from their `subscription_reference` URL parameter."
+          },
           "shipping_selection": {
             "$ref": "#/components/schemas/V2ShippingSelection"
           },
@@ -5883,7 +6369,12 @@
             }
           },
           "metadata": {
-            "$ref": "#/components/schemas/V2Metadata"
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/V2Metadata"
+              }
+            ],
+            "description": "Integration metadata. A contract created by a checkout carries the checkout session's and the checkout's metadata, and `askell_source` records where the contract came from (`type`: `checkout_session`, `checkout` or `payment_page`, with the ids of that source)."
           },
           "subscriber_page": {
             "type": "string",
@@ -5957,6 +6448,13 @@
           },
           "latest_billing_run": {
             "$ref": "#/components/schemas/V2BillingRunSummary"
+          },
+          "scheduled_changes": {
+            "type": "array",
+            "description": "Pending item changes scheduled for the items' next renewals.",
+            "items": {
+              "$ref": "#/components/schemas/V2SubscriptionContractScheduledChange"
+            }
           }
         }
       },
@@ -7076,6 +7574,34 @@
           }
         }
       },
+      "V2ProrationConflict": {
+        "description": "Conflict, e.g. `scheduled_change_exists`, `pending_interval_change`, `scheduled_change_not_cancelable`, `idempotency_key_conflict`, `preview_stale`, `billing_run_overlap`",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "error": {
+                  "type": "string"
+                },
+                "code": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      },
+      "V2BillingRunRefundPending": {
+        "description": "The refund is not reflected on the returned billing run yet, which is still `succeeded`: either the payment processor accepted the refund but has not completed it, or it refunded the charge and the run is still being updated. The request is recorded under `metadata.refund_requests`. Wait for the `billing_run.changed` webhook, or re-read the run, to see it move to `refunded`; do not treat this as a failure or immediately resend the request.",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/V2BillingRun"
+            }
+          }
+        }
+      },
       "V2BillingRun": {
         "description": "V2 billing run",
         "content": {

package/src/resources/register.ts

@@ -9,7 +9,7 @@ Askell POSTs signed JSON to each URL you register. Verify \`Hook-HMAC\` before p
 Headers:
 - Hook-HMAC: base64 HMAC-SHA512 of the **raw body** (secret = \`hmac_secret\` from webhook create)
 - Hook-Event: event type (\`subscription.renewed\`, \`payment.changed\`, or a family wildcard \`subscription.*\`)
-- Hook-API-Version: \`v1\` for plan/subscription/customer/payment/checkout, \`v2\` for subscription_contract / billing_run / fulfillment_order
+- Hook-API-Version: \`v1\` for plan/subscription/customer/checkout and one-off \`payment.*\`; \`v2\` for subscription_contract / billing_run / fulfillment_order and for \`payment.*\` of a billing-run charge
 
 ## Body shape
 
@@ -17,7 +17,7 @@ JSON body **is the event object**. It is **not** \`{ event, data }\`.
 
 Upstream swagger used to document a dummy \`POST /your-webhook-url/\` with \`SubscriptionMultiLite\` (\`{ customer, subscriptions[] }\`). \`sync-specs\` strips that path.
 
-Most inbound families are still undocumented in OpenAPI — this resource is the overlay. Exception: \`fulfillment_order.*\` body **is** \`V2FulfillmentOrder\` (same as \`GET /v2/fulfillment-orders/{id}/\`). Live https://docs.askell.is/en/api/webhooks.html does not list this family yet.
+Most inbound families are still undocumented in OpenAPI — this resource is the overlay. Exception: \`fulfillment_order.*\` body **is** \`V2FulfillmentOrder\` (same as \`GET /v2/fulfillment-orders/{id}/\`). Live https://docs.askell.is/en/api/webhooks.html lists that family (\`created\`, \`shipment_booked\`, \`fulfilled\`, \`cancelled\`).
 
 Rare historical payloads used \`{ event, data, ref?, sender? }\`. If both \`event\` and \`data\` are objects, use \`data\`.
 
@@ -42,28 +42,52 @@ Live REST \`Subscription\` objects have extra fields the OpenAPI schema omits. W
 V2 migration: \`subscription.*\` is **not** aliased onto the new contract (payload is \`SubscriptionContract\`). \`subscription.canceled\` is not sent merely because billing moved to a V2 contract.
 
 ### subscription_contract.* (v2)
-\`created\`, \`changed\`, \`renewed\`, \`migrated\`
+\`created\`, \`changed\`, \`renewed\`, \`migrated\`. Live https://docs.askell.is/en/api/webhooks.html also names \`activated\`, \`paused\`, \`resumed\`, \`canceled\`, \`ended\`.
 
-\`id\`, \`customer\`, \`state\`, \`billing_anchor_at\`, \`next_billing_at\`, \`cancel_at\`, \`cancel_at_period_end\`, \`canceled_at\`, \`ended_at\`, \`currency\`, \`recurring\`, \`legacy_subscription\`, \`legacy_subscription_ids\`, \`migration_effective_at\`, \`billing_managed_by\`, \`created_at\`, \`updated_at\`.
+A scheduled cancellation sends \`subscription_contract.ended\`, not \`canceled\`, even though \`state\` becomes \`canceled\`. \`canceled\` is only an immediate cancel. \`changed\` often arrives next to the more specific event.
+
+Except \`migrated\`, the body is the contract as GET \`/v2/subscription-contracts/{id}/\` returns it (\`V2SubscriptionContract\`). \`customer\` is an object; the numeric id is \`customer_id\`. The page also puts \`reference\` and \`scheduled_changes\` on that body, and a pending item change on item \`scheduled_change\` (the example JSON omits \`scheduled_changes\`; the following paragraph names it). The example includes \`legacy_source_mappings\`, which OpenAPI does not list.
+
+\`migrated\` is not the whole contract, and \`customer\` there is a numeric id. Fields: \`id\` / \`subscription_contract_id\` (same value), \`migration_batch_id\`, \`customer\`, \`customer_reference\`, \`billing_managed_by\`, \`migration_effective_at\`, \`legacy_subscription_ids\`, \`legacy_source_mappings\`.
+
+\`subscription_contract_scheduled_change.*\` and \`subscription_contract_item.*\` are not included in this family.
+
+### subscription_contract_item.* (v2)
+Not covered by \`subscription_contract.*\`. Register \`subscription_contract_item.*\` or \`subscription_contract_item.entitlement_changed\`.
+
+Sent when an item's entitlement changes (\`service_active\` / \`service_state\`, \`entitled_until\`, quantity, or product). \`id\` and \`contract_item_id\` are the item id. Also \`subscription_contract_id\`, numeric \`customer\`, \`customer_reference\`, \`changed_fields\`, and \`previous\` (entitlement fields before the change).
+
+### subscription_contract_scheduled_change.* (v2)
+Not covered by \`subscription_contract.*\`. Register \`subscription_contract_scheduled_change.*\` or a specific event.
+
+\`subscription_contract_scheduled_change.created\` — item change scheduled for the next renewal (\`apply_at=period_end\`). \`subscription_contract_scheduled_change.applied\` — applied when that renewal's billing run is created. \`subscription_contract_scheduled_change.canceled\` — canceled via the API, or automatically when the item is removed or the contract is canceled.
+
+Payload is the scheduled change (same shape as \`scheduled_changes[]\`) plus \`subscription_contract_id\`, \`customer\` (numeric id), \`customer_reference\`. \`operation\` is \`update_item\`. \`state\` is \`scheduled\` / \`applied\` / \`canceled\`. \`applied_at\`, \`applied_change_id\`, and \`billing_run_id\` are set only on \`applied\`. \`canceled_at\` is set only on \`canceled\`.
 
 ### billing_run.* (v2)
 \`created\`, \`changed\`, \`succeeded\`, \`failed\`, \`retry\`
 
-\`id\`, \`contract\`, \`period_start_at\`, \`period_end_at\`, \`state\`, \`currency\`, \`subtotal_amount\`, \`tax_amount\`, \`total_amount\`, \`attempt_count\`, \`max_attempts\`, \`next_retry_at\`, \`last_attempt_at\`, \`transaction\`, \`created_at\`, \`updated_at\`.
+Body matches \`V2BillingRun\`: \`contract_id\` (not \`contract\`), \`customer_id\`, \`period_start_at\`, \`period_end_at\`, \`state\`, amounts, \`attempt_count\`, \`max_attempts\`, \`next_retry_at\`, \`last_attempt_at\`, \`transaction_id\`, \`transaction_uuid\`, \`transaction_external_reference\` (null when no transaction exists), \`lines\`, \`attempts\`. Live page \`state\` values: \`scheduled\`, \`processing\`, \`retry_scheduled\`, \`pending_external\`, \`succeeded\`, \`failed_terminal\`, \`canceled\`, \`voided\`, \`refunded\`. OpenAPI leaves \`state\` an unconstrained string.
+
+Refunding a succeeded run (\`POST /v2/billing-runs/{id}/refund/\`) sends \`billing_run.changed\`, not a new event type. The run's \`state\` becomes \`refunded\`. A \`202\` means the run is still \`succeeded\`.
 
 ### customer.* (v1)
 \`created\`, \`changed\` — same shape as GET \`/customers/{ref}/\` (\`id\`, names, \`email\`, \`phone\`, \`customer_reference\`, address fields, \`payment_method[]\`).
 
-### payment.* (v1)
-\`created\`, \`changed\`, \`retry\`
+### payment.*
+\`created\`, \`changed\`, \`retry\`. One registration receives both shapes. Tell them apart with \`Hook-API-Version\`, or with \`subscription_contract_id\` (only on a billing-run charge).
+
+One-off Payment (\`Hook-API-Version: v1\`): \`uuid\`, \`amount\`, \`currency\`, \`description\`, \`reference\`, \`state\` (\`pending\` | \`settled\` | \`failed\` | \`retrying\`), \`created_at\`, \`updated_at\`, \`transactions[]\`.
+
+Billing-run charge (\`Hook-API-Version: v2\`): a flat transaction, no \`transactions[]\`. \`uuid\` (transaction id), \`amount\`, \`currency\`, \`description\`, \`reference\` (processor reference), \`state\` (\`initial\` | \`pending\` | \`settled\` | \`failed\` | \`canceled\` | \`refunded\`), \`fail_code\`, \`refund_code\`, \`cancel_code\`, \`payment_method\` (numeric id), \`billing_run_id\`, \`billing_run_attempt_id\`, \`subscription_contract_id\`, \`customer\`, \`customer_reference\`, \`legacy_subscription_ids\`. \`payment.created\` when an attempt opens a transaction, \`payment.changed\` when the charge succeeds, fails permanently, or waits on the processor, \`payment.retry\` when another attempt is scheduled. A \`payment.retry\` with no transaction has null \`uuid\`, \`reference\`, \`created_at\`, \`updated_at\`, \`payment_method\`, and codes; \`amount\` / \`currency\` come from the run, and \`state\` is the run's state (for example \`retry_scheduled\`).
 
-\`uuid\`, \`amount\`, \`currency\`, \`description\`, \`reference\`, \`state\` (\`pending\` | \`settled\` | \`failed\` | \`retrying\`), \`created_at\`, \`updated_at\`, \`transactions[]\`.
+That \`uuid\` is not a Payment. Do not \`POST /payments/{uuid}/refund/\`. Refund with \`POST /v2/billing-runs/{billingRunId}/refund/\`.
 
 ### checkout.* (v1)
 \`created\`, \`changed\` — \`token\`, \`checkout_url\`, \`status\`.
 
 ### fulfillment_order.* (v2)
-Family wildcard \`fulfillment_order.*\`. Bundled swagger names \`fulfillment_order.fulfilled\` (\`POST .../fulfill/\` or dashboard ship) and \`fulfillment_order.cancelled\` (\`POST .../cancel/\`). Do not invent \`created\`/\`changed\`. Live https://docs.askell.is/en/api/webhooks.html still omits this family.
+Live https://docs.askell.is/en/api/webhooks.html names \`fulfillment_order.created\` (after payment succeeds), \`fulfillment_order.shipment_booked\` (tracking is available; the payload also has \`shipment_id\` pointing at that entry in \`fulfillments[]\`), \`fulfillment_order.fulfilled\`, and \`fulfillment_order.cancelled\`. Swagger operation text only names \`fulfilled\` and \`cancelled\`. Do not invent \`changed\`.
 
 Body = \`V2FulfillmentOrder\` = \`GET /v2/fulfillment-orders/{fulfillmentOrderId}/\` (list items are the same object). Physical order from a paid billing run (\`billing_run_id\`; at most one order per run). \`delivery_address\` is a snapshot (later contract address edits do not change it). \`shipping_selection\` is the checkout snapshot. \`fulfillments[]\` are booked shipments (empty until booked / if no shipping providers). Status: \`open\` | \`partially_fulfilled\` | \`fulfilled\` | \`cancelled\`. External carrier with no Askell integration: shipment \`handler\` is \`""\` — read \`carrier\`.
 

package/src/server.ts

@@ -36,7 +36,7 @@ Workflow:
 3. Use askell_call (GET/HEAD) or askell_mutate (POST/PUT/PATCH/DELETE) when no dedicated tool covers the request.
 
 API models:
-- v1 (legacy): PlanVariant + Subscription at paths like /subscriptions/, /customers/. Still supported for existing integrations.
+- v1 (legacy): PlanVariant + Subscription at paths like /subscriptions/, /customers/. Customer, webhook, and one-off payment writes are not this guard. Legacy subscription writes can 400 with LegacySubscriptionGuardError — match \`code\`, not the message (askell_describe_operation omits response descriptions). \`legacy_subscriptions_disabled\`: contracts-only account, on POST /subscriptions/multi/ (customer is neither created nor updated), POST /customers/{ref}/subscriptions/add/ (that body also has \`status: error\`), and POST /checkouts/ with a plan (payment_processor checkout still works). \`subscription_managed_by_contract\`: that subscription's billing moved; PATCH/cancel/activate/set_expiry. Body has migrated_to_contract_id and v2_endpoint.
 - v2 (current): Catalog, bundles, quotes, checkouts, subscription contracts, billing runs, coupons/promotion codes, fulfillment orders under /v2/. Prefer v2 for new integrations.
 - Prose docs at https://docs.askell.is/api/ may describe flows (embedded checkout, 3D Secure, wallet passes) not fully listed in OpenAPI.
 
@@ -59,6 +59,18 @@ V2 checkout notes:
 - Hosted POST /v2/checkouts/: shipping {option, location_id?} is required when the offer has physical products and the account has active shipping options. No shipping-options list in OpenAPI (ids are account config). Pickup options need location_id. Snapshot is contract.shipping_selection (plus location / zone_name / weight_band), not on V2Checkout. Rate-table option with no zip/weight rate: 400, shipping_code shipping_not_available. Quote/checkout totals already include shipping_fee when present.
 - Hosted iframe (not askell.js): POST /v2/checkouts/ and POST .../payment-method-registrations/ take allowed_origin (one origin, no path; http only localhost/loopback). Replaces account-level frame-ancestors; GET empty string = account-level. Rejected on /v2/checkout-sessions/ (sales-channel allowed_origins[]).
 - Embedded checkout uses POST /v2/checkout-sessions/ plus browser session-token sub-paths (widget collects address/shipping; see docs, not all in OpenAPI).
+- Checkout/session metadata is copied onto the contract at finalize except Askell-owned keys (askell_source, billing_anchor_mode, activation_failure, email_markers, copied_legacy_pauses, copied_legacy_extra_data, migration_source, migration_cadence_mode, legacy_subscription_ids, seed). On a shared key the session value wins.
+
+V2 contract changes:
+- reference: external id, max 128, no commas. Create: blank means none. PATCH null/blank clears. GET /v2/subscription-contracts/?reference= is an exact filter.
+- PATCH body is only metadata, reference, payment_processor_override. The operation description also lists delivery_address, accounting_department, accounting_cost_center; V2SubscriptionContractPatch does not include them — do not send them.
+- PATCH metadata replaces the integration's keys. The Askell-owned keys above keep their current values; sending them does nothing.
+- items/update apply_at=now (default): effective_at must not be in the future (400 future_effective_at_not_supported). apply_at=period_end charges nothing now and stores scheduled_change (change_id null); do not send effective_at, settlement_behavior, or include_pending_adjustments with it. A pending scheduled change rejects further item updates with 409 scheduled_change_exists until POST .../scheduled-changes/{scheduledChangeId}/cancel/ (already canceled → replayed: true; applied/failed → 409 scheduled_change_not_cancelable). items/add and items/remove can also 409 (V2ProrationConflict); their operation text does not say so. Webhook families subscription_contract_scheduled_change.* and subscription_contract_item.* are not part of subscription_contract.*. Non-migrated contract events match GET: customer is an object, numeric id is customer_id. A scheduled cancellation sends subscription_contract.ended, not canceled, even though state becomes canceled.
+- An immediate billing-interval change with an amount due sets item.pending_interval_change status awaiting_payment (applies_on_payment). The item switches only when that billing run succeeds. Other item edits and change-anchor return 409 pending_interval_change until then. A failed payment abandons the interval change; retrying the run does not apply it.
+- POST .../change-anchor/ moves the next renewal of the contract and every active item. new_billing_anchor_at must be after effective_at and, with proration, at most one billing period later. Does not extend entitlements. Preview with proration-preview operation=change_anchor (new_billing_anchor_at required). Do not PATCH billing_anchor_at.
+
+V2 refunds:
+- A billing-run charge is not a Payment. payment.* for that charge is a flat object (Hook-API-Version v2, subscription_contract_id, billing_run_id, billing_run_attempt_id), not transactions[]; a payment.retry may have a null uuid and state retry_scheduled. Refund with POST /v2/billing-runs/{id}/refund/ (no body, full amount only, secret). 200 → state refunded, metadata.transaction_refund, webhook billing_run.changed (no separate refund event). 202 → run still succeeded (metadata.refund_requests); wait or re-GET; do not resend immediately. 400 if not succeeded, zero amount, already refunded, or the processor cannot refund. No response (timeout): GET the run and check state plus metadata.refund_requests before retrying. POST /payments/{uuid}/refund/ is one-off Payments only.
 
 V2 fulfillment (warehouse):
 - GET /v2/fulfillment-orders/ and GET /v2/fulfillment-orders/{id}/. Same body as fulfillment_order.* webhooks (V2FulfillmentOrder). Secret key. 403 if contracts/shipping off. Poll updated_since after a missed webhook (newest first).

package/src/tools/analysis.ts

@@ -218,7 +218,7 @@ export function registerAnalysisTools(
     {
       title: 'Subscription contract overview (v2)',
       description:
-        'Fetch a v2 subscription contract and recent billing runs filtered by contract id. The contract payload includes `discount` (active coupon) when one is applied, `shipping_selection` when shipping was chosen at checkout, and `subscriber_page` (customer-facing management URL, read-only). Result is an error when the contract fetch fails. `failures` lists every call that failed.',
+        'Fetch a v2 subscription contract and recent billing runs filtered by contract id. The contract payload includes `discount` (active coupon) when one is applied, `shipping_selection` when shipping was chosen at checkout, `subscriber_page` (customer-facing management URL, read-only), `reference`, `scheduled_changes`, and per-item `scheduled_change` / `pending_interval_change` (status `awaiting_payment` while an interval change waits for its charge). Result is an error when the contract fetch fails. `failures` lists every call that failed.',
       inputSchema: z.object({
         contractId: z
           .union([z.string().min(1), z.int()])