DPP Agent docs

WooCommerce — integration guide

WooCommerce is the WordPress e-commerce plugin behind most EU SMB textile/footwear stores. DPP Agent reads via the REST API with a read-only consumer key + secret pair.

What the adapter does, in one sentence

DPP Agent paginates /wp-json/wc/v3/products, folds product variations into their parents, and emits one DPP row per GTIN-bearing leaf — Read-only, no WordPress side changes, no write-back.

Authentication

HTTP Basic with a consumer key + consumer secret pair issued in WP-admin → WooCommerce → Settings → Advanced → REST API → Add key.

Set the key to Read permission. Do not grant Read/Write.

We store the pair as consumer_key:consumer_secret (colon-joined) and split at runtime. The colon is significant — keys themselves never contain a colon.

GET <site_url>/wp-json/wc/v3/products?per_page=100&page=1
Authorization: Basic <base64(key:secret)>

Credential handling

Same envelope as the other adapters: AES-256-GCM at rest, the pair is shown redacted in the UI, decrypted in-memory for the duration of a sync only, never logged. Deleting the key from WP-admin invalidates it immediately — the next sync run fails cleanly with HTTP 401.

Scope limitation

1. Read-only consumer key

The key permission level is enforced by WordPress, not by us. With Read permission the consumer pair cannot:

  • Create / update / delete products
  • Read or modify orders, customers, refunds
  • Access store settings, payment gateways, or webhooks

Even if our code were compromised it could not mutate the store.

2. Status filter (default publish)

settings.status = "publish" excludes drafts, private and trashed products. Only the public, live catalogue is returned.

3. Page size

settings.page_size = 100 (max) keeps the per-page payload to a few hundred KB and stays comfortably under WordPress's max_execution_time defaults.

4. Variation handling

When include_variations = Y (default) the adapter fetches each variable product's variations endpoint and folds them into the parent before emitting DPP rows. The variations endpoint follows the same read_products-equivalent permission — no extra scope needed.

5. Network IP allowlist

WordPress doesn't expose an IP allowlist out of the box, but ModSecurity, Cloudflare, or a host-level firewall can scope the /wp-json/wc/v3/* endpoints to Vercel's egress IPs.

Settings reference

Setting Required Purpose
site_url yes https://yourshop.com (no trailing slash needed)
api_version no Default wc/v3
page_size no 1–100. Default 100.
status no Default publish. Set to draft for a dry-run pull.
include_variations no Y (default) or N. Y is recommended for variable products.

The credential row is stored as key:secret. Rotate by overwriting the pair in the UI; the old row is cleared before the new one is written.

Sync semantics

Conflict policy is the platform default:

  • Draft DPPs are overwritten
  • Active DPPs spawn dpp_revisions(status=pending) for human review
  • Withdrawn / archived / recalled DPPs are skipped

Deletion: if a product is trashed in WooCommerce, the corresponding DPP remains in dpp_runtime. EN 18219 / EN 18223 retention rules apply.

Onboarding sequence

  1. WP-admin → WooCommerce → Settings → Advanced → REST API → Add key
  2. Description: DPP Agent, User: a service account, Permissions: Read
  3. Copy the consumer_key + consumer_secret pair (shown once)
  4. In DPP Agent → Integrations → Add WooCommerce → paste site_url and the credential pair as key:secret
  5. Connection test pulls 1 page and reports the product count
  6. First sync, sync_max_pages = 2-3
  7. Review draft DPPs in admin; verify variations folded correctly
  8. Full sync once mapping is locked
  9. Cron picks up the schedule (6h default, per-tenant configurable)

Compliance hooks

ESPR field WooCommerce path
espr.pid.gtin meta_data._global_unique_id or sku (if numeric 8–14)
espr.pid.product_name name
espr.pid.product_description short_description (HTML stripped, 600-char cap)
espr.pid.color attributes[name=pa_color].options[]
espr.pid.size attributes[name=pa_size].options[]
tex.product.brand_category categories[].name
tex.product.hero_image_url images[0].src

WooCommerce doesn't carry a first-class GTIN field — most stores record it under meta_data._global_unique_id (GS1 plugin), under _alg_ean (EAN Manager), or simply as the SKU. The mapper checks those candidates in order. If your store uses a different key, add a gtin_meta_key override in the integration's Edit modal.

WooCommerce has no supplier or supply-chain model — for AGEC traceability connect Delogue or TrusTrace alongside.

Troubleshooting

  • HTTP 401 on probe — key was revoked in WP-admin, or you pasted the pair without the : separator
  • HTTP 401 over HTTPS, HTTP 200 over HTTP — common WordPress quirk: some hosts strip the Authorization header on HTTPS. Set HTTP_AUTHORIZATION rewrite in .htaccess or switch to query-string auth (?consumer_key=...&consumer_secret=...)
  • GTIN missing on many rows — your store doesn't expose GTIN at a standard meta key. Configure the gtin_meta_key override or backfill the SKU field with the EAN
  • Variations not folded — include_variations = N, or the parent product is type=simple (no variations exist)
  • HTTP 502 / Cloudflare timeout — WP host can't serve the requested page_size in time; lower to 50 and re-run

Open a ticket at support@dppagent.com with the integration ID + log.