OpenCannabis: Commerce Extension

  • Version 1.0
  • Status: RAW

Status of this Memo

This specification's current status is considered RAW, i.e. pre-DRAFT. Distribution of this memo is unlimited.

Abstract

This document describes an extension to the OpenCannabis Specification, version 1, that introduces commerce- related structures, protocols, statuses, types, and so on.

"Commerce" in this context, refers to:

  • Structures for discounts
  • Items
  • Orders
  • Currencies
  • Product Variants
  • Scheduling

Table of Contents


Protocol Definition

opencannabis.commerce

Specifies a commercial discount structure, order structure, product variance, currency type, etc.

Discount id:string spec:DiscountSpec name:string label:string description:string modified_at:opencannabis.temporal.Instant created_at:opencannabis.temporal.Instant DiscountSpec type:DiscountType basis:DiscountBasis percentage:double static_value:double DiscountBasics ITEM:0 ORDER_SUBTOTAL:1 ORDER_TOTAL:2

DiscountType CUSTOM:0 STATUTORY:1 COMMERCIAL:2 DeliveryDestination address:opencannabis.geo.Address instructions:string Customer person:opencannabis.person.Person foreign_id:string user_key:string Item key:opencannabis.base.ProductKey variant:VariantSpec count:uint32 VariantSpec variant:ProductVariant weight:opencannabis.structs.pricing.PricingWeightTier size:string color:string Product Variant WEIGHT:0 COLOR:1 SIZE:2 Order id:string type:OrderType status:OrderStatus customer:Customer scheduling:OrderScheduling destination:DeliveryDestination notes:string item:Item action_log:StatusCheckin created_at:opencannabis.temporal.Instant subtotal:double updated_at:opencannabis.temporal.Instant sid:string OrderKey id:string OrderScheduling scheduling:SchedulingType desired_time:opencannabis.temporal.Instant

StatusCheckin status:OrderStatus instant:opencannabis.temporal.Instant message:string OrderStatus PENDING:0 APPROVED:1 REJECTED:2 ASSIGNED:3 EN_ROUTE:4 FULFILLED:5 OrderType PICKUP:0 DELIVERY:1 SchedulingType ASAP:0 TIMED:1

CurrencyValue value:float type:CurrencyType fiat:FiatCurrency custom:string CurrencyType FIAT:0 REAL:1 CRYPTO:2 FiatCurrency USD:0 PricingDescriptor type:PricingType unit:UnitPricingDescriptor weighted:WeightedPricingDescriptor

PricingTierAvailability offered:bool available:bool ProductPricing discounts:SaleDescriptor manifest:PricingDescriptor UnitPricingDescriptor price:opencannabis.commerce.CurrencyValue status:PricingTierAvailability discounts:SaleDescriptor

WeightedPricingDescriptor weight:PricingWeightTier tier:UnitPricingDescriptor weight_in_grams:float PricingType UNIT:0 WEIGHTED:1 PricingWeightTier OTHER:0 GRAM:1 HALFGRAM:2 QUARTERGRAM:3 DUB:4 EIGHTH:5 QUARTER:6 HALF:7 OUNCE:8 POUND:9 KILO:10 TON:11

BOGODiscount trigger:uint32 reward:uint32 LoyaltyDiscount trigger:uint32 reward:uint32 PercentDiscount discount:uint32 SaleDescriptor type:SaleType effective:opencannabis.temporal.Instant expiration:opencannabis.temporal.Instant percentage_off:PercentageDiscount bogo:BOGODiscount loyalty:LoyaltyDiscount SaleType PERCENTAGE_REDUCTION:0 VALUE_REDUCTION:1 BOGO:2 LOYALTY:3

Discount

Specifies a discount to be applied during a purchase or order.

Field Type Label Description
id string ID code for this discount entry.
spec DiscountSpec Specification for how this discount behaves.
name string Back-office name for this tax.
label string User-visible name for this tax.
description string Narrative description for this discount, to be displayed to back-office and end-users in some special circumstances.
modified_at opencannabis.temporal.Instant Last time this discount was modified.
created_at opencannabis.temporal.Instant When this discount was created.

DiscountSpec

Specifies the concept of a discount, and how it is set to behave.

Field Type Label Description
type DiscountType Type of discount to apply.
basis DiscountBasis Basis to form when calculating the discount.
percentage double Percentage rate for the discount.
static_value double Flat rate for the discount.

DiscountBasis

Enumerates operational calculation modes for discounts.

Name Number Description
ITEM 0 The discount is calculated per-item.
ORDER_SUBTOTAL 1 The discount is calculated from the order subtotal, before tax.
ORDER_TOTAL 2 The discount is calculated from the order total, after tax.

