Promotions Service
Cova's advanced promotions let retailers create and modify complex promotions, such as:
- Buy X Get Y
- Bundles
- Buy One Get One
- Percent or dollar discounts
The Promotions Service endpoints let you query these promotions so you can display or apply them outside of Cova.
Base URL:
https://api.covasoft.net/promotions
Definitions
| Term | Definition |
|---|---|
| Company | A business, firm, or corporation that may operate one or many locations as physical brick-and-mortar stores and/or a virtual ecommerce presence. Most calls to Cova APIs require a CompanyId, which is included in every integration onboarding package. |
| Location | A physical store or dispensary that customers can visit to purchase cannabis and accessories. A company may have many locations. Each location has its own inventory and may define its own prices. Many Cova API endpoints require a location ID, commonly called an EntityId. Promotion queries don't require one, but each promotion has a list of the locations where it's active. |
| Entity | A generic term for locations, divisions, groups, and the company itself. A multi-location company's entity tree usually reflects the real world: the company is the root, divisions and groups are branches under it, and locations are the leaves. Promotions use the entity tree to configure which locations they're enabled at. |
| Cart | A list of products with their quantities and prices: a sale before it's tendered. Each line item in the cart has the same per-unit price, CatalogId, and package number. Adding a duplicate product increases the line item's quantity rather than adding another line item. |
| Product | A single product defined within a company's catalog. |
| Package | Units of batch-tracked products are grouped into Packages. Packages have information associated with the specific inventory included in each package. (e.g. Test Results, Expiry Date) |
| CatalogId | Also known as ProductId. A GUID/UUID value. |
Endpoints
The Promotions Service has two endpoints. Which one you need depends on whether you only want to show that products are on promotion, or actually apply the promotions.
| Endpoint | Use it to |
|---|---|
| Promotions by capabilities | Apply promotions to a cart. Returns the full details of each promotion, filtered to the promotion types and conditions your integration supports. |
| Promotions for menu board | Show products as "on promotion". Returns each promotion with the list of products it can apply to, but no information about the discount or how to apply it. |
Promotions by capabilities
GET https://api.covasoft.net/promotions/v1/Companies/{companyId}/ConditionCapabilities/{condBits}/PromotionTypeCapabilities/{proBits}/Promotions
Returns a list of promotions filtered by two capability bitmasks: one for the conditions and one for the promotion types your integration has implemented. Only promotions your integration can handle are returned. There should be no need to call this endpoint more than once a day.
Promotion
| Name | Type | Description |
|---|---|---|
PromotionId | guid | A unique identifier for this promotion. |
CompanyId | int32 | The company this promotion belongs to. Always matches the companyId in the URL. |
Name | string | The name of the promotion. |
Status | string | Active or Deleted. Always Active on this endpoint. Doesn't reflect the promotion's scheduled start or end. |
HumanReadablePromotionType | string | A human-readable label for the type of promotion. One of BOGO, Buy X Get Y, Bundle, Dollar Off or Percent Off. |
EnabledAtLocationIds | int32[] | The IDs of the locations where this promotion applies. |
ICalVEventSchedule | string | An iCalendar-formatted string with the promotion's schedule. See Scheduling. |
PromotionType | PromotionType | Most of the details about how to apply the promotion and when it's applicable. |
CartCondition | CartCondition | A nestable tree of the requirements a cart must meet to apply this promotion. |
LineCondition | LineCondition | A nestable tree of the requirements a line item must meet to be considered for this promotion. |
CreatedByUserId | int32 | The ID of the user who created this promotion. |
CreatedDateTimeUTC | DateTime | When this promotion was created, in UTC. |
Version | int32 | The version of this promotion. Incremented by 1 for each change made to it. |
Promotions for menu board
GET https://api.covasoft.net/promotions/v1/Companies/{companyId}/PromotionsForMenuBoard
Returns all promotions for a company, each with a list of the CatalogIds that may qualify for the discount if all of its conditions are met. It doesn't need capability bitmasks, so it's simpler to consume.
This endpoint is for integrators who want to display items as "on promotion". It doesn't say what the discount is or how to apply it. To apply promotions, use Promotions by capabilities instead.
The CatalogIds lists are calculated and cached for approximately an hour (subject to change without notice).
PromotionForMenuBoard
| Name | Type | Description |
|---|---|---|
PromotionId | guid | A unique identifier for this promotion. |
CompanyId | int32 | The company this promotion belongs to. Always matches the companyId in the URL. |
Name | string | The name of the promotion. |
Status | string | Active or Deleted. Always Active on this endpoint. Doesn't reflect the promotion's scheduled start or end. |
HumanReadablePromotionType | string | A human-readable label for the type of promotion. One of BOGO, Buy X Get Y, Bundle, Dollar Off or Percent Off. |
EnabledAtLocationIds | int32[] | The IDs of the locations where this promotion applies. |
ICalVEventSchedule | string | An iCalendar-formatted string with the promotion's schedule. See Scheduling. |
CreatedByUserId | int32 | The ID of the user who created this promotion. |
CreatedDateTimeUTC | DateTime | When this promotion was created, in UTC. |
Version | int32 | The version of this promotion. Incremented by 1 for each change made to it. |
CatalogIds | guid[] | The CatalogIds of the products this promotion can apply to. |
Next steps
To apply promotions in your integration:
- Decide which promotion types and conditions you can support, and build your capability bitmasks.
- Learn the promotion types and the conditions that control which carts and products they apply to.
- Check each promotion's schedule.
- Apply the promotions to the cart.