The bulk subscription update import allows users to edit high-level subscription information such as labels and some 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. Note that you can not 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. 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 | Date the subscription will activate. This time must be within the contract start and end date. 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 | Identifier of a particular billing period. This can be located under the Customer Overview page, on the Invoice section. | Integer |
|
InvoiceOwner |
Set the owner of the subscription (who will be invoiced). | InvoiceThisCustomer/ InvoiceParent |
Restrictions:
- File must contain at least 2 columns.
- File cannot contain more than 1000 subscriptions.
- Subscription IDs must exist, or,
- If using subscription names 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.
- 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.