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

# Migrating to Multiple Products

> Move from a single product integration to a partner-scoped, multi-product integration

This guide is for partners whose integration started with a single Imprint product and are
expanding to multiple products. A single-product integration uses an API key, webhook
subscriptions, and a webhook secret that are all scoped to one product. A multi-product
integration replaces each of them with a **partner-scoped** equivalent that covers every product
under your partnership:

| Resource | Single product | Multiple products |
| - | - | - |
| API key | Product-scoped key | Partner-scoped key, sent with the `x-imprint-merchant-key` header |
| Webhook subscriptions | Product-scoped subscriptions | Partner-scoped subscriptions |
| Webhook secret | Product-scoped secret | Partner-scoped secret |

The merchant key for each of your products can be found in the **Imprint Dashboard**.

> [!NOTE]
>
> Creating a partner-scoped resource never deactivates the product-scoped one it replaces. Each
> product-scoped API key, webhook subscription, and webhook secret keeps working until you remove
> it, so you can complete each step below before retiring the old resource. Removing resources in
> the **Imprint Dashboard** requires an Admin role or higher.

## How requests resolve to a product

Every API request applies to exactly one product.

| Request | Result |
| - | - |
| Partner-scoped key with a merchant key for one of your products | Applies to that product |
| Partner-scoped key with no `x-imprint-merchant-key` header | `401 Unauthorized` |
| Product-scoped key with that product's merchant key | Applies to that product |
| Any key with a merchant key that does not belong to it | `403 Forbidden` |

Send the merchant key of the product the customer belongs to. A request that names one of your
other products is not rejected, but resources belonging to a different product are not visible to
it, so it returns an empty result rather than an error.

## Step 1: Create the partner-scoped resources

In the **Imprint Dashboard**, create:

1. A partner-scoped **API key** with the scopes your integration uses today (see
   [Scopes](/authentication#scopes)).
2. A partner-scoped **webhook secret**. Store it alongside your existing product-scoped secret;
   do not replace it yet.
3. Partner-scoped **webhook subscriptions** for each event type you consume, pointing at the URL
   that will receive events for all of your products.

None of these change how your existing product is served yet. Requests made with your
product-scoped key keep working, and events for your existing product keep going to your
product-scoped subscriptions, signed with your product-scoped secret.

## Step 2: Switch to the partner-scoped API key

Choose the path that matches how you deploy changes.

#### Option A: Switch the key and add the header together

If you can change the API key and start sending `x-imprint-merchant-key` in the same release, do
both at once: replace the product-scoped key with the partner-scoped key and send your existing
product's merchant key on every request.

```bash theme={null}
curl https://dev.sbx.imprint.co/v2/customers \
  -u YOUR_PARTNER_SCOPED_API_KEY: \
  -H "x-imprint-merchant-key: your-merchant-key"
```

#### Option B: Add the header first, then switch the key

If the API key and request headers are changed in separate releases, add the header first.

1. Start sending `x-imprint-merchant-key` with your existing product's merchant key, while still
   using your product-scoped key. A product-scoped key accepts its own product's merchant key, so
   your integration keeps working unchanged.

   ```bash theme={null}
   curl https://dev.sbx.imprint.co/v2/customers \
     -u YOUR_PRODUCT_SCOPED_API_KEY: \
     -H "x-imprint-merchant-key: your-merchant-key"
   ```

2. Once every request includes the header, replace the product-scoped key with the
   partner-scoped key.

> [!WARNING]
>
> Do not switch to the partner-scoped key before every request sends `x-imprint-merchant-key`.
> Requests made with a partner-scoped key and no header are rejected with `401`.

## Step 3: Move webhook handling to the partner-scoped subscriptions

1. Update the endpoint behind your partner-scoped subscriptions to verify signatures against
   **both** your partner-scoped secret and your product-scoped secret, accepting the event if
   either matches (see [Verify event signature](/verify-event-notification)). Events for your
   existing product are signed with the product-scoped secret for as long as it exists, including
   after they start arriving at the new URL.
2. Use the `merchant_key` field in each event's `data` to tell which product the event belongs
   to (see [Event notifications](/event-notifications)).
3. Remove your product-scoped webhook subscriptions. Events for your existing product are then
   delivered to your partner-scoped subscriptions instead.
4. Confirm events for your existing product arrive at the new URL and pass signature
   verification.

## Step 4: Retire the product-scoped resources

After you have confirmed that API requests and webhook delivery work for every product:

1. Revoke the product-scoped **webhook secret**. Events are then signed with your partner-scoped
   secret only, and your endpoint can stop checking the product-scoped secret.
2. Delete the product-scoped **API key**, either in the **Imprint Dashboard** or with the
   [**`delete API key API`**](https://docs.imprint.co/api-reference/keys/delete-an-api-key).

## Adding more products

To serve another product, keep using the same partner-scoped API key and send that product's
merchant key in `x-imprint-merchant-key`. Its events are delivered to your partner-scoped
subscriptions and signed with your partner-scoped secret.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.