Skip to main content
The API is fully merchant-account aware, which means that every transaction, buyer, payment method, and most other resources are accessed within the context of a specific merchant account.
Support for multiple merchant accounts in one instance is a premium feature. In a standard instance, all your API calls are associated with the default merchant account without any extra effort.

​
Managing accounts

Merchant accounts can be managed via the dashboard as well as via the API.

​
API keys

API keys can only be created by administrators via the dashboard, they cannot be managed via the API. Keys can be created to either have access to a specific merchant account, or to all merchant accounts. These so-called administrator keys can be used to make API calls on behalf of any merchant account. Restricted API keys, or merchant keys, can only be used to make API calls on behalf of the merchant account they are associated with.
Administrator keysMerchant keys
AccessAll merchant accountsOne merchant account
HeaderOptional, defaults to defaultDefaults to account associated to key
Use casePlatforms calling the API on behalf of merchantsMerchants making their own API calls

​
Merchant account header

Most API endpoints can only access and operate on records in one merchant account at a time. Every request is processed within the context of that one merchant account, and it only allows for using other resources from within the same merchant account. For example, an API call to create a transaction associates that transaction with the merchant account for which the request is made, and it can only use buyers, payment methods, connections, and flow rules that belong to the same merchant account. To identify the merchant account to use, set the X-GR4VY-MERCHANT-ACCOUNT-ID header. For example, the following request fetches a list of buyers for the legendary-games-uk account on the legendary-games instance. 
curl https://api.sandbox.legendary-games.gr4vy.app \
  -H "X-GR4VY-MERCHANT-ACCOUNT-ID: legendary-games-uk"  \
  -H "AUTHORIZATION: bearer [token]"
In a single merchant instance, the X-GR4VY-MERCHANT-ACCOUNT-ID header can be omitted and the API falls back to the default merchant account ID. Additionally, when using a merchant key the header can be omitted and the API falls back to the merchant account associated with the key.

​
Administrator APIs

A few endpoints are not merchant aware and therefore can only be accessed by administrator keys. The only public endpoints currently affected are the GET /api-logs endpoint. Setting the X-GR4VY-MERCHANT-ACCOUNT-ID on this API has no effect.

​
SDK usage

Each of the SDKs supports setting the merchant account ID. This automatically sets the X-GR4VY-MERCHANT-ACCOUNT-ID for each request to this value. Without setting the ID explicitly its value falls back to default. 
var sdk = new Gr4vySDK(
    id: "example",
    server: SDKConfig.Server.Sandbox,
    bearerAuthSource: Auth.WithToken(privateKey),
    merchantAccountId: "my-merchant-id"
);