Cancel a warranty

A warranty can be cancelled in four ways, and which one applies determines what happens to any open claims. None of them move money on their own: for plans sold through your store, the customer's refund runs through your platform's own refund flow, not Mulberry — see How refunds work — and there is no webhook that tells you a refund completed.

🚧

Cancellations propagate automatically. Returns don't.

On a platform integration (Shopify, BigCommerce, Magento, WooCommerce), cancelling the underlying order cancels its warranties for you — no call to make. A return is different: unless it's recorded as a refund of the item's line items, nothing reaches Mulberry and the warranty stays active. Returns are the main reason you'll ever cancel a warranty by hand — from the order in your partner dashboard, below.

This page covers the four cancellation paths and what each one does. For where the customer's money comes back from, see How refunds work.

The four paths

Automatic: cancelling the order

This is the default on a platform integration. When an order is cancelled in your store, the Mulberry extension or app sends Mulberry a cancellation notice and the warranties on that order are cancelled for you.

1. The order is cancelled in your commerce platform.

2. The platform integration notifies Mulberry at POST /api/order_cancelled (retailer-authenticated; the app sends this — you don't write it).

3. Mulberry finds each WarrantyIssued for the cancelled line items and sets its status to Cancelled. When every warranty on the order is cancelled, the order itself is marked cancelled.

   The customer's refund flows back through your platform's own refund path — plans sold through your store are refunded by you, not by Mulberry. (The exception is plans Mulberry billed directly, such as post-purchase sales; Mulberry refunds those itself.)

   The customer receives a cancellation email. The warranty's lifecycle status becomes Cancelled — the value you'll see in warranty.status on a subsequent CLAIM_UPDATE.

🚧

A return doesn't cancel the warranty

Only two storefront events reach Mulberry: an order cancellation (cancels every warranty on the order) and a refund that includes the item's line items (cancels the warranties covering those products). A return recorded any other way — an exchange, a custom-amount refund, a return processed outside your platform's refund flow — never notifies Mulberry, and the warranty stays active. After a return like that, cancel the warranty from your partner dashboard.

🚧

Order-cancel does not auto-close open claims

The POST /api/order_cancelled path cancels the warranty, but it leaves any open WarrantyClaim records untouched — it does not close them or send a CLAIM_UPDATE. Open-claim auto-close (status CLOSED, reason CLOSED_CANCELLED_BY_CUSTOMER) happens only on the retailer transaction-cancel path below. If you rely on a CLOSED CLAIM_UPDATE to reconcile, expect it from a transaction cancellation, not from a plain order cancellation.

📘

There's no refund webhook

Mulberry does not send a partner webhook about refunds — for plans sold through your store, the refund is yours to issue anyway. The only customer-facing signal is the cancellation email Mulberry sends. Don't wait on a callback — treat the cancellation itself as the event.

Dashboard: cancel from the order page

When a warranty needs cancelling by hand — most often after a return that didn't propagate — your team can do it directly:

1. Sign in to the partner dashboard and open the order.
2. Click Cancel order. All partner dashboard roles can cancel, though some accounts limit which actions appear.
3. You should now see the order's warranties as Cancelled, and the customer receives the cancellation email.

If you don't see the action, or you only want to cancel one warranty on a multi-warranty order and aren't sure how, your Partner Success contact can cancel on your behalf.

Retailer API: cancel a transaction

If you're on the transaction-level partner API (Link/Stripe-style plans registered as transactions), you cancel a warranty by updating its transaction to Cancelled. This is not the standard Shopify/retailer warranty path — it applies only to orders registered through the external transactions API.

Prerequisites

1. The plan was registered as a transaction through the external partner API (order_source is PARTNER_TRANSACTION).
2. You have a partner OAuth bearer token. Get one from POST /external/oauth/authorize with your client_id and client_secret; it carries your partner_uuid and expires in 4 hours. See Get your credentials.
3. You know the transaction_order_id — the order id you supplied when you created the transaction.

The endpoint

PATCH /external/{partner}/transactions/{transaction_order_id}
Content-Type: application/json
Authorization: Bearer <partner-oauth-token>

The transaction is identified by the transaction_order_id in the URL path — not by a body field. Omitting it returns 400 with "Missing transaction_order_id.". The {partner} segment must match the partner your token was issued for, or the request is rejected with 401.

Request body

{ "status": "Cancelled" }

🚧

The status value is "Cancelled", capital-C

The update accepts the order-status string "Cancelled". It will not accept CANCELLED, cancelled, or canceled. (Unlike transaction creation, which restricts the initial status to Active/Pending, the update accepts any order status — including Cancelled.)

What it does

On success you get HTTP 200 with:

{ "id": 1029384, "customer": { "id": "<customer-uuid>" } }

Behind that response Mulberry:

• Cancels every WarrantyIssued on the transaction, then marks the order cancelled. No Mulberry refund is issued — the customer's refund, if any, is yours to handle, and the cancelled plans are reconciled on your billing.

• Closes any open claim on those warranties — every claim not already CLOSED, RESOLVED, DENIED, INCOMPLETE, or ABANDONED is moved to status CLOSED with reason CLOSED_CANCELLED_BY_CUSTOMER. Each close emits a CLAIM_UPDATE.

  If the order was already cancelled, the call is a no-op and returns the same response.

📘

Handle the auto-close CLAIM_UPDATE

Because a transaction cancellation closes open claims, you'll receive a CLAIM_UPDATE with status CLOSED and reason CLOSED_CANCELLED_BY_CUSTOMER for each one. Treat a system-triggered CLOSED exactly like a human-triggered one. The payload shape, signing, and headers are in Webhook catalog; reacting to statuses is covered in React to claim updates.

Customer: through Mulberry

Customers cancel through Mulberry, not through you: they contact Mulberry customer support, or your Partner Success contact cancels on their behalf. (Mulberry Unlimited subscribers are the exception — they can cancel their subscription directly from their Mulberry account.) There is no partner-facing endpoint for this — it runs through Mulberry's own tools, driving the same internal cancellation logic as the paths above (including the cancellation email; for Mulberry-billed plans, Mulberry also issues the refund).

• A cancellation is only accepted from the warranty's owner.
• A post-sale warranty normally needs an associated payment on file to be cancelled; Partner Success can force a cancellation (skipping the Stripe refund) when that's missing. This is an internal override, not something you call.

If a customer asks you to cancel a plan, you can do it yourself from the order in your partner dashboard — or route the request to Partner Success.

What the refund will be

For plans sold through your store, the refund is whatever your store refunds — in practice the full plan price, issued through your platform's normal refund flow. Mulberry doesn't compute or issue it. Plans Mulberry billed directly (post-purchase and direct sales) are refunded by Mulberry under the plan's own terms. See How refunds work.

Related

• How refunds work — where the customer's money comes back from
• Webhook catalog — the CLAIM_UPDATE payload an auto-close emits, plus signing and headers
• React to claim updates — handling the CLOSED / CLOSED_CANCELLED_BY_CUSTOMER event
• Get your credentials — the partner OAuth token for the transaction API
• How claims work — the claim lifecycle a cancellation can close