askell-mcp 0.4.5 → 0.4.7

package/README.md

@@ -127,7 +127,8 @@ Typical agent workflow:
 
 - **v1** — legacy paths like `/customers/`, `/subscriptions/` (no `/v2` prefix)
 - **v2** — current model: catalogs, quotes, checkouts, contracts, billing runs under `/v2/`
-- **v2 discounts** — coupons: `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. Totals already include both. Recurring `finalize` needs a verified payment method even when due-now is 0. Not the v1 `discount` 0–100 field.
+- **v2 discounts** — coupons: `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 fulfilment** — British spelling: `GET /v2/fulfilment-orders/` (read-only). Path param is order `id`, not `number`. List `403` if shipping is off. Quote/checkout `shipping_fee` is already in totals.
 - 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.5",
+  "version": "0.4.7",
   "description": "MCP server for the Askell payment and subscription API (Bun + stdio)",
   "author": "Neschadin Oleksandr",
   "license": "MIT",
@@ -67,6 +67,6 @@
   },
   "dependencies": {
     "@modelcontextprotocol/server": "2.0.0",
-    "zod": "4.6.1"
+    "zod": "4.6.5"
   }
 }

package/spec/openapi-v2.json

@@ -55,6 +55,10 @@
     {
       "name": "V2 Billing Runs",
       "description": "Subscription V2 billing-run read and retry APIs, requires secret api key."
+    },
+    {
+      "name": "V2 Fulfilment",
+      "description": "Subscription V2 fulfilment order read APIs for warehouse integrations, requires secret api key."
     }
   ],
   "paths": {
@@ -1672,6 +1676,119 @@
           }
         ]
       }
+    },
+    "/v2/fulfilment-orders/": {
+      "get": {
+        "tags": [
+          "V2 Fulfilment"
+        ],
+        "summary": "List fulfilment orders",
+        "description": "Returns the authenticated account's fulfilment orders, newest first, with the same body the `fulfilment_order.*` webhooks carry. Intended for backfill and for polling-based reconciliation after a missed webhook delivery. Read-only. Requires a secret key, that the account uses subscription contracts, and that shipping is enabled for the account.",
+        "parameters": [
+          {
+            "in": "query",
+            "name": "status",
+            "schema": {
+              "type": "string",
+              "enum": [
+                "open",
+                "partially_fulfilled",
+                "fulfilled",
+                "cancelled"
+              ]
+            },
+            "description": "Filter by fulfilment status."
+          },
+          {
+            "in": "query",
+            "name": "contract",
+            "schema": {
+              "type": "integer"
+            },
+            "description": "Filter by subscription contract id."
+          },
+          {
+            "in": "query",
+            "name": "customer",
+            "schema": {
+              "type": "integer"
+            },
+            "description": "Filter by customer id."
+          },
+          {
+            "in": "query",
+            "name": "customer_reference",
+            "schema": {
+              "type": "string"
+            },
+            "description": "Filter by customer reference."
+          },
+          {
+            "in": "query",
+            "name": "updated_since",
+            "schema": {
+              "type": "string",
+              "format": "date-time"
+            },
+            "description": "Only orders changed at or after this ISO 8601 timestamp. A bare date means the start of that day. This is the reconciliation filter: poll it with the `updated_at` of the last order you processed."
+          },
+          {
+            "in": "query",
+            "name": "created_since",
+            "schema": {
+              "type": "string",
+              "format": "date-time"
+            },
+            "description": "Only orders created at or after this ISO 8601 timestamp. A bare date means the start of that day."
+          },
+          {
+            "$ref": "#/components/parameters/PageSizeFilter"
+          }
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/V2FulfilmentOrderList"
+          },
+          "403": {
+            "$ref": "#/components/responses/V2PermissionDenied"
+          }
+        },
+        "security": [
+          {
+            "Secret-Api-Key": []
+          }
+        ]
+      }
+    },
+    "/v2/fulfilment-orders/{fulfilmentOrderId}/": {
+      "get": {
+        "tags": [
+          "V2 Fulfilment"
+        ],
+        "summary": "Get a fulfilment order",
+        "description": "Returns one fulfilment order belonging to the authenticated account, with its lines, delivery address, shipping selection and booked shipments. Orders belonging to another account return `404`. Read-only. Requires a secret key.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/V2FulfilmentOrderId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/V2FulfilmentOrder"
+          },
+          "403": {
+            "$ref": "#/components/responses/V2PermissionDenied"
+          },
+          "404": {
+            "$ref": "#/components/responses/V2NotFound"
+          }
+        },
+        "security": [
+          {
+            "Secret-Api-Key": []
+          }
+        ]
+      }
     }
   },
   "components": {
@@ -3088,6 +3205,10 @@
               "shipping": {
                 "$ref": "#/components/schemas/V2ShippingSelectionInput",
                 "description": "The shipping option the customer chose. Required when the offer contains physical products and the account has active shipping options."
+              },
+              "allowed_origin": {
+                "type": "string",
+                "description": "Origin allowed to embed the hosted card form for this checkout in an iframe, for example `https://shop.example`. A single http(s) origin with no path; http is accepted only for `localhost` and loopback addresses (`127.0.0.0/8`, `[::1]`). When set it replaces the account-level checkout origins in the hosted page's `frame-ancestors` policy. Not accepted on checkout-session endpoints, where the sales channel's allowed origins apply."
               }
             }
           }
