Guides
Start typing to search…

Operator Experience

This page describes how an Operator (or an authorized Customer User acting in admin) creates, configures, publishes, duplicates, and manages an Operation. It focuses on the business flow first, with API quicklinks at the end.

Keep in mind

  • Draft in DRAFT, then publish to ACTIVE, later deactivate to INACTIVE.
  • Type is immutable once set: default PRIVATE; only Operators can set PUBLIC.
  • Lines and account attachments are editable only in DRAFT.
  • You cannot delete an Operation if it is linked to any cart or order.
  • Operations are store‑scoped and localized (names and descriptions by locale).

🧰 Create an Operation

Route POST /admin/operations When: feature flag enabled, user has the right to create. Who: Operator or Customer User with the specific admin right. Only Operator users can set type=PUBLIC.

Example payload

POST /admin/operations
{
  "externalId": "BTS-2025",
  "type": "PRIVATE",
  "names": { "en": "Back-to-school 2025", "fr": "Rentrée 2025" },
  "description": { "en": "Staples and kits", "fr": "Fournitures et kits" },
  "startDate": "2025-09-01",
  "endDate": "2025-10-15"
}

Notes

  • Type: default is PRIVATE. If you set PUBLIC, only an Operator can do so. Once set, type cannot be changed.
  • Owner: only the creator can modify the Operation.
  • Store: the Operation is linked to a Store context.

➕ Add product lines with quantity rules

Route POST /admin/operations/{id}/lines When: only while DRAFT. What: for each product variant, set optional minQuantity, maxQuantity, and recommendedQuantity.

Example

POST /admin/operations/{operationId}/lines
[
  { "variantExternalId": "VAR-001", "minQuantity": 0, "maxQuantity": 50, "recommendedQuantity": 20 },
  { "variantExternalId": "VAR-002", "minQuantity": 1, "recommendedQuantity": 5 }
]

Good to know

  • Enforce Min ≤ Max when both exist; Recommended must be between bounds.
  • Lines remain locked once the Operation is ACTIVE or INACTIVE to protect existing orders.

Other actions

  • Read: GET /admin/operations/{id}/lines (paginated)
  • Update: PUT /admin/operations/{id}/lines (batch)
  • Delete: DELETE /admin/operations/{id}/lines (body lists product variants)

👥 Attach Accounts for PRIVATE Operations

Route POST /admin/operations/{id}/accounts When: only while DRAFT and type=PRIVATE. Who:

  • Customer User (admin) can only attach Accounts they are attached to.
  • Operator can attach any Account.

Example

POST /admin/operations/{operationId}/accounts
[ "ACC-001", "ACC-042" ]

Other actions

  • List: GET /admin/operations/{id}/accounts
  • Remove: DELETE /admin/operations/{id}/accounts

🚀 Publish, deactivate, reactivate

Route PATCH /admin/operations/{id}

  • Publish: { "status": "ACTIVE" }
  • Deactivate: { "status": "INACTIVE" }
  • Reactivate: { "status": "ACTIVE" } with valid future endDate

Example

PATCH /admin/operations/{operationId}
{ "status": "ACTIVE" }

Rules

  • Buyers see Operations only if status=ACTIVE and now is within [startDate, endDate].
  • When endDate passes, an ACTIVE Operation becomes INACTIVE automatically.
  • Avoid changing dates in ACTIVE unless strictly necessary for the campaign.

🧬 Duplicate an existing Operation

Route POST /admin/operations?fromOperationId={id} Creates a new Operation in DRAFT using the source Operation’s snapshot (without past usages). Update dates, lines, or attached accounts as needed, then publish.

🗑️ Delete rules

Route DELETE /admin/operations/{id}

  • Allowed only if there is no order linked to the Operation.
  • If linked objects exist, deletion is blocked by design.

🧭 Admin flow at a glance

sequenceDiagram
    participant Operator
    participant AdminAPI as Admin API

    Operator->>AdminAPI: POST /admin/operations (DRAFT)
    AdminAPI-->>Operator: Operation id

    Operator->>AdminAPI: POST /admin/operations/{id}/lines
    AdminAPI-->>Operator: Lines created

    alt PRIVATE type
        Operator->>AdminAPI: POST /admin/operations/{id}/accounts
        AdminAPI-->>Operator: Accounts attached
    else PUBLIC type
        AdminAPI-->>Operator: No account attachment required
    end

    Operator->>AdminAPI: PATCH /admin/operations/{id} (ACTIVE)
    AdminAPI-->>Operator: Published

    Operator->>AdminAPI: PATCH /admin/operations/{id} (INACTIVE)
    AdminAPI-->>Operator: Deactivated

    Operator->>AdminAPI: POST /admin/operations?fromOperationId={id}
    AdminAPI-->>Operator: New DRAFT copy

🧪 Practical tips

  • Decide type early; you will not be able to change PUBLIC ↔ PRIVATE later.
  • Configure Recommended quantities that are already valid pack multiples to reduce buyer friction.
  • For very large Operations, rely on pagination in your admin UI for lines and accounts.
  • Use future startDate to schedule visibility without relying on auto‑activation.

✅ Pre‑publish checklist

  • The Operation type is correct (PUBLIC or PRIVATE).
  • Localized name/description filled for key locales.
  • Store scope selected.
  • Lines configured with Min/Max/Recommended where needed.
  • For PRIVATE, required Accounts attached.
  • Dates reviewed and endDate in the future.

🔗 API quicklinks

Required headers (Admin)

  • dj-client: OPERATOR (or ACCOUNT for authorized admin actions)
  • dj-api-key: your key
  • dj-store, dj-store-view (optional, for store scoping)
  • locale (optional, for localized fields)

Operations (create/read/update/status/delete)

Operation Lines (product variants & quantities)

Accounts (PRIVATE Operations only)


📘

Notes

  • type (PUBLIC vs PRIVATE) is immutable once set; only OPERATOR can set PUBLIC on creation.
  • Lines and account attachments are editable only in DRAFT, to protect carts/orders once the Operation is ACTIVE/INACTIVE.

Updated 17 days ago