Quickstart

This guide creates a product, a price, a customer, and a subscription — all in test mode. You’ll need a merchant account and a nep_test_ API key (see Authentication).

Pick cURL or the TypeScript SDK with the toggle on each step — your choice syncs across the page.

Base URL

All examples use https://api.trile.app. For local development the API runs on http://localhost:3000. The path prefix is always /v1.

1. Set your key (cURL) or create a client (SDK).

   cURL

   export TRILE_KEY="nep_test_your_key_here"
   export TRILE_API="https://api.trile.app"

   TypeScript

   npm install @trilehq/sdk

   import { Configuration, CatalogApi, CustomersApi, SubscriptionsApi } from '@trilehq/sdk'
   
   const config = new Configuration({ apiKey: process.env.TRILE_KEY })
   const catalog = new CatalogApi(config)
   const customers = new CustomersApi(config)
   const subscriptions = new SubscriptionsApi(config)

2. Create a product. Note the Idempotency-Key — it’s required on every write.

   cURL

   curl -s "$TRILE_API/v1/catalog/products" \
     -H "x-api-key: $TRILE_KEY" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{ "name": "Pro plan" }'

   TypeScript

   const { data: product } = await catalog.createProduct({
     createProduct: { name: 'Pro plan' },
     idempotencyKey: crypto.randomUUID(),
   })
   // product.id → "prod_…"

   Every response is enveloped — the object is in data (the SDK returns it typed):

   {
     "success": true,
     "data": { "id": "prod_01ARZ3NDEKTSV4RRFFQ69G5FAX", "name": "Pro plan", "active": true },
     "meta": { "requestId": "req_aBcDeFgHiJkL" }
   }

3. Create a monthly price. Amounts are in paisa (NPR 499.00 → "49900"), as a string.

   cURL

   curl -s "$TRILE_API/v1/catalog/prices" \
     -H "x-api-key: $TRILE_KEY" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "productId": "prod_01ARZ3NDEKTSV4RRFFQ69G5FAX",
       "amountPaisa": "49900",
       "interval": "month"
     }'

   TypeScript

   const { data: price } = await catalog.createPrice({
     createPrice: { productId: product.id, amountPaisa: '49900', interval: 'month' },
     idempotencyKey: crypto.randomUUID(),
   })
   // price.id → "price_…"

4. Create a customer.

   cURL

   curl -s "$TRILE_API/v1/customers" \
     -H "x-api-key: $TRILE_KEY" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{ "email": "asha@example.com", "name": "Asha K." }'

   TypeScript

   const { data: customer } = await customers.createCustomer({
     createCustomer: { email: 'asha@example.com', name: 'Asha K.' },
     idempotencyKey: crypto.randomUUID(),
   })
   // customer.id → "cus_…"

5. Fund the wallet (test mode). A subscription’s first cycle charges immediately, so the customer’s wallet must hold at least the cycle amount. In production the customer tops up via hosted checkout; in test mode you can drive the customer wallet flow or start the subscription via a checkout session. The simplest path for a first integration is to send the customer through a checkout session, which combines top-up and subscribe.

6. Create the subscription (direct API path — assumes a funded wallet):

   cURL

   curl -s "$TRILE_API/v1/subscriptions" \
     -H "x-api-key: $TRILE_KEY" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "customerId": "cus_01ARZ3NDEKTSV4RRFFQ69G5FAW",
       "priceId": "price_01ARZ3NDEKTSV4RRFFQ69G5FAY"
     }'

   TypeScript

   const { data: subscription } = await subscriptions.createSubscription({
     createSubscription: { customerId: customer.id, priceId: price.id },
     idempotencyKey: crypto.randomUUID(),
   })
   // subscription.status → "active"

   A 201 returns a sub_… with status: "active". If the wallet is short you get a 400 with error.code: "insufficient_funds".

7. Listen for events. Register a webhook endpoint and handle subscription.created, invoice.paid, and invoice.payment_failed so your app reacts to renewals without polling.

What just happened

You modeled a plan (product + price), a buyer (customer + wallet), and a recurring commitment (subscription). From here Trile’s billing engine generates an invoice each cycle and deducts the wallet automatically.

Next steps

• TypeScript SDK — typed clients for every endpoint.
• Hosted checkout — the recommended way to onboard real customers (handles top-up + KYC + subscribe).
• Webhooks — verify signatures and react to billing events.
• Going live — swap nep_test_ for nep_live_.