# Billing Export The billing export script generates a compressed archive of billing data from your Synqly instance. This archive is sent to Synqly for monthly, quarterly, or yearly billing reconciliation. ## Quick Start Export the previous month's billing data: ```bash ./scripts/billing-export.sh \ --url https://synqly.example.com \ --user admin \ --token-file ~/.synqly-token \ --password-file ~/.synqly-pass ``` Export a specific month: ```bash ./scripts/billing-export.sh \ --url https://synqly.example.com \ --user admin \ --month 2026-01 ``` ## Requirements The script requires `curl`, `jq`, `tar`, and `gzip` to be available on your system. If any of these are missing, the script will report which dependencies need to be installed before proceeding. You will need administrative credentials for your Synqly instance, including the root token and a username and password with administrative permissions. ## Finding Your Credentials These credentials are configured in your helm chart's `values.yaml` file. **Root Token** is configured at `global.root.credentials.rootToken`, or referenced from a Kubernetes Secret via `global.root.secretRef`. Generate one with `openssl rand -base64 32`. **Admin Username and Password** are configured at `global.organizationAdmin.default.credentials`, or referenced from Kubernetes Secrets via `global.organizationAdmin.default.secretRef`. ## Providing Credentials The script supports several methods for providing credentials. ### Root Token The root token can be provided through these methods (in order of precedence): 1. `--token` passes the token directly, but it will appear in shell history. 2. `SYNQLY_TOKEN` environment variable. 3. `--token-file` reads the token from the first line of a file. Recommended for automation. 4. Interactive prompt when running in a terminal with no token provided. ### Password The password follows a similar precedence, with an additional option for piped input: 1. `--password` passes the password directly (appears in shell history). 2. `SYNQLY_PASSWORD` environment variable. 3. `--password-file` reads the password from the first line of a file. 4. Piped input for integration with secret managers: `vault read -field=password secret/synqly | ./billing-export.sh ...` 5. Interactive prompt when running in a terminal with no password provided. ## Specifying the Time Period By default, the script exports billing data for the previous calendar month. You can override this behavior to export a specific month or a range of months. ### Single Month Use `--month` to export a single month. The value can be either a `YYYY-MM` format or a month name: ```bash --month 2026-01 --month january ``` Month names are case-insensitive. When using a month name without a year, the script assumes the most recent occurrence of that month. For example, running the script in January 2026 with `--month march` will export March 2025, since March 2026 has not yet occurred. ### Month Range Use `--from` and `--to` together to export multiple months: ```bash --from 2025-10 --to 2026-01 --from october --to january ``` Both flags must be specified when exporting a range. The range is inclusive of both endpoints. ### Current Month Warning If your time period includes the current month, the script will display a warning that the data may be incomplete since the month is still in progress. ## Output Format The script produces a compressed tar archive named `synqly-billing-export-YYYY-MM-DD-HHMMSS.tar.gz` containing: - A CSV file for each exported month, named like `2026-january.csv` - A `metadata.json` file with export details including the Synqly version, source URL, and list of included months - An `export.log` file with timestamps of each operation performed during the export The CSV files contain one row per integration, with a `Deleted` column indicating whether the integration was deleted during the billing period. Use `--output` to specify the destination directory for the archive. The default is the current working directory. ## Sending to Synqly Email the export archive to `monthlyusagereport@synqly.com`. The subject line should include your company name and the reporting period. The script outputs the date range at the end of execution for easy reference. Example subject line: ``` Acme Corp: 2026-january ``` Or for multi-month reports: ``` Acme Corp: 2025-october to 2026-january ``` No message body is required. You can just attach the archive file. ## Troubleshooting ### `Required dependencies not found` Install the missing tools listed in the error message. On most systems, these are available through the standard package manager. ### `Error: --url is required` or `Error: --user is required` Both the instance URL and admin username must be provided. ### `Error: No token provided` or `Error: No password provided` The script could not obtain credentials through any of the supported methods. Ensure you are providing credentials through one of the methods described above. ### `Error: Token file not found` or `Error: Password file not found` The path specified with `--token-file` or `--password-file` does not exist or is not readable. ### `Authentication failed` The credentials were rejected by the Synqly instance. Verify that the root token is valid and the username and password are correct. ### `Error: Cannot specify both --month and --from/--to` Use either `--month` for a single month or `--from`/`--to` for a range, but not both. ### `Error: --from requires --to` or `Error: --to requires --from` When specifying a range, both endpoints must be provided. ### `Warning: No data for [month], skipping` No billing records were found for the specified month. This may be expected for new deployments or months with no activity. ## Security Notes Credential files should have restrictive permissions (readable only by the user running the script). Avoid using the `--password` or `--token` command-line flags in scripts or automation, as these values may be captured in shell history or process listings. The `--insecure` flag disables SSL certificate verification. Use this only when connecting to instances with self-signed certificates in controlled environments, and never in production. The generated archive contains billing metadata including organization identifiers and usage counts. It does not contain customer data, credentials, or API keys.