API reference

Merchant, team and keys

GET /v1/merchant returns the merchant, its tier, its limits and how much of each is used.

What the API may change here is deliberately narrow. Dashboard only, with a signed-in member and where noted a passkey: the settlement asset (it decides where takings land), rails on or off, the fee bearer default, verification, owners, any role that holds a wallet key (Owner, Finance), passkeys, and closing the account.

API keys can be listed, created, rolled and revoked by a full secret key or by a restricted key with keys:write. A key can never create a key with a scope it does not itself hold. Every key creation, roll and revocation emails all Owners.

The `merchant` object

JSON

{
  "id": "mer_93r9sfyrrm5km287343znd4f",
  "object": "merchant",
  "livemode": true,
  "created": "2026-09-02T09:15:44.020Z",
  "name": "Acme Coffee Roasters",
  "slug": "acme",
  "profile_url": "https://pay.orrerie.com/m/acme",
  "country": "US",
  "business_type": "company",
  "support_email": "help@acme.example",
  "tier": "unverified",
  "restricted": false,
  "settlement": {
    "mode": "convert",
    "asset": "base:usdc"
  },
  "fee_bearer": "payer",
  "default_order_expiry_seconds": 3600,
  "rails": {
    "orrerie_app": true,
    "relay": true,
    "direct": true
  },
  "app_pay_allowed": true,
  "branding": {
    "logo": "file_xn5cz8fk5zmyx3kp37rvddgs",
    "accent_color": null
  },
  "limits": {
    "order_max": {
      "amount": "1000.00",
      "currency": "USD"
    },
    "rolling_30_days_max": {
      "amount": "5000.00",
      "currency": "USD"
    },
    "lifetime_max": {
      "amount": "20000.00",
      "currency": "USD"
    },
    "open_orders_max": 50,
    "outside_payouts_daily_max": {
      "amount": "1000.00",
      "currency": "USD"
    },
    "payout_batch_rows_max": 0,
    "members_max": 2,
    "live_keys_max": 2,
    "webhook_endpoints_max": 1,
    "requests_per_minute": 60
  },
  "usage": {
    "rolling_30_days_paid": {
      "amount": "1284.50",
      "currency": "USD"
    },
    "lifetime_paid": {
      "amount": "1284.50",
      "currency": "USD"
    },
    "open_orders": 3,
    "outside_payouts_today": {
      "amount": "0.00",
      "currency": "USD"
    },
    "members": 2,
    "live_keys": 1,
    "webhook_endpoints": 1
  }
}

Table: The merchant object
Field	Meaning
`tier`	One of `unverified`, `verification_pending`, `verified`, `verification_failed`.

The `member` object

JSON

{
  "id": "mem_ceh1wpzdrpk13cnpcjy9w0fa",
  "object": "member",
  "livemode": true,
  "created": "2026-09-02T09:15:44.020Z",
  "user": "usr_yrwyak6zrppn5310bxms89nv",
  "email": "owner@acme.example",
  "name": "Sam Rivera",
  "role": "owner",
  "status": "active",
  "holds_wallet_key": true,
  "passkey_count": 2,
  "invited_by": null,
  "invitation_expires_at": null,
  "last_active_at": "2026-10-12T09:00:00.000Z"
}

Table: The member object
Field	Meaning
`role`	One of `owner`, `admin`, `finance`, `developer`, `support`, `cashier`, `viewer`.
`status`	One of `invited`, `active`, `removed`.

The `api_key` object

JSON

{
  "id": "key_6e3gg2c6ea176xxdek2nar6v",
  "object": "api_key",
  "livemode": true,
  "created": "2026-09-03T09:50:00.000Z",
  "name": "Shop backend",
  "type": "restricted",
  "prefix": "sk_live_",
  "last4": "x9Tq",
  "scopes": [
    "checkout_sessions:write",
    "orders:read",
    "refunds:write",
    "events:read"
  ],
  "allowed_ips": [],
  "status": "active",
  "api_version": "2026-10-11",
  "created_by": {
    "type": "member",
    "id": "mem_ceh1wpzdrpk13cnpcjy9w0fa"
  },
  "last_used_at": "2026-10-12T09:30:00.000Z",
  "expires_at": null,
  "rolled_from": null
}

