Connect your optical lab

Lab metadata uses key and value pairs to set fields in the order sent to your lab.

In the LensAdvisor flow editor, open an item’s three-dot menu and select the lab metadata option.

Override a value

A lens option overrides its parent lens when both use the same key.

• lens: RELensMaterial = PO-58-NONE-NONE-00
• lens option: RELensMaterial = PO-67-POLR-BRWN-00
• result: RELensMaterial = PO-67-POLR-BRWN-00

Replace part of a value

Use [variable=value] to set a placeholder and its default value.

Use {{variable=value}} on a lens option to replace that placeholder.

• lens: PO-58-[lens_type=NONE]-[lens_color=NONE]-00
• lens option: {{lens_type=POLR}}{{lens_color=GREY}}
• result: PO-58-POLR-GREY-00

The fixed 58 remains unchanged. Only the named placeholders change.

Ask your HOYA representative for SFTP access. You need the host, username, password, and customer folder name.

The integration follows these steps:

1. LensAdvisor creates an XML file with the prescription, frame, and lens data.
2. LensAdvisor uploads the file to your HOYA folder.
3. HOYA processes the order and writes status files to its output folder.
4. LensAdvisor reads those files and updates the order status.

Create a product metafield in Shopify:

1. Open Settings, then Custom data, then Products.
2. Add a definition named HOYA Frame Data.
3. Set the namespace and key to lensadvizor.hoya-frame.
4. Select JSON as the type, then save the definition.
5. Open the product and enter its frame data in the new metafield.

{
  "frameMfr": "Oakley",
  "frameName": "product:title",
  "frameColor": "Variant:option1",
  "frameMat": "Acetate",
  "segHeight": "21",
  "edgeType": "EDGED",
  "frameWidth": "145",
  "frameHeight": "32",
  "eyeSize": "55",
  "bridge": "18",
  "templeLength": "137",
  "ED": "62",
  "DBL": "18"
}

Use these prefixes to read Shopify data:

• product:title: the product title
• Variant:sku: the variant SKU
• Variant:barcode: the variant barcode
• Variant:option1: the first variant option

If the Shopify line item has a SKU, LensAdvisor sends it as frameSKU.

With a SKU, HOYA receives the frame measurements below instead of the separate manufacturer, model, color, material, and edge fields.

Frame fields

• frameMfr: Frame manufacturer
• frameName: Frame model name
• frameColor: Frame color
• frameMat: Frame material
• segHeight: default segment height
• edgeType: Edge finishing type
• frameWidth: Overall frame width
• frameHeight: Lens height (B measurement)
• eyeSize: Eye size (A measurement)
• bridge: Bridge width
• templeLength: Temple length
• ED: effective diameter
• DBL: distance between lenses

Use right_ or left_ before each HOYA lens field to identify the eye.

• right_material / left_material: Lens material code
• right_lensStyle / left_lensStyle: Lens design/style code
• right_color / left_color: Lens color code
• right_coating / left_coating: Lens coating code
• right_nearPd / left_nearPd: near PD for each eye

Prescription data sent automatically

LensAdvisor sends sphere, cylinder, axis, addition, segment height, pupillary distance (PD), and prism from the customer’s prescription.

It also maps the prescription type to HOYA’s lens type. You do not need metadata for these values.

Follow the lab metadata instructions to add these values in LensAdvisor.

These fields apply to the whole order:

• dispenser: Dispenser or optician name
• orderType: Order type code (defaults to "L" if not specified)
• instruction: Free-text lab instructions or special requests
• accountId: Override the default HOYA account ID for this order
• tint: Tint color (for example, "Gray", "Brown")
• tintType: Tint type code (defaults to "SLD" if a tint is specified). Common values: SLD (Solid), GRD (Gradient)
• services: Comma-separated list of HOYA service codes (for example, "AR,UV,HC"). Each code is sent as a separate service element in the order XML.
• dropShip: Drop ship entity data. Can be a JSON string with shipping details, or a simple name string.

Follow the lab metadata instructions to add these values in LensAdvisor.

After an order is sent, LensAdvisor checks HOYA’s SFTP output folder for status files.

Status updates can include:

• Received: HOYA has received and acknowledged the order
• In Progress: The order is being processed (coating, surfacing, other steps)
• Edging: Lenses are being edged
• Quality Check: Order is in quality control
• Waiting for Frame: Lab is waiting to receive the frame
• Waiting for Lenses: Lab is waiting for lens blanks
• Shipped / Complete: Order has been shipped from the lab
• Rejected: Order was rejected by HOYA (check the order notes for details)

