---
title: "Migrate from Gumroad"
description: "Move software you sell on Gumroad to Sherpo, with its license keys, buyers and members, and switch your app's license check without breaking a key."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.sherpo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate from Gumroad

This guide moves a Gumroad product with license keys to a [software](/overview/categories#software) product on Sherpo: the products and their variants, the buyers and their access, the keys they hold, the license check your app makes, and the webhooks your server listens to. Every key your customers hold keeps working, and Sherpo takes no share of your sales ([Payments and payouts](/overview/payments)). It uses the `sherpo` helper from [your first call](/merchant-api/first-call).

## What maps to what

| On Gumroad | On Sherpo |
| --- | --- |
| A product with license keys | A product in the `software` category, which issues one [license](/overview/licenses) per customer |
| A version or variant | A [tier](/overview/concepts#tiers-and-prices), which can list the features it unlocks and the devices its licenses activate |
| A membership | A recurring price on a tier, which customers subscribe to |
| A sale | An order, which gives the customer access to the product |
| A license key | A license, its status following the customer's access |
| Enable, disable and decrement uses | <a href="/merchant-api/reference/enable-license/">Enable</a>, <a href="/merchant-api/reference/disable-license/">disable</a> and <a href="/merchant-api/reference/update-license/">update</a> a license |
| The license verify call | <a href="/merchant-api/reference/verify-license/">`POST /products/{product}/licenses/verify`</a>, from your server |
| Ping and resource subscriptions | [Webhooks](/merchant-api/webhooks) |

What Gumroad has no counterpart for comes with it: devices counted per license and freed by your customers, features per tier, a key your customers rotate themselves, and the latest release of your software in every check.

## Tokens and a test run

Create an API token in the merchant app ([Authentication](/merchant-api/authentication)). The migration needs `product:write` and `price:write` to recreate products, `file:read` and `file:write` to upload their downloads and list them before uploading again, `product:read` to read the products back, `customer:read` and `customer:write` to import keys and give access, and `transaction:write` if you record past sales. The server that checks keys afterwards needs only `customer:read`, plus `customer:write` if it activates devices: give it a token of its own, a [business token](/merchant-api/authentication#business-tokens) so it keeps working when people leave, holding just those scopes.

There is no separate test mode, so rehearse on one product first. Run every step below on it while it's a draft nobody can buy, with buyers' addresses you own, since every address you import becomes a customer of your store and counts toward your [plan's](/overview/plans) customers. Check a handful of imported keys from your server, then repeat for the rest.

A script that stops halfway runs again from the start with the same [idempotency keys](/merchant-api/idempotency), within 24 hours of the first run: each write already done answers what it answered the first time, and does nothing again. A bulk call answers that way too, refused items included, so retry a refused item on its own, under a fresh key. Not every write takes one: uploads don't, so list a product's files before uploading again, and past orders take their own `source_key`. Past that window, or under fresh keys, a key recorded already answers `409` [`conflict`](/merchant-api/errors#conflict) on `key`, and a grant given already `409` on `tier`.

## Recreate products and tiers

Create each product in the `software` category, with its tiers and prices, as [Products and prices](/merchant-api/guides/products-and-prices) does. A product's tiers are cumulative: a higher tier holds everything a lower one does. So versions that rank, like Standard and Pro, become tiers of one product, and a membership's tiers become tiers with recurring prices. Versions that exclude each other, like a Windows and a macOS build sold apart, become one tier holding both downloads, or separate products when each must be bought on its own. Give each tier the features your software unlocks for it, and how many devices its licenses activate at once:

```bash
curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/tiers' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Idempotency-Key: tier-app-pro' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Pro",
  "settings": {
    "software": {
      "features": [
        "export",
        "sync"
      ],
      "activation_limit": 3
    }
  }
}'
```

```js
const answer = await sherpo('POST', '/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/tiers', {
  body: {
    "name": "Pro",
    "settings": {
      "software": {
        "features": [
          "export",
          "sync"
        ],
        "activation_limit": 3
      }
    }
  },
  key: 'tier-app-pro',
});
```

Answers `201`, abridged:

```json
{
  "id": "e1d2c3b4-a596-4877-8695-a4b3c2d1e0f9",
  "product_id": "3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7",
  "rank": 2,
  "name": "Pro",
  "settings": {
    "software": {
      "features": [
        "export",
        "sync"
      ],
      "activation_limit": 3
    }
  }
}
```

Upload the files buyers download ([Upload a file](/merchant-api/guides/upload-a-file)), limited to a tier where a version had files of its own. The product's `settings.software.key_prefix` starts every key Sherpo issues from now on; the keys you import keep their Gumroad form.

## Import keys and access

Export your sales from Gumroad: for each sale, the buyer's email, the product, its variant, the license key, its uses, and whether it was refunded, disputed or its membership ended. Then, for each one, record the key first and give access second, in that order, so the access keeps the key you recorded instead of issuing a new one. Every recorded key sends a `license.issued` [webhook](#webhooks) to an endpoint that takes it.

1. **Record the key** with <a href="/merchant-api/reference/record-license/">`POST /products/{product}/licenses`</a>, naming the buyer by email: a buyer who isn't a customer yet becomes one, invited, and finds the product and their key in their library when they first sign in with that address. It carries over the uses, and keeps the Gumroad sale's id in `metadata` so support can find it:

   ```bash
   curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/licenses' \
     -H "Authorization: Bearer $SHERPO_TOKEN" \
     -H 'Idempotency-Key: gumroad-import-B4C5D6E7' \
     -H 'Content-Type: application/json' \
     -d '{
     "customer": {
       "email": "ada@example.com"
     },
     "key": "B4C5D6E7-12345678-9ABCDEF0-0F0F0F0F",
     "uses": 14,
     "metadata": {
       "gumroad_sale_id": "A1b2C3d4=="
     }
   }'
   ```

   ```js
   const answer = await sherpo('POST', '/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/licenses', {
     body: {
       "customer": {
         "email": "ada@example.com"
       },
       "key": "B4C5D6E7-12345678-9ABCDEF0-0F0F0F0F",
       "uses": 14,
       "metadata": {
         "gumroad_sale_id": "A1b2C3d4=="
       }
     },
     key: 'gumroad-import-B4C5D6E7',
   });
   ```

   Answers `201`, abridged:

   ```json
   {
     "id": "8c7b6a59-4837-4261-9f0e-1d2c3b4a5968",
     "source": "imported",
     "key_ending": "F0F0F",
     "status": "expired",
     "has_access": false,
     "uses": 14
   }
   ```

   A whole catalog goes in [bulk](/merchant-api/bulk). The call answers `200` whatever its items do, so read each item's `outcome`: `done`, or refused with its error. A key refunded or lost to a dispute at Gumroad goes in with `disabled: true`, so it never checks as valid and support can still find it:

   ```bash
   curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/bulk' \
     -H "Authorization: Bearer $SHERPO_TOKEN" \
     -H 'Idempotency-Key: gumroad-import-page-1' \
     -H 'Content-Type: application/json' \
     -d '{
     "accessor": "recordLicense",
     "items": [
       {
         "customer": {
           "email": "ada@example.com"
         },
         "product": {
           "id": "3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7"
         },
         "key": "B4C5D6E7-12345678-9ABCDEF0-0F0F0F0F"
       },
       {
         "customer": {
           "email": "grace@example.com"
         },
         "product": {
           "id": "3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7"
         },
         "key": "1A2B3C4D-56789ABC-DEF01234-56789ABC",
         "disabled": true,
         "disabled_reason": "Refunded at Gumroad"
       }
     ]
   }'
   ```

   ```js
   const answer = await sherpo('POST', '/v1/stores/STORE_ID/bulk', {
     body: {
       "accessor": "recordLicense",
       "items": [
         {
           "customer": {
             "email": "ada@example.com"
           },
           "product": {
             "id": "3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7"
           },
           "key": "B4C5D6E7-12345678-9ABCDEF0-0F0F0F0F"
         },
         {
           "customer": {
             "email": "grace@example.com"
           },
           "product": {
             "id": "3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7"
           },
           "key": "1A2B3C4D-56789ABC-DEF01234-56789ABC",
           "disabled": true,
           "disabled_reason": "Refunded at Gumroad"
         }
       ]
     },
     key: 'gumroad-import-page-1',
   });
   ```

   Answers `200`, abridged:

   ```json
   {
     "results": [
       {
         "outcome": "done"
       },
       {
         "outcome": "done"
       }
     ]
   }
   ```

2. **Give access** with <a href="/merchant-api/reference/grant-access/">`POST /grants`</a>, one for each sale that still pays ([Customers' access](/merchant-api/guides/customer-access)): the tier of the variant they bought, with no end for a one-time purchase and a membership's as [below](#memberships), never one refunded or lost to a dispute, whose buyer would otherwise download the software with a disabled key. Name the sale in the grant's `reason` and in its idempotency key, and keep the grant's `id` with the sale. A grant that fails after its key was recorded leaves a paying buyer locked out, so retry it until it lands.

Until it's granted, a recorded key reads as `expired`. A buyer is imported once their key is recorded, or answered `409` on `key` from an earlier run, and each sale that still pays is granted or answered `409` on `tier`: the customer already holds that tier or a higher one for at least as long, through the grant `context.current` names. When that grant is one of your Gumroad grants, the sale owes nothing more. When it's another, such as a Sherpo purchase or subscription, keep the sale as owed and grant it again once that grant ends: [`grant.revoked`](/merchant-api/webhooks#grant.revoked) and [`order.refunded`](/merchant-api/webhooks#order.refunded) tell you when one ends early. One that lapses on its own date covered the sale to its end, so nothing is owed then, and neither is a membership sale whose paid period ended by the time you grant it. A buyer whose sales were all refunded, or whose membership already ended, is owed no grant. Any other refusal, a `409` on `customer` included, is a key still to handle. Confirm what each buyer holds with <a href="/merchant-api/reference/list-entitlements/">`GET /entitlements`</a> rather than an answer a rerun replayed. [Manage licenses](/merchant-api/guides/manage-licenses#import-existing-keys) covers the rest of what an import answers.

To keep each Gumroad sale in your order history too, record it with <a href="/merchant-api/reference/record-order/">`POST /orders`</a> ([Recording orders from elsewhere](/merchant-api/guides/sync-orders#recording-orders-from-elsewhere)), with `grants: false`: left on, it gives the product for good from the sale's date, beside the access you granted, so a member's access would never end.

A customer holds one license per product. A buyer who bought the product more than once on Gumroad, and so holds several keys, gets the one they use recorded: a second key for the same customer answers `409` on `customer`. To move them to another of their keys later, record it with `replace: true`, which stops the one before, and with `disabled: false` when the one before was disabled, since the new key takes its disabled state otherwise. Their other keys work only through Gumroad: tell those buyers which key to keep, since the others stop once your server no longer asks Gumroad. A Gumroad license with several seats becomes one license whose `activation_limit` you set with <a href="/merchant-api/reference/update-license/">`PATCH /products/{product}/licenses/{license}`</a>.

Access you give sends the customer no email. Tell your buyers yourself that their software moved, where to sign in, and that their key stays the same.

Gumroad keeps the sales you imported, and new ones, refunds and disputes can land there until you stop selling and the last refund window closes. Keep its sale, refund and dispute notifications on until then, and mirror each on Sherpo:

- **A sale**, a membership's renewal or an upgrade, by a buyer you imported: grant it as above, under that sale's or charge's own idempotency key. When their key was imported disabled for an earlier refund or lost dispute, [enable](/merchant-api/guides/manage-licenses#disable-and-enable) it too, since a grant never lifts a disable.
- **A full refund or a lost dispute**: [revoke](/merchant-api/guides/customer-access#take-it-back) that sale's own grant, if it has one and it's still live (<a href="/merchant-api/reference/list-grants/">`GET /grants`</a> with `filter[live]=true` and `filter[customer_id]` lists the live ones). Then grant each of the buyer's other sales that still pays again, under fresh idempotency keys, since a key used before would answer what it answered then: one the refunded grant covered gets its own grant now, and one still granted answers `409` on `tier`. Retry each that failed on a limit, the connection or the API's side until it lands; one whose `ends_at` has passed is owed nothing. The license follows, and stays active while the customer holds the product another way, such as a subscription on Sherpo.
- **A partial refund, or a dispute still open or won**: nothing.

Importing a key again only answers that it's there.

## Memberships

Gumroad keeps billing a membership on the card it holds, which can't move. So each member keeps what they paid for, then subscribes on Sherpo:

1. Record their key, then grant their tier until a day past the end of the period they paid on Gumroad, with `ends_at`, so a renewal Gumroad charges late never locks a member who paid:

   ```bash
   curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/grants' \
     -H "Authorization: Bearer $SHERPO_TOKEN" \
     -H 'Idempotency-Key: gumroad-grant-C9d8E7f6' \
     -H 'Content-Type: application/json' \
     -d '{
     "customer": {
       "email": "ada@example.com"
     },
     "product": {
       "id": "3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7"
     },
     "tier": {
       "id": "e1d2c3b4-a596-4877-8695-a4b3c2d1e0f9"
     },
     "ends_at": "2026-12-03T09:14:00Z",
     "reason": "Gumroad sale C9d8E7f6, paid through and a day"
   }'
   ```

   ```js
   const answer = await sherpo('POST', '/v1/stores/STORE_ID/grants', {
     body: {
       "customer": {
         "email": "ada@example.com"
       },
       "product": {
         "id": "3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7"
       },
       "tier": {
         "id": "e1d2c3b4-a596-4877-8695-a4b3c2d1e0f9"
       },
       "ends_at": "2026-12-03T09:14:00Z",
       "reason": "Gumroad sale C9d8E7f6, paid through and a day"
     },
     key: 'gumroad-grant-C9d8E7f6',
   });
   ```

   Answers `200`, abridged:

   ```json
   {
     "id": "4b3a2918-0f7e-4d6c-9b5a-4c3b2a190807",
     "customer": {
       "id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918",
       "name": "Ada Lovelace",
       "email": "ada@example.com",
       "phone": null,
       "erased": false
     },
     "product": {
       "id": "3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7",
       "slug": "focus-timer",
       "path": "/p/focus-timer",
       "url": "https://shop.example.com/p/focus-timer",
       "title": "Focus timer",
       "category": "software",
       "deleted": false
     },
     "tier": {
       "id": "e1d2c3b4-a596-4877-8695-a4b3c2d1e0f9",
       "name": "Pro"
     },
     "source_kind": "manual",
     "grant_reason": "Gumroad sale C9d8E7f6, paid through and a day",
     "ends_at": "2026-12-03T09:14:00.000Z",
     "end_reason": "lapse",
     "status": "active",
     "revocable": true
   }
   ```

2. Until you cancel their membership on Gumroad, each renewal it charges extends what they paid for: grant that charge until a day past its new date, as [above](#import-keys-and-access), from Gumroad's sale notification for it. Once their app calls your server, cancel the membership on Gumroad, so it never charges them again, and tell them where to subscribe on your store. Their last grant already runs to a day past the date their last charge paid through.

3. They subscribe on your store whenever they like, while their grant still runs, from the product's page, which offers them the plan under what they unlocked: checkout charges nothing and saves their card, and the subscription's first charge falls a day before the grant's `ends_at`, as every renewal is charged a day ahead, so access never lapses. Checkout, the `subscription.created` email and their subscription in their account show that date. Their grant stays as it is, and the license stays `active` with the key they already hold: nothing to type again in your app.

4. A member who never subscribes reads `expired` at `ends_at`, with the reason `lapse`, and your software locks as it would for a lapsed membership. Subscribing later makes the same license `active` again.

While the grant runs, the subscription waits on it: revoke the grant ([Take it back](/merchant-api/guides/customer-access#take-it-back)) and the first charge falls at once, grant the tier for longer and it falls a day before the new end. The first charge is the plan's renewal, at its amount less the price's `renewal_discount`; a coupon never reaches it. A grant with no end, or a tier the customer already holds through a subscription, offers no such subscription, so give a member a grant that ends, and grant nothing more for good while their subscription waits.

A member whose Gumroad membership already ended gets their key recorded and no grant, so it reads `expired` until they subscribe.

## Switch the license check

Gumroad's verify call takes no token, so apps often call it themselves. Sherpo's check takes a token that must never ship in your app ([Where the check runs](/merchant-api/guides/verify-licenses#where-the-check-runs)), so the app calls your server, and your server calls Sherpo.

Gumroad's call and its answer, as your app sends it today:

```sh
curl https://api.gumroad.com/v2/licenses/verify \
  -d product_id=GUMROAD_PRODUCT_ID \
  -d license_key=B4C5D6E7-12345678-9ABCDEF0-0F0F0F0F
```

```json
{
  "success": true,
  "uses": 15,
  "purchase": {
    "product_id": "GUMROAD_PRODUCT_ID",
    "email": "ada@example.com",
    "license_key": "B4C5D6E7-12345678-9ABCDEF0-0F0F0F0F",
    "variants": "(Pro)",
    "refunded": false,
    "disputed": false,
    "chargebacked": false,
    "subscription_id": null,
    "subscription_ended_at": null,
    "subscription_cancelled_at": null,
    "subscription_failed_at": null
  }
}
```

The same key checked on Sherpo, from your server, once imported and granted for good:

```bash
curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/licenses/verify' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "B4C5D6E7-12345678-9ABCDEF0-0F0F0F0F",
  "count_use": true
}'
```

```js
const answer = await sherpo('POST', '/v1/stores/STORE_ID/products/3e9d1f6b-72a4-4c58-b0e3-9a6f2d84c1b7/licenses/verify', {
  body: {
    "key": "B4C5D6E7-12345678-9ABCDEF0-0F0F0F0F",
    "count_use": true
  },
});
```

Answers `200`, abridged:

```json
{
  "id": "8c7b6a59-4837-4261-9f0e-1d2c3b4a5968",
  "status": "active",
  "reason": null,
  "expires_at": null,
  "tier": {
    "id": "e1d2c3b4-a596-4877-8695-a4b3c2d1e0f9",
    "name": "Pro",
    "rank": 2
  },
  "features": [
    "export",
    "sync"
  ],
  "uses": 15,
  "activations": {
    "count": 0,
    "limit": 3
  },
  "activation": null,
  "customer": {
    "id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918"
  },
  "subscription": null,
  "latest_release": {
    "id": "0e9d8c7b-6a5f-4e3d-9c2b-1a0f9e8d7c6b",
    "version": "2.4.0",
    "occurred_at": "2026-10-28T16:30:00.000Z"
  }
}
```

| Gumroad | Sherpo |
| --- | --- |
| `product_id` or `product_permalink` | The product in the path, by id or slug |
| `license_key` | `key`, matched in any case and spacing for a Gumroad key |
| `increment_uses_count`, `true` unless sent | `count_use`, `false` unless sent |
| `success` | `status` is `active` |
| `uses` | `uses` |
| `purchase.variants`, the variant in parentheses | `tier`, and the `features` it unlocks |
| `purchase.refunded`, `disputed`, `chargebacked` | `status` is `revoked`, with the reason `refund` (a lost dispute too) or `revoke` |
| `purchase.subscription_ended_at` | `subscription.ended_at`, and `status` is `expired` with the reason `lapse` |
| `purchase.subscription_cancelled_at` | `subscription.cancel_at_period_end`, ending at `subscription.current_period_end` |
| `purchase.subscription_failed_at` | `subscription.status` |
| `purchase.email` | `customer.id`; the check never answers who holds a key beyond that |
| `purchase.license_key` | Never answered: your server already holds the key it sent |
| A key that doesn't exist: `404`, `success: false` | `404` [`not_found`](/merchant-api/errors#not_found), for a key of another product too |

Gumroad answers `success: true` for a refunded key, and leaves it to your app to check `refunded`. Sherpo's `status` already says it: unlock only while it's `active`.

### Count uses explicitly

Gumroad counts every check as a use unless you send `increment_uses_count=false`. Sherpo counts one only when you send `count_use: true`, so checking a key at every start doesn't inflate its count. Send it where a check is a use you want counted, such as a first launch on a device, and to lower a count, set `uses` with <a href="/merchant-api/reference/update-license/">`PATCH /products/{product}/licenses/{license}`</a> where you called Gumroad's `decrement_uses_count`.

### Keep the app as it is

When an app update can't ship at once, answer Gumroad's shape from your server: point the app's verify URL at your server, and let it answer from Sherpo's check. This adapter takes the fields the app sends, by product id or permalink, and keeps Gumroad's counting:

```js
// Each Gumroad product your apps check, by its id and its permalink, with the software product its keys moved to.
const GUMROAD = [{ id: 'GUMROAD_PRODUCT_ID', permalink: 'GUMROAD_PERMALINK', product: 'PRODUCT_ID' }];
const PRODUCTS = new Map(GUMROAD.flatMap((entry) => [[entry.id, entry], [entry.permalink, entry]]));
const MISSING = { success: false, unknown: true, message: 'That license does not exist for the provided product.' };

// Takes what the app sent Gumroad's verify call; answers what Gumroad answered, unknown: true for a key Sherpo doesn't hold.
// Anything else throws (a product you didn't map, a wrong token, a limit, an outage): answer the app 503, never "invalid".
async function verifyGumroadStyle({ product_id, product_permalink, license_key, increment_uses_count = 'true' }) {
  // Gumroad reads the id when one is sent, the permalink otherwise.
  const sent = product_id || product_permalink;
  const gumroad = PRODUCTS.get(sent);
  if (gumroad === undefined) throw new Error(`No Sherpo product is mapped to ${sent}.`);
  let license;
  try {
    license = await sherpo('POST', `/v1/stores/STORE_ID/products/${gumroad.product}/licenses/verify`, {
      // Gumroad counted every check unless told not to; Sherpo counts only when asked.
      body: { key: license_key, count_use: String(increment_uses_count) !== 'false' },
    });
  } catch (error) {
    const context = error.problem?.context;
    if (error.status === 404 && context?.kind === 'license') return MISSING;
    if (error.status === 422 && context?.path?.at(-1) === 'key') return MISSING;
    throw error;
  }
  const subscription = license.subscription;
  return {
    success: license.status === 'active',
    uses: license.uses,
    purchase: {
      product_id: gumroad.id,
      license_key,
      variants: license.tier === null ? '' : `(${license.tier.name})`,
      refunded: license.reason === 'refund',
      subscription_id: subscription?.id ?? null,
      subscription_ended_at: subscription?.ended_at ?? null,
      subscription_cancelled_at: subscription?.cancel_at_period_end ? subscription.current_period_end : null,
      sherpo: { id: license.id, status: license.status, reason: license.reason, features: license.features },
    },
  };
}
```

- **What it answers** is `success`, `uses` and, in `purchase`, `product_id`, `license_key`, `variants`, `refunded` and the subscription's id, end and cancellation, with Sherpo's own reading under `sherpo`. It leaves out `email`, `disputed`, `chargebacked` and `subscription_failed_at`, and a key you imported disabled, or whose grant you revoked for a refund at Gumroad, answers `refunded: false`, its reason `disabled` or `revoke`: check what your app reads before relying on it, and add what it needs from your import's records.
- **Map only software products you moved**, each by its Gumroad id and its permalink, and keep checking the products you haven't moved with Gumroad itself, before the adapter: a product you didn't map throws. A check against a product that isn't software answers every key as unknown, so check a known key for each product before you switch.
- **`success` is `false` for any key that isn't active**, so a refunded or lapsed key locks even in an app that never read `refunded`.
- **A key Sherpo doesn't hold** answers `unknown: true`, as Gumroad answered a missing key: send it with a `404`, and everything else with a `200`.
- **Any other refusal throws**: a product you didn't map, a wrong token or store, a limit, an outage. Answer the app a `503` then, never an invalid key, so it keeps the grace it gives when the check can't be reached instead of locking a customer who paid. Once every app calls your server, move it to Sherpo's own fields, which also tell features, devices and the latest release ([Read the answer](/merchant-api/guides/verify-licenses#read-the-answer)).

## Webhooks

| Gumroad | Sherpo |
| --- | --- |
| `sale` | `order.created`, and `products.unlocked` for the access it gives. A customer's first key also sends `license.issued`. |
| `refund` | `order.refunded`. A full refund ends the access the sale gave, unless the store's `refund_revokes_access` setting is off, and the license reads `revoked` unless another grant still opens the product. A lost dispute does the same. |
| `dispute` | Nothing while it's open: disputes are handled with Stripe ([Payments and payouts](/overview/payments)). |
| `dispute_won` | Nothing: the access never changed. A lost dispute sends `order.refunded`, its `dispute` set. |
| `cancellation` | `subscription.canceled`, with when it stops. |
| `subscription_updated` | `subscription.plan_changed`. |
| `subscription_ended` | No event: the license reads `expired` at its next check. `subscription.canceled` told the date ahead. |
| `subscription_restarted` | `subscription.reactivated` for a cancellation taken back, `subscription.created` for a new one. |

Grants you give send no `products.unlocked`, and a grant reaching its `ends_at` sends no event: the license reads `expired` at its next check. Creating an endpoint takes `organization:write` and the read scopes of each event it takes, listed with the [events](/merchant-api/webhooks#events), which the migration's scopes don't hold.

Sherpo also tells each license change: `license.disabled`, `license.enabled`, `license.replaced`, and its devices' `license.activated`, `license.deactivated` and `license.limit_reached`. Events name the license and never carry its key. Set up an endpoint and check its signatures with [Receive webhooks](/merchant-api/guides/receive-webhooks).

## Rollout and rollback

1. **Rehearse.** Recreate one product as a draft, import its keys, grant its buyers, and check a few keys from your server, refunded and lapsed ones too. Check a known key for every product you map, so a product that isn't software shows now rather than when the fallback goes.
2. **Import everything.** Run the import for every product, then tell your buyers their software moved. Rerun it until every buyer is imported as [above](#import-keys-and-access), their key recorded and each sale that still pays granted, with each bulk item's outcome read on its own. What's left is buyers whose extra keys answered `409` on `customer`. Compare the imported licenses, listed with `filter[source]=imported`, with the distinct buyers and products in Gumroad's export: a license is one buyer's for one product, however many sales they made.
3. **Ship the server's check.** Deploy the endpoint your app calls, with the adapter if the app keeps Gumroad's shape. While both stores sell, have it check Sherpo first and ask Gumroad only for a key Sherpo doesn't hold (`unknown: true`), never for one Sherpo answered inactive and never when the check threw. Unlock from Gumroad's answer only when `success` is `true`, `refunded`, `disputed` and `chargebacked` are `false`, `subscription_ended_at` and `subscription_failed_at` are `null`, and `subscription_cancelled_at` is `null` or still ahead, so a new buyer on Gumroad during the switch still unlocks and a refunded one doesn't. Sales by buyers you imported reach their access on Sherpo through the mirroring [above](#import-keys-and-access).
4. **Ship the app.** Point the app's verify call at your server. Old versions keep calling Gumroad, which never hears of a refund, a disable or a revoke made on Sherpo: while they're in use, do the same on Gumroad for those keys, and keep your Gumroad products and keys so their checks still answer. Gumroad doesn't know keys sold on Sherpo, nor members who moved, so ask customers to update before you take the next steps.
5. **Switch sales.** Publish the products on Sherpo, point your links at your store, and stop selling on Gumroad. Import any key sold on Gumroad since the first import.
6. **Move members.** Once members run a version that calls your server, cancel each Gumroad membership and send them to your store to subscribe while their last grant still runs: nothing is charged until a day before it ends, as [Memberships](#memberships) explains.
7. **Retire Gumroad.** Once the oldest version your customers may run calls your server, and no refund can still land on a Gumroad sale, drop the fallback from your server. Keep the Gumroad export.

To roll back before step 5, point your server back at Gumroad's check: nothing on Gumroad changed, and every key still answers there. After it, keys sold on Sherpo exist only on Sherpo, so keep the server checking Sherpo for them while it checks Gumroad for the rest.

Source: https://docs.sherpo.io/merchant-api/guides/migrate-from-gumroad/index.mdx
