Custom licensing API
Launch supports Licentivo and custom licensing services. Select one store-wide provider in System settings → Licensing system.
Custom licensing products use the merchant's own licensing service and SDK. Launch manages sales, payment confirmation, purchase-state synchronization and delivery queries.
- Configure connections, signing keys, and product and plan mappings separately for sandbox and live. Check the connection before publishing plans.
- Connections with existing orders cannot be replaced directly. Migrate orders before switching providers, then publish the plans again.
- Verify purchases, renewals, upgrades, refunds and failure recovery in the test environment before publishing live settings.
Merchant licensing service endpoints
The merchant licensing service implements these four endpoints, and the Launch server calls them. Do not send these requests to www.licentivo.com.
| API | Purpose |
|---|---|
GET /launch/v1/capabilities | Declare the protocol, connection, environment, and supported purchase and delivery types. |
POST /launch/v1/events | Accept the complete purchase snapshot and return a receipt after durably storing the event. |
GET /launch/v1/events/{event_id} | Query the original event receipt. Only applied confirms that the licensing change is complete. |
GET /launch/v1/entitlements/{entitlement_ref}/delivery | Read existing delivery for the current purchase version without issuing another license. |
Snapshots contain the purchase version, current state and absolute validity dates; valid_until=null means a perpetual purchase. A base purchase may remain after a refund, so the receiver must recompute access from the complete snapshot.
{
"schema": "launch-external-licensing-v1",
"event_id": "7bf84b91-2749-4b01-a6a7-bd527c488ee8",
"connection_ref": "merchant-01-sandbox",
"environment": "sandbox",
"type": "entitlement.snapshot",
"change_reason": "purchase",
"account_ref": "customer_opaque_001",
"entitlement_ref": "purchase_opaque_001",
"launch_product_id": "c6dd463e-50f7-4b76-8239-0a8ec6fc304b",
"launch_plan_version_id": "5459a073-9362-4b46-949d-9b0c5d84421a",
"product_ref": "desktop-editor",
"plan_ref": "professional-yearly-v1",
"version": 1,
"desired_state": "active",
"valid_from": "2026-10-26T00:00:00Z",
"valid_until": "2027-10-26T00:00:00Z"
}Signatures and retries
Use a separate HMAC-SHA256 key with at least 32 random bytes for each connection. Requests include the key ID, Unix timestamp in seconds, a random nonce and a signature. Verify the signature, a 300-second time window and nonce replay protection.
v1
<key_id>
<timestamp>
<nonce>
<UPPERCASE HTTP METHOD>
<encoded full path and raw query>
<lowercase SHA-256 of the exact request body>Do not append a newline to the signature input. X-Launch-Signature is v1= followed by the unpadded base64url signature. GET bodies are empty.
Retries preserve the event ID and exact body, using a fresh nonce each time. Query the original event after a timeout. Older versions must not overwrite newer ones, and 202 does not confirm completed licensing.
Launch administration and customer endpoints
These endpoints belong to the merchant's own Launch site. Administrators use a website session and X-CSRF-Token. Customers can read only their own currently valid purchases.
PUT /api/v1/admin/licensing/provider | {"provider":"custom_http"} |
GET/POST /api/v1/admin/licensing/connections | GET/POST |
PUT /api/v1/admin/licensing/connections/{id} | POST /api/v1/admin/licensing/connections/{id}/check |
PUT /api/v1/admin/products/{id}/licensing | environment + connection_id + mappings |
GET /api/v1/me/products/{id}/delivery?environment=sandbox | pending / ready / unavailable |
Delivery may contain a license key, an HTTPS activation link or plain-text instructions. Successful synchronization does not replace runtime authorization checks in the client.
Full protocol and examples · Download OpenAPI · Python receiver example