@@ -3168,6 +3289,51 @@
           },
           "location_address": {
             "type": "string"
+          },
+          "location": {
+            "$ref": "#/components/schemas/V2PickupLocation"
+          }
+        }
+      },
+      "V2PickupLocation": {
+        "type": "object",
+        "nullable": true,
+        "description": "The chosen pickup location as a structured block an external fulfilment system can book against, or null when the selection has none (home delivery, freight, store pickup without an address). Derived from the shipping provider's own payload, with the flat `location_*` values as the fallback.",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "The provider's id for the location."
+          },
+          "name": {
+            "type": "string"
+          },
+          "address": {
+            "type": "string",
+            "description": "One-line address, composed from street, zip code and town when the provider does not supply one."
+          },
+          "street": {
+            "type": "string"
+          },
+          "zip_code": {
+            "type": "string"
+          },
+          "town": {
+            "type": "string"
+          },
+          "external_id": {
+            "type": "string",
+            "nullable": true,
+            "description": "The location's id in the provider's upstream system, when it exposes one."
+          },
+          "latitude": {
+            "type": "number",
+            "format": "double",
+            "nullable": true
+          },
+          "longitude": {
+            "type": "number",
+            "format": "double",
+            "nullable": true
           }
         }
       },
@@ -3638,6 +3804,10 @@
           },
           "metadata": {
             "$ref": "#/components/schemas/V2Metadata"
+          },
+          "allowed_origin": {
+            "type": "string",
+            "description": "Origin allowed to embed this hosted card form in an iframe, for example `https://shop.example`. A single http(s) origin with no path; http is accepted only for `localhost` and loopback addresses (`127.0.0.0/8`, `[::1]`). Defaults to the checkout's `allowed_origin`, and when set it replaces the account-level checkout origins in the hosted page's `frame-ancestors` policy. Not accepted on checkout-session endpoints, where the sales channel's allowed origins apply."
           }
         }
       },
@@ -3690,6 +3860,10 @@
           "metadata": {
             "$ref": "#/components/schemas/V2Metadata"
           },
+          "allowed_origin": {
+            "type": "string",
+            "description": "Origin allowed to embed this hosted card form, or an empty string when the account-level checkout origins apply."
+          },
           "error_message": {
             "type": "string"
           },
@@ -3753,6 +3927,25 @@
             "type": "string",
             "format": "decimal"
           },
