The bulk subscription update import allows users to edit high-level subscription information such as labels and timing elements. These elements are highlighted below.
This works by submitting a CSV file of specific subscriptions and the details that you would like to edit.
Target subscriptions need to be identified by supplying a unique Stax Bill ID generated subscription Id (available from the Subscription reporting from within Stax Bill). Not all of the subscription fields need to be submitted in the file. Subscriptions can alternatively be identified by Subscription Name. Those subscriptions identified by their name require unique names which are not enforced by Stax Bill and would need to be enforced by a business process outside of Stax Bill.
Because this job operates as an edit, if you wish to delete existing values in a field, the special string "clear" can be used. Any fields submitted with a blank value will be ignored by the bulk editor.
Fields that can be controlled in this import:
- Subscription Name
- Subscription Description
- Subscription Reference
- Contract Start Date
- Contract End Date
- Scheduled Activation Date
- Expiry Periods
- BillingPeriodDefinitionId
- InvoiceOwner
File format
The Bulk Subscription Edit job requires the upload of a CSV file.
The file must have a header row containing at least one of the following fields
- SubscriptionId
- SubscriptionName (note that names must be unique)
Sample of a full Bulk Subscription Activation file:
| SubscriptionId | SubscriptionName | SubscriptionDescription | SubscriptionReference | ContractStartDate | ContractEndDate | ScheduledActivationPeriod | ExpiryPeriod | BillingPeriodDefinitionId | InvoiceOwner |
| 234567 | Service for Jane | VIN#SAMJ45674A5 | 2020-06-13 | 2023-06-12 | 2020-07-13 | 12 | 10278085 | ||
| 345890 | clear | InvoiceParent | |||||||
| 456897 | VIN#55354J23M35 | clear |
Field definitions:
To clear a field, enter clear. A blank entry will make no changes to the value in Stax Bill. Just so you know, you can't clear a SubscriptionId or InvoiceOwner field.
| Field Name | Description | Value |
| SubscriptionId | A Stax Bill generated identifier. This can be obtained by downloading the subscription report. This value is mandatory if a SubscriptionName is not provided. | |
| SubscriptionName | Unique name for a subscription. This value is mandatory if a SubscriptionId is not provided. | 255 character string |
| SubscriptionDescription | Description of subscription. It will appear on the invoice. | 255 character string |
| SubscriptionReference | A text field that can be used for API or GeoTab integrations. | 255 character string |
| ContractStartDate | Start date of the contract. | YYYY-MM-DD |
| ContractEndDate | End date of the contract. | YYYY-MM-DD |
| ScheduledActivationDate | The date the subscription will activate. This time must be within the contract start and end dates. On this date, the subscription will be set to active. If you clear this field before activation, the subscription will return to draft status. You cannot change the field after the subscription has been activated. | YYYY-MM-DD |
| ExpiryPeriods | The number of billing cycles remaining before the subscription status is set to expire. | Integer. (Note: clear will remove any expiry set). |
| BillingPeriodDefinitionId | The ID of a particular billing period is located under the Customer Overview page in the Invoice section. | Integer |
|
InvoiceOwner |
Set the owner of the subscription (who will be invoiced). | InvoiceThisCustomer/ InvoiceParent |
Restrictions:
- The file must contain at least two columns.
- The file cannot contain more than 5000 subscriptions.
- Subscription IDs must exist, or,
- If subscription names are used instead of subscription IDs, then subscription names must be unique and already exist in the account.
- Blank field values will be ignored.
- Submitting the string clear will clear out an existing value.
- The date values submitted will be interpreted in your account time zone.
- Scheduled activation timestamp cannot be modified on subscriptions that have already generated financial records.