Mass Subscription Updates

Trevor Buckerfield
Trevor Buckerfield
  • Updated

CSV Template

https://gaiia.zendesk.com/guide-media/01KMZTMTPZCXBTGC4K5GGXXXAV

Overview

The Mass Subscriptions Update tool allows you to modify subscriptions on accounts en masse. It can be used to:

  1. Add new subscriptions.
  2. Remove subscriptions.
  3. Swap subscriptions (for pricing changes).

It can be extremely helpful for the following purposes:

  1. Adding a new promotional discount to a subset of accounts.
  2. Removing an expiring or no longer offered plan.
  3. Swapping out the price version of a subscription for pricing updates.

This feature only modifies subscriptions on accounts. It does not modify speeds or communicate with the network. Limit usage to non-network services or pricing changes.

Permissions

To access this tool, users must have the Apply mass subscription changes permission enabled.

This permission is located under Settings. Users with Edit can create changes, while users with View can only review past updates.

 

Using the tool

This section explains how to use the tool and key considerations.

Creating a subscription modification

To begin a mass subscription update:

  1. Click on Settings in the left-hand panel.
  2. Select Mass action.
  3. Click Subscription modifications.
  4. Click New modification.

 

The import template

A key part of the process is the CSV file defining which accounts and subscriptions are impacted.

Swapping a subscription changes billing only. If the new product version represents a different speed tier, gaiia does not provision that speed or notify the network. Confirm the speed change is handled separately before importing, otherwise accounts are billed at the new tier while still running at the old one.

CSV import

https://gaiia.zendesk.com/guide-media/01KMZTMTPZCXBTGC4K5GGXXXAV

Helpful reports

Account Services

  • Located in Analytics → Reports → Billing → Built-in Reports.
  • Provides:
    • accountId → Id column.
    • subscriptionId → Subscription Id column.

Product Versions

  • Located in Analytics → Reports → Billing → Built-in Reports.
  • Provides:
    • newProductVersionId → Product Version Id column.

 

Building the CSV from a report export

The fastest way to fill the template is to export the accounts to be updated from the Account Services report, then complete the file with the product version of the new subscription.

  1. Open Analytics → Reports → Billing → Built-in Reports and select the Account Services report.
  2. Apply filters so the report only returns the accounts and services that should be modified.
  3. Export the report to CSV.
  4. Copy the Id and Subscription Id columns from the export, then paste them into the accountId and subscriptionId columns of the mass action CSV.
    Keep both values on the same row as exported. Because a subscription UUID belongs to a single account, mixing values between rows targets the wrong subscription or fails the import.
  5. Add the product version UUID of the new subscription in the newProductVersionId column, taken from the Product Versions report.
    When every account moves to the same product version, the same value is repeated on all rows.
  6. Import the completed CSV in gaiia.

Saving the file

The importer expects a plain comma-separated file. How the file is saved matters as much as what it contains.

Do not use the CSV UTF-8 (Comma delimited) option in Excel. That format adds a hidden marker to the beginning of the file, which prevents the importer from reading the accountId column.

    1. Open Save As.
    2. Select CSV (Comma delimited) (*.csv) in the file type dropdown.
    3. Save the file.
    1. Open File → Download.
    2. Select Comma-separated values (.csv).

Keep the column headers exactly as they appear in the template: accountId, subscriptionId, and newProductVersionId.

If every row fails with "The Required field is missing" on the accountId column while the values themselves look correct, the file was saved in the wrong format. Re-save it as CSV (Comma delimited) and upload it again.

 

Choosing the action for each row

The CSV has no Action column. gaiia decides what to do with a row by looking at which cells are filled: subscriptionId points at a subscription that already exists, and newProductVersionId points at a product version to put in place. The combination of the two determines whether the row adds, removes or swaps a subscription.

Scroll right to view the whole table on smaller screens.

Action accountId subscriptionId newProductVersionId Result
Add Required Leave empty Required A new subscription is assigned to the account.
Remove Required Required Leave empty The subscription is cancelled on the account.
Swap Required Required Required The subscription is cancelled and replaced by a new one on the new product version.

A single file can mix the three actions. Each row is evaluated on its own, and rows are processed in parallel, so the order of the rows in the file is not the order in which they are applied.

Because rows are processed in parallel, do not rely on one row running before another. If an account must lose a subscription before gaining a new one, run two separate mass updates instead of two rows in the same file.

 

A. Adding a subscription

Use this action to put a new product on accounts that do not have it yet, such as a promotional discount or an add-on service.

  1. Fill accountId with the account UUID that receives the subscription.
  2. Leave subscriptionId empty.
    This is the cell that tells gaiia the row is an addition. If any value is present, gaiia treats the row as a swap and tries to replace that subscription instead.
  3. Fill newProductVersionId with the product version UUID to assign.

gaiia assigns the product version to the account as a brand-new subscription. Nothing existing on the account is touched, so the same product can end up on the account twice if it is already subscribed.

  1. The Prorate accounts to reflect their billing cycles setting applies to additions.
  2. The Manage accounts with custom pricing setting does not apply to additions. A new subscription is always created at the product version's price.

 

B. Removing a subscription

