Overview
This document provides all the necessary information on building the CSVs that can be used when applying discounts through the Mass Actions area. Other documentation on this particular subject will cover other areas of the feature and how to use it.
Why CSVs?
CSVs are an extremely flexible way to provide a list of data to gaiia that will accomplish a variety of different actions. They offer a means to provide a complex list of accounts that can all have varying discounts and amounts applied within a single process.
Guide: Mass Discounts
This article is part of a larger guide about the Mass Discounts feature
How Can I Generate these CSVs?
The required CSVs can be generated in a variety of different ways, depending on your preference.
A few means to generate the required CSVs are:
- Downloading the CSV template (provided below) and manually filling it out with the required information.
- Using Snowflake to help generate the data for you.
- Using a combination of both methods.
If at any point you need help with building your template, you are more than welcome to contact our support for assistance.
You do not need to use the provided template, as long as your CSV has the same column names.
CSV Data & Requirements
General CSV Requirements
In order for gaiia to process your CSV, it must meet the following requirements:
-
Is in a CSV format
-
Uses commas to separate the data
-
Contains the required columns.
-
When not using a particular column (for example, you are choosing to use a subscription proration instead of applying a flat amount) the values for those columns should be left empty.
-
Double quotes (””) should not be added to the data.
- Amounts should always be entered as cents.
For example $10.99, would be entered as 1099 in the CSV.
- Dates should always follow this format: YYYY-MM-DD.
Expected Format
accountId | discountReason | amountOverride | internalNote |
---|---|---|---|
a2fca971-ee52-46e5-b28e-d0cf3d8b5e5b | PROMOTION | 1099 | Test |
Will Cause Errors
accountId | discountReason | amountOverride | internalNote |
---|---|---|---|
"a2fca971-ee52-46e5-b28e-d0cf3d8b5e5b" | "PROMOTION" | "10.99" | "Test" |
Available CSV Fields
Scroll right to view the whole table on smaller screen
Merge tag | Description | CSV Template(s) | Required? | Requirements | Example |
---|---|---|---|---|---|
accountId | The UUID of the account receiving the discount. The same account can be repeated if they are receiving multiple discounts. | ALL | Always |
This is NOT the Account ID, but the unique id assigned to each account within it (UUID). This id can easily be determined by following one of those methods: Finding an object's UUID Please ensure that the account is in “good” standing before selecting. |
a2fca971-ee52-46e5-b28e-d0cf3d8b5e5b |
discountReason | The reason for applying the discount. | ALL | Always |
Can be one of the following options: “ADJUSTMENT”, “GUARANTEE”, “OUTAGE”, “PROMOTION”, “REFERRAL”. An “ADJUSTMENT” discount reason can only be created with a product/subscription discount. All discount reasons MUST be in uppercase. |
PROMOTION |
productVersionId | If applying a product discount, this is the id of the product being discounted. | Product Discount | Only when applying a product discount. |
It can be determined by using the value from the Product version ID column when viewing the product from the product catalogue. |
f9fb9d56-ef17-4ef0-88b7-719af11ea93f |
subscriptionId | If applying a subscription discount, this is the id of the subscription being discounted. | Subscription Discount | Only when applying a subscription discount. |
The id provided must match a subscription currently assigned to the account. This is not the product version id of equivalent product in the product catalogue. The id can be found by starting modifying the desired subscription, and pulling the id from the URL. Alternatively, tools like Snowflake provide these details as well. |
3f98ce65-15f7-4136-8abe-d439df87d792 |
amountOverride | The value of the discount. | ALL |
Required for custom discounts. Product/service discounts are optional if applying the full amount or using subscription proration. |
This field must be provided and expressed as the amount in cents (for example, $1 = 100). A $0 value cannot be provided nor can the amount specified exceed the amount of the product or subscription being discounted. Can be removed/left empty if the full value of the product/subscription in should be discounted. |
2225 (will apply a $22.25 discount) |
amountOverrideTaxable | Whether tax should also be included as part of the discount. | ALL |
Optional |
Can either be “true” or “false”. If taxes should also be included in the discount, specify “true”. This must be used with the amount override field. If applying a product/subscription discount, if left empty, tax will be calculated if tax is collected on the product/service. |
true |
proratedFrom |
If desired, the subscription discount amount can be calculated by using a specified date range within the current billing cycle (prorated). This is the start date of the proration. |
Subscription Discount |
Optional |
Always expressed in the following format: YYYY-MM-DD. Both the proratedFrom and proratedTo dates must be provided. Dates a minimum of one day apart should be prorated in order for the subscription to be prorated. If you are choosing to use the amountOverride, this is not required and can be left empty or removed. |
2024-03-21 |
proratedTo |
If desired, the subscription discount amount can be calculated by using a specified date range within the current billing cycle (prorated). This is the end date of the proration. |
Subscription Discount |
Optional |
Always expressed in the following format: YYYY-MM-DD. Both the proratedFrom and proratedTo dates must be provided. Dates a minimum of one day apart should be prorated in order for the subscription to be prorated. If you are choosing to use the amountOverride, this is not required and can be left empty or removed. |
2024-03-22 |
quantity | How many times the discount should be applied to the account. | Custom Discount |
Required for Custom Discounts |
Must be a whole number. Cannot be 0 or negative. |
1 |
description | The name of the discount that will appear on an account’s invoice (”Invoice description” when applying it in gaiia). | Custom Discount |
Required for Custom Discounts |
Cannot exceed 250 characters. |
Credit for recent outage |
internalNote | The full billing address associated with the account. For example: 123 Fake Street, Toronto, ON L6H 1Y4. | Custom Discount | Optional | Cannot exceed 250 characters. |
CRX-22 outage credit
|
CSV Templates
-
This CSV will apply the same custom discount as if it was applied through the Transactions area by a user. Key details to remember here are:
- Within the list of accounts provided, ensure that they are in “good” standing.
- The “ADJUSTMENT” reason type cannot be used with custom discounts.
- The following fields must be provided:
-
accountId (UUID of the account)
Read Finding an object's UUID
- discountReason
- amountOverride
- description (Invoice Description)
- quantity
-
accountId (UUID of the account)
- If not specified, gaiia will by default check to see if a tax rate (or if rates are setup) for the region the account’s physical address is located in.
- A quantity of 1 or more must be specified.
- The discount must have a value greater than 0.
-
This CSV will apply the same subscription discount as if it was applied through the Transactions area by a user. Key details to remember here are:
- Within the list of accounts provided, ensure that they are in “good” standing.
- Note the unique id of the subscription being discounted for each account.
- Requires manual additional verification to ensure that each account being included actually have the active subscription specified in the CSV.
- Requires that the amount being specified does not exceed the value of the subscription.
- Wether tax should be included in the discount.
- The value of the subscription discount can be calculated in one of three ways:
- Full subscription price, by removing both the amountOverride and prorated columns
- A flat amount using the amountOverride column, but removing the prorated columns
- A calculated amount based on a date range using the prorated columns, and removing the amountOverride column
- The following fields must be provided:
-
accountId (UUID of the account)
Read Finding an object's UUID
- discountReason
- subscriptionId
-
accountId (UUID of the account)
- The discount must have a value greater than 0.
-
This CSV will apply the same product discount as if it was applied through the Transactions area by a user. Key details to remember here are:
- Within the list of accounts provided, ensure that they are in “good” standing.
- Note the unique id of the product being discounted for each account
- Ensure that the amount being specified does not exceed the value of the product.
- Wether tax should be included in the discount.
- The value of the product discount can be calculated in one of two ways:
- Full product price, by removing the amountOverride column.
- A specific amount by entering the desired amount in the amountOverride column.
- The following fields must be provided:
-
accountId (UUID of the account)
Read Finding an object's UUID
- discountReason
- productVersionId
-
accountId (UUID of the account)
- The discount must have a value greater than 0.
Related to
- Subscription Discount Template.csv91 Bytes
- Product Discount Template.csv69 Bytes
- Custom Discount Template.csv95 Bytes