Skip to main content
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: The merchant key for each of your products can be found in the Imprint Dashboard.
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. 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).
  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.

​
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.
  2. Once every request includes the header, replace the product-scoped key with the partner-scoped key.
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). 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).
  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.

​
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.