Upsert variants and providers

Purpose

Creates or updates service variants and providers (professionals) in a single API call.

This endpoint manages the complete lifecycle of service variants identified by SKU, providers identified by reference, and their associated configurations including provider-variant associations, availability schedules, and working areas.

The endpoint processes execution variants only (not budgeted variants).

This endpoint is specifically designed for external integration systems to synchronize professional data and service configurations. It supports creating or updating professionals that are either natural persons or networks, but must not be used for technicians that belong to a company.

Field Definitions

🗂️ Request Body

👷 Provider

🪪 Provider Basic Information

📅 Provider Availability

Availability is fully replaced on update. All previous availability records are deleted and replaced by the incoming set.

🗺️ Provider Areas

When variantCoverage is provided for an area, only the listed variants will be restricted to that specific working area. Variants not listed in any variantCoverage entry retain total coverage (unrestricted).

🔧 Variant

🏷️ Parent Service

🗺️ Operation Areas

Example Request

{
  "variants": [
    {
      "sku": "SV-001",
      "name": "Standard Cleaning Service",
      "isInStore": false,
      "isExecution": true,
      "parentService": {
        "name": "Cleaning Services",
        "description": "Professional cleaning services",
        "category": {
          "name": "Home Services",
          "description": "Services for home maintenance"
        }
      },
      "operationAreas": {
        "detailed": [
          {
            "type": "areaReference",
            "value": ["AREA-001", "AREA-002"],
            "duration": "120",
            "price": 150.0,
            "cost": 100.0,
            "bookingAnticipationHours": 24
          }
        ],
        "all": {
          "duration": "60",
          "price": 100.0,
          "cost": 50.0,
          "bookingAnticipationHours": 12
        }
      }
    }
  ],
  "providers": [
    {
      "reference": "PROV-001",
      "basicInformation": {
        "name": "John",
        "lastName": "Doe",
        "email": "john.doe@example.com",
        "phoneNumber": "+1234567890",
        "identificationNumber": "12345678",
        "identificationNumberCountry": "US"
      },
      "isCompany": false,
      "workOnHolidays": false,
      "isMainProviderEligible": true,
      "isLeadAssignmentEligible": true,
      "service_variants": [
        {
          "type": "variantSku",
          "value": "SV-001"
        },
        {
          "type": "variantSku",
          "value": "SV-002"
        }
      ],
      "availability": [
        {
          "day_of_week": 1,
          "start_time": "09:00",
          "end_time": "17:00"
        },
        {
          "day_of_week": 2,
          "start_time": "09:00",
          "end_time": "17:00"
        }
      ],
      "areas": [
        {
          "type": "areaReference",
          "value": "AREA-001"
        },
        {
          "type": "areaReference",
          "value": "AREA-002",
          "variantCoverage": [
            {
              "type": "variantSku",
              "value": "SV-001"
            }
          ]
        }
      ]
    }
  ]
}

In this example, the provider covers AREA-001 with total coverage (all their variants) and AREA-002 with differentiated coverage restricted to SV-001 only.

Response Example

{
  "success": true,
  "message": "All operations completed successfully",
  "variantsProcessed": 1,
  "providersProcessed": 1,
  "variantResults": [
    {
      "variantId": 123,
      "sku": "SV-001",
      "success": true
    }
  ],
  "providerResults": [
    {
      "providerId": 456,
      "reference": "PROV-001",
      "success": true
    }
  ]
}

Response Fields

Error Response Example

{
  "success": false,
  "message": "Completed with 2 error(s)",
  "variantsProcessed": 0,
  "providersProcessed": 1,
  "errors": [
    "Variant SV-001: Multiple variants found for the same SKU",
    "Provider PROV-002: Provider cannot be part of a network"
  ],
  "variantResults": [
    {
      "variantId": 0,
      "sku": "SV-001",
      "success": false,
      "error": "Multiple variants found for the same SKU"
    }
  ],
  "providerResults": [
    {
      "providerId": 456,
      "reference": "PROV-001",
      "success": true
    },
    {
      "providerId": 0,
      "reference": "PROV-002",
      "success": false,
      "error": "Provider cannot be part of a network"
    }
  ]
}

Error Responses

Business Rules & Constraints

Provider Type Restrictions

