| domain | shortname | name | status | editor | contributors | |
|---|---|---|---|---|---|---|
rfc.opencannabis.info |
6/OCS-C |
OpenCannabis Commerce Extension |
raw |
Randal Stevens <[email protected]> |
|
This specification's current status is considered RAW, i.e. pre-DRAFT. Distribution of this memo is unlimited.
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
- Protocol Definition:
commerce: Commercial ordering and fulfillment structures. - Protocol Definition:
pricing: Pricing schemes and structures.
Specifies a commercial discount structure, order structure, product variance, currency type, etc.
{% nomnoml %}
#fill: #d5e7ee; #8ebff2
[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]
{% endnomnoml %}
{% nomnoml %} #fill: #d5e7ee; #8ebff2 [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] {% endnomnoml %} {% nomnoml %}
#fill: #d5e7ee; #8ebff2 [Item | key:opencannabis.base.ProductKey | variant:VariantSpec | count:uint32]
[VariantSpec | variant:ProductVariant | weight:opencannabis.structs.pricing.PricingWeightTier | size:string | color:string]
{% endnomnoml %} {% nomnoml %}
#fill: #d5e7ee; #8ebff2 [Product Variant | WEIGHT:0 | COLOR:1 | SIZE:2]
{% endnomnoml %} {% nomnoml %}
#fill: #d5e7ee; #8ebff2
[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]
{% endnomnoml %}
{% nomnoml %}
#fill: #d5e7ee; #8ebff2 [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]
{% endnomnoml %}
{% nomnoml %}
#fill: #d5e7ee; #8ebff2
[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] {% endnomnoml %}
{% nomnoml %}
#fill: #d5e7ee; #8ebff2
[PricingTierAvailability | offered:bool | available:bool]
[ProductPricing | discounts:SaleDescriptor | manifest:PricingDescriptor]
[UnitPricingDescriptor | price:opencannabis.commerce.CurrencyValue | status:PricingTierAvailability | discounts:SaleDescriptor] {% endnomnoml %}
{% nomnoml %}
#fill: #d5e7ee; #8ebff2
[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]
{% endnomnoml %}
{% nomnoml %}
#fill: #d5e7ee; #8ebff2 [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] {% endnomnoml %}
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. |
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. |
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. |
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. |
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 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. |
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. |
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. |
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. |
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. |
Specifies a unique key for a commercial order.
| Field | Type | Label | Description |
|---|---|---|---|
| id | string | Order ID, assigned by the server upon creation. |
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. |
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. |
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. |
Specifies the type of order requested.
| Name | Number | Description |
|---|---|---|
| PICKUP | 0 | Express pickup order. |
| DELIVERY | 1 | Delivery order. |
Specifies the types of delivery timing.
| Name | Number | Description |
|---|---|---|
| ASAP | 0 | As soon as possible. |
| TIMED | 1 | Desired time. |
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. |
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. |
Specifies known or explicitly supported fiat currencies.
| Name | Number | Description |
|---|---|---|
| USD | 0 | Specifies 'US Dollar' as a currency. |
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. |
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.' |
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. |
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. |
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. |
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). |
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. |
| Field | Type | Label | Description |
|---|---|---|---|
| trigger | uint32 | ||
| reward | uint32 |
| Field | Type | Label | Description |
|---|---|---|---|
| trigger | uint32 | ||
| reward | uint32 |
| Field | Type | Label | Description |
|---|---|---|---|
| discount | uint32 |
| Field | Type | Label | Description |
|---|---|---|---|
| type | SaleType | sale metadata | |
| effective | opencannabis.temporal.Instant | ||
| expiration | opencannabis.temporal.Instant | ||
| percentage_off | PercentageDiscount | ||
| bogo | BOGODiscount | ||
| loyalty | LoyaltyDiscount |
| Name | Number | Description |
|---|---|---|
| PERCENTAGE_REDUCTION | 0 | |
| VALUE_REDUCTION | 1 | |
| BOGO | 2 | |
| LOYALTY | 3 |