Upsert Combined Listing

This endpoint allows you to manage Combined Listings on Shopify. This feature enables the creation or update of a Parent Product, which acts as a logical container to group various child products (childrenSkus).

Flow Architecture

The system adopts a separate management logic for entities:

1. Parent Product: The creation and update of the container (Parent) take place via this dedicated Combined Listings endpoint.
2. Child Products: Child products must already exist on Shopify, as they are managed through the standard product master data flow.

Identification via SKU (Metafield)

Since Parent Products on Shopify do not natively have an SKU field, Flowlyze uses a dedicated Metafield for unique identification. This allows the system to perform update operations without creating duplicates.

Required Metafield configuration on Shopify:

• Namespace: flowlyze
• Key: uniqueSku
• Type: single_line_text_field
• Options: Must be set as filterable and must allow only unique values.

If the metafield is not already present, it will be created automatically by the endpoint.

Destination configuration

Configure a Shopify destination and associate it with the flow, in addition to the basic data flow configuration.

Field	Value	Notes
Destination Type	Shopify
Operation	Combined Listing	POST /egress/sync-combined-listing-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-combined-listing-to-shopify	Path for the combined listing flow
Headers :: x-api-key	**********	Verification API key
Headers :: x-shopify-access-token	shpat_CODICEALFANUMERICO	Shopify custom app secret
Headers :: x-shopify-graphql-url	https://SHOPIFYURL.myshopify.com/	Shopify store URL

Input Message

Sending the JSON manages the entire lifecycle of the parent and the declarative synchronization of the children. Upon creation, the parent product status is set to DRAFT.

Parent Product Fields

• sku - Required field.
  Unique identifier for the parent (mapped to the flowlyze.uniqueSku metafield).
• handle
  URL-friendly identifier. If omitted during creation, it is generated by Shopify based on the title.
• title
  The product name. Required during creation; if omitted during an update, the existing value remains unchanged.
• Informational Fields: description, type, vendor, tags, markets.
• media: Array of objects containing url (required), alternativeText, and filename.
• metafields & files: Key-value objects (format namespace.key) to extend the parent information.
• SEO: metaTitle and metaDescription for page metadata.

To clear the content of a field (e.g., the description), pass an empty string (""). If the field is passed as null or omitted, no changes will be made to that specific field.

Children Management (childrenSkus)

The list of child products is managed in an atomic/declarative way:

• Association: The SKUs in childrenSkus must correspond to existing variants on Shopify (managed by the master data flow).
• Synchronization: The array is authoritative. Only the products present in the array will be associated with the parent. Any previously associated child not included in the current submission will be removed.
• Emptying: To remove all children, send "childrenSkus": [].
• No Change: If the field is null, the current associations will not be modified.

Full JSON Payload Example

{
  "sku": "PARENT-SHORT-001",
  "title": "Combined Sports Shorts",
  "handle": "combined-sports-shorts",
  "description": "Extended description of the parent product",
  "type": "Apparel",
  "vendor": "Brand Name",
  "tags": ["Summer", "Sport"],
  "markets": ["123456", "789789"],
  "media": [
    {
      "alternativeText": "Front view",
      "url": "[https://demo.sintra-soh.com/images/parent_front.jpg](https://demo.sintra-soh.com/images/parent_front.jpg)",
      "filename": "parent_front.jpg"
    }
  ],
  "metafields": {
    "custom.season": "SS24"
  },
  "files": {
    "custom.pdf": "[http://dev3.sintra-soh.com/PDF/sample_pdf.pdf](http://dev3.sintra-soh.com/PDF/sample_pdf.pdf)"
  },
  "childrenSkus": [
    {
      "sku": "blue-short-XS",
      "optionValues": {
        "color": "blue"
      }
    },
    {
      "sku": "pink-short-XS",
      "optionValues": {
        "color": "pink"
      }
    }
  ]
}