Skip to content
Trile Docs

Quickstart

import { Steps } from ‘@astrojs/starlight/components’;

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

  1. Set your key and a base URL.

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

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

    Terminal window
    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" }'

    The response is enveloped; grab data.id (a prod_… ID):

    {
      "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.

    Terminal window
    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",
        "amount_paisa": "49900",
        "interval": "month"
      }'

    Keep the returned price_… ID.

  4. Create a customer.

    Terminal window
    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.", "phone": "+9779800000000" }'

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

    Terminal window
    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"
      }'

    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

Section titled “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

Section titled “Next steps”
  • 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_.