Retail Transactions

A queryable API that will provide records of POS transactions for a specific retailer. The API should accept a starting and ending datetime specified as URL parameters, and should return a JSON list containing all retail transactions within the specified start and end times.

Requirements

  • Transactions must be reported if they contain at least 1 item that has a LucidID

  • If a POS transaction doesn’t contain any items with LucidIDs, it can be omitted from the response data

  • Items without LucidIDs that are part of a POS transaction do not need to be reported, with the exception that they should be included in the count of the total items that comprise the transaction. For example, if a consumer purchases 3 items that have LucidIDs and 2 items that do not have LucidIDs, the items field should only include the 3 LucidIDs, but the total_items_count field should have the value 5.

Parameters

The start and end times for the data retrieval will be provided as URL parameters in ISO-8601 format.

https//example.net/api/v1/transactions/?start_date=2021-03-11T12:00:00Z&end_datetime=2021-04-11T12:00:00Z

If start_date is not specified, it should default to midnight UTC on the prior day to the current day (as measured from when the API is accessed). For example, if today is 4/3/2021, start_date should default to 2021-04-02T00:00:00Z.

If end_date is not specified, it should default to midnight UTC on the current day (as measured from when the API is accessed). For example, if today is 4/3/2021, end_date should default to 2021-04-03T00:00:00Z.

When querying for transactions, both start_date and end_date should be treated as inclusive. That means that all transactions that match start_date ≤ transaction_date ≤ end_date should be included in the response.

HTTP Response Codes

The API response must return the following HTTP status codes in response:

Response Codes

201 Created:

successful API call

400 Bad Request:

error in processing HTTP Post

401 Unauthorized:

authentication failure

Other 40x and 50x:

errors may also be returned as appropriate

Response Payload

The response for this API should be a JSON document. The data format should be a list of “transaction” data, where each “transaction” is represented as a JSON dict with the following fields:

Fields

transacted_on (ISO-8601):

the date and time of the retail transaction

total_items_count (int):

the # of items that were part of this retail transaction, including both items with LucidIDs and items without LucidIDs

transaction_id (string):

a 3PP generated unique, persistent ID for the transaction (Note: If the same transaction appears in multiple calls to the Retail Transactions API, a transaction should retain a persistent unique ID to enable accurate matching within LucidRetail)

consumer_id (string):

a 3PP generated unique, persistent ID for the consumer that purchased the items (Note: If the same transaction appears in multiple calls to the Retail Transactions API, a consumer should retain a persistent unique ID to enable accurate matching within LucidRetail)

budtender_id (string):

a 3PP generated unique, persistent ID for the budtender that is credited with making the transaction (Note: If the same transaction appears in multiple calls to the Retail Transactions API, a budtender should retain a persistent unique ID to enable accurate matching within LucidRetail)

items (list):

a list of the LucidIDs that were part of the transaction, in UUID format (not full URLs)

Example Transaction List JSON Document

[
    {
        "transacted_on": "ISO-8601",
        "items": [
            "LUCID ID",
            "LUCID ID",
            "LUCID ID"
        ],
        "total_items_count": 10,
        "transaction_id": "<POS Transaction ID>",
        "consumer_id": "<POS Consumer ID>",
        "budtender_id": "<POS Budtender ID>"
    },
    {
        "transacted_on": "ISO-8601",
        "items": [
            "LUCID ID",
            "LUCID ID",
            "LUCID ID"
        ],
        "total_items_count": 5,
        "order_id": "<POS Transaction ID>",
        "consumer_id": "<POS Consumer ID>",
        "budtender_id": "<POS Budtender ID>"
    }
]