Metafield File Synchronization

Endpoint for updating, inserting, or removing media files within Shopify Metafields for various entities.

⚠️ Important Note This endpoint uploads files from the provided URLs and associates them with the specified metafields. Ensure that the Metafield type on Shopify (e.g., file_reference o list.file_reference) is consistent with the data sent (single string or array).

General Information

The endpoint manages the association of resources to the Metafields of three main entities: Products, Variants e Orders.

Identification Logic

Target identification follows this hierarchy:

1. Id: If populated, the unique Shopify ID is used (either the numeric part 12345678 or the full GID gid://shopify/Order/12345678).
2. Reference: If the ID is absent, the system performs a search via the reference value. The behavior varies by entity:
   • ORDER: Search via orderName.
   • PRODUCTVARIANT: Search via SKU.
   • PRODUCT: Search via the SKU of any of its associated variants.

Field Structure

Main Fields

Campo	Tipo	Descrizione
id	String	Shopify numeric ID or GID. Takes priority over reference.
reference	String	Lookup value (Order Name or SKU). Ignored if id is present.
entity	Enum	Target entity type. Values: PRODUCT, PRODUCTVARIANT, ORDER.
files	Object	Map of keys (metafields) and values (file URLs).

Key Management (files)

The keys within the files object identify the Metafield:

• Full Namespace: (Es: "flowlyze.manuale") Recommended method. Uniquely identifies the metafield.
• Key Only: (Es: "manuale") If multiple metafields exist with the same key in different namespaces, the system will update the one created first chronologically.

Value Management

Values associated with the keys can be of two types, based on the Metafield configuration in Shopify:

• Single String: A single URL (e.g., "http://.../file.pdf").
• Array of Strings: A list of URLs (e.g., ["http://.../1.pdf", "http://.../2.pdf"]). Use only if the metafield is defined as a list.

Example Payload

[
  {
    "id": "594412345678",
    "reference": "#1108",
    "entity": "ORDER",
    "files": {
      "flowlyze.list_file": [
        "http://PDF/esempio1_pdf.pdf",
        "http://PDF/esempio2_pdf.pdf"
      ],
      "flowlyze.single_file": "http://PDF/esempio_pdf.pdf"
    }
  },
  {
    "id": null,
    "reference": "SKU-VARIANT-123",
    "entity": "PRODUCTVARIANT",
    "files": {
      "custom.manuale_tecnico": "http://PDF/esempio_pdf.pdf"
    }
  }
]

Operazione sui dati

The endpoint operates in Upsert mode (Update or Insert) and manages the file lifecycle on the Shopify metafield as follows:

• Insert/Update: By providing a URL (or a list of URLs), the system uploads the files to Shopify and updates the reference in the metafield. If the metafield already contained data, it will be overwritten by the new provided links.
• Removal: To clear a metafield and remove the file association, simply send a null value, an empty string (""), or an empty array ([]) for the corresponding key.

Destination configuration

Configure a Shopify destination and associate it with the flow.

Field	Value	Notes
Destination Type	Shopify
Operation	Metafield file upload	POST /egress/sync-file-to-shopify
GraphQL endpoint URL	https://SHOPIFYURL.myshopify.com/	Shopify Admin GraphQL endpoint URL
Admin API access token	shpat_CODICEALFANUMERICO	Or Client ID (API key) + Client secret — see Authentication
Client ID (API key)	YOUR_CLIENT_ID
Client secret	YOUR_CLIENT_SECRET

Deprecated — previous configuration (HTTP Adapter)

Deprecated

Configuration via HTTP Adapter with Base Url, Resource Path, and x-api-key header in Settings Override is deprecated. Use the Shopify destination configuration described above.

In addition to the basic data flow configuration, the following Settings Override settings were required:

Field	Value	Notes
Base Url	https://adapter.flowlyze.io	Adapter URL
Resource Path	/api/adp/shopify/egress/sync-file-to-shopify	Adapter path for file metafield addition flow
Headers :: x-api-key	**********	API key for endpoint interaction verification
Headers :: x-shopify-graphql-url	https://SHOPIFYURL.myshopify.com/	Shopify shop URL to connect to
Headers :: x-shopify-access-token	shpat_CODICEALFANUMERICO	Secret of the custom app created for integration