DiscountType

Enumerates types of discounts that may be applied.

Name Number Description
CUSTOM 0 Some custom discount applied at the time of purchase.
STATUTORY 1 Statutorily-mandated discount, for instance, for medical-only patients.
COMMERCIAL 2 Commercial discount, for instance, for vendors, brand ambassadors, and staff.

DeliveryDestination

Specifies the location to deliver the order.

Field Type Label Description
address opencannabis.geo.Address Location/address to send a delivery order.
instructions string Special delivery instructions

Customer

Customer identity.

Field Type Label Description
person opencannabis.person.Person Person attached to this customer.
foreign_id string Partner-scoped foreign system ID.
user_key string Resolved subject user key.

Item

Specifies the Item via the product key as well as weight, and count of product ordered

Field Type Label Description
key opencannabis.base.ProductKey Key for the item, which is the type and ID, combined.
variant VariantSpec repeated Variance specifications for this item.
count uint32 Count of this item requested.

VariantSpec

Specifies if it is a weighted product or a unit priced product and attaches that to item.

Field Type Label Description
variant ProductVariant Specifies the variance type for this spec.
weight opencannabis.structs.pricing.PricingWeightTier Specifies a product weight, when varying by weight.
size string Specifies a size option for the product.
color string Specifies a color option for the product.

ProductVariant

Specifies weight and price of ordered product

Name Number Description
WEIGHT 0 Variance by product weight.
COLOR 1 Variance by product color.
SIZE 2 Variance by product size.

Order

Represents a full order submitted to the server for fulfillment, from an end-user, for delivery or express pickup.

Field Type Label Description
id string ID assigned to the order by the server, and potentially nominated by the client.
type OrderType Type of order requested - either PICKUP or DELIVERY.
status OrderStatus Current status of this order.
customer Customer Customer that submitted this order.
scheduling OrderScheduling Scheduling spec for this order.
destination DeliveryDestination Location for delivery, if applicable.
notes string User-provided notes or questions, if any.
item Item repeated Items being ordered.
action_log StatusCheckin repeated Actions taken on this order.
created_at opencannabis.temporal.Instant When this order was created.
subtotal double Order subtotal.
updated_at opencannabis.temporal.Instant When this order was created.
sid string Session ID that was active when this order was submitted.

OrderKey

Specifies a unique key for a commercial order.

Field Type Label Description
id string Order ID, assigned by the server upon creation.

OrderScheduling

Specifies the desired timing of the delivery order.

Field Type Label Description
scheduling SchedulingType Scheduling type, either 'ASAP' or a target time.
desired_time opencannabis.temporal.Instant Desired delivery time, if specified.

StatusCheckin

Specifies a moment at which an order changed status, when it happened, and, optionally, why.

Field Type Label Description
status OrderStatus Status the order moved to.
instant opencannabis.temporal.Instant Instant the order was moved to this status.
message string Message or reason given for this status change, if any.

OrderStatus

Enumeration for current status of order

Name Number Description
PENDING 0 Order has been submitted and is not yet approved.
APPROVED 1 Order has been approved for fulfillment.
REJECTED 2 Order could not be fulfilled for some reason.
ASSIGNED 3 Order has been assigned.
EN_ROUTE 4 Order is en-route to the user (for delivery).
FULFILLED 5 Order has been fulfilled and is considered complete.

OrderType

Specifies the type of order requested.

Name Number Description
PICKUP 0 Express pickup order.
DELIVERY 1 Delivery order.

SchedulingType

Specifies the types of delivery timing.

Name Number Description
ASAP 0 As soon as possible.
TIMED 1 Desired time.

CurrencyValue

Specifies a value, with a particular currency specification as the unit.

Field Type Label Description
value float Numeric amount value to specify.
type CurrencyType Categorical or general type for the specified currency.
fiat FiatCurrency Fiat currency selection for a given currency value.
custom string Custom currency, by name or symbol, for a given currency value.

CurrencyType

Specifies known or explicitly supported currency types.

Name Number Description
FIAT 0 Fiat-based currency, such as the US Dollar.
REAL 1 Real currency, such as gold or other raw materials.
CRYPTO 2 Crypto-currency, based on unique cryptographic signatures or proof-of-work.

FiatCurrency

Specifies known or explicitly supported fiat currencies.

Name Number Description
USD 0 Specifies 'US Dollar' as a currency.

PricingDescriptor

Specifies a descriptor for product pricing, which specifies the price configuration for one independent price tier in a given set of pricing tiers for a product.

