Virto Commerce (virtocommerce/vc-docs)

Virto Commerce

https://github.com/virtocommerce/vc-docs
Admin
Virto Commerce is an open-source platform for building extensible ecommerce applications. This...

Tokens:735,195
Snippets:5,162
Trust Score:8.5
Update:3 weeks ago
Show doc for...
Context Summary (auto-generated)
Raw
# Virto Commerce Documentation

Virto Commerce is an enterprise-grade, open-source B2B e-commerce platform built on .NET Core. It provides a comprehensive suite of tools for building digital commerce solutions including catalog management, shopping cart functionality, order processing, customer management, and multi-store support. The platform uses a modular architecture that allows businesses to customize and extend functionality through a rich set of APIs.

The platform exposes its functionality primarily through a GraphQL Storefront API (xAPI) for frontend applications and includes the vc-build CLI tool for development workflows. It supports multiple search engines (Elasticsearch, Azure Cognitive Search, Algolia), various payment gateways, and integrates with identity providers via OpenID Connect. The documentation covers the Platform (core), Marketplace, and Storefront components.

## Authentication API

The Virto Commerce OAuth 2.0 service provides authentication through client credentials, password flow, and refresh token flows. Access tokens are required for all API requests and can be obtained by authenticating against the `/connect/token` endpoint.

```bash
# Password flow - authenticate with username/password
curl -X POST "https://your-platform/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password&username=johndoe&password=A3ddj3w&scope=offline_access"

# Response:
# {
#   "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjQ0NjQ2...",
#   "token_type": "Bearer",
#   "expires_in": 1799,
#   "refresh_token": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6..."
# }

# Client credentials flow - machine-to-machine authentication
curl -X POST "https://your-platform/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=s6BhdRkqt3&client_secret=gX1fBat3bV"

# Use access token in API requests
curl -X POST "https://your-platform/api/some_resource" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjQ0NjQ2..."

# Refresh token flow
curl -X POST "https://your-platform/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token&refresh_token={token}&scope=offline_access"
```

## GraphQL Products Query

The products query enables searching and retrieving product catalog data with full-text search, filtering, faceting, and pagination support. It returns product details including pricing, availability, and images.

```graphql
# Query products with pagination
query {
  products(
    storeId: "B2B-Store"
    userId: "d97ee2c7-e29d-440a-a43a-388eb5586087"
    cultureName: "en-Us"
    currencyCode: "USD"
    first: 10
    after: "0"
  ) {
    totalCount
    items {
      id
      code
      name
      price {
        actual {
          amount
          formattedAmount
        }
      }
    }
    pageInfo {
      hasNextPage
      startCursor
    }
  }
}

# Query with filters and full-text search
query {
  products(
    storeId: "B2B-store"
    filter: "productfamilyid:baa4931161214690ad51c50787b1ed94 status:hidden,visible"
    query: "Stainless Steel Carriage Bolt"
    first: 23
    after: "0"
  ) {
    totalCount
    items {
      id
      code
      name
    }
  }
}

# Get single product by ID with images and pricing
query {
  product(
    id: "2dcd49147dc04892892af26bb91e5530"
    storeId: "B2B-store"
    currencyCode: "USD"
  ) {
    id
    name
    images {
      id
      name
      group
    }
    prices {
      minQuantity
      tierPrices {
        quantity
        price {
          amount
        }
      }
    }
  }
}
```

## GraphQL Categories Query

The categories query retrieves product category data for building navigation and category browsing experiences in storefront applications.

```graphql
query {
  categories(
    storeId: "B2B-Store"
    userId: "d97ee2c7-e29d-440a-a43a-388eb5586087"
    cultureName: "en-Us"
    currencyCode: "USD"
    first: 10
    after: "10"
  ) {
    items {
      id
      name
      hasParent
    }
    pageInfo {
      hasNextPage
      startCursor
    }
  }
}

# Response:
# {
#   "data": {
#     "categories": {
#       "items": [
#         {
#           "id": "b674f311-5dbe-42f7-bc30-8076744c59bf",
#           "name": "Kitchen supplies",
#           "hasParent": false
#         },
#         {
#           "id": "177c7dc2-7e21-4890-81fb-c7c0d37125b0",
#           "name": "Coffee",
#           "hasParent": true
#         }
#       ],
#       "pageInfo": {
#         "hasNextPage": true,
#         "startCursor": "10"
#       }
#     }
#   }
# }
```

