Hi OpenMeter team,

We are running a self-hosted OpenMeter OSS deployment with Helm on Alibaba Cloud ACK.

• OpenMeter chart: 1.0.0-beta.227
• API used for this POC: OSS /api/v1 and customer entitlement /api/v2
• We do not use Stripe billing in OpenMeter. Our current use case is subscription quota calculation and native entitlement threshold webhooks.
• Meter: api_credits
• Feature: api_credits
• Test customer: poc-test-20250519

Our product requirement:

1. Mid-cycle upgrade from free to starter should take effect immediately.
2. Current billing-period usage must be preserved.
3. Entitlement threshold notifications should continue to work using OpenMeter native notifications.
4. Mid-cycle downgrade from starter to free should take effect at the next billing cycle.
5. We prefer subscription-managed entitlements, because manual entitlements require us to separately handle next-cycle reset and plan-to-entitlement synchronization.

Plan setup

The plans use subscription-managed metered entitlements through rateCards[].entitlementTemplate.

Example free plan entitlement:

{
  "type": "usage_based",
  "key": "api_credits",
  "name": "API Credits",
  "featureKey": "api_credits",
  "billingCadence": "P1M",
  "price": null,
  "entitlementTemplate": {
    "type": "metered",
    "issueAfterReset": 50000,
    "usagePeriod": "P1M"
  }
}

Example starter plan entitlement:

{
  "type": "usage_based",
  "key": "api_credits",
  "name": "API Credits",
  "featureKey": "api_credits",
  "billingCadence": "P1M",
  "price": null,
  "entitlementTemplate": {
    "type": "metered",
    "issueAfterReset": 550000,
    "usagePeriod": "P1M"
  }
}

Current validation flow

1. Check customer subscription and entitlement value

curl -i -X GET 'http://8.211.17.102/api/v1/customers/poc-test-20250519?expand=subscriptions' \
  -H 'content-type: application/json'

curl -i -X GET 'http://8.211.17.102/api/v1/customers/poc-test-20250519/entitlements/api_credits/value' \
  -H 'content-type: application/json'

curl -i -X GET 'http://8.211.17.102/api/v2/customers/poc-test-20250519/entitlements/api_credits' \
  -H 'content-type: application/json'

2. Send a usage event

curl -i -X POST 'http://8.211.17.102/api/v1/events' \
  -H 'content-type: application/cloudevents+json' \
  -d '{
    "specversion": "1.0",
    "type": "api_request",
    "id": "req-poc-20250519-before-upgrade-001",
    "time": "2026-05-20T06:00:00Z",
    "source": "api7-gateway",
    "subject": "poc-test-20250519",
    "data": {
      "credits": 3,
      "service_type": "control_api"
    }
  }'

Then check entitlement value again:

curl -i -X GET 'http://8.211.17.102/api/v1/customers/poc-test-20250519/entitlements/api_credits/value' \
  -H 'content-type: application/json'

Expected before upgrade:

{
  "totalAvailableGrantAmount": 50000,
  "usage": 3,
  "balance": 49997
}

3. Try change subscription from free to starter

curl -i -X POST 'http://8.211.17.102/api/v1/subscriptions/<FREE_SUBSCRIPTION_ID>/change' \
  -H 'content-type: application/json' \
  -d '{
    "timing": "immediate",
    "plan": {
      "key": "starter"
    },
    "billingAnchor": "2026-05-01T00:00:00Z"
  }'

Observed behavior:

• The subscription plan changes to starter.
• A new subscription-managed entitlement is created.
• The new entitlement starts measuring from the change time.
• Current-period usage is reset to 0 from the entitlement value perspective.

This causes native entitlements.balance.threshold notifications to lose the previous current-period usage.

4. Try overriding the customer entitlement after subscription change

We tried to force the new entitlement to measure from the current period start:

