Troubleshooting & FAQs

This page lists common symptoms, root causes, and fixes for Operations, plus short FAQs.

Quick orientation

• Feature flag: the tenant-level flag OPERATIONS must be enabled.
• Buyers can only use ACTIVE Operations within the start/end window and correct Store.
• Product lines inside an Operation remain subject to Catalog Views.
• Lines and Accounts are editable only in DRAFT.
• Deleting an Operation is blocked if carts or orders are linked.
• Shop client: buyer endpoints require dj-client=ACCOUNT.

🚨 Common issues

1) Can’t find my Operation in the shop list

Symptom: /v1/shop/operations does not show the Operation. Likely causes & fixes

• Status is not ACTIVE → publish via PATCH /v1/operations/{id} with { "status": "ACTIVE" }.
• Dates out of window → set startDate and endDate so that now is within [startDate, endDate].
• Store mismatch → ensure the Operation is linked to the same Store as the buyer context.
• PRIVATE without attachment → attach the buyer’s Account to the Operation.

2) Operation detail returns 404

Symptom: GET /v1/shop/operations/{id} returns 404. Why: Only ACTIVE Operations within the time window are accessible. Fix: Publish, adjust dates, and verify Store scope.

3) Some products are missing in the Operation detail

Symptom: The buyer does not see all lines. Why: Product visibility follows Catalog Views for the Account. Fix: Update Catalog Views to expose those products for the Account.

4) Default quantities look wrong

Symptom: When starting from an Operation, line quantities are unexpected. Expected rule: Recommended, else Min, else 1. Fix: Check per-line recommendedQuantity; if absent, verify minQuantity.

5) Quantity update is rejected

Symptom: Adding or updating a line fails. Checks applied

• Min/Max bounds violated
• Pack multiples invalid
• Insufficient stock Fix: Respect pack rules and Min/Max; reduce to available stock.

6) Cannot delete an Operation

Symptom: DELETE /v1/operations/{id} is rejected. Why: Deletion is blocked if any cart or order is linked. Fix: Ensure no linked objects remain; otherwise keep as INACTIVE.

🧾 Error reference

Messages are indicative; use your platform’s standard error payloads. Do not add new parameters or fields.

🔎 Error routing flow (high level)

graph LR
  R[Request] --> S[Status & date<br>eligibility]
  S -->|Eligible| V[Visibility checks<br>type, store, account]
  S -->|Not eligible| ERR404[404 / filtered out]
  V --> C[Catalog Views for lines]
  C --> OK[Success]

  %% ---------- Styles ----------
  classDef total fill:#e8f1ff,stroke:#2f6feb,stroke-width:2px,color:#0b3d91;
  classDef diff fill:#fff4e5,stroke:#f59e0b,stroke-width:2px,color:#7a3e00;
  classDef acct fill:#f5e9ff,stroke:#8a2be2,stroke-width:2px,color:#3b0764;
  classDef view fill:#ede9fe,stroke:#7c3aed,stroke-width:1.5px,color:#1e1b4b;
  classDef union fill:#e9d5ff,stroke:#6d28d9,stroke-width:1.5px,color:#3b0764;
  classDef visible fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#064e3b;
  classDef op fill:#e0f7fa,stroke:#06b6d4,stroke-width:2px,color:#065f46;
  classDef inter fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#7f1d1d;
  classDef resp fill:#f2f4f7,stroke:#475569,stroke-width:2px,color:#111827;

  class S,V,C diff;
  class OK visible;
  class ERR404 inter;

  style R rx:8,ry:8
  style S rx:8,ry:8
  style V rx:8,ry:8
  style C rx:8,ry:8
  style OK rx:8,ry:8
  style ERR404 rx:8,ry:8

This flow explains why a buyer might not see an Operation or some of its lines.

🗑️ Delete guard

graph LR
  D[DELETE /v1/operations/#123;id#125;] --> L[Check linked<br>carts/orders]
  L -->|Links exist| REJ[Reject delete<br>keep INACTIVE]
  L -->|No links| OK[Delete allowed]

  %% ---------- Styles ----------
  classDef total fill:#e8f1ff,stroke:#2f6feb,stroke-width:2px,color:#0b3d91;
  classDef diff fill:#fff4e5,stroke:#f59e0b,stroke-width:2px,color:#7a3e00;
  classDef acct fill:#f5e9ff,stroke:#8a2be2,stroke-width:2px,color:#3b0764;
  classDef view fill:#ede9fe,stroke:#7c3aed,stroke-width:1.5px,color:#1e1b4b;
  classDef union fill:#e9d5ff,stroke:#6d28d9,stroke-width:1.5px,color:#3b0764;
  classDef visible fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#064e3b;
  classDef op fill:#e0f7fa,stroke:#06b6d4,stroke-width:2px,color:#065f46;
  classDef inter fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#7f1d1d;
  classDef resp fill:#f2f4f7,stroke:#475569,stroke-width:2px,color:#111827;

  class L diff;
  class REJ inter;
  class OK visible;

  style D rx:8,ry:8
  style L rx:8,ry:8
  style REJ rx:8,ry:8
  style OK rx:8,ry:8

Deletion is prevented when carts or orders are linked to preserve history and avoid data inconsistencies.

❓ FAQs

Q: Can I change PUBLIC to PRIVATE (or vice‑versa) after creation? A: No. Type is immutable once set. Default is PRIVATE; only Operators can set PUBLIC.

Q: Can I edit lines or attached Accounts after publishing? A: Only in DRAFT. After ACTIVE (or INACTIVE), lines and attachments are locked to protect existing carts and orders.

Q: What happens if endDate has passed? (Not yet released) A: An ACTIVE Operation becomes INACTIVE automatically. Reactivating requires a valid future endDate.

Q: Can buyers add items not in the Operation? A: Yes. Standard rules apply; Operation constraints only apply to Operation lines.

Q: Why does the price not match the Operation price? (Not yet released for specific operation prices) A: Pricing precedence is Operation → Account → Tag → Public. If no Operation price exists for the line, the next level applies.

🔗 API quicklinks (read-only)

• Admin: GET /v1/operations — ADM-OPERATION-550, GET /v1/operations/(operationId) — ADM-OPERATION-500, GET /v1/operations/operationId)/lines — ADM-OPERATION-551, GET /v1/operations/(operationId)/accounts — ADM-OPERATION-552, PATCH /v1/operations/(operationId) — ADM-OPERATION-201, DELETE /v1/operations/(operationId) — ADM-OPERATION-300
• Shop: `GET /v1/shop/operations — OPERATION-550, GET /v1/shop/operations/(operationId) — OPERATION-500