Partner-scoped requests

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

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:

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:

{
  "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`	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}`	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`	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`	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`	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`	Lists the customer’s payment methods on every one of your products.
`GET /v2/payment_methods`	Lists the customer’s payment methods on every one of your products.
`GET /v2/payment_methods/{payment_method_id}`	Retrieves a payment method on any of your products.
`GET /v2/rewards`	Returns the reward for a `transaction_event_id` when it was earned on any of your products.
`GET /v2/card_designs`	Lists your partner-level card designs. See Managing Card Designs.
`GET /v2/card_designs/{card_design_id}`	Retrieves a card design of any of your products. See Managing Card Designs.
`PATCH /v2/card_designs/{card_design_id}`	Changes a card design of any of your products. See Managing Card Designs.

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.

Getting Started

Applications

Cards

Transactions

Rewards

Account Linking

Webhook Event Notifications

API Keys

Servicing

Sandbox Testing

SDK Reference

Partner-scoped requests

How a request resolves

Making a partner-scoped request

Supported endpoints

Resources outside your partner

API versions

​How a request resolves

​Making a partner-scoped request

​Supported endpoints

​Resources outside your partner

​API versions

How a request resolves

Making a partner-scoped request

Supported endpoints

Resources outside your partner

API versions