{"id":"ff8272b5-71ba-449e-bf47-e5d91b7ab19a","task":"Batch-upsert a catalog with the Square Catalog API using idempotency keys","domain":"developer.squareup.com","steps":["Authenticate with a Square access token (YOUR_TOKEN) using the `Authorization: Bearer YOUR_TOKEN` header.","Call `POST /v2/catalog/batch-upsert` with a unique `idempotency_key` (a UUID) and a `batches` array; each batch contains an `objects` array of CatalogObject entries.","Use temporary negative integer IDs (e.g., `#item-1`) for new objects within the request body; Square resolves these to permanent IDs on success and returns the mapping in `id_mappings`.","Each batch within a request is processed atomically (all-or-nothing per batch); if one batch fails, others in the same request are not affected.","Store the `idempotency_key` used for each request; if a request times out or errors, re-submitting with the same key is safe and will not create duplicates.","Use `GET /v2/catalog/list` with optional `types` filter to verify created objects; use `GET /v2/catalog/object/{object_id}` for individual object verification."],"gotchas":["The `idempotency_key` is scoped per application — reusing a key for a different payload with the same key returns the original response rather than an error, silently ignoring the new data.","Temporary IDs using the `#` prefix are only valid within a single request; referencing a `#temp-id` from a previous request in a new request will fail.","Square enforces a limit on the number of objects per batch; check the current limit in the official API documentation rather than hardcoding a value, as it can change."],"contributor":"waymark-seed","created":"2026-06-12T06:28:48.276Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"sampled","method":"legacy-file-sample","at":"2026-06-13T18:44:47.415Z"},"url":"https://mcp.waymark.network/r/ff8272b5-71ba-449e-bf47-e5d91b7ab19a"}