Use this action to take an expiring plan, a promotion or a discontinued service off a set of accounts.

  1. Fill accountId with the account UUID.
  2. Fill subscriptionId with the UUID of the subscription to cancel.
    The subscription must still be active. A subscription that was already unassigned is rejected during validation with the "No active subscription" error.
  3. Leave newProductVersionId empty.

gaiia cancels the subscription. In the results, it appears as "Cancelled" with an "Unassigned since" date.

  1. The Prorate accounts to reflect their billing cycles setting applies to removals and can generate a credit for the unused portion of the cycle.
  2. The Manage accounts with custom pricing setting does not apply to removals.

 

C. Swapping a subscription

Use this action for pricing changes: the customer keeps the same service, on a different product version.

  1. Fill accountId with the account UUID.
  2. Fill subscriptionId with the UUID of the subscription being replaced.
  3. Fill newProductVersionId with the UUID of the product version the subscription moves to.

A swap is not an edit of the existing subscription. gaiia cancels the subscription and creates a new one on the same account, on the new product version. This is why the results show two entries for a swapped account: the original subscription as "Cancelled", and its replacement.

The replacement carries over the subscription's status, its share configuration and its billing thresholds. Threshold usage counters restart at zero on the new subscription.

  1. Both additional settings apply to swaps. This is the only action where Manage accounts with custom pricing changes the outcome.
  2. A subscription can only be swapped to a product version that is compatible with it. Incompatible pairings are rejected when the row runs and are listed in the Errors tab.

Swapping a subscription changes billing only. If the new product version represents a different speed tier, gaiia does not provision that speed or notify the network. Confirm the speed change is handled separately before importing, otherwise accounts are billed at the new tier while still running at the old one.

 

CSV columns

The file has three columns. Which ones are filled defines the action, as described above.

Column Value When it is required
accountId The account UUID. Every row, for all three actions.
subscriptionId The subscription UUID. It is unique to a single account and is never shared between accounts, even when those accounts hold the same product. Removals and swaps. Must be left empty on additions.
newProductVersionId The product version UUID. Additions and swaps. Must be left empty on removals.

Every row needs an accountId plus at least one of subscriptionId or newProductVersionId. A row carrying only an accountId has no action to perform and fails validation.

Keep the three column names spelled as they appear in the template. Capitalization of the headers does not matter, so accountId, AccountId and accountid are all read correctly, but a different spelling is not recognized and the column is ignored.

 

What gaiia checks before the update runs

The file is validated as soon as it is uploaded, before anything is applied. If a row fails, the whole file is refused and the errors are listed with the column and the line concerned. Correct the file and upload it again.

Scroll right to view the whole table on smaller screens.

Error What it means How to fix it
"Required field is missing" on accountId The row has no account, or the file was saved in a format gaiia cannot read. Fill the column. If every row fails while the values look correct, re-save the file as CSV (Comma delimited).
"Required field is missing" on newProductVersionId The row has an account but neither a subscription nor a product version, so there is no action to perform. Add a subscriptionId to remove a subscription, or a newProductVersionId to add one.
"Invalid UUID" A value is not a UUID. This is often an Account ID pasted instead of the account UUID. Take the values from the Id and Subscription Id columns of the Account Services report.
"Missing entities" The account or the product version does not exist in this environment. Confirm the export came from the same environment as the import.
"Archived product version" The product version in newProductVersionId is archived and cannot be assigned. Use an active product version, or unarchive it before importing.
"No active subscription" The subscription in subscriptionId does not exist or has already been unassigned. Refresh the export from the Account Services report and rebuild the file.
"Empty CSV" The file has headers but no rows. Add the rows to update.

A file that passes validation shows the number of subscriptions it will update, and that same count is repeated in the confirmation dialog before the update runs. Check it against the number of rows expected before confirming.

Validation confirms that the accounts, subscriptions and product versions exist. A row can still fail while it is being applied, for example on an incompatible product version. Those failures are listed in the Errors tab of the update.

 

Import process

The import process is completed in the following steps:

  1. Name the update using the Name field.
  2. Upload the CSV file.
  3. Configure additional settings.
  4. Click New modification to run the import.
  5. Monitor the activity in the results section.

import process

Additional settings

These settings define how gaiia behaves during the update.

Manage accounts with custom pricing

This setting controls how existing price overrides are handled:

  1. Keep existing price overrides: Maintains current pricing.
  2. Apply lower price: Uses the lowest price between override and new version.
  3. Override existing price overrides: Applies the new version pricing.

Prorate accounts to reflect their billing cycles

When enabled, gaiia creates prorated charges or discounts based on the billing cycle.

When disabled, pricing changes take effect at the next billing cycle.

 

Review results

You can review a mass update by selecting it from the list.

  1. Review modified subscriptions.
  2. Review generated transactions (if prorated).

Subscriptions area

The Subscriptions tab shows the final state of each modified subscription.

A subscription removed will appear as "Cancelled" with an "Unassigned since" date.

Click a row to view more details or navigate to the account.

subscriptions tab

Transactions area

The Transactions tab displays any charges or discounts created by proration.

Both debit and discount entries may appear depending on the update.

Click a row to view more details or navigate to the account.

transactions tab

Related to

Was this article helpful?

Have more questions? Submit a request