Subscription Batches

Use POST /api/v1/subscriptions/batch to create a batch of subscription
adds and removals for a partner. The same endpoint accepts either a CSV file
or JSON rows. Send exactly one source per request.

This endpoint requires a Bearer JWT with subscription:write; the submitting
partner must be FICA verified. Batch creation is a partner-only write
operation; MVNO users do not create subscriptions themselves. Every row is
validated against accounts attributed to the submitting partner.

CSV upload

Send multipart/form-data with a single file field containing a CSV file.
The CSV format contains these columns:

account_uuid,action,product_uuid,start_date
22222222-2222-4222-8222-222222222222,add,33333333-3333-4333-8333-333333333333,2026-07-15
44444444-4444-4444-8444-444444444444,remove,55555555-5555-4555-8555-555555555555,

start_date is required for add rows and must be a future YYYY-MM-DD date.
Remove rows leave start_date blank. billing_date is no longer supported.

JSON upload

Send application/json with a rows array:

{
  "rows": [
    {
      "accountUuid": "22222222-2222-4222-8222-222222222222",
      "action": "add",
      "productUuid": "33333333-3333-4333-8333-333333333333",
      "startDate": "2026-07-15"
    },
    {
      "accountUuid": "44444444-4444-4444-8444-444444444444",
      "action": "remove",
      "productUuid": "55555555-5555-4555-8555-555555555555"
    }
  ]
}

action must be add or remove. Batches can contain up to 7500 rows.
Add rows require a future startDate. Remove rows omit startDate.
billingDate is no longer supported.
Submitting both file and rows, or neither, returns 400 Bad Request.

Response

The response is enveloped like other Nova API responses:

{
  "data": {
    "batchUuid": "66666666-6666-4666-8666-666666666666"
  }
}

After creation, poll GET /api/v1/subscriptions/batch/{batchUuid} to review
validation status and row-level errors.

Correcting a batch

Use PATCH /api/v1/subscriptions/batch/{batchUuid} to replace the rows on an
existing batch. The correction request accepts the same multipart/form-data
CSV file or application/json rows as the create request.

Corrections replace the full row set and restart validation. They are allowed
only after validation has finished and before processing starts. In practice,
correctable batches have status VALID, INVALID, or FAILED. Batch
correction is also a partner-only write operation, and partners can only
correct their own batches and attributed accounts.

Processing

Call POST /api/v1/subscriptions/batch/{batchUuid}/process after the batch
reaches VALID.

Processing is all-or-nothing at the batch gate: Nova rejects processing unless
every row in the batch is valid. If any row is invalid, correct the batch first
and process it after the corrected batch validates successfully.

Processing is a partner-only write operation. MVNO users can audit
subscriptions and batch history through the read endpoints, but they remain
read-only for creation, correction, and processing. Partners can only process
their own batches and attributed accounts.

Recurring billing

Nova runs subscription-start-activation before billing each day to publish activation events for due future-dated subscriptions. Then subscription-recurring-billing creates one subscription_billing_event for each active subscription whose next_billing_date is due, advances last_billing_date, next_billing_date, and bill_count, and posts one invoiceable finance event for Xero billing.

This first engine bills the full product price from the subscription start date. It does not calculate first-cycle pro-rata and does not call Totogi for recurring top-ups; the active Totogi plan subscription remains the benefit-renewal mechanism.