# Virto Commerce GraphQL API

## Description

Virto Commerce exposes a unified GraphQL API (the "Experience API" or xAPI) as the primary interface for headless storefronts. Built on top of the GraphQL.NET library, the xAPI aggregates catalog, cart, order, and customer data into a single composable endpoint suited for B2B commerce frontends.

The GraphQL layer is implemented across a set of open-source modules:
- **vc-module-x-catalog** — product and category queries
- **vc-module-x-cart** — cart and wishlist queries and mutations
- **vc-module-x-order** — order queries and payment mutations
- **vc-module-profile-experience-api** — customer (contact/organization) queries and mutations
- **vc-module-x-api** — core infrastructure (auth, middleware, settings)

## Endpoint

```
POST /graphql
```

Virto's own public reference deployment (verified live, 2026-08-13):
```
https://virtostart-demo-admin.govirto.com/graphql
```

> Corrected 2026-08-13: an earlier revision of this file listed
> `https://demo.virtocommerce.com/graphql`. That host 301s to `https://virtocommerce.com/`
> and serves no GraphQL endpoint.

**Required header.** The platform enforces CSRF protection on `/graphql`. A request without a
non-empty `GraphQL-Require-Preflight` header is rejected with HTTP 400 and
`extensions.code: CSRF_PROTECTION`:

```
POST /graphql
Content-Type: application/json
GraphQL-Require-Preflight: 1
```

Introspection is open on the reference deployment — the full `__schema` document was retrieved
anonymously on 2026-08-13 (435 types, 89 `Query` fields, 144 `Mutations` fields, plus a
`Subscriptions` root). The resulting SDL is captured verbatim in
`graphql/virto-commerce-schema.graphql`.

A GraphQL Playground (GraphiQL) is available at:
```
https://<your-platform-host>/graphql/ui
```

## Authentication

Most read queries are public. Authenticated mutations (cart management, order placement, profile updates) require a bearer token obtained via the platform's OAuth2/OpenID Connect flow:
```
POST /connect/token
```

Pass the token as a header:
```
Authorization: Bearer <token>
```

## Key Query Roots

| Query | Description |
|---|---|
| `product(id, storeId, currencyCode, cultureName)` | Single product by ID |
| `products(storeId, query, filter, sort, facet, ...)` | Product search with faceting and pagination |
| `category(id, storeId, cultureName)` | Single category by ID |
| `categories(storeId, query, filter, sort, ...)` | Category search with pagination |
| `cart(storeId, userId, currencyCode, cultureName, cartName, cartType)` | Active shopping cart |
| `wishlists(storeId, userId, currencyCode, cultureName)` | Customer wishlists |
| `order(id, number)` | Single order by ID or order number |
| `orders(filter, sort, cultureName, userId)` | Order history connection |
| `me` | Authenticated user / contact profile |
| `organizations` | B2B organization list |
| `contacts` | Customer contact list |

## Key Mutation Roots

| Mutation | Description |
|---|---|
| `addItem` | Add product to cart |
| `addItems` | Bulk add items to cart |
| `changeCartItemQuantity` | Update cart line item quantity |
| `removeCartItem` | Remove item from cart |
| `addCoupon` / `removeCoupon` | Apply or remove discount coupon |
| `addOrUpdateCartAddress` | Set cart billing/shipping address |
| `addOrUpdateCartShipment` | Configure shipment on cart |
| `addOrUpdateCartPayment` | Configure payment on cart |
| `createOrderFromCart` | Convert cart to order |
| `changeOrderStatus` | Update order status |
| `initializePayment` / `authorizePayment` | Payment gateway integration |
| `createWishlist` / `addWishlistItem` / `removeWishlistItem` | Wishlist management |
| `createContact` / `updateContact` / `deleteContact` | Contact management |
| `createOrganization` / `updateOrganization` | B2B organization management |
| `updateMemberAddresses` | Address book management |
| `registerByInvitation` | Invited user registration |
| `changePassword` / `resetPasswordByToken` | Password management |

## Documentation

- Developer docs: https://docs.virtocommerce.org/
- GraphQL / xAPI overview: https://docs.virtocommerce.org/platform/developer-guide/GraphQL-Storefront-API-Reference-xAPI/
- Source — catalog module: https://github.com/VirtoCommerce/vc-module-x-catalog
- Source — cart module: https://github.com/VirtoCommerce/vc-module-x-cart
- Source — order module: https://github.com/VirtoCommerce/vc-module-x-order
- Source — profile module: https://github.com/VirtoCommerce/vc-module-profile-experience-api
- Source — core xAPI: https://github.com/VirtoCommerce/vc-module-x-api