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

# Partner-scoped requests

> Call supported endpoints across all of your products with a partner-scoped API key

A **partner-scoped request** is a request made with a partner-scoped API key and **no**
`x-imprint-merchant-key` header. It acts for your partner across every one of your products,
so you do not need to know which product a customer belongs to before you call the endpoint.

Sending `x-imprint-merchant-key` with the same key narrows the request to that one product.
See [Migrating to Multiple Products](https://docs.imprint.co/migrate-to-multi-product.md) for how to get a
partner-scoped key.

## How a request resolves

| Request | Acts for |
| - | - |
| Partner-scoped key, no `x-imprint-merchant-key` | Your partner, across all of your products, on the [supported endpoints](#supported-endpoints). Every other endpoint returns `401 Unauthorized`. |
| Partner-scoped key with the merchant key of one of your products | That product |
| Product-scoped key, with or without its own product's merchant key | That product |
| Any key with a merchant key that does not belong to it | `403 Forbidden` |

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

## Making a partner-scoped request

Send your partner-scoped API key and leave out `x-imprint-merchant-key`:

```bash theme={null}
curl https://dev.sbx.imprint.co/v2/customers/{customer_id} \
  -u YOUR_PARTNER_SCOPED_API_KEY:
```

To act for a single product instead, add that product's merchant key:

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

An endpoint that does not support partner-scoped requests rejects a partner-scoped key sent
without a merchant key:

```json theme={null}
{
  "error": {
    "type": "UNAUTHORIZED_ERROR",
    "message": "API key is valid but not associated with a product. This partner-scoped key requires an x-imprint-merchant-key header identifying the merchant/product."
  }
}
```

Send the merchant key of the product the request is for, and the request succeeds as before.

## Supported endpoints

These endpoints accept a partner-scoped request. Each endpoint's reference page describes its
behavior in full.

| Endpoint | With a partner-scoped request |
| - | - |
| [`POST /v2/customer_sessions`](https://docs.imprint.co/api-reference/customer-sessions/create-a-new-customer-session) | Creates the session for your brand's credit card product. Returns `401` if your partner has no brand or more than one, and `400` if that brand does not have exactly one credit card product; send `x-imprint-merchant-key` to choose the product. |
| [`GET /v2/customers/{customer_id}`](https://docs.imprint.co/api-reference/customers/retrieve-a-customer) | Describes the customer across every one of your products they hold an account on, with one `statuses` entry per card program. If they hold accounts on more than one of your products, `partner_customer_id`, `metadata`, and `authorized_users` are omitted. |
| [`GET /v2/customers`](https://docs.imprint.co/api-reference/customers/search-for-customers) | Matches customers linked to `partner_customer_id` on any of your products and returns each customer once, in the same shape as Retrieve a customer. |
| [`POST /v2/customers`](https://docs.imprint.co/api-reference/customers/search-for-customers) | A `partner_customer_id` search matches across your products; an `ssn` and `date_of_birth` search returns the customer only if they hold an account on one of your products. Results have the same shape as Retrieve a customer. |
| [`POST /v2/customers/{customer_id}/link`](https://docs.imprint.co/api-reference/customer-links/link-an-imprint-customer-and-partner-customer-accounts) | Links the customer on the one product of yours they hold an account on; when they also hold closed accounts, only products with an open account count. Returns `400` if more than one of your products qualifies; send `x-imprint-merchant-key` to choose the product to link. |
| [`GET /v2/customers/{customer_id}/payment_methods`](https://docs.imprint.co/api-reference/customers/list-customers-payment-methods) | Lists the customer's payment methods on every one of your products. |
| [`GET /v2/payment_methods`](https://docs.imprint.co/api-reference/payment-methods/list-payment-methods) | Lists the customer's payment methods on every one of your products. |
| [`GET /v2/payment_methods/{payment_method_id}`](https://docs.imprint.co/api-reference/payment-methods/retrieve-a-payment-method) | Retrieves a payment method on any of your products. |
| [`GET /v2/rewards`](https://docs.imprint.co/api-reference/rewards/search-for-rewards) | Returns the reward for a `transaction_event_id` when it was earned on any of your products. |
| [`GET /v2/card_designs`](https://docs.imprint.co/api-reference/card-designs/list-card-designs) | Lists your partner-level card designs. See [Managing Card Designs](https://docs.imprint.co/managing-card-designs.md). |
| [`GET /v2/card_designs/{card_design_id}`](https://docs.imprint.co/api-reference/card-designs/retrieve-a-card-design) | Retrieves a card design of any of your products. See [Managing Card Designs](https://docs.imprint.co/managing-card-designs.md). |
| [`PATCH /v2/card_designs/{card_design_id}`](https://docs.imprint.co/api-reference/card-designs/update-a-card-design) | Changes a card design of any of your products. See [Managing Card Designs](https://docs.imprint.co/managing-card-designs.md). |

Every other endpoint, including applications, orders, transactions, transaction intents, and
every rewards endpoint other than searching by `transaction_event_id`, acts on a single product
and requires `x-imprint-merchant-key` with a partner-scoped key.

## Resources outside your partner

A partner-scoped request only sees resources on your own products. A customer, payment method,
reward, or card design that belongs to another partner is treated as if it does not exist:
retrieving or linking it returns `404 Not Found`, and listing or searching for it returns an
empty list.

## API versions

Partner-scoped requests are available in every API version. Adding support to an endpoint does
not change its behavior for requests that send `x-imprint-merchant-key` or use a product-scoped
key.


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