## GraphQL Add Item to Cart Mutation

The addItem mutation validates products, adds them to the shopping cart, and automatically recalculates promotion rewards and taxes.

```graphql
mutation addItem($command: InputAddItemType!) {
  addItem(command: $command) {
    id
    items {
      id
      quantity
      listPrice {
        amount
      }
      note
    }
    total {
      amount
    }
    discountTotal {
      amount
    }
  }
}

# Variables:
# {
#   "command": {
#     "cartId": "e6a7d5af-6378-44a6-b645-af9ecf702c05",
#     "storeId": "B2B-store",
#     "cartName": "default",
#     "userId": "c50e5237-8a4c-41fe-b878-8e5a72390a08",
#     "cartType": "null",
#     "productId": "ec235043d51848249e90ef170c371a1c",
#     "quantity": 1,
#     "currencyCode": "USD",
#     "cultureName": "en-US",
#     "price": 10.85,
#     "comment": ""
#   }
# }
```

## GraphQL Change Cart Item Quantity Mutation

The changeCartItemQuantity mutation updates the quantity of a specific item in the shopping cart.

```graphql
mutation changeCartItemQuantity($command: InputChangeCartItemQuantityType!) {
  changeCartItemQuantity(command: $command) {
    id
    items {
      id
      name
      quantity
    }
    total {
      amount
    }
  }
}

# Variables:
# {
#   "command": {
#     "cartId": "e6a7d5af-6378-44a6-b645-af9ecf702c05",
#     "storeId": "B2B-store",
#     "cartName": "default",
#     "userId": "c50e5237-8a4c-41fe-b878-8e5a72390a08",
#     "cartType": "null",
#     "currencyCode": "USD",
#     "cultureName": "en-US",
#     "lineItemId": "e3ce8982-b5d7-4246-8d1a-840ed52368d4",
#     "quantity": 3
#   }
# }
```

## GraphQL Remove Cart Item Mutation

The removeCartItem mutation removes a specific item from the shopping cart by its line item ID.

```graphql
mutation removeCartItem($command: InputRemoveItemType!) {
  removeCartItem(command: $command) {
    items {
      id
      quantity
      product {
        id
      }
    }
  }
}

# Variables:
# {
#   "command": {
#     "cartId": "e6a7d5af-6378-44a6-b645-af9ecf702c05",
#     "storeId": "B2B-store",
#     "cartName": "default",
#     "userId": "c50e5237-8a4c-41fe-b878-8e5a72390a08",
#     "cartType": "null",
#     "currencyCode": "USD",
#     "cultureName": "en-US",
#     "lineItemId": "a3c9e72a-5b33-48c2-90b4-780886f54ec8"
#   }
# }
```

## GraphQL Add/Update Cart Shipment Mutation

The addOrUpdateCartShipment mutation manages shipping methods for a cart with support for partial updates and dynamic properties.

```graphql
mutation($command: InputAddOrUpdateCartShipmentType!) {
  addOrUpdateCartShipment(command: $command) {
    name
    availableShippingMethods {
      code
      optionName
      optionDescription
    }
  }
}

# Variables:
# {
#   "command": {
#     "storeId": "B2B-store",
#     "cartName": "default",
#     "userId": "c50e5237-8a4c-41fe-b878-8e5a72390a08",
#     "cultureName": "en-US",
#     "currencyCode": "USD",
#     "cartType": "cart",
#     "shipment": {
#       "fulfillmentCenterId": "7777-7777-7777-7777",
#       "height": 7,
#       "shipmentMethodCode": "code",
#       "currency": "USD",
#       "price": 98,
#       "dynamicProperties": [
#         {
#           "name": "ShipmentProperty",
#           "value": "test value"
#         }
#       ]
#     }
#   }
# }
```

## GraphQL Create Order from Cart Mutation

The createOrderFromCart mutation converts a shopping cart into a customer order, completing the checkout process.

