ADR-009 — Google Sheets ProductAdapter via API v4

Status: Accepted
Date: 2026-05-21

Context

buy2give.store uses Google Sheets as an interim PIM (synced to LunarPHP via n8n). Other tenants may also use Google Sheets as their primary product database.

Options Considered

Option	Pros	Cons
CSV export URL (public sheet only)	Zero credentials	Only works for publicly shared sheets; not suitable for production PIM data
Google Sheets API v4 (service account)	Works for any sheet, public or private	Requires service account setup

Decision

Google Sheets API v4 with a service account.

Setup (per tenant)

1. Opsome creates or provides a service account email
2. Tenant shares their Google Sheet with that email (Viewer role)
3. Opsome stores { sheet_id, service_account_json } encrypted in tenants.product_adapter

Rationale

Production PIM data is never publicly accessible. CSV export only works for demo/test sheets. Building on the API from the start means no rework when a tenant's sheet is private (which is always in production).

The service account approach is the standard pattern for server-to-server Google API access — no OAuth user flow required.

Consequences

• GoogleSheetsProductAdapter uses the Google API PHP client (google/apiclient)
• Column mapping (which column = product name, price, SKU, etc.) is configurable per tenant in product_adapter config
• When a tenant migrates from Sheets to Akeneo, they swap the ProductAdapterContract implementation — interface is identical