shopping-utils
=====================

Shopping utils aims to supply useful wrappers for shopping APIs like Google Merchant API and Bing Content API.

Google Shopping uses Merchant API (`products_v1` / `reports_v1` / `datasources_v1`). Content API for Shopping is sunset on August 18, 2026.

Before first Merchant API calls, link the Cloud project to Merchant Center (`developerRegistration:registerGcp`). Writes require an API primary data source.

```python
GoogleShopping(merchant_id, service_account_info, data_source='accounts/{account}/dataSources/{id}')
```

Product payloads may still use Content API field layout (`title`, `price.value`, `online:en:US:sku`). They are converted to Merchant API `productInputs` (`productAttributes`, `amountMicros`, `en~US~sku`) on write.

Long-running jobs (`update_expiration`, `cleanup`) checkpoint by default. Existing files are looked up in this order:

1. `checkpoint_path=` argument
2. `GoogleShopping(..., checkpoint_dir=...)`
3. environment variable `SHOPPING_UTILS_CHECKPOINT_DIR`
4. `./shopping-utils-checkpoints/merchant-{id}-{operation}.json`
5. `~/.shopping-utils/checkpoints/merchant-{id}-{operation}.json`

If none exist, a new file is created in the first available directory above. Failed writes go to `{checkpoint_path}.failed.jsonl` and are retried on resume. Delete/patch treats HTTP 404 as already done. Re-run the same command to continue; `resume=False` starts a new job; `checkpoint_path=False` disables checkpointing.

```python
# source='full' reads googleExpirationDate from the catalog.
# source='report' reads product_view and refreshes products whose submitted
# expiration_date is missing or on or before today + days_before_expire.
# The reports API rejects an expiration_date comparison in WHERE.
shopping.update_expiration(days_before_expire=14)
shopping.update_expiration(days_before_expire=14, source='full')

# Does not delete. Still exports policy products and writes a delete preview.
for _ in shopping.cleanup(dry_run=True):
pass

# Delete disapproved products, including policy violations. Price mismatch,
# inaccessible landing pages, images that cannot be loaded, and missing shipping
# are kept. Policy violations are also exported to
# merchant-{id}/{year}/{policy_code}.jsonl, one file per highest-level policy.
for _ in shopping.cleanup():
pass
```

Installation
-------------

You can install shopping-utils with `pip`:

pip install shopping-utils




Render warnings:
<string>:26: (WARNING/2) Inline literal start-string without end-string.