```graphql
mutation createOrder($command: InputCreateOrderFromCartType!) {
  createOrderFromCart(command: $command) {
    id
    items {
      name
      id
      quantity
      product {
        availabilityData {
          isActive
          isInStock
          isBuyable
          isAvailable
          availableQuantity
        }
      }
    }
    customerId
  }
}

# Variables:
# {
#   "command": {
#     "cartId": "297056b4-df8e-4f78-aab7-40c048b42959"
#   }
# }
```

## GraphQL Orders Query

The orders query retrieves customer order history with filtering, sorting, and faceting capabilities for order management interfaces.

```graphql
query {
  orders {
    totalCount
    items {
      id
      status
      number
      createdDate
      modifiedDate
      customerId
      customerName
      shipments {
        id
        status
        shipmentMethodCode
        shipmentMethodOption
        total {
          amount
        }
      }
      addresses {
        id
        firstName
        lastName
        line1
        countryName
        countryCode
        postalCode
      }
      total {
        amount
      }
      subTotal {
        amount
      }
      discountTotal {
        amount
      }
    }
  }
}

# Response:
# {
#   "data": {
#     "orders": {
#       "totalCount": 3,
#       "items": [
#         {
#           "id": "order_id_1",
#           "status": "Processing",
#           "number": "ORD-20230702",
#           "createdDate": "2023-07-02T10:15:30Z",
#           "total": { "amount": 149.99 },
#           "subTotal": { "amount": 129.99 },
#           "discountTotal": { "amount": 20.00 }
#         }
#       ]
#     }
#   }
# }
```

## GraphQL Create Quote from Cart Mutation

The createQuoteFromCart mutation creates a quote request from an existing cart for B2B scenarios where pricing negotiation is required.

```graphql
mutation ($command: CreateQuoteFromCartCommandType!) {
  createQuoteFromCart(command: $command) {
    id
    number
    status
    comment
    items {
      productId
      name
      sku
      listPrice {
        amount
      }
      salePrice {
        amount
      }
      selectedTierPrice {
        quantity
        price {
          amount
        }
      }
    }
  }
}

# Variables:
# {
#   "command": {
#     "cartId": "d34cae74-e863-4a93-a20d-845472b85037",
#     "comment": "Sample comment"
#   }
# }
```

## GraphQL Create User Mutation

The createUser mutation creates a new user account in the system for customer registration workflows.

```graphql
mutation($command: InputCreateUserType!) {
  createUser(command: $command) {
    succeeded
  }
}

# Variables:
# {
#   "command": {
#     "applicationUser": {
#       "email": "graphql@test.local",
#       "userName": "graphqlTestUserName",
#       "userType": "Customer",
#       "createdBy": "admin"
#     }
#   }
# }
```

## GraphQL Create Contact Mutation

The createContact mutation creates a contact profile with personal information, addresses, and organization associations for CRM functionality.

```graphql
mutation createContact($command: InputCreateContactType!) {
  createContact(command: $command) {
    fullName
    id
    lastName
    name
  }
}

# Variables:
# {
#   "command": {
#     "name": "UserA",
#     "memberType": "Contact",
#     "addresses": [],
#     "fullName": "UserA",
#     "firstName": "UserA",
#     "lastName": "UserA"
#   }
# }
```

## GraphQL Contact Query

The contact query retrieves detailed contact information including organizations, addresses, and default billing/shipping addresses.

```graphql
query {
  contact(id: "5f807280-bb1a-42b2-9a96-ed107269ea06") {
    id
    fullName
    memberType
    name
    organizationId
    emails
    organizations {
      totalCount
      items
    }
    addresses {
      totalCount
      items
    }
    defaultBillingAddress {
      id
      key
      city
      countryName
    }
    defaultShippingAddress {
      id
      key
      city
      countryName
    }
  }
}

# Response:
# {
#   "data": {
#     "contact": {
#       "id": "5f807280-bb1a-42b2-9a96-ed107269ea06",
#       "fullName": "John Doe",
#       "memberType": "Customer",
#       "emails": ["john.doe@example.com"],
#       "defaultBillingAddress": {
#         "id": "addr1",
#         "city": "New York",
#         "countryName": "United States"
#       }
#     }
#   }
# }
```

