Company Creation (B2B)

🏢 Company Create/Update Functionality on Shopify

The endpoint allows you to create or update a B2B Company on Shopify, including contacts (company contact) and locations (company location).

Company search logic

Before creating or updating, the system searches for an existing company on Shopify:

1. If the company Id is present, a search is performed via Shopify Id (node(id: …)).
   • If the company exists, the flow continues with an update.
   • If not found, the flow continues with creation.
2. If the Id is not set, the search is performed via Reference (input field reference → externalId on Shopify).
   • Search filter: external_id:{reference}.
   • If the company exists → update; otherwise → creation.

💡 Note: The reference field is required in every request (ingress validation). Even when id is present, reference must be set.

Input validation

Validation is performed by the adapter before any call to Shopify. If validation fails, the message is rejected with the corresponding error.

Field	Rule
reference	Required on every request
contacts[].email	Required for each contact when the contacts list is provided
contacts[].email	Must be unique within the list (case-insensitive)
contacts[].phone	When set, must be unique within the list
locations[].reference	Required for each location when the locations list is provided
locations[].reference	Must be unique within the list (case-insensitive)
locations (update)	When the list is present, it cannot be an empty array ([]). Allowed values: null or one or more objects

💡 Main contact: set isMainContact: true on exactly one contact in the contacts list.

Contact checks

In addition to ingress validation, before creating or linking a contact the service checks whether a Shopify customer already exists with the same email (or, when both are set, via the contact id and email).

Situation	Outcome
Customer not found on Shopify	The contact can be created
Existing customer, not linked to any company	The contact can be linked to the company
Customer already linked to another company	Error — synchronization not allowed

Error message:

The following contacts are already associated with another company: email1@example.com, email2@example.com.

Create and update

The endpoint creates or updates the company, contacts, and locations in upsert mode.

Company

Managed fields: reference, name, note. On update, omitted fields keep their existing values on Shopify.

Contacts

Matching with existing contacts on Shopify (in order):

1. Company contact id (GID or normalized numeric value)
2. email (case-insensitive comparison)

Result	Action
Not found	Contact creation or linking
Found	Update of the existing contact
Present on Shopify, absent in input	Contact deletion

Location

Matching with existing locations on Shopify (in order):

1. Company location id (GID or normalized numeric value)
2. reference (mapped to externalId on Shopify)

Result	Action
Not found	Location creation
Found	Location update (master data, configuration, tax exemptions, shipping and billing addresses)
Present on Shopify, absent in input	Location deletion

On location update, the following are also supported:

• Tax exemptions via configurations.taxExemptions
• Shipping (shippingAddress) and billing (billingAddress) addresses
• When isBillingSameAsShipping is true, the billing address matches the shipping address

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	Sync company	POST /egress/sync-company-to-shopify
GraphQL endpoint URL	https://SHOPIFYURL.myshopify.com/	Shopify Admin GraphQL API 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
x-parallel-processes-number	1 (default)	Number of parallel workers for bulk processing (minimum 1)

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-company-to-shopify	Adapter path for the company sync flow
Headers :: x-api-key	**********	API key for endpoint interaction verification
Headers :: x-shopify-access-token	shpat_CODICEALFANUMERICO	Secret of the custom app created for integration
Headers :: x-shopify-graphql-url	https://SHOPIFYURL.myshopify.com/	Shopify shop URL to connect to
Headers :: x-parallel-processes-number	1	Message processing parallelism

Input message examples

1. Full company creation / update

{
  "reference": "ACME-001",
  "name": "Acme Corporation",
  "note": "Primary B2B customer",
  "contacts": [
    {
      "isMainContact": true,
      "email": "mario.rossi@acme.com",
      "firstName": "Mario",
      "lastName": "Rossi",
      "phone": "+393401234567",
      "title": "Purchasing Manager"
    },
    {
      "email": "luisa.bianchi@acme.com",
      "firstName": "Luisa",
      "lastName": "Bianchi",
      "title": "Accounting"
    }
  ],
  "locations": [
    {
      "reference": "ACME-HQ-MILANO",
      "name": "Milan Office",
      "phone": "+390212345678",
      "isBillingSameAsShipping": true,
      "shippingAddress": {
        "firstName": "Mario",
        "lastName": "Rossi",
        "street1": "Via Roma 1",
        "city": "Milano",
        "zip": "20100",
        "countryCode": "IT",
        "phone": "+393401234567"
      },
      "configurations": {
        "checkoutToDraft": false,
        "editableShippingAddress": true,
        "paymentTermsTemplateId": "gid://shopify/PaymentTermsTemplate/2",
        "taxExemptions": []
      }
    },
    {
      "reference": "ACME-WH-ROMA",
      "name": "Rome Warehouse",
      "isBillingSameAsShipping": false,
      "shippingAddress": {
        "street1": "Via Appia 100",
        "city": "Roma",
        "zip": "00100",
        "countryCode": "IT"
      },
      "billingAddress": {
        "street1": "Via del Corso 50",
        "city": "Roma",
        "zip": "00186",
        "countryCode": "IT"
      },
      "configurations": {
        "checkoutToDraft": false,
        "editableShippingAddress": true,
        "depositPercentage": 50,
        "paymentTermsTemplate": "Net 30",
        "taxExemptions": ["CA_BC_COMMERCIAL_FISHERY_EXEMPTION"]
      }
    }
  ]
}