Field Type Label Description
type PricingType Type of pricing tier this descriptor is specifying.
unit UnitPricingDescriptor Unit-based pricing information, with no variance in price change.
weighted WeightedPricingDescriptor Weight-based pricing information, with prices assgined to specific or known weights.

PricingTierAvailability

Specifies availability and stock status flags for a particular pricing tier.

Field Type Label Description
offered bool Specifies whether a particular pricing tier is offered at all. This would be interpreted to indicate whether a particular pricing tier is 'ever available' or 'ever offered.'
available bool Specifies whether a particular pricing tier is currently available. This would be interpreted to indicate whether a particular pricing tier is 'currently available,' 'currently in stock,' or 'currently offered.'

ProductPricing

Pricing manifest for a product, with the combined tiers and top-level discounts that are currently configured for a given sellable material or unit of merchandise.

Field Type Label Description
discounts SaleDescriptor repeated Discounts that should apply across all pricing tiers for the subject product.
manifest PricingDescriptor repeated Pricing tiers attached to this product pricing manifest.

UnitPricingDescriptor

Specifies pricing information for a unit-priced product, including the price value, tier status, and any discounts that currently apply.

Field Type Label Description
price opencannabis.commerce.CurrencyValue Unit price value.
status PricingTierAvailability Availability flags for this unit-priced tier.
discounts SaleDescriptor repeated Discounts that should apply to this tier.

WeightedPricingDescriptor

Specifies pricing information for a weight-priced product, at a particular weight tier, including the price value, tier status, and, optionally, a custom weight.

Field Type Label Description
weight PricingWeightTier Weight tier selection.
tier UnitPricingDescriptor Pricing descriptor for this tier, including the price value, status, and any discounts that should apply.
weight_in_grams float Custom weight in grams, if any.

PricingType

Enumerates supported pricing schemes. Defaults to 'UNIT'-based pricing.

Name Number Description
UNIT 0 Cost-per-item based pricing scheme, where each product is priced individually, regardless of other attributes. For example, edibles or standard merchandise are purchased, at their price, "each."
WEIGHTED 1 Cost-by-weight pricing scheme, where each product has multiple weight tiers, each priced individually. For example, standard retail flower pricing is weighted at 1g (one gram), 3.5g, 7g, 14g and 28g (one ounce).

PricingWeightTier

Enumerates supported pricing tiers, when the 'WEIGHTED' pricing scheme is in effect. Each known tier is enumerated, with an additional defaulted option for 'OTHER,' which would allow a custom weight to be assigned via some other property or metric.

Name Number Description
OTHER 0 'Other,' or custom weighted pricing.
GRAM 1 Pricing for 'ONE GRAM' of the subject material or merchandise.
HALFGRAM 2 Pricing for one 'HALF GRAM' of the subject material or merchandise. Usually used only for extracts.
QUARTERGRAM 3 Pricing for one 'QUARTER GRAM' of the subject material or merchandise. Usually used only for extracts.
DUB 4 Pricing for TWO GRAMS of the subject material or merchandise. Rarely used.
EIGHTH 5 Pricing for an 'EIGHTH' of the subject material or merchandise, usually defined as 3-and-one-half grams. In some cases, providers may choose to define their 'EIGHTH' weight value at 4 grams. This functionality is supported via partner or location-level settings. 'EIGHTH' usually refers to an eighth-of-an-ounce.
QUARTER 6 Pricing for a 'QUARTER' of the subject material or merchandise, usually defined as 7 grams.
HALF 7 Pricing for a 'HALF OUNCE' of the subject material or merchandise. Usually defined as 14 grams.
OUNCE 8 Pricing for 'ONCE OUNCE' of subject material or merchandise. Usually defined as 28 grams.
POUND 9 Pricing for 'ONE POUND' of subject material or merchandise.
KILO 10 Pricing for 'ONE KILO' of subject material or merchandise.
TON 11 Pricing for 'ONE TON' of subject material or merchandise.

structs/pricing/SaleDescriptor.proto

BOGODiscount

Field Type Label Description
trigger uint32
reward uint32

LoyaltyDiscount

Field Type Label Description
trigger uint32
reward uint32

PercentageDiscount

Field Type Label Description
discount uint32

SaleDescriptor

Field Type Label Description
type SaleType sale metadata
effective opencannabis.temporal.Instant
expiration opencannabis.temporal.Instant
percentage_off PercentageDiscount
bogo BOGODiscount
loyalty LoyaltyDiscount

SaleType

Name Number Description
PERCENTAGE_REDUCTION 0
VALUE_REDUCTION 1
BOGO 2
LOYALTY 3

results matching ""

    No results matching ""