Shopify Upsert a Customer by Email

arazzo: 1.0.1
info:
  title: Shopify Upsert a Customer by Email
  summary: Search for a customer by email and update it if it exists, otherwise create it.
  description: >-
    A common CRM synchronization pattern. The workflow searches customers using
    an email query, then branches: when a match is found it updates that
    customer in place, and when none is found it creates a new customer. This
    keeps an external contact list idempotently in sync with Shopify without
    creating duplicate customers. Every step spells out its request inline so
    the flow can be read and executed without opening the underlying OpenAPI
    description.
  version: 1.0.0
  x-realizes-capability-ids:
  - BC-420.10
  x-capability-derivation:
    method: 'deterministic join: sourceDescriptions -> per-tag OpenAPI -> tag/capability edge. No classification at this step.'
    min_confidence: 0.7
    sources:
    - capability_id: BC-420.10
      capability_name: Customer Data Management
      spec: shopify-customers-api-openapi.yml
      confidence: 0.85
    model: Turbo EA Capabilities by Vincent Verdet — Turbo EA, https://github.com/vincentmakes/turbo-ea-capabilities, CC BY 4.0
sourceDescriptions:
- name: customersApi
  url: ../openapi/shopify-customers-api-openapi.yml
  type: openapi
workflows:
- workflowId: upsert-customer-by-email
  summary: Upsert a single customer keyed on their email address.
  description: >-
    Looks for an existing customer whose email matches the supplied value and
    either updates the matched customer or creates a new one.
  inputs:
    type: object
    required:
    - email
    properties:
      email:
        type: string
        description: The customer email used as the upsert key.
      firstName:
        type: string
        description: Customer first name.
      lastName:
        type: string
        description: Customer last name.
      phone:
        type: string
        description: Phone number in E.164 format.
      tags:
        type: string
        description: Comma-separated list of tags to apply.
  steps:
  - stepId: findCustomer
    description: >-
      Search for a customer by email address, returning at most one candidate
      match.
    operationId: searchCustomers
    parameters:
    - name: query
      in: query
      value: "email:$inputs.email"
    - name: limit
      in: query
      value: 1
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      matchedCustomerId: $response.body#/customers/0/id
    onSuccess:
    - name: customerExists
      type: goto
      stepId: updateExisting
      criteria:
      - context: $response.body
        condition: $.customers.length > 0
        type: jsonpath
    - name: customerMissing
      type: goto
      stepId: createNew
      criteria:
      - context: $response.body
        condition: $.customers.length == 0
        type: jsonpath
  - stepId: updateExisting
    description: Update the matched customer with the supplied profile fields.
    operationId: updateCustomer
    parameters:
    - name: customer_id
      in: path
      value: $steps.findCustomer.outputs.matchedCustomerId
    requestBody:
      contentType: application/json
      payload:
        customer:
          first_name: $inputs.firstName
          last_name: $inputs.lastName
          phone: $inputs.phone
          tags: $inputs.tags
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      customerId: $response.body#/customer/id
    onSuccess:
    - name: done
      type: end
  - stepId: createNew
    description: >-
      Create a new customer using the supplied fields when no existing customer
      matched the email.
    operationId: createCustomer
    requestBody:
      contentType: application/json
      payload:
        customer:
          email: $inputs.email
          first_name: $inputs.firstName
          last_name: $inputs.lastName
          phone: $inputs.phone
          tags: $inputs.tags
    successCriteria:
    - condition: $statusCode == 201
    outputs:
      customerId: $response.body#/customer/id
  outputs:
    updatedCustomerId: $steps.updateExisting.outputs.customerId
    createdCustomerId: $steps.createNew.outputs.customerId