Arc XP CLI: Subscriptions

The Arc XP CLI provides commands for migrating paid subscriptions into Arc XP Subscriptions. This guide covers the available commands, input file format, and recommended migration approach.

Before You Begin

Create a new Access Token specifically for this migration. Once the migration is complete, delete the token.

CLI Modes

If you haven’t set up the CLI yet, see the Arc XP CLI documentation to get started. The CLI supports two modes:

Attended — an interactive menu guides you through each step.
Unattended — you run a single command and wait for it to complete.

A new Subscriptions product menu has been added for attended mode, with submenus that correspond to the commands described below.

Unattended Commands

Simulate

The simulate command validates each row in your input file using nearly all of the same checks the API performs. Run this command before executing a migration.

arcxp subscriptions upload simulate --file <filename>.csv

Results are written to the same directory as the input file with the name <filename>-simulate.csv. Any rows that fail validation will have a value in the error column.

Correct the flagged rows in your input file and re-run the simulate command as many times as needed until all rows pass.

There are two things the simulate command cannot validate:

token — the payment token stored at the gateway
gatewayId — the payment gateway ID configured in the admin portal

These should be validated manually before running the execute step.

Execute

The execute command calls the API and creates subscription records row by row.

arcxp subscriptions upload execute --file <filename>.csv

The output file is written to the same directory as the input file with the name <filename>-execute.csv.

Any failures are flagged with a false value in the results column and an error message in the message column. The token column is intentionally masked with asterisks to avoid propagating sensitive data outside of the input file.

Terminate

The Terminate command can be used to remove any existing subscriptions.

arcxp subscriptions terminate --file <filename>.csv

See Terminate Input File Format for the required file structure.

Input File Format

The migration input file must be a .csv file with the following header columns:

SITE,GATEWAY_ID,LEGACY_ID,SKU,PRICE_CODE,CLIENT_ID,NEXT_RENEWAL_DATE,COUNTRY,LINE1,LINE2,LOCALITY,REGION,POSTAL,TOKEN,FIRST_SIX,LAST_FOUR,EXPIRATION,CARDHOLDER_NAME,TAX_EXEMPT,TAX_LOCATION_ID

staging,1,sub-0001a,deluxepremium,YZWICX,817e2957-8047-495b-a077-ea1f5a058448,2026-07-15T00:00:00Z,US,742 Evergreen Terrace,,Springfield,IL,62704,tok_abc123def456,411111,1234,0827,Homer Simpson,false,tax-loc-001b

Spreadsheet number coercion

If your LEGACY_ID or SKU/PRICE_CODE columns contain large numbers:

Excel — edit the file as .xlsx and export to .csv when done.
LibreOffice — mark the affected columns as text in the import dialog.
Apple Numbers — install LibreOffice or Excel. Numbers does not currently offer a way to avoid automatic coercion to scientific notation when the file is opened.

Required Fields

Parameter	Description
SITE	Site as configured in Site Service
GATEWAY_ID	ID of payment gateway configured in CSR Admin
LEGACY_ID	ID of subscription in legacy system
SKU	The subscription’s product from Retail section of the CSR Admin
PRICE_CODE	The subscription’s price code from Retail section of the CSR Admin
CLIENT_ID	The Arc Identity ID of the subscription owner
NEXT_RENEWAL_DATE	The date the renewal engine will attempt the first payment
COUNTRY	Country used for tax calculations
TOKEN	A token representing the credit card stored at the payment gateway
TAX_EXEMPT	`true` or `false` — set to `true` if the subscription is exempt from taxes

Optional Fields

Parameter	Description
LINE1	Line 1 of billing address
LINE2	Line 2 of billing address
LOCALITY	City of the billing address
REGION	State of the billing address
POSTAL	Zip or postal code
FIRST_SIX	First six digits of credit card
LAST_FOUR	Last four digits of credit card
EXPIRATION	Expiration month + year of credit card — four digits required
CARDHOLDER_NAME	Name of the cardholder
TAX_LOCATION_ID	Only used by the Taxamo tax gateway

Terminate Input File Format

The terminate input file uses a different format to prevent accidentally running a terminate against a migration input file. Only two columns are required:

LEGACY_ID,SITE
sub-0001a,staging

Failure Recovery

The CLI can detect failures during the execute and terminate commands and can usually restart from where the failure occurred. To resume:

Restart the CLI.
Run the same command on the same file.
When prompted with “Resume from where it left off?”, select yes.

Recommended Migration Approach

Transform your data — reshape your subscription records to match the input file format described above.
Split into smaller files — break the transformed file into multiple files of approximately 25,000 records each.
Run simulation — if you can write scripts, create a simple script that iterates through each input file and runs:
Terminal window
```
arcxp subscriptions upload simulate --file <filename>.csv
```

Correct errors — find rows with errors in the output files, correct them in the input files, and re-run simulation. Repeat until all files pass with no errors.
Validate with the business — check each output file for billing amounts and validate them against what the business expects. Correct input files again as needed.
Execute the migration — run the execute command on each input file:
Terminal window
```
arcxp subscriptions upload execute --file <filename>.csv
```
Handle execution errors — collate any errors from the output files into a single new input file, correct the errors, and re-run the execute command against that file.