Arcane MCT

Internal package for Merchant Center (MCT) access. It talks to Google Shopping via Content API for Shopping v2.1 by default, with an optional migration path to the Merchant API (Accounts + Products client libraries).

Installation

Install from the monorepo (Poetry):

poetry add ../arcane-mct   # or your path to this package

Dependencies include arcane-core, arcane-datastore, arcane-credentials, and the Google Shopping client libraries (see pyproject.toml).

Usage

MctClient (service account only)

Use a GCP service account JSON to create a client and call MCT:

from arcane.mct import MctClient

client = MctClient(
    gcp_service_account="/path/to/service-account.json",
    user_email="user@example.com",  # optional; needed for user-delegated credentials
    secret_key_file="/path/to/secret.key",  # required when user_email is set
    gcp_project="my-gcp-project",
)

# Get the account display name for a merchant ID
name = client.get_mct_account_details(merchant_id=123456789)
print(name)  # e.g. "My Store"

# Check that the account is not a multi-client account (MCA); raises if it is
client.check_if_multi_client_account(merchant_id=123456789)

When you already have an MCT account dict (e.g. from your API), you can pass it instead of user_email:

client = MctClient(
    gcp_service_account="/path/to/service-account.json",
    mct_account={"creator_email": "user@example.com", ...},
    secret_key_file="/path/to/secret.key",
    gcp_project="my-gcp-project",
)
name = client.get_mct_account_details(merchant_id=123456789)

Using only the service account (no user credentials):

client = MctClient(
    gcp_service_account="/path/to/service-account.json",
)
name = client.get_mct_account_details(merchant_id=123456789)

check_access_before_creation

Before linking or creating an MCT account, you can verify that the user has access and that the account is not an MCA:

from arcane.mct import check_access_before_creation

should_use_user_access = check_access_before_creation(
    mct_account_id=123456789,
    user_email="user@example.com",
    gcp_service_account="/path/to/arcane-service-account.json",
    secret_key_file="/path/to/secret.key",
    gcp_project="my-gcp-project",
)
# Returns True if the user's credentials have access (use user access when linking).
# Raises MctAccountLostAccessException or MerchantCenterServiceDownException on failure.

Exceptions

• MctAccountLostAccessException — The account is not accessible (e.g. wrong merchant ID, revoked access, or MCA when only sub-accounts are allowed).
• MerchantCenterServiceDownException — The Merchant Center API is unavailable or returned a server error.

Merchant API migration

Content API for Shopping is being sunset (August 2026). You can switch to the Merchant API in two ways:

1. Environment: set USE_MERCHANT_API=true (or 1) so all clients use the Merchant API when no explicit flag is passed.
2. In code: pass use_merchant_api=True (or False) where supported:
   • MctClient(..., use_merchant_api=True)
   • check_access_before_creation(..., use_merchant_api=True)

If you omit use_merchant_api (or pass None), the backend is chosen from the USE_MERCHANT_API environment variable. Default is Content API (with a deprecation warning).