## vc-build CLI - Installation and Package Management

The vc-build CLI tool manages Virto Commerce platform and module installations, updates, and configurations. It fetches packages from GitHub, GitLab, Azure, or local sources.

```bash
# Install vc-build CLI globally
dotnet tool install -g VirtoCommerce.GlobalTool

# Install platform and modules from vc-package.json
vc-build install

# Install with authentication token for private repos
vc-build install -GitLabToken $GITLAB_TOKEN

# Install specific platform version
vc-build install -platform -version 3.216.13

# Install platform from specific URL
vc-build install -platform -PlatformAssetUrl https://github.com/VirtoCommerce/vc-platform/releases/download/3.216.13/VirtoCommerce.Platform.3.216.13.zip

# Install specific module with version
vc-build install -module VirtoCommerce.Cart -version 3.200.0
vc-build install -module VirtoCommerce.Cart:3.200.0

# Install with custom paths
vc-build install -PackageManifestPath some_directory/vc-package.json \
  -DiscoveryPath ../modules \
  -ProbingPath platform_dir/app_data/modules \
  -SkipDependencySolving

# Update platform and all modules to latest stable
vc-build update

# Update to latest edge versions
vc-build update -edge

# Update to specific bundle version
vc-build update -v 5

# Uninstall a module
vc-build uninstall -module VirtoCommerce.Cart

# Configure connection strings
vc-build configure -sql "Server=localhost;Database=VirtoCommerce;..." \
  -redis "localhost:6379" \
  -AzureBlob "DefaultEndpointsProtocol=https;..."
```

## vc-build CLI - Build Automation

The vc-build tool provides build automation for .NET solutions including compilation, testing, packaging, and Docker image management.

```bash
# Clean build artifacts
vc-build clean

# Restore NuGet dependencies
vc-build restore
vc-build restore -NugetConfig path/to/NuGet.config

# Compile solution
vc-build compile -configuration Release
vc-build compile -configuration Debug

# Run unit tests with coverage report
vc-build test
vc-build test -TestsFilter "Category!=IntegrationTest"

# Create NuGet packages
vc-build pack
vc-build pack -configuration Release

# Publish NuGet packages
vc-build publishPackages -source https://api.nuget.org/v3/index.json -apiKey YOUR_API_KEY
vc-build publishPackages -source C:\local-nuget

# Compress artifacts for deployment
vc-build compress
vc-build compress -configuration Release

# Build frontend assets with Webpack
vc-build WebPackBuild

# Docker operations
vc-build dockerlogin -DockerRegistryUrl https://myregistry.com \
  -DockerUsername user -DockerPassword 12345

vc-build BuildImage -DockerfilePath ./dockerfile -DockerImageFullName myimage:tag

vc-build PushImage -DockerImageFullName myimage:tag

vc-build BuildAndPush -DockerRegistryUrl https://myregistry.com \
  -DockerUsername user -DockerPassword password \
  -DockerfilePath ./dockerfile \
  -DockerImageName myimage \
  -DockerImageTag latest v1.0.0

# Create GitHub release
vc-build release -GitHubUser VirtoCommerce -GitHubToken $GITHUB_TOKEN

# SonarQube analysis
vc-build SonarQubeStart -SonarBranchName dev -SonarAuthToken $SONAR_TOKEN -RepoName vc-module-marketing
vc-build SonarQubeEnd -SonarAuthToken $SONAR_TOKEN

# Validate version consistency
vc-build MatchVersions
```

## vc-package.json Configuration

The vc-package.json file defines platform version and module dependencies with support for multiple package sources including GitHub, GitLab, Azure, and local files.

