API Reference

Digital Retail Engine exposes the following six services built on the SAP CAP framework.

Services

Service	Path	Protocol	Consumers	Description
Admin Service	/admin/	OData V4	Fiori Elements admin portal	Full CRUD for promotion management, budgets, coupons, campaigns
Public API	/api/v1/	OData V4 + REST	External integrators, ERP systems	Stable external contract — collection catalogue, read/write matrix, scopes, tenant isolation, bulk import
POS Service	/pos	REST	POS terminals, mobile apps	Real-time evaluation, coupons, article import, transaction confirmation
Reporting Service	/reporting/	OData V4	Fiori analytics apps	Read-only analytics, performance reports, CSV export
Sync Service	/sync	REST	Local-store instances	Heartbeat, promotion sync, store registration
Master Data Ingest	/api/v1/master-data	SOAP + REST (mTLS)	S/4HANA DRFOUT (SOAP) / integrators (REST)	S/4HANA article master data replication

Admin Service (OData V4)

Standard OData v4 conventions apply:

• Metadata: GET /admin/$metadata
• Entity sets: GET /admin/Promotions
• Single entity: GET /admin/Promotions(<key>)
• Navigation: GET /admin/Promotions(<key>)/posGroups (real composition; conditions are queried separately — see below)
• Filtering: GET /admin/Promotions?$filter=status eq 'ACTIVE'
• Expansion: GET /admin/Promotions?$expand=posGroups,calculationConfig,campaign (there is no conditionGroups — conditions are flat)
• Draft editing: Supported for most entities

Conditions and DiscountActions are flat (no conditionGroups tree). They point back to their promotion via a promotion association, so query them with a filter rather than an expand:

GET /admin/Conditions?$filter=promotion_ID eq <promotionID>
GET /admin/DiscountActions?$filter=promotion_ID eq <promotionID>

See the Admin Service reference for the full entity catalogue.

Public API (/api/v1)

The stable external contract for integrators. Dual-mounted as OData V4 and REST on the same /api/v1 path. Two OAuth scopes gate it: PublicApi.Read for GET, PublicApi.Write for writes. Every writable collection is tenant-scoped.

• Metadata: GET /api/v1/$metadata
• Writable business entities: Promotions, Budgets, Articles, CouponTypes, Stakeholders, Campaigns, PromotionTemplates, PromotionPilotConfigs, … (full CRUD)
• Read-only collections: AuditLogs, CalculationLogs, RedemptionLogs, code lists, …
• Bulk import: POST /api/v1/<Entity>:bulk-import → tracked via ImportJobs

See the Public API reference for the collection catalogue, read/write matrix, scopes, the new Campaigns/AuditLogs/PromotionTemplates/PromotionPilotConfigs exposures, and tenant isolation; and the Article Import API for the bulk-import body schema.

POS Service (REST)

The POS Service uses plain REST (not OData). All endpoints accept POST requests with JSON bodies.

• Evaluate: POST /pos/v2/evaluate
• Simulate: POST /pos/v2/simulate
• Confirm: POST /pos/v2/confirm
• Side-effects poll: GET /pos/v2/transactions/{id}/{counter}/side-effects
• Coupon ops: POST /pos/coupons/{validate|reserve|redeem|cancel|activate|issue}
• Article import: POST /pos/articles/import (sync) or POST /pos/articles/import-batch (async)
• Heartbeat: GET /pos/heartbeat

Reporting Service (OData V4)

Read-only OData v4 service for analytics. Supports standard OData query options ($filter, $orderby, $top, $skip).

• Reports: GET /reporting/PromotionPerformance, GET /reporting/BudgetUtilization, etc.
• CSV export: POST /reporting/exportCsv

Authentication

All endpoints require authentication:

• Development: Basic auth with mocked users
• Production: OAuth 2.0 via SAP XSUAA (JWT bearer tokens)

Service Documentation

• Admin Service -- Entity details, supported operations, and custom actions
• Public API -- External /api/v1 contract: collection catalogue, read/write matrix, scopes, tenant isolation
• Article Import API -- bulkImport body schema, ImportJobs tracking, idempotency
• POS Service -- REST endpoints for POS terminal integration
• Reporting Service -- Analytics reports and CSV export