JavaScript and TypeScript SDK

Install the official SDK and complete a checkout with typed Public API v1 methods

The official @cowtic/sdk package covers every Public API v1 endpoint and requires Node.js 20 or newer.

Install

npm install @cowtic/sdk

Create an order and receive its ticket

Create an API key with orders:write and tickets:read. For this quickstart, use a free ticket type so the order completes immediately.

import { Cowtic } from "@cowtic/sdk";

const cowtic = new Cowtic({
	apiKey: process.env.COWTIC_API_KEY!,
});

const response = await cowtic.orders.create({
	eventId: process.env.COWTIC_EVENT_ID!,
	customer: {
		email: `sdk-${Date.now()}@example.com`,
		name: "SDK verification",
	},
	items: [{
		ticketId: process.env.COWTIC_TICKET_TYPE_ID!,
		quantity: 1,
	}],
});

const ticket = response.data.issuedTickets[0];

if (response.data.order.status !== "COMPLETED" || !ticket) {
	throw new Error("The order did not issue a ticket.");
}

const issuedTicket = await cowtic.tickets.get(ticket.id);
console.log(issuedTicket.data.code);

Creating an order issues its tickets automatically when the order completes. cowtic.tickets.issue is a separate operation for complimentary/manual tickets that do not belong to an order.

Configuration

Override the complete API v1 base URL for staging or local development:

const cowtic = new Cowtic({
	apiKey: process.env.COWTIC_API_KEY!,
	baseUrl: "http://localhost:8080/api/v1",
});

The SDK automatically supplies X-Api-Key and generates idempotency keys for order creation and manual ticket issuance. Each response also exposes the HTTP status, headers, request ID, and parsed rate-limit values.

Paid checkout with custom return URLs

For a custom storefront, pass checkoutRedirectUrls so Zahls returns buyers to your domain. Keep the API key on your server — see Headless checkout and the runnable example in examples/headless-checkout.

const response = await cowtic.orders.create({
	eventId: process.env.COWTIC_EVENT_ID!,
	customer: { email: "buyer@example.com", name: "Buyer" },
	items: [{ ticketId: process.env.COWTIC_TICKET_TYPE_ID!, quantity: 1 }],
	checkoutRedirectUrls: {
		success: "https://shop.example.com/success",
		failure: "https://shop.example.com/failure",
		cancel: "https://shop.example.com/cancel",
	},
});

if (response.data.checkoutUrl) {
	// Redirect the customer to Zahls
}

Version compatibility

@cowtic/sdk 1.x targets /api/v1. Additive v1 support is released as a minor SDK version, fixes as a patch, and a future /api/v2 requires SDK 2.x.