Table: The api_key object
Field	Meaning
`scopes`	What the key may do. ["*"] for a full secret key.
`type`	One of `secret`, `restricted`, `publishable`.
`status`	One of `active`, `rolling`, `revoked`, `expired`.

Every field

Fields of the `merchant` object

Fields of the merchant object
Field	Type	Meaning
`id`	string	Unique identifier: the object prefix, an underscore, 24 lower-case Crockford base32 characters.
`object`	string	The type of this object.
`livemode`	boolean	`true` for live mode (real money); `false` for test mode (simulated payments).
`created`	string (date-time)	When the object was created. RFC 3339, UTC, milliseconds.
`name`	string	The business name payers see on the checkout, receipts and invoices.
`slug`	string or null	The short name in the public profile's address; `null` until the merchant picks one.
`profile_url`	string or null	The merchant's public profile page on the payer site; `null` while the profile is off.
`country`	string	The country the business is registered in, an ISO 3166-1 alpha-2 code.
`business_type`	string	The kind of business, as given at sign-up (for example `company`).
`support_email`	string	The address payers are shown for questions about an order.
`tier`	string	One of `unverified`, `verification_pending`, `verified`, `verification_failed`.
`restricted`	boolean	`true` while the merchant is restricted: new orders, payouts to others and conversions are off; reads and withdrawals to saved addresses still work.
`verification`	object or null	The business's newest identity verification through Didit, read-only (04 the states every object uses; 06 Idempotency); `null` when none was started. Started, followed and decided only in the dashboard.
`verification.id`	string	The verification's id (`ver_`).
`verification.status`	string	Where the verification stands (06 Idempotency). One of `created`, `in_progress`, `awaiting_people`, `in_review`, `needs_more`, `approved`, `declined`, `lapsed`.
`verification.workflow`	string	Which check: a registered business, a sole trader, or the registry's owners for limits above US$250,000 in 30 days (06 Idempotency). One of `business`, `soletrader`, `ubo`.
`verification.created`	string (date-time)	When it was started.
`verification.decided`	string (date-time) or null	When Didit's decision was read; `null` until then.
`settlement`	object	What new orders settle in by default.
`settlement.mode`	string	`convert`: payments are delivered in the settlement asset. `keep`: each payment stays in the asset it was paid in.
`settlement.asset`	string	The settlement asset id when `mode` is `convert`.
`fee_bearer`	string	Who pays the routing fee on the relay rail by default: `payer` or `merchant`.
`default_order_expiry_seconds`	integer	How long a new order stays payable unless the request says otherwise, in seconds.
`rails`	object	The ways payers may pay this merchant, each on or off.
`rails.orrerie_app`	boolean	`true` when Pay with Orrerie is offered.
`rails.relay`	boolean	`true` when payers may pay from other assets and networks through Relay.
`rails.direct`	boolean	`true` when payers may send straight to the merchant's own wallet.
`app_pay_allowed`	boolean	`true` when the checkout shows the Pay with Orrerie button; set by a rule only Orrerie changes.
`branding`	object	How the merchant's pages look to payers.
`branding.logo`	string or null	The `file_` id of the logo shown on the checkout and receipts; `null` for none.
`branding.accent_color`	string or null	The accent colour of the payer pages, `#rrggbb`; Verified merchants only, `null` for the default.
`limits`	object	What the merchant's tier allows.
`limits.order_max`	object	The largest single order, in US dollars.
`limits.rolling_30_days_max`	object	The most that may be paid to the merchant in any 30 days, in US dollars.
`limits.lifetime_max`	object or null	The most that may ever be paid to the merchant, in US dollars; `null` when the tier has no lifetime cap.
`limits.open_orders_max`	integer	How many orders may be open at once.
`limits.outside_payouts_daily_max`	object	The most that may be paid out to others in a day, in US dollars.
`limits.payout_batch_rows_max`	integer	The most rows in one payout batch; 0 when batches are not allowed.
`limits.members_max`	integer	How many team members the merchant may have.
`limits.live_keys_max`	integer	How many live API keys may exist at once.
`limits.webhook_endpoints_max`	integer	How many webhook endpoints each mode may have.
`limits.requests_per_minute`	integer	The API's request budget per minute for this merchant and mode.
`usage`	object	How much of each limit is used now.
`usage.rolling_30_days_paid`	object	What was paid to the merchant in the last 30 days, in US dollars.
`usage.lifetime_paid`	object	What was ever paid to the merchant, in US dollars.
`usage.open_orders`	integer	How many orders are open now.
`usage.outside_payouts_today`	object	What was paid out to others today, in US dollars.
`usage.members`	integer	How many members the merchant has.
`usage.live_keys`	integer	How many live API keys exist.
`usage.webhook_endpoints`	integer	How many webhook endpoints exist in this mode.

