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
SOBTRA_API_URL=https://api.sobtra.com
SOBTRA_API_KEY=your_test_api_key2. 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
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
{
"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
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
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.