If HOYA rejects an order, check its notes for the reason before sending it again.

Create a product metafield in Shopify:

1. Open Settings, then Custom data, then Products.
2. Add a definition named Ocuco Frame Data.
3. Set the namespace and key to lensadvizor.ocuco_labs-frame.
4. Select JSON as the type, then save the definition.
5. Open the product and enter its frame data in the new metafield.

{
  "frame_upc": "ABC123",
  "frame_status": "SUPPLIED",
  "frame_model": "XYZJKL",
  "instructions": "product:title",
  "frame_eye": "50",
  "frame_a": "60",
  "frame_mounting": "STANDARD",
  "frame_edge": "EDGED"
}

Use these prefixes to read Shopify data:

• product:title: the product title
• Variant:sku: the variant SKU
• Variant:barcode: the variant barcode
• Variant:option1: the first variant option

Frame fields

• frame_status (UNCUT,SUPPLIED,ENCLOSED,LENSES ONLY,TO COME) (default: ENCLOSED)
• frame_vendor
• frame_model
• frame_shape
• frame_color
• frame_upc (default: Shopify product SKU)
• frame_eye
• frame_bridge
• frame_temple
• frame_a (default: 65.00)
• frame_b
• frame_ed
• frame_dbl
• frame_circ
• frame_long_rad
• frame_rad_angle
• frame_mounting (STANDARD, METAL, RIMLESS, HALFEYE, DRILLED, FACET)
• frame_edge (EDGED, UNCUT) (default: EDGED)

Use these keys for lens material, design, and color. In the field names, od means right eye and os means left eye.

• lens_od_material_code
• lens_os_material_code
• lens_od_material_desc
• lens_os_material_desc
• lens_od_style_code
• lens_os_style_code
• lens_os_style_desc
• lens_od_style_desc
• lens_od_color_code
• lens_os_color_code

Follow the lab metadata instructions to add these values in LensAdvisor.

Use an ocuco_misc_ key to add a coating, tint, or other order item. Give each item a unique key.

For example, set ocuco_misc_coating to this JSON value:

{
  "sku": "ABC123",
  "item_source": "COAT",
  "item_description": "",
  "item_value": ""
}

Use item_value only when item_source is TINT.

Accepted item_source values are:

• MISC
• FRAME
• FLENS
• SFLENS
• NONSTK
• REM
• PACK
• TINT
• COAT
• EDGING
• PACKAGE
• OVERSIZE
• RXPRISM
• RXAdd

Create a product metafield in Shopify:

1. Open Settings, then Custom data, then Products.
2. Add a definition named VisionWeb Frame Data.
3. Set the namespace and key to lensadvizor.visionweb-frame.
4. Select JSON as the type, then save the definition.
5. Open the product and enter its frame data in the new metafield.

{
    "jobType": "Supply",
    "ED": "55",
    "Dbl": "20",
    "Eye": "50",
    "ABox": "50",
    "BBox": "42.5",
    "FrameSKU": "Variant:sku",
    "FrameUPC": "Variant:barcode",
    "FrameType": "ZYLO",
    "FrameColor": "Variant:option1",
    "FrameModel": "product:title",
    "FrameManufacturer": "ABCXYZ",
    "FrameTempleLength": "140"
}

Use these prefixes to read Shopify data:

• product:title: the product title
• Variant:sku: the variant SKU
• Variant:barcode: the variant barcode
• Variant:option1: the first variant option

Use these keys for lens design, material, and treatments. RE identifies the right eye and LE identifies the left eye.

• LELensDesign
• RELensDesign
• LELensMaterial
• RELensMaterial
• LETreatment1
• RETreatment1
• LETreatment2
• RETreatment2
• LETreatmentComments
• RETreatmentComments

Follow the lab metadata instructions to add these values in LensAdvisor.

LensAdvisor sends frame details, lens selections, prescription data, add-ons, and lab metadata to Optivision.

Set frame and lens SKUs and barcodes on the relevant Shopify variants.

Confirm the required lens codes and metadata with your Optivision lab before sending orders.

Follow the lab metadata instructions to add these values in LensAdvisor.

Before sending orders, set up your Gino Optical account:

1. Request an app_id and api_secret from your Gino Optical representative.
2. Enter the credentials in the Gino Optical lab settings in LensAdvisor.
3. Add frame metadata to your Shopify products.
4. Add lens metadata to your LensAdvisor flows.

LensAdvisor sends the customer’s prescription, PD, prism, and segment height automatically. It also supplies patient and order details.