+          "shipping_fee": {
+            "type": "object",
+            "nullable": true,
+            "description": "Sendingargjald sem er hluti af checkout-samtölunum, eða null.",
+            "properties": {
+              "amount": {
+                "type": "string"
+              },
+              "subtotal_amount": {
+                "type": "string"
+              },
+              "tax_amount": {
+                "type": "string"
+              },
+              "total_amount": {
+                "type": "string"
+              }
+            }
+          },
           "contract_id": {
             "type": "integer",
             "nullable": true
@@ -3767,6 +3960,10 @@
           "metadata": {
             "$ref": "#/components/schemas/V2Metadata"
           },
+          "allowed_origin": {
+            "type": "string",
+            "description": "Origin allowed to embed hosted pages for this checkout, or an empty string when the account-level checkout origins apply."
+          },
           "created_at": {
             "type": "string",
             "format": "date-time"
@@ -3916,6 +4113,25 @@
             "type": "string",
             "format": "decimal"
           },
+          "shipping_fee": {
+            "type": "object",
+            "nullable": true,
+            "description": "Sendingargjald sem er hluti af tilboðinu (samtölur innihalda það), eða null.",
+            "properties": {
+              "amount": {
+                "type": "string"
+              },
+              "subtotal_amount": {
+                "type": "string"
+              },
+              "tax_amount": {
+                "type": "string"
+              },
+              "total_amount": {
+                "type": "string"
+              }
+            }
+          },
           "first_period_recurring_subtotal_amount": {
             "type": "string",
             "format": "decimal"
@@ -3998,6 +4214,21 @@
               "original_total_amount": {
                 "type": "string",
                 "format": "decimal"
+              },
+              "recurring_original_amount": {
+                "type": "string",
+                "format": "decimal",
+                "description": "What a renewal bills without the coupon. The recurring_* totals of the quote do not include the promotion code discount."
+              },
+              "recurring_discount_amount": {
+                "type": "string",
+                "format": "decimal",
+                "description": "The coupon's discount applied to a renewal's recurring lines. Computed regardless of duration: a once coupon lapses after the first payment and a repeating coupon after duration_in_months, so only treat this as the renewal discount while the coupon is active."
+              },
+              "recurring_final_amount": {
+                "type": "string",
+                "format": "decimal",
+                "description": "What a renewal bills with the coupon's discount applied. Only meaningful while the coupon is still active (see duration and duration_in_months)."
               }
             }
           },
@@ -4551,6 +4782,211 @@
           }
         }
       },
+      "V2FulfilmentAddress": {
+        "type": "object",
+        "nullable": true,
+        "description": "The delivery address as it stood when the order was created. This is the order's own snapshot, so editing the contract's address afterwards does not change it.",
+        "properties": {
+          "id": {
+            "type": "integer"
+          },
+          "delivery_name": {
+            "type": "string",
+            "nullable": true
+          },
+          "address_1": {
+            "type": "string"
+          },
+          "address_2": {
+            "type": "string",
+            "nullable": true
+          },
+          "address_3": {
+            "type": "string",
+            "nullable": true
+          },
+          "zip_code": {
+            "type": "string"
+          },
+          "city": {
+            "type": "string",
+            "nullable": true
+          },
+          "state": {
+            "type": "string",
+            "nullable": true
+          },
+          "country": {
+            "type": "string",
+            "description": "ISO 3166-1 alpha-2 country code."
+          }
+        }
+      },
+      "V2FulfilmentOrderLine": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "integer"
+          },
+          "product_id": {
+            "type": "integer",
+            "nullable": true
+          },
+          "product_reference": {
+            "type": "string",
+            "nullable": true,
+            "description": "The seller's own product reference, i.e. the SKU a warehouse picks by. Null when the catalog product has been deleted."
+          },
+          "product_name": {
+            "type": "string",
+            "description": "Product name at the time the order was created."
+          },
+          "quantity": {
+            "type": "integer"
+          },
+          "quantity_fulfilled": {
+            "type": "integer",
+            "description": "How many units have been included in a shipment."
+          }
+        }
+      },
+      "V2Fulfilment": {
+        "type": "object",
+        "description": "A shipment booked for (part of) an order.",
+        "properties": {
+          "id": {
+            "type": "integer"
+          },
+          "order_id": {
+            "type": "integer"
+          },
+          "handler": {
+            "type": "string",
+            "enum": [
+              "dropp",
+              "posturinn",
+              "store_pickup"
+            ]
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "pending",
+              "booked",
+              "failed",
+              "shipped",
+              "delivered",
+              "cancelled"
+            ]
+          },
+          "provider_order_id": {
+            "type": "string",
+            "description": "The provider's own identifier for the shipment, such as a Dropp order UUID or a Pósturinn shipment id."
+          },
+          "tracking_number": {
+            "type": "string"
+          },
+          "weight_grams": {
+            "type": "integer",
+            "nullable": true,
+            "description": "Package weight used for the booking."
+          },
+          "error": {
+            "type": "string",
+            "description": "The last booking error, empty when the booking succeeded."
+          },
+          "booked_at": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "V2FulfilmentOrder": {
+        "type": "object",
+        "description": "A physical order generated by a paid billing run. This is also the body of the `fulfilment_order.*` webhooks.",
+        "properties": {
+          "id": {
+            "type": "integer"
+          },
+          "number": {
+            "type": "integer",
+            "description": "Per-account sequential order number."
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "open",
+              "partially_fulfilled",
+              "fulfilled",
+              "cancelled"
+            ]
+          },
+          "contract_id": {
+            "type": "integer"
+          },
+          "billing_run_id": {
+            "type": "integer",
+            "description": "The successful billing run that generated this order. Each run generates at most one order."
+          },
+          "customer_id": {
+            "type": "integer"
+          },
+          "customer_reference": {
+            "type": "string"
+          },
+          "customer_name": {
+            "type": "string"
+          },
+          "customer_email": {
+            "type": "string",
+            "nullable": true
+          },
+          "delivery_address": {
+            "$ref": "#/components/schemas/V2FulfilmentAddress"
+          },
+          "shipping_selection": {
+            "$ref": "#/components/schemas/V2ShippingSelection"
+          },
+          "lines": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/V2FulfilmentOrderLine"
+            }
+          },
+          "fulfilments": {
+            "type": "array",
+            "description": "Shipments booked for this order. Empty until one is booked, and always empty for an account with no shipping providers configured.",
+            "items": {
+              "$ref": "#/components/schemas/V2Fulfilment"
+            }
+          },
+          "estimated_weight_grams": {
+            "type": "integer",
+            "nullable": true,
+            "description": "Sum of the products' chargeable unit weights, or null when any line lacks weight data, so a partial estimate is never mistaken for a total."
+          },
+          "metadata": {
+            "$ref": "#/components/schemas/V2Metadata"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
       "V2SubscriptionContractCustomer": {
         "type": "object",
         "properties": {
@@ -5077,6 +5513,17 @@
           "type": "integer"
         }
       },
+      "V2FulfilmentOrderId": {
+        "name": "fulfilmentOrderId",
+        "in": "path",
+        "description": "Fulfilment order id. This is the order's `id`, not its per-account `number`.",
+        "required": true,
+        "style": "simple",
+        "explode": false,
+        "schema": {
+          "type": "integer"
+        }
+      },
       "V2CustomerReference": {
         "name": "customerReference",
         "in": "path",
@@ -5439,6 +5886,70 @@
           }
         }
       },