```json
{
  "Sources": [
    {
      "Name": "GithubReleases",
      "ModuleSources": [
        "https://raw.githubusercontent.com/VirtoCommerce/vc-modules/master/modules_v3.json"
      ],
      "Modules": [
        {
          "Id": "VirtoCommerce.Assets",
          "Version": "3.200.0"
        },
        {
          "Id": "VirtoCommerce.Cart",
          "Version": "3.200.0"
        }
      ]
    },
    {
      "Name": "GithubPrivateRepos",
      "Owner": "VirtoCommerce",
      "Modules": [
        {
          "Id": "vc-module-custom",
          "Version": "3.16.0"
        }
      ]
    },
    {
      "Name": "AzureUniversalPackages",
      "Organization": "https://dev.azure.com/YOUR_ORGANIZATION",
      "Feed": "FEED_NAME",
      "Project": "YOUR_PROJECT_NAME",
      "Modules": [
        {
          "Id": "PACKAGE_NAME",
          "Version": "PACKAGE_VERSION"
        }
      ]
    },
    {
      "Name": "AzureBlob",
      "Container": "modules",
      "ServiceUri": "https://vcpsblob.blob.core.windows.net",
      "Modules": [
        {
          "BlobName": "CustomCompany.CustomModule1_3.200.0.zip"
        }
      ]
    },
    {
      "Name": "Local",
      "Modules": [
        {
          "Path": "C:/projects/vc/vc-module-custom/artifacts/VirtoCommerce.Custom_3.214.0.zip",
          "Id": "VirtoCommerce.Custom"
        }
      ]
    }
  ],
  "ManifestVersion": "2.0",
  "PlatformVersion": "3.216.0"
}
```

## Payment Method Registration

Custom payment methods can be implemented by extending the PaymentMethod abstract class and registering with the payment methods registrar for off-site or on-site payment processing.

```csharp
// Define custom payment method
public class DefaultManualPaymentMethod : PaymentMethod
{
    // Process payment transaction with external payment system
    public override ProcessPaymentRequestResult ProcessPayment(ProcessPaymentRequest request)
    {
        // Implement payment processing logic
        return new ProcessPaymentRequestResult
        {
            OuterId = "external-transaction-id",
            IsSuccess = true
        };
    }

    // Check payment status from external system
    public override PostProcessPaymentRequestResult PostProcessPayment(PostProcessPaymentRequest request)
    {
        return new PostProcessPaymentRequestResult
        {
            IsSuccess = true
        };
    }

    public override VoidPaymentRequestResult VoidProcessPayment(VoidPaymentRequest request) { ... }
    public override CapturePaymentRequestResult CaptureProcessPayment(CapturePaymentRequest request) { ... }
    public override RefundPaymentRequestResult RefundProcessPayment(RefundPaymentRequest request) { ... }

    // Validate callback from payment system
    public override ValidatePostProcessRequestResult ValidatePostProcessRequest(
        System.Collections.Specialized.NameValueCollection queryString)
    {
        return new ValidatePostProcessRequestResult
        {
            OuterId = queryString["transactionId"],
            IsSuccess = true
        };
    }
}

// Register payment method in Module.cs PostInitialize
public void PostInitialize(IApplicationBuilder applicationBuilder)
{
    var settingsRegistrar = appBuilder.ApplicationServices.GetRequiredService<ISettingsRegistrar>();
    var paymentMethodsRegistrar = appBuilder.ApplicationServices.GetRequiredService<IPaymentMethodsRegistrar>();

    paymentMethodsRegistrar.RegisterPaymentMethod<DefaultManualPaymentMethod>();
    settingsRegistrar.RegisterSettingsForType(
        ModuleConstants.Settings.DefaultManualPaymentMethod.AllSettings,
        typeof(DefaultManualPaymentMethod).Name
    );
}
```

## Summary

Virto Commerce provides a comprehensive e-commerce platform suitable for building B2B and B2C digital commerce solutions. The primary integration point is the GraphQL Storefront API (xAPI) which exposes all commerce operations including product catalog browsing, shopping cart management, order processing, customer profiles, and quote requests. The API follows a consistent pattern with queries for data retrieval and mutations for state changes, supporting multi-store, multi-currency, and multi-language configurations through request parameters.

Development workflows are streamlined through the vc-build CLI tool which handles platform installation, module management, build automation, and deployment tasks. The modular architecture allows extending the platform with custom modules for payment methods, shipping providers, and business logic. Integration options include multiple search engines (Elasticsearch, Azure Cognitive Search, Algolia, Lucene), identity providers via OpenID Connect (Azure AD, Google), and various payment gateways. The platform is designed for enterprise deployments with support for Docker containerization, SonarQube code analysis, and CI/CD pipeline integration.