After Gino accepts an order, LensAdvisor records the lab reference. Track later production and shipping updates in Gino’s portal.

Use dotted field names

Each metadata key identifies a field in the order. For example, order.pair.frame.code sets the frame code.

Keys under order.pair.lens.* apply to both eyes. Keys under order.pair.patient.pupil.* apply to both pupils.

Create a product metafield in Shopify:

1. Open Settings, then Custom data, then Products.
2. Add a definition named Gino Optical Frame Data.
3. Set the namespace and key to lensadvizor.ginoptics-frame.
4. Select JSON as the type, then save the definition.
5. Open the product and enter its frame data in the new metafield.

For variant-specific values, add the same definition to variants. Variant values override product values.

{
  "order.pair.frame.code": "STK-001",
  "order.pair.frame.name": "product:title",
  "order.pair.frame.model": "AV-50",
  "order.pair.frame.color": "Variant:option1",
  "order.pair.frame.barcode": "Variant:barcode",
  "order.pair.frame.shape_code": "RND-12",
  "order.pair.frame.dbl": 18,
  "order.pair.frame.ed": 62,
  "order.pair.frame.hbox": 32,
  "order.pair.frame.vbox": 50,
  "order.pair.frame.pa": 8,
  "order.pair.frame.ffa": 5,
  "order.pair.frame.ztilt": 6,
  "order.pair.frame.size.width": 50,
  "order.pair.frame.size.height": 32,
  "order.pair.frame.size.bridge": 18,
  "order.pair.frame.size.temple": 140
}

Use these prefixes to read Shopify data:

• product:title: the product title
• Variant:sku: the variant SKU
• Variant:barcode: the variant barcode
• Variant:option1: the first variant option

Frame fields

