Getting Started

An initial integration with LucidSource APIs can be streamlined by implementing only essential functionality and laying the groundwork for a more complete integration later on.

To get started with an essential integration, the following components must be implemented. All technical details are provided in Push APIs and LucidRetail documentation.

Receive Case Data and Process Regulatory (METRC) IDs

Using the LucidRetail mobile app, retailers can scan and import cases of received product featuring CaseIDs. The import process requires that a POS system provide a webhook endpoint that LucidRetail will use to send case data in JSON format.

While the JSON document contains Brand, Product, Batch, Regulatory and LucidID information about the items with the case (see Push APIs), only Regulatory ID information is required to be processed by the POS integration.

When receiving a Case JSON Document, the relevant data is in the regulator_ids section of the JSON data, and the integration can merely perform the following logic to get the relevant regulator (METRC) IDs:

  • If there is only 1 entry in regulator_ids, select the identifier field and use it as the regulator (METRC) ID for the case.

  • If there is more than 1 entry in regulator_ids, gather the correct regulator IDs using the following logic:

    1. Iterate over the list of items

    2. For each item, using the regulator_id_uuids list, find the newest regulator_id entry (based on its added_on field) and extract the identifier field. The identifier field will be the current regulator (METRC) ID for that item.

      1. Add the identifier to a set of collected regulator (METRC) IDs

    3. After collecting all of the most recent regulator IDs, process them through an existing import process provided by your POS system to import the case.

Note: while the vast majority of cases will contain only a single product and batch, and hence should have only a single latest regulator_id it is possible for (a) there to be more than 1 regulator_id entry since a case may have received multiple regulator_ids over time, and (b) there may be some cases with mixed products/batches. Using the above logic will ensure that the correct regulator ID(s) are selected from the Case JSON document.

Support Checkout with LucidIDs

Retail POS systems can scan the LucidID on any item and use the LucidRetail APIs to extract the correct regulator (METRC) ID for that item.

  1. Upon scanning a LucidID, use the LucidIDs, CaseIDs, and Collections documentation to properly recognize and extract the ID from the LucidID that is needed for API lookup

  2. Using the extracted ID, use the [items_get](items) API to retrieve the information about that particular LucidID and item

  3. Process the collections list in the API response and select the most recent entry with collection_type="regulator". The identifier field will be the actual regulator (METRC) ID.

Provide Transaction Reporting

Lucid Green requires submission of all purchased LucidIDs so that we can activate the LucidID for consumer use. There are 2 methods for providing this information. Select the method that is easiest for your POS integration to provide; only 1 is required to be implemented.

  • Submit the transaction details to LucidRetail at or shortly after the purchase is completed at the POS terminal using the details provided in Push APIs

or

  • Provide a query endpoint that can be configured within LucidRetail to retrieve the transaction data on a periodic basis using the details provided in Push APIs

Ensure LucidRetail Credential Storage

For webhook authentication and correct delivery of Case JSON data, be sure to follow both the Authentication and Push APIs sections of the LucidRetail push/index API document.

For LucidRetail API usage, each retail location will require its own account on LucidRetail and will be able to retrieve an OAuth2 server access token and configuration from their account. You should follow the Authentication portion of the LucidRetail document and ensure you provide a way to store location specific API credentials securely within your system.