Skip to content

OpenAPI / Swagger Documentation

Merchello exposes two OpenAPI (Swagger) documents that describe its API surface. You can use these to explore endpoints interactively, generate client SDKs, or integrate with API testing tools.

Available Swagger Documents

Merchello registers two separate Swagger documents, each covering a different audience:

1. Backoffice API (merchello)

  • Title: Merchello Backoffice API
  • Version: 1.0
  • Covers: All admin/management endpoints (products, orders, customers, payments, providers, settings, reporting, etc.)
  • Authentication: Requires Umbraco backoffice session
  • Base path: /umbraco/api/v1

2. Storefront API (merchello-storefront)

  • Title: Merchello Storefront API
  • Version: 1.0
  • Description: Public checkout and storefront endpoints for headless clients
  • Covers: Basket operations, checkout flow, storefront context, payment processing, upsells, downloads
  • Authentication: Most endpoints are anonymous; some require member authentication
  • Base paths: /api/merchello/storefront, /api/merchello/checkout, /api/merchello/downloads

Accessing Swagger UI

Swagger UI is available through Umbraco's built-in Swagger integration. The URLs follow Umbraco's standard pattern:

https://yourdomain.com/umbraco/swagger

From the Swagger UI, use the document selector dropdown at the top of the page to switch between:

  • merchello -- the backoffice API
  • merchello-storefront -- the public storefront API

Note: Umbraco registers its own API documents alongside Merchello's. You will see Umbraco's core API documents in the dropdown as well. Look for the ones prefixed with "Merchello" in the title.

OpenAPI JSON URLs

You can access the raw OpenAPI JSON specifications at:

https://yourdomain.com/umbraco/swagger/merchello/swagger.json
https://yourdomain.com/umbraco/swagger/merchello-storefront/swagger.json

These are useful for:

  • Client SDK generation with tools like NSwag, openapi-generator, or Kiota
  • API testing with Postman or Insomnia (import the JSON directly)
  • Documentation generation with tools like Redoc or Stoplight

How Controllers Map to Documents

Merchello uses Umbraco's [MapToApi] attribute and [ApiExplorerSettings(GroupName)] to route controllers into the correct Swagger document:

Attribute Swagger Document
[MapToApi("merchello")] Backoffice API
[MapToApi("merchello-storefront")] Storefront API

Backoffice controllers inherit from MerchelloApiControllerBase, which sets the MapToApi attribute to merchello and applies the [BackOfficeRoute] and [Authorize] attributes.

Storefront controllers apply [MapToApi("merchello-storefront")] directly and use the route prefix /api/merchello/storefront or /api/merchello/checkout.

Some controllers (like payment webhooks and fulfillment webhooks) are not mapped to either Swagger document because they use custom routes outside the standard API prefixes.

Generating a TypeScript Client

If you are building a headless storefront, you can generate a typed TypeScript client from the storefront Swagger document:

# Using NSwag
npx nswag openapi2tsclient \
  /input:https://yourdomain.com/umbraco/swagger/merchello-storefront/swagger.json \
  /output:src/api/merchello-client.ts

# Using openapi-generator
npx @openapitools/openapi-generator-cli generate \
  -i https://yourdomain.com/umbraco/swagger/merchello-storefront/swagger.json \
  -g typescript-fetch \
  -o src/api/generated

Tip: Pin a specific API version in your generated client to avoid breaking changes when Merchello is updated. The API uses ASP.NET API versioning (/api/v{version:apiVersion}), so you can target a specific version.

Customizing Swagger

Merchello's Swagger configuration is set up in Startup.cs using Swashbuckle. If you need to customize the Swagger output (e.g., add additional metadata, include custom headers), you can modify the SwaggerGenOptions in your own startup code:

builder.Services.Configure<SwaggerGenOptions>(opt =>
{
    // Your customizations here
});

The operation IDs are generated by a custom IOperationIdHandler (CustomOperationHandler) to produce clean, predictable operation IDs suitable for client generation.