Skip to main content

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​

TermDefinition
CompanyA 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.
LocationA 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.
EntityA 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.
CartA 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.
ProductA single product defined within a company's catalog.
PackageUnits 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)
CatalogIdAlso 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.

EndpointUse it to
Promotions by capabilitiesApply promotions to a cart. Returns the full details of each promotion, filtered to the promotion types and conditions your integration supports.
Promotions for menu boardShow 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​

NameTypeDescription
PromotionIdguidA unique identifier for this promotion.
CompanyIdint32The company this promotion belongs to. Always matches the companyId in the URL.
NamestringThe name of the promotion.
StatusstringActive or Deleted. Always Active on this endpoint. Doesn't reflect the promotion's scheduled start or end.
HumanReadablePromotionTypestringA human-readable label for the type of promotion. One of BOGO, Buy X Get Y, Bundle, Dollar Off or Percent Off.
EnabledAtLocationIdsint32[]The IDs of the locations where this promotion applies.
ICalVEventSchedulestringAn iCalendar-formatted string with the promotion's schedule. See Scheduling.
PromotionTypePromotionTypeMost of the details about how to apply the promotion and when it's applicable.
CartConditionCartConditionA nestable tree of the requirements a cart must meet to apply this promotion.
LineConditionLineConditionA nestable tree of the requirements a line item must meet to be considered for this promotion.
CreatedByUserIdint32The ID of the user who created this promotion.
CreatedDateTimeUTCDateTimeWhen this promotion was created, in UTC.
Versionint32The 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​

NameTypeDescription
PromotionIdguidA unique identifier for this promotion.
CompanyIdint32The company this promotion belongs to. Always matches the companyId in the URL.
NamestringThe name of the promotion.
StatusstringActive or Deleted. Always Active on this endpoint. Doesn't reflect the promotion's scheduled start or end.
HumanReadablePromotionTypestringA human-readable label for the type of promotion. One of BOGO, Buy X Get Y, Bundle, Dollar Off or Percent Off.
EnabledAtLocationIdsint32[]The IDs of the locations where this promotion applies.
ICalVEventSchedulestringAn iCalendar-formatted string with the promotion's schedule. See Scheduling.
CreatedByUserIdint32The ID of the user who created this promotion.
CreatedDateTimeUTCDateTimeWhen this promotion was created, in UTC.
Versionint32The version of this promotion. Incremented by 1 for each change made to it.
CatalogIdsguid[]The CatalogIds of the products this promotion can apply to.

Next steps​

To apply promotions in your integration:

  1. Decide which promotion types and conditions you can support, and build your capability bitmasks.
  2. Learn the promotion types and the conditions that control which carts and products they apply to.
  3. Check each promotion's schedule.
  4. Apply the promotions to the cart.