Fields of the `member` object

Fields of the member object
Field	Type	Meaning
`id`	string	Unique identifier: the object prefix, an underscore, 24 lower-case Crockford base32 characters.
`object`	string	The type of this object.
`livemode`	boolean	`true` for live mode (real money); `false` for test mode (simulated payments).
`created`	string (date-time)	When the object was created. RFC 3339, UTC, milliseconds.
`user`	string or null	The `usr_` id of the person; `null` while the invitation is not accepted.
`email`	string	The member's email address.
`name`	string or null	The member's name; `null` when none was given.
`role`	string	One of `owner`, `admin`, `finance`, `developer`, `support`, `cashier`, `viewer`.
`status`	string	One of `invited`, `active`, `removed`.
`holds_wallet_key`	boolean	`true` when the member holds a copy of the wallet key and can approve money out.
`passkey_count`	integer	How many passkeys the member has.
`invited_by`	string or null	The `mem_` or `key_` id that invited the member; `null` for the merchant's first Owner.
`invitation_expires_at`	string or null	When an unaccepted invitation stops working; `null` once accepted.
`last_active_at`	string (date-time) or null	When the member last used the dashboard; `null` for never.

Fields of the `api_key` object

Fields of the api_key object
Field	Type	Meaning
`id`	string	Unique identifier: the object prefix, an underscore, 24 lower-case Crockford base32 characters.
`object`	string	The type of this object.
`livemode`	boolean	`true` for live mode (real money); `false` for test mode (simulated payments).
`created`	string (date-time)	When the object was created. RFC 3339, UTC, milliseconds.
`name`	string	The key's name, as the merchant set it.
`type`	string	One of `secret`, `restricted`, `publishable`.
`prefix`	string	How the key starts: `sk_live_`, `sk_test_`, `pk_live_` or `pk_test_`.
`last4`	string	The last four characters of the key, to tell keys apart.
`scopes`	array of strings	What the key may do. ["*"] for a full secret key.
`allowed_ips`	array of strings	The addresses and ranges the key may be used from; empty for any.
`status`	string	One of `active`, `rolling`, `revoked`, `expired`.
`api_version`	string	The API version the key is pinned to.
`created_by`	object	Who made the key: a member or another key.
`created_by.type`	string	`member` or `api_key`.
`created_by.id`	string	The id of the member (`mem_…`) or key (`key_…`) that made it.
`last_used_at`	string (date-time) or null	When the key was last used; `null` for never.
`expires_at`	string or null	When the key stops working; `null` for never.
`rolled_from`	string or null	The `key_` id of the key this one replaced; `null` for a key that replaced none.

Endpoints

Events

Webhook events whose data.object is an object of this page.

Merchant, team and keys

The merchant object

The member object

The api_key object

Every field

Fields of the merchant object

Fields of the member object

Fields of the api_key object

Endpoints

Events

The `merchant` object

The `member` object

The `api_key` object

Fields of the `merchant` object

Fields of the `member` object

Fields of the `api_key` object