Building the CSVs for Mass Discounts

Trevor Buckerfield
Trevor Buckerfield
  • Updated

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

  1. Mass Discounts - Overview
  2. Building the CSVs for Mass Discounts
  3. Creating Mass Discounts
  4. Managing Mass Discounts

 

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:

  1. Downloading the CSV template (provided below) and manually filling it out with the required information.
  2. Using Snowflake to help generate the data for you.
  3. 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:

  1. Is in a CSV format

  2. Uses commas to separate the data

  3. Contains the required columns.

  4. 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.

  5. Double quotes (””) should not be added to the data.

  6. Amounts should always be entered as cents.
    For example $10.99, would be entered as 1099 in the CSV.
  7. 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:

    DOWNLOAD LINK

    1. Within the list of accounts provided, ensure that they are in “good” standing.
    2. The “ADJUSTMENT” reason type cannot be used with custom discounts.
    3. The following fields must be provided:
      1. accountId (UUID of the account)
        Read Finding an object's UUID
      2. discountReason
      3. amountOverride
      4. description (Invoice Description)
      5. quantity
    4. 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.
    5. A quantity of 1 or more must be specified.
    6. 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:

    DOWNLOAD LINK

    1. Within the list of accounts provided, ensure that they are in “good” standing.
    2. Note the unique id of the subscription being discounted for each account.
    3. Requires manual additional verification to ensure that each account being included actually have the active subscription specified in the CSV.
    4. Requires that the amount being specified does not exceed the value of the subscription.
    5. Wether tax should be included in the discount.
    6. The value of the subscription discount can be calculated in one of three ways:
      1. Full subscription price, by removing both the amountOverride and prorated columns
      2. A flat amount using the amountOverride column, but removing the prorated columns
      3. A calculated amount based on a date range using the prorated columns, and removing the amountOverride column
    7. The following fields must be provided:
      1. accountId (UUID of the account)
        Read Finding an object's UUID
      2. discountReason
      3. subscriptionId
    8. 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:

    DOWNLOAD LINK

    1. Within the list of accounts provided, ensure that they are in “good” standing.
    2. Note the unique id of the product being discounted for each account
    3. Ensure that the amount being specified does not exceed the value of the product.
    4. Wether tax should be included in the discount.
    5. The value of the product discount can be calculated in one of two ways:
      1. Full product price, by removing the amountOverride column.
      2. A specific amount by entering the desired amount in the amountOverride column.
    6. The following fields must be provided:
      1. accountId (UUID of the account)
        Read Finding an object's UUID
      2. discountReason
      3. productVersionId
    7. The discount must have a value greater than 0.

Related to

Was this article helpful?

Have more questions? Submit a request