Scopes and Merchant Binding

Scopes define the maximum capabilities an application can request. User consent cannot grant scopes beyond the client’s approved set.

User identity scopes

Scope	Capability	Merchant required?
`openid`	Pairwise subject and ID Token	No
`profile`	Username and nickname, excluding email	No
`email`	Email address and verification status	No

Email access requires approved email capability and user consent: request openid email or openid profile email. Existing clients are not automatically expanded. Administrators can review scope changes in the OAuth client review screen; changes revoke existing user grants and tokens and require new user consent.

openid requires a nonce. A “Sign in with TD Cloud” integration normally requests only openid profile.

Merchant and transaction scopes

Scope	Capability	Actor
`merchant.profile.read`	Read bound merchant public profile	User or Client Credentials
`products.write`	Create/update bound-merchant external API products	Client Credentials only
`inventory.write`	Update bound-merchant virtual inventory	Client Credentials only
`merchant_payments.create`	Create an amount-based collection and replay failed notifications	Client Credentials only
`merchant_payments.read`	Read this merchant’s collections, channels and notification deliveries	Client Credentials only
`products.read`	Read enabled products for the bound merchant	User or Client Credentials
`orders.create`	Create an order for the authorized user	User only
`orders.read`	Read orders belonging to the authorized user and bound merchant	User only
`payments.create`	Start payment for an accessible order	User only
`payments.read`	Read payment status for an accessible order	User only

Enforced merchant binding

If any merchant or transaction scope is requested, the server ignores a client-supplied merchant number and binds the applicant’s own approved, active merchant.

This means:

a sign-in client does not require a merchant;
merchant scopes cannot be requested without an active merchant;
a client cannot name another account’s merchant;
related OpenAPI calls fail after the bound merchant is disabled;
switching back to identity-only scopes removes the merchant association.

Client Credentials restriction

Only a confidential, merchant-bound client can use client_credentials. The current flow allows only:

Allowed scopes


merchant.profile.read products.read products.write inventory.write
merchant_payments.create merchant_payments.read

Catalog-order orders.* and payments.* still require user authorization. merchant_payments.* is for server-side collection independent of buyer accounts; checkout sign-in depends on merchant policy and channel. See General merchant collection. Request only needed, approved scopes from the supported set above.

Client Credentials


curl -X POST "{TOKEN_ENDPOINT}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id={CLIENT_ID}" \
  --data-urlencode "client_secret={CLIENT_SECRET}" \
  --data-urlencode "scope=merchant.profile.read products.read"