+      "V2PermissionDenied": {
+        "description": "The account may not use this endpoint, for example because it does not use subscription contracts or does not have shipping enabled",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "detail": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      },
+      "V2FulfilmentOrder": {
+        "description": "V2 fulfilment order",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/V2FulfilmentOrder"
+            }
+          }
+        }
+      },
+      "V2FulfilmentOrderList": {
+        "description": "V2 fulfilment order list",
+        "content": {
+          "application/json": {
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/V2FulfilmentOrder"
+                  }
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "count": {
+                      "type": "integer"
+                    },
+                    "next": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "previous": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "results": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/V2FulfilmentOrder"
+                      }
+                    }
+                  }
+                }
+              ]
+            }
+          }
+        }
+      },
       "V2BillingRun": {
         "description": "V2 billing run",
         "content": {

package/src/client/paths.ts

@@ -1,6 +1,29 @@
+/**
+ * Askell OpenAPI uses British "fulfilment"; agents (and Shopify/Stripe training)
+ * type American "fulfillment". Fold to the British form Askell actually serves.
+ */
+export function foldFulfilmentSpelling(text: string): string {
+  return text.replace(/fulfillment/gi, (match) => {
+    const first = match[0];
+    if (match === match.toUpperCase()) {
+      return 'FULFILMENT';
+    }
+    if (first !== undefined && first === first.toUpperCase()) {
+      return 'Fulfilment';
+    }
+    return 'fulfilment';
+  });
+}
+
+/** Lowercased text with American/British fulfilment spelling folded together. */
+export function canonicalSearchText(text: string): string {
+  return foldFulfilmentSpelling(text).toLowerCase();
+}
+
 /** Normalize Askell API paths: leading slash + trailing slash (OpenAPI convention). */
 export function normalizeApiPath(path: string): string {
-  let normalized = path.startsWith('/') ? path : `/${path}`;
+  let normalized = foldFulfilmentSpelling(path);
+  normalized = normalized.startsWith('/') ? normalized : `/${normalized}`;
 
   if (normalized !== '/' && !normalized.endsWith('/')) {
     normalized += '/';

package/src/openapi/registry.ts

@@ -1,6 +1,10 @@
 import v1Spec from '../../spec/openapi-v1.json';
 import v2Spec from '../../spec/openapi-v2.json';
 
+import {
+  canonicalSearchText,
+  foldFulfilmentSpelling,
+} from '../client/paths.ts';
 import type {
   ApiKeyKind,
   ApiOperation,
@@ -184,7 +188,10 @@ export class OperationRegistry {
   }
 
   getById(id: string): ApiOperation | undefined {
-    return this.operations.find((operation) => operation.id === id);
+    const folded = foldFulfilmentSpelling(id);
+    return this.operations.find(
+      (operation) => operation.id === id || operation.id === folded,
+    );
   }
 
   find(filters: {
@@ -206,7 +213,13 @@ export class OperationRegistry {
         return false;
       }
 
-      if (filters.tag && !operation.tags.includes(filters.tag)) {
+      const tagFilter = filters.tag;
+      if (
+        tagFilter &&
+        !operation.tags.some(
+          (tag) => canonicalSearchText(tag) === canonicalSearchText(tagFilter),
+        )
+      ) {
         return false;
       }
 
@@ -216,7 +229,9 @@ export class OperationRegistry {
 
       if (
         filters.pathPrefix &&
-        !operation.path.startsWith(filters.pathPrefix)
+        !canonicalSearchText(operation.path).startsWith(
+          canonicalSearchText(filters.pathPrefix),
+        )
       ) {
         return false;
       }
@@ -226,17 +241,18 @@ export class OperationRegistry {
       }
 
       if (search) {
-        const haystack = [
-          operation.id,
-          operation.path,
-          operation.summary,
-          operation.description ?? '',
-          operation.tags.join(' '),
-        ]
-          .join(' ')
-          .toLowerCase();
-
-        if (!haystack.includes(search)) {
+        const needle = canonicalSearchText(search);
+        const haystack = canonicalSearchText(
+          [
+            operation.id,
+            operation.path,
+            operation.summary,
+            operation.description ?? '',
+            operation.tags.join(' '),
+          ].join(' '),
+        );
+
+        if (!haystack.includes(needle)) {
           return false;
         }
       }

package/src/resources/register.ts

@@ -9,13 +9,15 @@ 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
+- Hook-API-Version: \`v1\` for plan/subscription/customer/payment/checkout, \`v2\` for subscription_contract / billing_run / fulfilment_order
 
-## Body shape (not in OpenAPI)
+## Body shape
 
 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. Inbound payloads are still undocumented in OpenAPI — this resource is the overlay.
+Upstream swagger used to document a dummy \`POST /your-webhook-url/\` with \`SubscriptionMultiLite\` (\`{ customer, subscriptions[] }\`). \`sync-specs\` strips that path.
+
+Most inbound payloads are still undocumented in OpenAPI — this resource is the overlay. Exception: \`fulfilment_order.*\` is \`V2FulfilmentOrder\` (same body as \`GET /v2/fulfilment-orders/\` / \`GET /v2/fulfilment-orders/{id}/\`). Live webhook docs omit this family; bundled spec is right. Spelling is British \`fulfilment_order.*\`, not American \`fulfillment_order.*\`. Specific verbs beyond the wildcard are not listed — do not invent \`created\`/\`shipped\`/….
 
 Rare historical payloads used \`{ event, data, ref?, sender? }\`. If both \`event\` and \`data\` are objects, use \`data\`.
 
@@ -59,6 +61,11 @@ V2 migration: \`subscription.*\` is **not** aliased onto the new contract (paylo
 
 ### checkout.* (v1)
 \`created\`, \`changed\` — \`token\`, \`checkout_url\`, \`status\`.
+
+### fulfilment_order.* (v2)
+Family wildcard only in OpenAPI (\`fulfilment_order.*\`). Not American \`fulfillment_order.*\`. Live docs omit this family.
+
+Body is \`V2FulfilmentOrder\`: \`id\` (path param; not per-account \`number\`), \`number\`, \`status\` (\`open\` | \`partially_fulfilled\` | \`fulfilled\` | \`cancelled\`), \`contract_id\`, \`billing_run_id\` (successful run that generated the order; at most one order per run), \`customer_id\`, \`customer_reference\`, \`customer_name\`, \`customer_email\`, \`delivery_address\` (snapshot; later contract address edits do not change it), \`shipping_selection\` (includes structured \`location\` plus flat \`location_*\` fallback), \`lines[]\` (\`product_id\`, \`product_reference\` SKU, \`product_name\`, \`quantity\`, \`quantity_fulfilled\`), \`fulfilments[]\` (booked shipments; empty until booked / if no shipping provider), \`estimated_weight_grams\` (null if any line lacks weight — never a partial total), \`metadata\`, \`created_at\`, \`updated_at\`.
 `;
 
 export function registerResources(server: McpServer): void {

package/src/server.ts

@@ -47,15 +47,23 @@ API layout:
 - V2 list endpoints paginate only when page_size is provided (default 10, max 1000).
 - GET /v2/customer-entitlements/ requires customer_reference query param.
 
+V2 fulfilment (British spelling on the wire — not American fulfillment):
+- Read-only GET /v2/fulfilment-orders/ and GET /v2/fulfilment-orders/{fulfilmentOrderId}/. No POST/PATCH in OpenAPI. Path param is the order's id, not per-account number.
+- List 403 = account does not use V2 contracts or shipping is disabled (not a bad API key). GET 404 = missing or other-account.
+- Reconciliation: poll list with updated_since = updated_at of the last order you processed. Filter by contract, customer, customer_reference, status.
+- Webhook family fulfilment_order.* (not fulfillment_order.*). Body is V2FulfilmentOrder, same as GET. Live webhook docs omit this family; bundled spec is right. Do not invent event verbs beyond the wildcard until Askell lists them.
+- Quote and checkout shipping_fee is already in totals; do not add it again (askell_describe_operation omits response schemas). shipping_selection.location is the structured pickup block; flat location_* are fallback.
+
 V2 discounts — two systems, not v1 Subscription.discount (0-100 on a PlanVariant; never send that to v2):
 - Coupons: one active per contract. GET /v2/subscription-contracts/{id}/discount/ (also nested as contract.discount). Apply with POST .../apply-code/ {promotion_code}. Remove with POST .../remove-discount/.
-- Quotes (POST /v2/subscription-offer-quotes/): pass promotion_code for coupons. When quoting an existing customer, pass customer (numeric id) or combo discounts from their other active contracts and promo-code customer restrictions are skipped. Quoted totals already include coupon + combo; do not subtract again. combo_discounts[] is on the quote response (askell_describe_operation omits response schemas). Combo is automatic, not apply-code.
+- Quotes (POST /v2/subscription-offer-quotes/): pass promotion_code for coupons. When quoting an existing customer, pass customer (numeric id) or combo discounts from their other active contracts and promo-code customer restrictions are skipped. First-period subtotal/tax/total already include coupon + combo. quote.recurring_* include combo, not the coupon — renewal-with-coupon is discount.recurring_final_amount, and only while duration still applies (once → after first payment use recurring_*). combo_discounts[] and discount.recurring_* are on the quote response (askell_describe_operation omits response schemas). Combo is automatic, not apply-code.
 
 V2 checkout notes:
 - checkout_url on V2 checkouts points to the API object URL, not a hosted payment page.
 - GET contract.subscriber_page is the customer-facing subscription management URL (readOnly, nullable). Not checkout_url, not v1 /public/payments/{id}/ (hosted signup). Do not send it on create/patch.
 - finalize: a recurring offer needs a verified payment method even when due-now/total is 0 (trial or fully discounted first period). Only a free one-time purchase finalizes without one. Live docs still say "unless 0 ISK" — ignore that; bundled OpenAPI is right.
 - 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, not on V2Checkout.
+- 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).
 
 Auth:
@@ -70,7 +78,7 @@ Safety:
 
 Resources:
 - askell://spec/v1 and askell://spec/v2 — bundled OpenAPI
-- askell://docs/webhook-events — inbound webhook payloads (not in OpenAPI; dummy /your-webhook-url/ is stripped on sync), HMAC-SHA512, /webhooks/ hmac_secret`;
+- askell://docs/webhook-events — inbound webhook payloads (most not in OpenAPI; fulfilment_order.* is V2FulfilmentOrder), HMAC-SHA512, /webhooks/ hmac_secret`;
 }
 
 export function createServer(config: AppConfig): McpServer {

package/src/tools/analysis.ts

@@ -141,7 +141,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).',
+        '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). Physical shipping: GET /v2/fulfilment-orders/?contract= (read-only; 403 if shipping is disabled — do not treat as a bad API key).',
       inputSchema: z.object({
         contractId: z
           .union([z.string().min(1), z.int()])

package/src/tools/discovery.ts

@@ -21,7 +21,7 @@ const listInputSchema = z.object({
     .string()
     .optional()
     .describe(
-      'Case-insensitive search in id, path, summary, description, tags',
+      'Case-insensitive search in id, path, summary, description, tags. American "fulfillment" matches British "fulfilment" (Askell paths use the latter).',
     ),
   apiKeyKind: z
     .enum(['secret', 'public'])