Quickstart

GETTING STARTED

Quickstart

Learn how to connect your application to Sobtra and begin managing products, customers, subscriptions, and billing.

Before you begin

You need a Sobtra merchant account, at least one product and price, and an API credential appropriate for the endpoints you intend to call.

  • Create or select your merchant account.
  • Configure a product, plan, and price.
  • Create an API key for the appropriate environment if the endpoint uses API-key authentication.
  • Keep secret credentials on your server, never in browser JavaScript.

1. Configure your API connection

Set your backend API origin in your application's environment configuration. Use the origin provided by your Sobtra deployment; local development and hosted deployments may use different origins.

Environment variables

dotenvExample
SOBTRA_API_URL=https://api.sobtra.com
SOBTRA_API_KEY=your_test_api_key

2. Authenticate your requests

For endpoints protected by API-key authentication, send your key in the Authorization header. Use the authentication method required by the particular endpoint.

HTTP request

bashExample
curl "$SOBTRA_API_URL/users/me/merchants" \
  -H "Authorization: Bearer $SOBTRA_API_KEY" \
  -H "Accept: application/json"

3. Create your billing configuration

Configure your product, plan, and price before creating a subscription. A product describes what you sell, a plan describes the subscription offering, and a price defines its billing terms.

Example subscription pricing

jsonExample
{
  "product": "Premium Workspace",
  "plan": "Professional",
  "price": 7500,
  "currency": "NGN",
  "billingInterval": "monthly"
}

4. Create a customer

Customers represent the people or businesses whose subscriptions you manage. Create a customer within your merchant before creating subscriptions for them.

Create a customer

bashExample
curl -X POST "$SOBTRA_API_URL/merchants/YOUR_MERCHANT_ID/customers" \
  -H "Authorization: Bearer $SOBTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalCustomerId": "customer_123",
    "name": "Ada Okafor",
    "email": "ada@example.com"
  }'

5. Create a subscription

Once the customer and price exist, create a subscription using their identifiers. The subscription tracks its billing period and lifecycle state.

Create a subscription

bashExample
curl -X POST "$SOBTRA_API_URL/subscriptions" \
  -H "Authorization: Bearer $SOBTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "CUSTOMER_ID",
    "planId": "PLAN_ID",
    "priceId": "PRICE_ID",
    "currentPeriodStart": "2026-10-22T00:00:00.000Z",
    "currentPeriodEnd": "2026-11-22T00:00:00.000Z"
  }'

6. Continue your integration

After creating a subscription, integrate invoice and payment handling, process webhook events, and keep your application in sync with subscription state changes.

Related documentation