Compliance & Taxes
      Back to home
      1. BLAZE US Knowledge Center
      2. BLAZE Retail
      3. Compliance & Taxes

      Metrc API Bulletin

      New API endpoints update to support California Retail Sales Delivery requirements, plus optional sales fields.

      Metrc API Bulletin

      Bulletin Number: 109 Distribution Date: 01/03/23 Effective Date: IN BULLETIN Contact Point: Subject: Metrc API updates for California Retail Sales Delivery

      api-info@metrc.com

      requirements and new optional sales fields

      Reason: New API endpoints update to support California Retail Sales Delivery requirements, plus optional sales fields.

      Greetings Metrc® integration partners,

      Please read on for an important update regarding the Metrc API program in California and upcoming API changes related to Retail Sales Delivery reporting announced in Bulletin 108, plus new optional sales fields that have gone into effect on January 1, 2023.

      Current deployment status:
      Production deployment for California was released on Wednesday, December 28, 2022, and enablement of the new endpoints has occurred on January 1st, 2023.

      Updated Sales Receipt Endpoints:

      • Record Sales Receipts – POST /sales/v1/receipts

      • Update Sales Receipts – PUT /sales/v1/receipts

        Please read on for additional details regarding the new delivery endpoints:

      ©MetrcInc.2 023

      Page 1|6

      Metrc API Bulletin

      API Permissions for Retail Deliveries

      Retail Sales Deliveries will be considered new functionality released to support the legislative changes and new requirements in California. Please note: For integrator partners that work with Sales Delivery reporting and supporting functionality in states outside of California, current functionality, as it stands today, will remain unchanged.

      Similar to Sales Deliveries or any other area for reporting into Metrc, Retail Sales Deliveries will require new permissions for non-admin employees of retail licenses and vendors planning to support reporting of retail deliveries via the API.

      For vendors planning to support Retail Sales Deliveries, please send your request to api- info@metrc.com with the subject “Retail Sales Delivery Permission Request”. Once received, Metrc’s API Support team will coordinate with the requestor to outline the steps for the API key to be reflective of the new permissions available.

      Any non-admin employee of a retail license that is granted the new Retail Delivery permission and is expected to have their employee license integrated with a vendor’s system will also need to regenerate a new API key once the permission has been granted to their account.

      New Fields for Sales Receipts Endpoints

      Currently, there is only 1 field ̶ “Total Amount” ̶ that reflects a final sale in Metrc. The previous expectation for sales reported in the Total Amount was the total dollar amount sold before tax and after any discount was given.

      To enhance sales reporting functionality, Metrc will deploy the following new, optional sales fields in the Metrc UI, CSV upload, and API:

      • Invoice: Invoice number which documents the sale

      • Price: Pre-tax/net selling price before all taxes

      • Excise Tax

      • City Tax

      • County Tax: This field is not currently used in California

      • Municipal Tax: This field is not currently used in California

      • Discount: Use this field to record the “below the line” discount, if any, applied to the

        overall ticket value and enter the Discount as a positive value

      • Subtotal: Price + Excise Tax + City Tax + County Tax + Municipal Tax – Discount

        o Note: Do not include the Sales Tax
        ©MetrcInc.2 023 Page 2|6

      Metrc API Bulletin

      • Sales Tax

      Starting on January 1st, 2023, the value in the existing Total Price (Total Amount for API Purposes) field for each package should be entered as the Subtotal + Sales Tax. An example in Figure 1 below indicates a Subtotal of $36.45 and Sales Tax of 3.61, a value of $40.06 should be entered in the Total Price field.

      Figure 1: Sales Receipt – Transaction Details Optional Fields

      Note: Metrc will not be calculating or validating any of the entries (or interfaced through the API) for the new fields being deployed. Any changes to requirements for reporting with these new fields will be communicated in a future bulletin.

      ©MetrcInc.2 023 Page 3|6

      Metrc API Bulletin

      Updated Sales Receipts Sample Request Examples

      Example 1: Record sales receipt - POST /sales/v1/receipts • Permissions: Sales

      [ {

      • Parameters: License Number

      "SalesDateTime": "2016-10-04T16:44:53.000", "SalesCustomerType": "Consumer", "PatientLicenseNumber": null, "CaregiverLicenseNumber": null, "IdentificationMethod": null, "PatientRegistrationLocationId": null, "Transactions": [

      {
      "PackageLabel": "ABCDEF012345670000010331", "Quantity": 1.0,
      "UnitOfMeasure": "Ounces",
      "TotalAmount": 9.99,
      "UnitThcPercent": null,
      "UnitThcContent": null, "UnitThcContentUnitOfMeasure": null, "UnitWeight": null, "UnitWeightUnitOfMeasure": null,

      "InvoiceNumber": null,

      "Price": null,
      "ExciseTax": null,
      "CityTax": null,
      "CountyTax": null,
      "MunicipalTax": null,

      "DiscountAmount": null,

      "SubTotal": null,
      "SalesTax": null

      }, {

      "PackageLabel": "ABCDEF012345670000010332", "Quantity": 1.0,
      "UnitOfMeasure": "Ounces",
      "TotalAmount": 9.99,

      "UnitThcPercent": null, "UnitThcContent": null, "UnitThcContentUnitOfMeasure": null, "UnitWeight": null, "UnitWeightUnitOfMeasure": null,

      "InvoiceNumber": null,

      "Price": null,
      "ExciseTax": null,

      ©MetrcInc.2 023

      Page 4|6

      Metrc API Bulletin

      "CityTax": null,
      "CountyTax": null,
      "MunicipalTax": null,

      "DiscountAmount": null,

      "SubTotal": null,
      "SalesTax": null

      } ]

      } ]

      Example 2: Update Sales Receipt – PUT /sales/v1/receipts • Permissions: Sales

      [ {

      • Parameters: License Number

      "Id": 51,
      "SalesDateTime": "2016-10-04T16:47:24.000", "SalesCustomerType": "Consumer", "PatientLicenseNumber": null, "CaregiverLicenseNumber": null, "IdentificationMethod": null, "PatientRegistrationLocationId": null, "Transactions": [

      {
      "PackageLabel": "ABCDEF012345670000010331", "Quantity": 1.0,
      "UnitOfMeasure": "Ounces",
      "TotalAmount": 9.98,
      "UnitThcPercent": null,
      "UnitThcContent": null, "UnitThcContentUnitOfMeasure": null, "UnitWeight": null, "UnitWeightUnitOfMeasure": null,

      "InvoiceNumber": null,

      "Price": null,
      "ExciseTax": null,
      "CityTax": null,
      "CountyTax": null,
      "MunicipalTax": null,

      "DiscountAmount": null,

      "SubTotal": null,
      "SalesTax": null

      }, {

      "PackageLabel": "ABCDEF012345670000010332", "Quantity": 2.0,
      "UnitOfMeasure": "Ounces",
      "TotalAmount": 9.99,

      "UnitThcPercent": null, "UnitThcContent": null,

      ©MetrcInc.2 023

      Page 5|6

      Metrc API Bulletin

      "UnitThcContentUnitOfMeasure": null, "UnitWeight": null, "UnitWeightUnitOfMeasure": null,

      } ]

      } ]

      If you have questions regarding information included in this bulletin, please contact Metrc Support at api-info@metrc.com. As a reminder, this information is subject to change and has been provided in advance of finalizing all endpoints.