Promotions Service

Back

Overview

Promotions represent discounts or special offers that can be applied to sales orders.

They provide a consistent reference for:

• time-limited promotions
• one-time or recurring discounts
• minimum order thresholds
• tracking promo code usage

Promotions are tenant-scoped and can be applied to specific entities or globally.

All operations are tenant-aware and scoped to the current tenant.

Endpoints

Back to Reference

GET

/api/v1/Promotions/HasPromoCodeBeenUsed/{promoId}/{entityId}

Checks if a specific promo code has already been used by an entity.

Behavior:

• Returns 200 OK if the promo code has been used
• Returns 404 Not Found if the promo code has not been used

Authorization:

• Requires Bearer Token

GET

/api/v1/Promotions/GetAllPromotions

Returns all promotions for the current tenant.

Behavior:

• Returns a list of promotions
• Returns 404 if no promotions exist

Authorization:

• Requires Bearer Token

GET

/api/v1/Promotions/GetPromotionById/{id}

Returns a single promotion by its numeric identifier.

Behavior:

• Looks up a promotion by ID
• Returns 404 if the promotion does not exist

Authorization:

• Requires Bearer Token

GET

/api/v1/Promotions/GetPromotionByPromoCode/{promoCode}

Returns a single promotion by its unique promo code.

Behavior:

• Promo codes must be unique
• Returns 404 if no promotion matches the provided code

Authorization:

• Requires Bearer Token

POST

/api/v1/Promotions/AddNewPromotion

Creates a new promotion.

Request body:

• PromoCode (string, required)
• StartDate (DateTime, required)
• EndDate (DateTime, required)
• MoneyOff (decimal, optional)
• PercentageDiscount (decimal, optional)
• MinOrderLevel (decimal, required)
• IsOneUse (bool, optional)
• IsActive (bool, optional)

Behavior:

• Validation is handled in the service layer
• Promo code must be unique
• IsActive is optional and defaults to database settings
• Successful creation writes an audit log entry

Errors:

• Returns 400 if validation -

Authorization:

• Requires Bearer Token

PUT

/api/v1/Promotions/UpdatePromotionById/{id}

Updates an existing promotion.

Request body:

• Same fields as POST

Behavior:

• ID is taken from the route
• Partial updates are not supported
• Successful update writes an audit log entry

Errors:

• Returns 400 if validation - or promotion does not exist

Authorization:

• Requires Bearer Token

DELETE

/api/v1/Promotions/DeletePromotionById/{id}

Deletes a promotion by its ID.

Behavior:

• Performs a hard delete
• Record is permanently removed from the database
• Successful deletion writes an audit log entry

Errors:

• Returns 400 if promotion does not exist or deletion -

Authorization:

• Requires Bearer Token

Notes

• Validation is enforced in the service layer
• Deleting a promotion does not cascade changes to related orders
• Promo codes are expected to be unique
• All state-changing operations are audited
• Internal errors are logged but not exposed to clients