Send orders to your lab. Same day.

Lab Metadata is a series of key:value pairs.

This data will be used to modify the request to the selected lab's API.

Example:

Key: RELensMaterial
Value: PO-58-NONE-NONE-00

Calculating and Cascading Metadata

By default, if the same key exists at a lower level in the metadata chain, the value of the lower level will replace the value of the higher level for the same key.

Example:

Lens Level:
Key: RELensMaterial
Value: PO-58-NONE-NONE-00

Lens Option Level:
Key: RELensMaterial
Value: PO-67-POLR-BRWN-00

Final Result:
Key: RELensMaterial
Value: PO-67-POLR-BRWN-00

Using Variables in Metadata

Metadata can have variables where the lower level of metadata will instead replace parts of the higher level of metadata. This is accomplished by 'creating a variable' and 'setting a variable'.

Creating a Variable in a String

This is done by using the format of [variable=value].

Setting a Variable in a String

This is done by using the format of {{variable=value}}.

Example:

Lens Level:
Key: RELensMaterial
Value: PO-58-[lens_type=NONE]-[lens_color=NONE]-00

Lens Option Level:
Key: RELensMaterial
Value: {{lens_type=POLR}}{{lens_color=GREY}}

Final Result:
Key: RELensMaterial
Value: PO-67-POLR-GREY-00

LensAdvisor integrates with HOYA by sending order data to their SFTP server as XML files. Job status updates are received automatically via SFTP status files.

You will need a HOYA account with SFTP credentials (host, username, password, and customer folder name). Contact your HOYA representative to obtain these.

Data is passed to HOYA via Frame Metadata, Lens Metadata, and Order Metadata.

How it works:

1. When you send an order to HOYA, LensAdvisor builds an XML file containing the prescription, frame, and lens data.

2. The XML file is uploaded to your designated folder on HOYA's SFTP server.

3. HOYA processes the order and writes status updates (Received, In Progress, Shipped) to an output folder.

4. LensAdvisor periodically checks for status updates and syncs them back to your order.

Frame Metadata

Frame metadata is set on the Shopify product.

A custom field will now be available on your products, and you can add metadata using the following format:

{
  "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"
}

A metadata value with a prefix of product: will pull that data from the order line item's product fields.

For example, product:title will return the product's title, and product:sku will return the SKU.

A metadata value with a prefix of Variant: will pull that data from the order line item's variant fields.

For example, Variant:sku will return the order line item's SKU, and Variant:option1 will return the value from whatever the first option is.

Note: If a SKU is available on the Shopify line item, it will automatically be sent to HOYA as the frameSKU. When a frameSKU is present, the individual frame fields above (frameMfr, frameName, frameColor, frameMat, edgeType) are not sent — only the measurement fields (frameWidth, frameHeight, ED, DBL) are included alongside the SKU.

Here is the full list of frame data that can be sent:

• 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

Lens Metadata

Lens Metadata is set on any LensAdvisor object as key-value pairs. HOYA lens fields are side-specific — use the prefix right_ or left_ before the field name.

Lens fields:

• 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 value (per eye)

Prescription data sent automatically:

The following values are pulled directly from the customer's prescription and do not need to be set as metadata:

• Sphere (SPH), Cylinder (CYL), Axis

• Addition (ADD) and Segment Height

• Pupillary Distance (PD) — supports both Single PD and individual OD/OS

• Prism — Horizontal and Vertical with base direction

• Lens Type — automatically mapped from prescription type (Single Vision → SV, Progressive → PROGRESSIVE)

See Adding Lab Metadata below for instructions on how to enter Lab Metadata.

Order Metadata

Additional order-level data can be passed to HOYA using Lab Metadata. These fields apply to the entire order (not per-eye).

Order fields:

• 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

Tinting:

• tint — Tint color (e.g., "Gray", "Brown")

• tintType — Tint type code (defaults to "SLD" if a tint is specified). Common values: SLD (Solid), GRD (Gradient)

Services:

• services — Comma-separated list of HOYA service codes (e.g., "AR,UV,HC"). Each code is sent as a separate service element in the order XML.

Drop Shipping:

• dropShip — Drop ship entity data. Can be a JSON string with shipping details, or a simple name string.

See Adding Lab Metadata below for instructions on how to enter Lab Metadata.

Job Status Tracking

LensAdvisor automatically monitors your HOYA orders for status updates. Status files are read from the SFTP output folder and synced to your orders.

Status updates you will see:

• Received — HOYA has received and acknowledged the order

• In Progress — The order is being processed (coating, surfacing, etc.)

• 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)

Status updates are checked periodically for all active HOYA orders. No additional configuration is required — tracking begins automatically once an order is successfully sent.

Frame Metadata

Frame metadata is set on the Shopify product.

A custom field will now be available on your products, and you can add metadata using the following format:

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

A metadata value with a prefix of product: will pull that data from the order line item's product fields.

For example, product:title will return the product's title, and product:sku will return the SKU.

A metadata value with a prefix of Variant: will pull that data from the order line item's variant fields.

For example, Variant:sku will return the order line item's title, and Variant:option1 will return the value from whatever the first option is on the Variant

Here is a more thorough list of data that can be sent.

Lens Metadata

Lens Metadata is set on any LensAdvisor object as key-value pairs. You can pass data for any of the following keys:

See Adding Lab Metadata below for instructions on how to enter Lab Metadata.

Ocuco Miscellaneous Data

Ocuco passes some data as 'miscellaneous' data.

Miscellaneous Data can be added as lab metadata on any LensAdvisor object in the format of:

JSON for Miscellaneous data will be in the following format:

{
  "sku": "ABC123",
  "item_source": "COAT",
  "item_description": "",
  "item_value": "" // only use if item_source is TINT
}