• order.pair.frame.code: frame product code (required by Gino's catalog)
• order.pair.frame.qty: frame quantity (defaults to 1)
• order.pair.frame.name: frame name printed on the lab paperwork
• order.pair.frame.barcode: frame barcode
• order.pair.frame.model: model code
• order.pair.frame.color: color code
• order.pair.frame.shape_code: Gino standard shape catalog code
• order.pair.frame.dbl: distance between lenses, mm
• order.pair.frame.ed: effective diameter, mm
• order.pair.frame.hbox: measured box height, mm
• order.pair.frame.vbox: measured box width, mm
• order.pair.frame.pa: pantoscopic angle, deg
• order.pair.frame.ffa: frame face form angle, deg
• order.pair.frame.ztilt: wrap angle, deg

Frame size

• order.pair.frame.size.width: eye size width, mm
• order.pair.frame.size.height: eye size height, mm
• order.pair.frame.size.bridge: bridge width, mm
• order.pair.frame.size.temple: temple length, mm

Optional shape and transform overrides

• order.pair.frame.transform.height: height extension adjustment, mm (positive or negative)
• order.pair.frame.transform.width: width extension adjustment, mm (positive or negative)
• order.pair.frame.shape.type: Oma (raw trace) or Enc.oma (encrypted trace)
• order.pair.frame.shape.data: Base64-encoded OMA trace data

Add lab metadata to the lens flow, lens, or lens option in LensAdvisor. Lens option values override the parent lens.

You can also use a JSON metafield named lensadvizor.ginoptics-lens on Shopify products or variants.

Frame products can use this metafield to provide default lens values.

Lens metadata applies to both eyes. LensAdvisor sends each eye’s prescription values separately.

{
  "order.pair.lens.brand": "Gino",
  "order.pair.lens.code": "1.60-AS-PROG",
  "order.pair.lens.name": "Gino 1.60 AS Progressive",
  "order.pair.lens.design_type": "PROGRESSIVE",
  "order.pair.lens.corridor": 13,
  "order.pair.lens.atoric": false,
  "order.pair.lens.virtual": false,
  "order.pair.lens.reduce": "FRAME",
  "order.pair.lens.geometry.diameter.physical": 65,
  "order.pair.lens.geometry.diameter.optical": 60,
  "order.pair.lens.coating.code": "AR-PREMIUM",
  "order.pair.lens.coating.name": "Premium Anti-Reflective",
  "order.pair.lens.tinting.code": "GREY-80",
  "order.pair.lens.tinting.name": "Grey 80%",
  "order.pair.lens.thickness.thinnest": true,
  "order.pair.lens.thickness.center": 1.5,
  "order.pair.lens.thickness.edge": 1.0,
  "order.pair.lens.curve.base_curve": 6.0,
  "order.pair.lens.decentration.horizontal": 0.0,
  "order.pair.lens.decentration.vertical": 0.0,
  "order.pair.lens.inset": 2.5,
  "order.pair.lens.upset": 0.0,
  "order.pair.lens.centration.cto": false,
  "order.pair.lens.centration.height": 18.0,
  "order.pair.lens.centration.bvd": 12.0,
  "order.pair.lens.centration.centration_distance": 32.0,
  "order.pair.lens.mark": ""
}

Identification

• order.pair.lens.brand: lens brand printed on the envelope (required)
• order.pair.lens.code: lens product code in the Gino Optical catalog (required)
• order.pair.lens.name: print name; Gino falls back to its catalog default if blank
• order.pair.lens.virtual: true when only one side is ordered but the other side's data is still needed for the lens calculation

Design

• order.pair.lens.design_type: lens design family code
• order.pair.lens.corridor: progression zone length, mm
• order.pair.lens.atoric: true for atoric designs
• order.pair.lens.reduce: NONE, RAW, SHAPE, GIVEN, or FRAME
• order.pair.lens.inset: horizontal offset to near reference point, mm
• order.pair.lens.upset: vertical offset to top of near zone, mm (multifocal only)
• order.pair.lens.mark: engraving mark

Geometry

• order.pair.lens.geometry.diameter.physical: physical diameter, mm (required when overriding)
• order.pair.lens.geometry.diameter.optical: optical diameter, mm

Thickness

• order.pair.lens.thickness.thinnest: true requests "as thin as possible"
• order.pair.lens.thickness.center: center thickness, mm
• order.pair.lens.thickness.edge: edge thickness, mm
• order.pair.lens.thickness.drillhole: thickness at the drill hole, mm

Curve and decentration

• order.pair.lens.curve.base_curve: base curve, dpt
• order.pair.lens.decentration.horizontal: horizontal decentration, mm
• order.pair.lens.decentration.vertical: vertical decentration, mm

Coating and tinting

• order.pair.lens.coating.code: Gino coating code
• order.pair.lens.coating.name: printed coating description
• order.pair.lens.tinting.code: Gino tint code
• order.pair.lens.tinting.name: printed tint description

Centration

• order.pair.lens.centration.cto: true for centration to optical center
• order.pair.lens.centration.centration_distance: centration distance, mm
• order.pair.lens.centration.height: centration height, mm
• order.pair.lens.centration.bvd: back vertex distance, mm

Prescription data sent automatically

• Sphere: per eye
• Cylinder power and axis: per eye
• Addition: per eye
• Prism: horizontal and vertical with base direction, per eye
• Right / left side designation

Follow the lab metadata instructions to add these values in LensAdvisor.

Use these keys for pair, patient, and order details. Add them as lab metadata in the lens flow.

Pair-level fields

• order.pair.remark: comment passed to the lab
• order.pair.fitting: true if the lab should fit the lenses to the frame (default: false)
• order.pair.thickness_matching: true to match lens thickness across both eyes (default: false)
• order.pair.weight_matching: true to match lens weight across both eyes (default: false)
• order.pair.base_matching: true to match base curve across both eyes (default: false)

Patient fields

LensAdvisor fills most patient fields automatically. Override them only when needed.

• order.pair.patient.id: patient number
• order.pair.patient.name: patient name (defaults to the Shopify customer name)
• order.pair.patient.address: patient address
• order.pair.patient.gender: patient gender
• order.pair.patient.nvb: near vision behavior
• order.pair.patient.appliance.near / .middle / .far: weighting unity for lens design (integer)
• order.pair.patient.pupil.x: pupil x-coordinate, mm (applied to both pupils)
• order.pair.patient.pupil.y: pupil y-coordinate, mm (applied to both pupils). Overridden by the prescription's segment height when one is set.

Edging

• order.pair.edging.type: NONE, SHAPE, GIVEN, or FRAME
• order.pair.edging.polish: true to request edge polishing (default: false)

Accessory

• order.pair.accessory[].type: none, case, or warranty_card
• order.pair.accessory[].code: accessory product code
• order.pair.accessory[].info: required information for the accessory
• order.pair.accessory[].qty: accessory quantity (default: 1)

Order-level fields

• order.ref_no: reference number; override the generated value only if your lab requires another format
• order.ref_txt: commission / customer reference text
• order.ref_barcode: reference barcode that prints on the lens paper bag and delivery documents
• order.ship_to: ship-to label (defaults to the store name)
• optician: optician name on the order (defaults to the store name)

Follow the lab metadata instructions to add these values in LensAdvisor.