¶ Feature
This feature is the implementation of discount coupons that can be applied to a cart generating a global discount over the whole cart.
¶ API
¶ Model
Besides the standard entity properties (id, createdAt, updatedAt, companyId), the Coupon entity properties are:
- Code (
code): [string, required] The code to be entered to apply the coupon. It is a secret value that only the owner should have. - Expires At (
expiresAt): [datetime, required] The expiration date and time that gives the window of time where the coupon is valid. - Title (
title): [string] The text to show in UIs that represents the coupon. - Applied At (
appliedAt): [datetime] Date and time when the code was applied. If not present or empty, it means the coupon has not been used. - Applied By (
appliedBy): [object]: Object containing the usertypeandidof the user that applied the coupon to the cart (she/he could be an operator adding a coupon for a customer, a customer or a guest). - Cart Id (
cartId): [string]: Identifier of the cart where the coupon was applied. If not present or empty, it means that the coupon has not been applied. - Amount (
amount): [number, required]: The amount of the maximum discount applied when using the coupon. - Currency (
currencyCode): [string, required]: The currency that corresponds to the amount of the coupon. It restricts the coupon to be applied only to carts with that currency.
The Cartentity is updated adding the property:
- Coupon Ids (
coupons): [object[]] An array of basic coupons information of the coupons applied to the cart. If not present of empty it means that the cart has no applied coupons.
¶ Services
Services to manage and use coupons.
¶ CRUD
- Create:
POST /coupons(availability:operator) - Update:
PATCH /coupons/{id}(availability:operator) - Delete:
DELETE /coupons/{id}(availability:operator) - List:
GET /coupons(availability:operator) - Count:
GET /coupons/count(availability:operator) - Get by Id:
GET /coupons/{id}(availability:operator)
¶ Specific
- Apply:
POST /carts/{id}/apply-coupon/{couponCode}(availability:guest,customer,operator) - Remove:
DELETE /carts/{id}/coupons/{couponId}(availability:guest,customer,operator)
¶ Behavior
- When a coupon is created, it is available to be applied to any cart by adding it by its code.
- When a coupon is applied to a cart, it is available until the purchase is confirmed. So it could happen that the same coupon is added to multiple carts that have been not converted to orders. The first cart that completes the checkout receives the coupon discount. The rest will fail on the place operation until the -already used- coupon is removed.
- Coupons can be applied to a cart by its owner or by an operator. They can also be removed.
- Coupon discounts are applied to the global discount of the cart.
- Multiple coupons can be applied to the same cart.
- Each coupon can only be applied once to the same cart.
¶ Admin UI
A new menú "Coupons" in the Admin would be available under "Pricing".
The Coupons section would show a grid with the columns:
- Code (field
code): Sortable, searchable. - Title (field
title): Sortable, searchable. - Amount (expression showing fields
currencyCodeandamount): Sortable, searchable. - Created At (field
createdAt): Sortable, searchable. - Applied At (field
appliedAt): Sortable, searchable. If the field is not present or empty, show:"Not used yet"if not expired, otherwise show"Expired". - Applied By (expression showing
appliedBy.id + " (" + appliedBy.type + ")"): Sortable, searchable. If the field is not present or empty, show the empty string"". - Expires At (field
expiresAt): Sortable, searchable. - Actions: Include buttons to:
- Edit (inline edition): Expands the row showing the editable inputs Expires At, Title, Amount, Currency and a "Save" button that saves the coupon changes and collapses the row.
- Delete (with confirmation)
The grid is by default sorted by createdAt DESC (newer first).
¶ Store UI
The Store checkout would have an input to enter coupon codes.
And show the already applied ones.
Each coupon UI includes an "X" button to remove the coupon from the cart.
In the cases where the total discount of the applied coupons is not fully used (when the cart total is less than the coupons discount), a warning must be shown in the order summary section of the checkout.
If one or more coupons are removed from the cart and the discount becomes less than the cart total, the warning is automatically removed.
After each application or removal of coupons, the cart subtotals must be refreshed in the UI.