item_source is one of the following:

Frame Metadata

Frame metadata is set on the Shopify product.

A custom field will now be available on your products, and you can add metadata using the following format:

{
    "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"
}

A metadata value with a prefix of product: will pull that data from the order line item's product fields.

For example, product:title will return the product's title, and product:sku will return the SKU.

A metadata value with a prefix of Variant: will pull that data from the order line item's variant fields.

For example, Variant:sku will return the order line item's title, and Variant:option1 will return the value from whatever the first option is on the Variant

Lens Metadata

Lens Metadata is set on any LensAdvisor object as key-value pairs. You can pass any of the following data through.

Examples of Lens Metadata Keys:

See Adding Lab Metadata below for instructions on how to enter Lab Metadata.

Frame Metadata

Frame metadata is set on the Shopify product.

1. Navigate to Shopify > Custom Data > Add Definition
2. Create a new product metadata definition with the following:

• Name: VisionWeb Frame Data
• Namespace and key: lensadvizor.visionweb-frame
• Type: JSON

A custom field will now be available on your products, and you can add metadata using the following format:

  {
      "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"
  }
  

A metadata value with a prefix of product: will pull that data from the order line item's product fields.

For example, product:title will return the product's title, and product:sku will return the SKU.

A metadata value with a prefix of Variant: will pull that data from the order line item's variant fields.

For example, Variant:sku will return the order line item's title, and Variant:option1 will return the value from whatever the first option is on the Variant

LensAdvisor sends orders to Gino Optical automatically. Frame, lens, prescription, and patient information are bundled into a single order and delivered to Gino's order system.

To start sending orders you will need:

1. A Gino Optical account with API credentials (an app_id and an api_secret). Request these from your Gino Optical representative.

2. Credentials entered in LensAdvisor — open the Gino Optical lab card in the merchant app and paste in the app_id and api_secret.

3. Frame metadata on each frame product in Shopify — see the Frame metadata section below.

4. Lens metadata on each lens flow in LensAdvisor — see the Lens metadata section below.

Order data is passed to Gino Optical via three layers of metadata: Frame metadata (Shopify product / variant), Lens metadata (LensAdvisor lens flow, with optional fallbacks on the Shopify lens product), and Pair / order metadata for whole-order overrides.

Sent automatically from the customer's prescription (no metadata required):

• Sphere (SPH) — including reading-glasses prescriptions

• Cylinder (CYL) power and axis

• Addition (ADD)

• Pupillary Distance — Single PD or Dual PD with individual right and left values

• Segment Height — applied to both eyes when present in the prescription

• Prism — horizontal and vertical prism with base direction (IN, OUT, UP, DOWN)

• Patient name — pulled from the Shopify customer name

• Order reference number — generated by LensAdvisor and printed on the lens paper bag and delivery documents at Gino's facility

• Optician and ship-to — both default to the Shopify store name

What happens after the order is sent. Once Gino accepts the order, the lab's reference number is recorded on the order in LensAdvisor. Subsequent job-status updates (in production, shipped, and so on) are managed in Gino's own portal — LensAdvisor does not poll Gino for status changes.

Metadata key format — important. Unlike the other lab integrations on this page, Gino Optical metadata uses dotted paths as keys. Each key writes its value into the matching part of the order sent to Gino. For example, the key order.pair.frame.code sets the frame code Gino uses to look up the frame in its catalogue. Keys under order.pair.lens.* apply to both eyes; keys under order.pair.patient.pupil.* apply to both pupils.

Frame Metadata

Frame metadata is set on the Shopify product (and optionally on a variant for SKU-specific overrides).

(Optionally repeat the same definition at the variant level using the same namespace and key — variant values override product values for the matching variant.)

Gino Optical metadata uses dotted paths as keys. Each key writes its value into the matching field of the order sent to Gino.

{
  "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
}

A metadata value with a prefix of product: will pull that data from the order line item's product fields. For example, product:title returns the product's title and product:sku returns the SKU.

A metadata value with a prefix of Variant: will pull that data from the order line item's variant fields. For example, Variant:sku returns the variant's SKU and Variant:option1 returns the value of the first variant option.

Frame fields available:

• order.pair.frame.code — frame product code (required by Gino's catalogue)

• 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 catalogue 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

Lens Metadata

Lens metadata can be set in two places:

1. LensAdvisor lens flow — open Lens Flows in the merchant app, edit a flow, and add Lab Metadata key-value pairs at the Lens Flow, Lens, Lens Option, Coating, or Tint level. Lower levels override higher levels for the same key (see Adding Lab Metadata).

2. Shopify product / variant — create a JSON metafield definition with namespace lensadvizor and key ginoptics-lens on the lens product (and optionally the variant). Frame products may also carry a lensadvizor.ginoptics-lens metafield to seed lens defaults — useful for sun + Rx products that ship with a paired lens.

Important — both eyes share the same lens metadata. Lens code, coating, geometry, design, and curve apply to both the right and left lens. Per-eye values are limited to the prescription data (sphere, cylinder, axis, add, prism), which LensAdvisor populates automatically.

{
  "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 catalogue (required)

• order.pair.lens.name — print name; Gino falls back to its catalogue 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

Sent automatically from the prescription (no metadata needed):

• 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

See Adding Lab Metadata for instructions on entering metadata in the LensAdvisor lens flow editor.

Pair, Patient, and Order Metadata

These fields apply to the whole order rather than the frame or lens specifically. Set them as Lab Metadata on the lens flow (or on the order) using the same dotted-key format.

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 — most are auto-populated; override only if 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 behaviour

• 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. LensAdvisor generates a default reference for every order; override only if your lab requires a specific reference 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)

See Adding Lab Metadata for instructions on entering metadata in the LensAdvisor lens flow editor.