• This endpoint only supports creating or updating professionals that are either:

  • Natural persons (individual providers with isCompany: false and no parent relationship)

  • Networks (providers with isCompany: true that act as parent organizations)

• It MUST NOT be used to create or update technicians that belong to a company (providers with a parent relationship). Attempting to update a provider that has an existing parent relationship will result in an error.

Variant SKU Uniqueness

• Each service variant SKU sent in the request MUST be unique in the system.

• If more than one variant is found for the same SKU, the operation for that SKU must fail and be stored as an error.

• No partial processing occurs for that SKU — the entire variant upsert operation for that SKU is rejected.

Service and Category Changes

• If a SKU in the variants payload matches an existing variant, but the service or category differs from the existing one:

  • The variant and all its operation variants will be moved from the existing service to the new service provided in the request.

  • If the category also differs, the variant will be moved under the new category.

  • This operation preserves all existing operation variants and their configurations — only the service and category associations are updated.

Operation Variants Preservation

• Operation variants are NEVER deleted by the algorithm. The system preserves all existing operation variants and only updates or reassigns them based on the incoming payload.

• Operation variants NEVER end without being associated to an operation area. The re-shuffle logic ensures all operation variants maintain at least one area association.

Execution Variants Only

• Only variants with isExecution: true are processed. Variants with isExecution: false are skipped with a warning log entry and do not count toward the variantsProcessed total.

Differentiated Area Coverage (variantCoverage)

variantCoverage configures a restriction on the variant, not on the area. All areas in provider.areas are always associated to the provider as working areas, regardless of whether they carry a variantCoverage or not.

How it works:

• Variants listed in variantCoverage for an area are restricted to operate only in that area. Their provider-variant association is linked specifically to that working area. If the same variant appears in variantCoverage across multiple areas, it is restricted to all of those areas combined.

• Variants with no variantCoverage entry anywhere have total coverage — they operate across all working areas of the provider.

• A variant listed in variantCoverage but absent from service_variants is automatically added as a new provider-variant association with its area restriction.

Important: if the same variant appears in both service_variants and in a variantCoverage entry, the restriction takes effect — the variant will be limited to that area and will not have total coverage.

Delete behavior:

• Deletion of provider-variant associations only runs when service_variants is explicitly provided.

• Only associations absent from both service_variants and all variantCoverage entries across all areas are removed.

Update Strategy

When a provider is sent and it already exists (identified by reference), the update follows this pattern:

workingAreas (areas field)

• Keep: Working areas that match areas in the incoming areas array are preserved.

• Remove: Working areas that exist but are not in the incoming areas array are deleted.

• Add: New working areas are created for areas in the incoming areas array that don't have an existing working area association.

availabilities (availability field)

• Replace All: All existing availabilities are deleted and replaced by the new set provided in the availability array.

professionalServiceVariants (service_variants field)

• If service_variants is omitted: Existing provider-variant associations are left untouched. Only variantCoverage entries (from areas) may implicitly add new associations or update working-area restrictions on existing ones.

• If service_variants is provided: The existing associations are fully reconciled against the incoming list:

  • Keep: Associations that match variants in the incoming service_variants array (or variantCoverage entries) are preserved.

  • Remove: Associations absent from both service_variants and all variantCoverage entries are deleted.

  • Add: New associations are created for variants in service_variants or variantCoverage entries that don't have an existing association.

Provider basic information fields (isMainProviderEligible, isLeadAssignmentEligible, workOnHolidays) are updated directly from the payload values. The isCompany field is only set during creation and is not updated for existing providers.

Operation Variants Re-shuffle Logic

When an existing service variant is sent with operation area configurations (via the operationAreas object), the system performs intelligent re-shuffling of operation variants rather than deleting and recreating them. The algorithm supports two configuration modes: detailed (specific area configurations) and all (default parameters for remaining areas).

Processing Flow

The system processes operation areas in two phases:

Phase 1: Processing detailed Entries

1. Area Resolution and Currency Grouping

   • Each area value in each detailed entry is resolved to an Area entity with its associated currency.

   • Areas are automatically grouped by currency — one VariantOperation is created or updated per currency group.

   • The system tracks which areas have been processed in this phase.

2. Conflict Detection

   • For each currency group, the system identifies existing operation variants that have overlapping areas (same currency, shared area IDs).

   • If no conflicts exist, a new operation variant is created with the specified areas and parameters.

