Commerce in meine App integrieren

Verwende das Proyecta SDK, um Kunden anzulegen, Checkouts zu starten, Features abzusichern und Abonnements zu kündigen – direkt aus deinem App-Code.

Sobald du Stripe verbunden und ein Produkt erstellt hast, bindest du Commerce über die proyecta.commerce SDK-Ressource in deine App ein. Die vier häufigsten Operationen sind: einen Kunden anlegen, einen Checkout starten, den Feature-Zugang prüfen und ein Abonnement kündigen.

import Proyecta from '@proyecta-ai/sdk';

const proyecta = new Proyecta({ apiKey: process.env.PROYECTA_API_KEY });

1. Einen Kunden anlegen

Ein Kunde ist die abrechenbare Einheit in deiner App – in der Regel ein Nutzer, eine Organisation oder ein Projekt. Lege einen an, sobald die entsprechende Entität in deiner Datenbank erstellt wird, und speichere die zurückgegebene id, damit du den Kunden bei Checkouts und Zugangsprüfungen referenzieren kannst.

const customer = await proyecta.commerce.customers.create({
    email: 'alice@example.com',
    name: 'Alice Liddell',
});

await db.users.update({ id: userId, proyectaCustomerId: customer.id });

Du kannst bei der Erstellung oder über customers.update() auch eine Rechnungsadresse (line1, line2, city, state, postal_code, country) übergeben.

2. Einen Checkout starten

commerce.checkout() erstellt eine Stripe-gehostete Checkout-Session und gibt eine URL zurück, zu der der Kunde weitergeleitet wird. Nach der Zahlung leitet Stripe den Kunden zu deiner success_url weiter.

const { url } = await proyecta.commerce.checkout({
    customer_id: customer.id,
    line_items: [{ variant_id: 'var_pro_monthly', quantity: 1 }],
    success_url: 'https://myapp.com/welcome',
    cancel_url: 'https://myapp.com/pricing',
});

return Response.redirect(url);

Mehrere line_items werden unterstützt. Bei Abonnements steht quantity für die Anzahl der Plätze.

3. Feature-Zugang prüfen

Bevor du einem Kunden die Nutzung eines Premium-Features erlaubst, ruf commerce.check() auf, um den Zugang zu verifizieren:

const { has_access } = await proyecta.commerce.check({
    customer_id: customer.id,
    resource_id: 'feat_pro_features',
});

if (!has_access) {
    return Response.json({ error: 'Upgrade required' }, { status: 402 });
}

Dies ist der empfohlene Weg, um Premium-Inhalte abzusichern. Weitere Informationen zum Feature- und Entitlement-Modell findest du unter Produkte & Features.

4. Ein Abonnement kündigen

await proyecta.commerce.cancel({
    customer_id: customer.id,
    subscription_id: 'sub_123',
    cancellation_timing: 'at_billing_period_end', // or 'immediate'
});

Standardmäßig behält der Kunde den Zugang bis zum Ende des Abrechnungszeitraums.

Die KI alles verdrahten lassen

Du musst das nicht von Hand schreiben. Nützliche Prompts:

• "Create a Proyecta customer when a user signs up. Store the proyecta_customer_id on the user record."
• "Build a /pricing page that shows my Proyecta products and starts a checkout when a button is clicked."
• "Gate the /admin route — only allow users whose Proyecta customer has access to feat_admin."
• "When a user clicks Cancel Subscription, call proyecta.commerce.cancel with at_billing_period_end."