curl -i -X PUT 'http://8.211.17.102/api/v2/customers/poc-test-20250519/entitlements/api_credits/override' \
  -H 'content-type: application/json' \
  -d '{
    "type": "metered",
    "featureKey": "api_credits",
    "usagePeriod": {
      "interval": "MONTH",
      "anchor": "2026-05-01T00:00:00Z"
    },
    "measureUsageFrom": "2026-05-01T00:00:00Z",
    "isSoftLimit": false,
    "preserveOverageAtReset": false,
    "issue": {
      "amount": 550000,
      "priority": 1
    }
  }'

Observed response:

{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "detail": "forbidden error: entitlement is managed by subscription"
}

So override does not seem to be allowed for subscription-managed entitlements.

5. Possible workaround: edit subscription

Instead of change subscription, we can try editing the current subscription item and changing the entitlement limit from 50000 to 550000.

curl -i -X PATCH 'http://8.211.17.102/api/v1/subscriptions/<FREE_SUBSCRIPTION_ID>' \
  -H 'content-type: application/json' \
  -d '{
    "timing": "immediate",
    "customizations": [
      {
        "op": "add_item",
        "phaseKey": "default",
        "rateCard": {
          "type": "usage_based",
          "key": "api_credits",
          "name": "API Credits",
          "featureKey": "api_credits",
          "billingCadence": "P1M",
          "price": null,
          "entitlementTemplate": {
            "type": "metered",
            "issueAfterReset": 550000,
            "usagePeriod": "P1M"
          }
        }
      }
    ]
  }'

If the item already exists, try remove and add:

curl -i -X PATCH 'http://8.211.17.102/api/v1/subscriptions/<FREE_SUBSCRIPTION_ID>' \
  -H 'content-type: application/json' \
  -d '{
    "timing": "immediate",
    "customizations": [
      {
        "op": "remove_item",
        "phaseKey": "default",
        "itemKey": "api_credits"
      },
      {
        "op": "add_item",
        "phaseKey": "default",
        "rateCard": {
          "type": "usage_based",
          "key": "api_credits",
          "name": "API Credits",
          "featureKey": "api_credits",
          "billingCadence": "P1M",
          "price": null,
          "entitlementTemplate": {
            "type": "metered",
            "issueAfterReset": 550000,
            "usagePeriod": "P1M"
          }
        }
      }
    ]
  }'

This might preserve current-period usage, but it does not appear to change the subscription plan key from free to starter.

That means the entitlement behavior becomes starter-like, but the subscription still looks like the free plan.

We are also not sure whether this only edits the current subscription's rate card for the current timeline, instead of making the subscription truly become the starter plan for future billing periods. If so, the customer might not automatically continue as a starter subscriber in the next billing cycle, which would not satisfy our product requirement.

Question

For subscription-managed entitlements, what is the recommended way to implement this upgrade/downgrade lifecycle?

Required behavior:

1. Upgrade free -> starter in the middle of a billing period.
2. The upgrade takes effect immediately.
3. The subscription should reflect the new plan.
4. The subscription-managed metered entitlement should preserve current-period usage.
5. Native entitlement threshold notifications should continue using the preserved current-period usage.
6. Downgrade starter -> free should be scheduled for the next billing cycle.

Is edit subscription the only supported way to preserve current-period usage for immediate mid-cycle upgrades, even if the subscription plan key remains inaccurate?

If yes, does edit subscription make the customer continue with the edited starter-like rate card in future billing periods, or does it only patch the current subscription timeline without turning the subscription into the starter plan?

Or is there a supported way to use change subscription while making the new subscription-managed entitlement measure usage from the current billing period start?

Notes

We also validated a manual entitlement model:

• Create plans without entitlementTemplate
• Create subscription normally
• Create customer entitlement manually
• On subscription change, manually override the entitlement

That model can preserve usage, but it makes next-period reset and plan-to-entitlement synchronization the responsibility of our Portal. We would prefer to keep subscription-managed entitlements if possible.