3. Conflict Resolution Strategy

   • Operations with Remaining Areas: If an existing operation variant has both overlapping areas (to be reassigned) and non-overlapping areas (to remain), the system:

     • Removes the overlapping areas from the existing operation variant

     • Updates the operation variant to keep only the remaining areas

     • Preserves the existing operation variant's parameters (duration, cost, price, etc.)

     • The freed overlapping areas are added to the working set for reassignment

4. Operations That Would Become Empty

   • If an existing operation variant would become empty (all its areas are being reassigned), the system:

     • Sorts these operations by area count (fewest first) for deterministic processing

     • Updates all but the last operation with the new parameters and keeps their existing areas

     • Removes these areas from the working set

     • Updates the last operation with the new parameters and assigns all remaining areas from the working set to it

5. New Operation Creation

   • If any areas remain in the working set after conflict resolution, a new operation variant is created with those areas and the specified parameters.

Phase 2: Processing all Parameters (if provided)

1. Remaining Areas Identification

   • The system retrieves all active areas in the system.

   • It filters out areas already processed in Phase 1 (from detailed entries).

2. Synthetic DTO Creation

   • For the remaining areas, the system creates synthetic area configurations using the parameters from the all configuration.

3. Processing Remaining Areas

   • The synthetic configurations are processed using the same conflict resolution logic as Phase 1.

   • This ensures all remaining areas receive the default parameters specified in all.

Key Principles

• No Deletion: Operation variants are never deleted. They are either updated with new areas/parameters or preserved as-is.

• Area Preservation: All areas specified in the request (either explicitly in detailed or implicitly via all) are assigned to operation variants — no areas are lost.

• Parameter Updates: When an operation variant is updated, its parameters (duration, cost, price, bookingAnticipationHours) are updated to match the incoming values.

• Currency Isolation: Operation variants are always grouped by currency. Areas with different currencies are never mixed in the same operation variant.

• Priority: detailed entries take precedence over all. Areas specified in detailed are processed first, and all parameters are only applied to areas not covered by detailed.

Usage Patterns

Pattern 1: Detailed Configuration Only

Use detailed when you need specific configurations for specific areas:

{
  "operationAreas": {
    "detailed": [
      {
        "type": "areaReference",
        "value": ["AREA-001", "AREA-002"],
        "price": 150.0,
        "duration": "120"
      }
    ]
  }
}

Pattern 2: All Areas with Default Parameters

Use all when you want to apply the same parameters to all active areas:

{
  "operationAreas": {
    "all": {
      "price": 100.0,
      "duration": "60",
      "cost": 50.0
    }
  }
}

Pattern 3: Mixed Configuration (Recommended)

Use both detailed and all when you need specific configurations for some areas and default parameters for the rest:

{
  "operationAreas": {
    "detailed": [
      {
        "type": "areaReference",
        "value": ["AREA-001"],
        "price": 200.0,
        "duration": "180"
      }
    ],
    "all": {
      "price": 100.0,
      "duration": "60"
    }
  }
}

In this example, AREA-001 gets the specific configuration (price: 200.0, duration: 180), while all other active areas get the default parameters (price: 100.0, duration: 60).

Example Scenario

Existing State:

• Operation Variant A: Areas [1, 2, 3], Currency USD, Price $100

• Operation Variant B: Areas [4, 5], Currency USD, Price $80

• System has 10 total active areas: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

Incoming Request:

{
  "operationAreas": {
    "detailed": [
      {
        "type": "areaId",
        "value": ["2", "3", "6"],
        "price": 120.0,
        "duration": "90"
      }
    ],
    "all": {
      "price": 80.0,
      "duration": "60"
    }
  }
}

Result:

• Operation Variant A: Updated to Areas [1], Currency USD, Price $100 (areas 2, 3 removed; price preserved since not in detailed)

• Operation Variant B: Updated to Areas [4, 5], Currency USD, Price $80 (parameters updated from all)

• New Operation Variant C: Areas [2, 3, 6], Currency USD, Price $120, Duration 90 (created from detailed)

• New Operation Variant D: Areas [7, 8, 9, 10], Currency USD, Price $80, Duration 60 (created from all for remaining areas)