Orders And Subscriptions

Use this page to link external commerce records to licenses and reporting without treating LicenseKit as a billing engine.

Who This Is For

• teams syncing order or subscription records from another system
• developers linking commercial context to license issuance and renewal
• operators using reporting filters tied to commerce records

When To Use This

Use orders and subscriptions when you need external commerce linkage, attribution, and reporting filters.

Do not use them as a replacement for your billing provider.

How It Works

Commerce management routes:

• GET /api/v1/products/{id}/subscriptions
• POST /api/v1/products/{id}/subscriptions
• GET /api/v1/subscriptions/{id}
• PATCH /api/v1/subscriptions/{id}
• GET /api/v1/products/{id}/orders
• POST /api/v1/products/{id}/orders
• GET /api/v1/orders/{id}
• PATCH /api/v1/orders/{id}

Scope split:

• reads use product:read
• writes use product:write

Important semantics from the API contract:

• subscriptions require current_period_start and current_period_end
• orders may omit period fields, but if one is present the other must be too
• the service stores these records as linked external facts
• the service does not add proration or billing-provider-specific behavior

License linkage behavior:

• license create can persist order_id and subscription_id
• if the order already links to a subscription and subscription_id is omitted, the subscription link is inferred
• renewal-time order and subscription values are validated and written to audit metadata, but do not rewrite stored origin linkage

Example

Create a subscription:

curl -X POST https://api.licensekit.dev/api/v1/products/prod_123/subscriptions \
  -H "Authorization: Bearer $LICENSEKIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_123",
    "external_system": "stripe",
    "external_id": "sub_abc",
    "status": "active",
    "current_period_start": "2026-04-01T00:00:00Z",
    "current_period_end": "2026-05-01T00:00:00Z"
  }'

Create an order:

curl -X POST https://api.licensekit.dev/api/v1/products/prod_123/orders \
  -H "Authorization: Bearer $LICENSEKIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_123",
    "subscription_id": "sub_123",
    "external_system": "stripe",
    "external_id": "ord_abc",
    "status": "paid"
  }'

Common Mistakes

• assuming orders and subscriptions imply billing-engine behavior
• linking records across products that should not be linked
• assuming renewal rewrites the license’s stored origin linkage

Related Pages

• License Lifecycle
• Subscription Settlement
• Customer Summary