What ends up in the bucket
Every file in Endora Commerce goes through a single module: the assets library. It is a central catalogue of images, video, PDFs and documents, with a folder tree, used by product galleries and attachments, category main images, CMS pages and downloadable product files. In practice that means product photos, PDF invoices, quote attachments and anything else uploaded through the admin panel or the API.
Once GCS is selected as the active backend, each new file is written as an object in the one bucket you point it at. The object name is derived from the asset identifier and spread across subdirectories, so the original filename does not appear in the URL, and an optional prefix lets the bucket be shared with other applications. Exactly one backend is active at a time: local disk (the default), Amazon S3 or GCS.
Public and private files
Visibility is set for each file on its own, not once for the whole bucket. It decides what kind of URL the buyer gets:
- A public file (a product photo, for example) has a stable URL. By default it points straight at the bucket on the
storage.googleapis.comdomain. If a CDN or a custom domain sits in front of the bucket, entering its base URL in settings is enough. - A private file (a document meant for one customer, for example) has no stable URL. On every read the platform issues a fresh V4-signed link, valid for 300 seconds by default. The lifetime is a setting, and Google itself caps it at 7 days.
Changing the visibility of an existing file in the admin panel is carried over to the object in GCS: the platform grants or removes public read on it.
What to prepare on the Google Cloud side
- A bucket. The platform does not create it. The connection test only checks that the named bucket exists and can be reached.
- A service account allowed to write, read and delete objects and to change their ACLs.
- Credentials. You can paste the full service account JSON key into settings (it is stored as a sensitive value), or leave that field empty and rely on ambient credentials, such as the service account attached to the machine the backend runs on.
In the admin panel it comes down to a few fields under Settings, Storage:
| Setting | Required | What it is for |
|---|---|---|
| Active adapter | yes | selecting gcs instead of local or s3 |
| Bucket | yes | name of the bucket the files go to |
| Service account JSON key | no | skipped when the backend has ambient credentials |
| Object prefix | no | common leading part of every object name |
| Public CDN base URL | no | the base that public links are built on |
Three things worth checking before go-live
The bucket’s access control mode. The integration sets visibility through ACLs on individual objects. Google now recommends uniform bucket-level access, and with it enabled, ACL requests fail. The bucket used by Endora Commerce therefore has to run in the ACL-based (fine-grained) mode. If your organization enforces uniform access by policy, agree this with the cloud team before the rollout.
Public access prevention. When public access prevention is enforced on the bucket or by an organization policy, Google rejects granting public read on an object. A catalogue with images on stable URLs requires that this block is off for the bucket holding the store’s files.
Signing links without a key. With a pasted JSON key, private links are signed with that key. With ambient credentials the signature is produced through a Google API, so the service account additionally needs the Service Account Token Creator role granted on itself. The details are in the signed URLs documentation.
Deleting files
Deleting a file in the admin panel does not remove the object straight away. The asset disappears from listings and stays recoverable for the retention period (30 days by default), and only then does a background process delete the object from the bucket. If that fails, for instance after permissions were revoked, the platform retries on the next run. A file used by a product, a category or a CMS page cannot be deleted until every reference to it is detached.
GCS, S3 or local disk
The choice rarely comes from the platform itself, because all three backends offer the same features: per-file visibility, signed private links, and file type and size limits checked before upload. Switching is a settings change, so the surroundings decide:
- GCS when the company runs on Google Cloud and does not want to introduce AWS credentials just to run the store.
- S3 when the infrastructure is in AWS, or when you need S3-compatible storage on your own endpoint, such as MinIO.
- Local disk during development.
The other infrastructure components and ready-made integrations are collected on the integrations page.