Merchrocket.Client 2.1.0

Merchrocket .NET Client

A comprehensive, strongly-typed .NET client library for the Merchrocket print-on-demand API.

Features

• Typed API - Catalog Products, Variants, Mockup Tasks, Orders, Order Items, Shipments, Statistics, Users
• Error handling - Every call returns ApiResponse<T>; ThrowOnError (default) additionally raises MerchrocketApiException on failure
• Credit tracking - X-MR-Credits-Included / X-MR-Credits-Used headers extracted automatically
• Pagination - Hydra collections with page, itemsPerPage, totalItems, navigation links
• DI-ready - AddMerchrocketClient() extension registers all services
• Multi-targeting - net8.0, net9.0, net10.0
• Logging - Structured via Microsoft.Extensions.Logging; HTTP errors always logged at Warning

Installation

dotnet add package Merchrocket.Client

Getting Started

using Merchrocket.Client.Extensions;
using Merchrocket.Client.Models.Config;

builder.Services.AddMerchrocketClient(new MerchrocketConfig
{
    BaseUrl = "https://app.merchrocket.shop/api/",
    AccessToken = "mrp_your_access_token",
    ThrowOnError = true,     // default: throws MerchrocketApiException on errors
    RequestLogging = false   // set true for per-request Info-level logging
});

Inject IMerchrocketClient into your services:

public class MyService(IMerchrocketClient client)
{
    public async Task DoSomething()
    {
        var orders = await client.Order.GetOrdersAsync();
        // ...
    }
}

Every endpoint returns ApiResponse<T>. The ThrowOnError config flag only controls whether failures also throw.

Default mode (ThrowOnError = true) - failures throw, so you can access .Data directly:

try
{
    var response = await client.Order.GetOrderAsync("bad-id");
    var order = response.Data;
}
catch (MerchrocketApiException ex)
{
    // ex.StatusCode, ex.ResponseBody, ex.RequestPath
}

Opt-in mode (ThrowOnError = false) - failures never throw; inspect the response:

var response = await client.Order.GetOrderAsync("bad-id");
if (!response.IsSuccess)
{
    // response.Error.StatusCode, response.Error.ResponseBody
}

Endpoint Reference

Catalog Product

var products = await client.CatalogProduct.GetCollectionAsync();
var product  = await client.CatalogProduct.GetAsync("e2c2e18c-...");

Catalog Product Variant

var variants = await client.CatalogProductVariant.GetCollectionAsync(
    "952b416d-...", withAllAttributes: true);
var variant  = await client.CatalogProductVariant.GetAsync("0587b207-...");

// Typed attribute access
var sku = variant.TryGetAttributeValue<int?>(AttributeCodes.SupplierSku);

Mockup Task

var request = new MockupTaskRequest
{
    Format = MockupTaskFormats.JPEG,
    RequestedProducts =
    [
        new RequestedProduct
        {
            CatalogProductId = "e2c2e18c-...",
            Placements =
            [
                new Placement
                {
                    Type = PlacementTypes.Main,
                    Technique = PlacementTechniques.DirectPrint,
                    Layers = [new Layer { Url = "https://example.com/design.png", Type = PlacementLayerTypes.File }]
                }
            ]
        }
    ]
};

var task = await client.MockupTask.PostMockupTask(request);
var id = task.Data!.MockupTaskId!;

// Poll until done
while (task.Data.Status == "pending")
{
    await Task.Delay(5000);
    task = await client.MockupTask.GetMockupTask(id);
}

// Access results
foreach (var vm in task.Data.CatalogVariantMockups!)
foreach (var m in vm.Mockups!)
    Console.WriteLine(m.MockupUrl);

// Download all assets as ZIP
var zip = await client.MockupTask.DownloadMockupTaskAsync(id);

// List all tasks
var all = await client.MockupTask.GetMockupTasksAsync();

Order

var order = await client.Order.CreateOrderAsync(new CreateOrderRequest
{
    ExternalId = "SHOP-12345",
    Shipping = "STANDARD",
    Recipient = new Recipient { Name = "Max Mustermann", Address1 = "Musterstr. 1", City = "Berlin", CountryCode = "DE", Zip = "10115" },
    OrderItems =
    [
        new CreateOrderItemRequest { ExternalId = "ITEM-001", Quantity = 1, VariantId = "0587b207-..." }
    ]
});

var orders   = await client.Order.GetOrdersAsync();
var byId     = await client.Order.GetOrderAsync(orderId);
var byExt    = await client.Order.GetOrderAsync("@SHOP-12345");

await client.Order.PatchOrderAsync(orderId, new PatchOrderRequest { Shipping = "DHL_EXPRESS" });
await client.Order.ConfirmOrderAsync(orderId);
// await client.Order.CancelOrderAsync(orderId);
// await client.Order.RefundOrderAsync(orderId);

Order Items & Shipments

var items      = await client.Order.GetOrderItemsAsync(orderId);
var item       = await client.Order.GetOrderItemAsync(orderId, itemId);
var created    = await client.Order.CreateOrderItemAsync(orderId, new CreateOrderItemRequest { Quantity = 2, VariantId = "..." });
await client.Order.PatchOrderItemAsync(orderId, itemId, new CreateOrderItemRequest { Quantity = 3 });
await client.Order.DeleteOrderItemAsync(orderId, itemId);

var shipments  = await client.Order.GetShipmentsAsync(orderId);

Statistics & Users

var stats = await client.Statistics.GetMonthlyMockupStatsAsync("2026");
var users = await client.User.GetCollectionAsync();
var user  = await client.User.GetAsync(userId);
await client.User.DeleteAsync(userId);

Constants

MockupTaskFormats.JPEG                // "jpeg"
PlacementTypes.Main                   // "main"
PlacementTechniques.DirectPrint       // "direct_print"
PlacementTechniques.Engraving         // "engraving"
PlacementLayerTypes.File             // "file"
AttributeCodes.SupplierSku           // "supplierSku"

Key Models

API Coverage

License

MIT - see LICENSE.