Integrate Commerce Into My App

Use the Proyecta SDK to create customers, start checkouts, gate features, and cancel subscriptions from your app code.

Once you’ve connected Stripe and created a product, you wire commerce into your app via the proyecta.commerce SDK resource. The four most common operations are: create a customer, start a checkout, check feature access, and cancel a subscription.

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

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

1. Create a customer

A customer is the billable entity in your app — usually a user, org, or project. Create one as soon as the corresponding entity is created in your database, then store the returned id so you can reference the customer in checkouts and access checks.

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

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

You can also pass a billing address (line1, line2, city, state, postal_code, country) at creation or via customers.update().

2. Start a checkout

commerce.checkout() creates a Stripe-hosted checkout session and returns a URL to redirect the customer to. After payment, Stripe redirects the customer to your success_url.

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);

Multiple line_items are supported. For subscriptions, quantity represents seat count.

3. Check feature access

Before letting a customer use a premium feature, call commerce.check() to verify they have access:

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 });
}

This is the recommended way to gate premium content. See Products & Features for the feature/entitlement model.

4. Cancel a subscription

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

By default, the customer keeps access until the end of the billing period.

Let the AI wire it all up

You don’t need to write this by hand. Common 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."