Subscription Amendments | Abaxus Software

What Is an Amendment?

A subscription amendment is a scheduled change to a subscription. Rather than mutating the subscription object directly (which would corrupt billing history), amendments are separate objects that describe what should change and when. A background worker polls for pending amendments every 60 seconds and applies them at the scheduled time.

This design means you can schedule a cancellation for end of period, a plan upgrade for tomorrow, or a pause starting next week — and the historical billing record for the periods before the amendment remains untouched.

The 5 Amendment Types

`plan_change`

Migrates the subscription to a different plan or plan version. Used for upgrades, downgrades, and version migrations.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
curl -X POST "$ABAXUS_URL/v1/subscriptions/sub_01hx8km.../amendments" \
  -H "Authorization: Bearer $ABAXUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "plan_change",
    "new_plan_id": "plan_enterprise",
    "new_plan_version": 1,
    "effective": "end_of_period",
    "prorate": false
  }'

When effective: "immediate" and prorate: true, ABAXUS automatically calculates the prorated credit for the remaining days of the current period under the old plan and adds it as a line item on the next invoice.

`pause`

Suspends the subscription without terminating it. Events sent during a pause are not billed. Entitlements are suspended during the pause. The subscription resumes at the resume_date (or when a resume amendment is applied).

1
2
3
4
5
6
7
8
curl -X POST "$ABAXUS_URL/v1/subscriptions/sub_01hx8km.../amendments" \
  -H "Authorization: Bearer $ABAXUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "pause",
    "effective": "end_of_period",
    "resume_date": "2026-07-01T00:00:00Z"
  }'

`resume`

Lifts a pause and reactivates the subscription. Can be applied immediately or scheduled.

1
2
3
4
5
6
7
curl -X POST "$ABAXUS_URL/v1/subscriptions/sub_01hx8km.../amendments" \
  -H "Authorization: Bearer $ABAXUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "resume",
    "effective": "immediate"
  }'

`cancel`

Terminates the subscription. Usage events after the cancellation date are not billed. Entitlements are removed immediately when the cancellation takes effect.

1
2
3
4
5
6
7
8
curl -X POST "$ABAXUS_URL/v1/subscriptions/sub_01hx8km.../amendments" \
  -H "Authorization: Bearer $ABAXUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "cancel",
    "effective": "end_of_period",
    "reason": "customer_request"
  }'

Using effective: "end_of_period" is the standard approach for customer-initiated cancellations. The customer retains access and billing continues until the current period ends, then the subscription is cancelled.

`end_date_change`

Updates the subscription’s end_date — useful for extending a trial, shortening a fixed-term contract, or adjusting an expiry date without a full plan change.

1
2
3
4
5
6
7
8
curl -X POST "$ABAXUS_URL/v1/subscriptions/sub_01hx8km.../amendments" \
  -H "Authorization: Bearer $ABAXUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "end_date_change",
    "new_end_date": "2026-06-30T23:59:59Z",
    "effective": "immediate"
  }'

Immediate vs End-of-Period Timing

Most amendment types support two timing options:

"effective": "immediate": The amendment is applied at the exact time the background worker picks it up (within 60 seconds of the scheduled time). Use for upgrades where the customer should get immediate access, or for urgent cancellations.

"effective": "end_of_period": The amendment is applied at the end of the current billing period. ABAXUS calculates the period end from the subscription’s start_date and billing_period. This is the standard timing for non-urgent changes.

Scheduled future date: You can also specify a specific future timestamp:

1
{ "effective": "2026-05-01T00:00:00Z" }

Proration on Plan Changes

When a plan change takes effect mid-period with prorate: true, ABAXUS generates proration line items on the next invoice:

Credit: The unused portion of the old plan’s flat fees for the remaining days
Charge: The new plan’s flat fees for the same remaining days

Usage-based charges are not prorated — they’re calculated based on actual events in each partial period. Only flat fees and per-seat charges are subject to proration.

The Background Worker

Amendment application is handled by ABAXUS’s background worker process. The worker polls the amendments table every 60 seconds using PostgreSQL’s SKIP LOCKED pattern, which ensures:

Only one worker instance processes a given amendment even if you run multiple replicas
Worker restarts don’t cause double-processing
Database-level consistency — an amendment is either applied or not, never partial

The 60-second polling interval means amendments take effect within 60 seconds of their scheduled time, not at the exact second. For the vast majority of use cases (end-of-period changes, next-day plan upgrades), this is completely acceptable. If you need sub-minute precision, consider scheduling amendments a few minutes before the target time.

Cancelling a Scheduled Amendment

If you scheduled an amendment and need to undo it before it’s applied:

1
2
curl -X DELETE "$ABAXUS_URL/v1/subscriptions/sub_01hx8km.../amendments/amd_01hx9..." \
  -H "Authorization: Bearer $ABAXUS_KEY"

Only pending amendments can be cancelled. Once an amendment is in applied status, it has already taken effect and cannot be undone. To reverse an applied amendment, create a new corrective amendment.

Listing Amendments

1
2
curl "$ABAXUS_URL/v1/subscriptions/sub_01hx8km.../amendments" \
  -H "Authorization: Bearer $ABAXUS_KEY"

Returns all amendments for the subscription with their status (pending, applied, cancelled), scheduled effective time, and result details for applied amendments.