replace_supp_plan

Input Arguments
Allowable values for assignment_directive
Allowable values for do_write
Allowable values for auto_offset_months_option
Allowable values for invoice_unbilled_usage
Allowable values for sync_mstr_bill_dates_override
Allowable values for recurring_processing_model_ind
Allowable values for transaction_type
Output Arguments

Replaces a supplemental plan associated with a specified plan number.

Input Arguments

Req

Field Name

Field Type

Max Length

Description

client_no

long

Aria-assigned unique identifier indicating the Aria client providing service to this account.

auth_key

string

Aria-assigned unique key to be passed with each method call for authenticating the validity of the requestor.

acct_no

long

Aria-assigned account identifier. This value is unique across all Aria-managed accounts.

assignment_directive

long

Rule to apply to this assignment/de-assignment request, specifying: the date the assignment takes place (immediately or on the account's anniversary date), and the proration rule to apply (per client's default rules for proration, that is, prorate on plan assignment or force proration on or off for each request). Usage-arrears charges, recurring-in-arrears charges, and any plan cancellation fees (if applicable) will be invoiced during plan cancellation, as these charges are independent of assignment directive. Allowable Values

Values	Description
1	(Default) Perform the requested plan assignment/de-assignment on the account's next scheduled billing anniversary date. The account does not receive service under this plan (for plan assignments) or does not have it removed (for de-assignments) until that date. If a plan is being assigned, initial billing for a full period of the given plan is performed on the account's next scheduled anniversary date. No charge or credit proration effect. No new recurring charges or credits are generated when no proration occurs.
2	Perform the requested plan assignment/de-assignment immediately, honoring the client's pre-configured universal rule for performing or not performing proration as a result of a mid-billing-period plan assignment or de-assignment. No new recurring charges or credits are generated if no proration occurs.
3	Perform the requested plan assignment/de-assignment immediately, ignoring the client's pre-configured universal rule for performing or not performing proration and forcing NO PRORATION. No new recurring charges or credits are generated when no proration occurs.
4	Perform the requested plan assignment/de-assignment immediately, ignoring the client's pre-configured universal rule for performing or not performing proration and forcing PRORATION.
5	Perform the requested plan assignment/de-assignment immediately, ignoring the client's pre-configured universal rule for performing or not performing proration and forcing PRORATION FOR CHARGES ONLY. NOTE: This value is not permitted when calling the cancel_supp_plan API.
6	Perform the requested plan assignment/de-assignment immediately, ignoring the client's pre-configured universal rule for performing or not performing proration and forcing PRORATION FOR CREDITS ONLY. NOTE: This value is not permitted when calling the assign_supp_plan API.
7	Perform the requested plan assignment/de-assignment on the specified effective_date, honoring the client's pre-configured universal rule for performing or not performing proration as a result of a mid-billing-period plan assignment or de-assignment. No new recurring charges or credits are generated when no proration occurs.
8	Perform the requested plan assignment/de-assignment on the specified effective_date, ignoring the client's pre-configured universal rule for performing or not performing proration and forcing NO PRORATION. No new recurring charges or credits are generated when no proration occurs.
9	Perform the requested plan assignment/de-assignment on the specified effective_date, ignoring the client's pre-configured universal rule for performing or not performing proration and forcing PRORATION.
10	Perform the requested plan assignment/de-assignment on the specified effective_date, ignoring the client's pre-configured universal rule for performing or not performing proration and forcing PRORATION FOR CHARGES ONLY. NOTE: This value is not permitted when calling the cancel_supp_plan API.
11	Perform the requested plan assignment/de-assignment on the specified effective_date, ignoring the client's pre-configured universal rule for performing or not performing proration and forcing PRORATION FOR CREDITS ONLY. NOTE: This value is not permitted when calling the assign_supp_plan API.

existing_supp_plan_no

long

Supplemental Plan number to be replaced by this action.

client_existing_supp_plan_id

string

100

Client-defined Supplemental Plan ID to be replaced from this action.

new_supp_plan_no

long

New Supplemental Plan number that replaces the existing supplemental plan.

client_new_supp_plan_id

string

100

Client-defined new Supplemental ID number to use as the replacement supplemental plan.

alt_rate_schedule_no

long

Alternative Rate Schedule Number. Unique identifier for an alternative rate schedule that can be assigned to the account in place of the default rate schedule. Used by CSR's to provide special compensation or discounts as incentives to account holders.

client_alt_rate_schedule_id

string

100

Client-defined alternate rate schedule number to assign (if any). If none is specified, the default rate schedule number is used.

num_plan_units

long

Factor by which recurring fees for this plan are multiplied on future invoices. For example, a supplemental plan titled "Seats of XYZ Application" has a monthly flat cost of $10.00 per seat. To assign 5 seats, resulting in a monthly charge of $50.00 to the account, enter a value of 5 in this field.

coupon_code

string

Code of the coupon to which to apply the discount. If code is not valid for any reason, an appropriate error code is returned and the entire transaction (including the supplemental plan assignment and any possible invoice creation) is rolled back.

comments

string

300

Additional explanatory text relating to this API call.

do_write

string

Indicates whether to perform the requested plan assignment/de-assignment. If 'false' Aria will, if applicable, calculate any potential proration effect that would result and return that value in the output field 'proration_result_amount' without actually performing the requested operation or charging/crediting the account. Used for interfaces that return a 'confirmation page' informing of the effects of the requested operation before actually performing it. Allowable Values

Values	Description
true	true
false	false

client_receipt_id

string

Client-defined unique identifier used to track related system actions

offset_months

long

Number of months to add to the prorated period.

auto_offset_months_option

long

Automatically set offset months Allowable Values

Values	Description
1	Sync to master plan recurring bill thru date
2	Sync to old supplemental plan recurring bill thru date (only applies to replace_supp_plan API)

alt_client_acct_group_id

string

100

One-time collections account group to use for this specific call. Default collections group on the account is not changed.

new_acct_custom_rates

array

Array of new custom rates.

custom_rate_plan_no

long

Unique identifier for the plan to which this custom rate is to be applied for this account.

client_custom_rate_plan_id

string

100

Unique, client-defined identifier for the plan to which this custom rate is to be applied for this account.

custom_rate_service_no

long

Unique identifier for the service no, relative to the value provided in corresponding "custom_rate_plan_no", to which this custom rate is to be applied for this account.

client_custom_rate_service_id

string

100

Unique client-defined identifier for the service ID to determine which custom rate is to be applied for this account.

custom_rate_seq_no

long

Rate tier number to which this custom rate is to be applied.

custom_rate_from_unit

long

Starting unit of a range of units to which this custom rate is to be applied.

custom_rate_to_unit

long

Ending unit of a range of units to which this custom rate is to be applied.

custom_rate_per_unit

double

Custom rate per unit.

effective_date

string

If the assignment directive is for a future date assignment, this is the date, in yyyy-mm-dd format, on which the plan change will be executed. If this field is NULL, then the plan change will not happen until it is manually executed or until the effective_date is updated.

offset_interval

long

1000

If assigning a change on an anniversary day, the number of billing periods by which to delay that change

invoice_unbilled_usage

string

Specifies whether unbilled usage is invoiced. Allowable Values

Values	Description
false	Do not invoice the unbilled usage during mid-term plan termination.
true	Invoice the unbilled usage during mid-term plan termination.

sync_mstr_bill_dates_override

long

Overrides the client-level setting that determines whether master plan billing dates are reset when assigning a new supplemental plan. If this value is left empty, the client-level setting takes effect. Allowable Values

Values	Description
1	Do not reset master plan billing dates.
2	Reset master plan billing dates if master plan is "free", the account has no "billable" supplemental plans, and the newly-assigned supplemental plan is "billable.
3	Reset master plan billing dates if master plan is "free" and the account has no active supplemental plans.
	Client-level setting takes effect.

surcharge_no

array

surcharge_no

long

Surcharge number to be attached to the plan

rate_schedule_no

long

Schedule number for this surcharge

alt_caller_id

string

Person or process that submitted the API call. This can be someone's user ID, or the name of an application.

optional_transaction_qualifiers

array

Array of additional values you can associate with this API call.

qualifier_name

string

100

Name of the field you want to associate with this API call.

qualifier_value

string

100

Corresponding value of the field you want to associate with this API call.

application_id

string

300

The application identifier in which the API is being used in. (Example: “Sales Force”)

application_date

string

300

The application date/timestamp, ie. 01/01/2014 10:00:00 to track when the application called the API.

recurring_processing_model_ind

long

Defines a recurring payment type for Credit Card and Tokenized Credit Cards. Allowable Values

Values	Description
0	Cardholder-Initiated Transaction – Credentials on File: a credit card transaction initiated by the cardholder for a new order or a plan upgrade that uses a credit card that is currently stored in Aria. (Default)
1	Cardholder-Initiated Transaction: a credit card transaction initiated by the cardholder for a new account or creating an order that uses an alternate credit card that is not currently stored in Aria.
2	Merchant-Initiated Transaction – Standing Instruction – Recurring: a credit card transaction initiated by Aria’s clients for a recurring charge that uses a credit card that is currently stored in Aria.
3	Merchant-Initiated Transaction – Unscheduled Credentials on File: a credit card transaction initiated by Aria’s clients for a non-recurring charge (one-time order or plan upgrade) that uses a credit card that is currently stored in Aria.

Start of proc_field_override array

proc_field_override

array

Your chosen data to send to your payment gateway passed as an array of proc_field_name/proc_field_value key-value pairs.

The allowable field(s) and values for the key-value pairs are listed below.

Field Name

Field Type

Max Length

Description

transaction_type

string

If you use Chase Paymentech or Vantiv, this field allows you to tell that payment gateway which transaction type is involved (examples: single or recurring transaction) when you process a customer's payment information.

This field applies to credit cards and tokenized credit cards. If you don't pass a value into this field, it will default to -1 (use client configuration settings).

Notes:

The value that you pass into this field will override the Recurring Options that you set in the Aria application under:
- Configuration > Payments > Payment Gateways > Chase Paymentech > Gateway Options; and
- Configuration > Payments > Collection Groups > Chase Paymentech > Collection Group Options.
Currently, only Chase Paymentech supports this field. Other payment gateways might not honor all of the allowable values for this field. You will need to check your payment gateway documentation for confirmation.

Aria will use this order of precedence to determine the transaction type:

value passed into this field
collection group configuration
payment gateway configuration
transaction type that you specified in the <recurring_processing_model_ind> field

Allowable Values

Values	Description
-1	Use client configuration settings for "Send Transaction Type as Recurring for Initial Request Where Possible" or "Send Transaction Type as Recurring for Subsequent Request" as applicable. (default)
1	Single transaction mail/telephone order (MOTO) - Designates a transaction where the accountholder is not present at a merchant location and completes the sale over the phone or through the mail. The transaction is not for recurring services or products and does not include sales that are processed via an installment plan.
2	Recurring Transaction - Designates a transaction that represents an arrangement between an accountholder and the merchant where transactions are going to occur on a periodic basis.
3	Installment Transaction - Designates a group of transactions that originated from a single purchase where the merchant agrees to bill the accountholder in installments.
4	Deferred Transaction - Designates a transaction that represents an order with a payment delayed for a specified amount of time.
5	Secure Electronic Commerce Transaction - Designates a transaction completed via the Internet at a 3-D Secure capable merchant and in which the accountholder was fully authenticated. (examples: 3-D Secure includes Verified by Visa, Mastercard Identity Check, American Express SafeKey and Discover ProtectBuy.)
6	Non-Authenticated Electronic Commerce Transaction - Designates a transaction completed via the Internet at a 3-D Secure capable merchant that attempted to authenticate the accountholder using 3-D Secure (examples: 3-D Secure includes Verified by Visa and Mastercard Identity Check.) Verified by Visa, Mastercard Identity Check, American Express SafeKey and Discover ProtectBuy transactions in the event of: * A non-participating issuer * A non-participating accountholder of a participating issuer * A participating issuer, but the authentication server is not available
7	Channel Encrypted Transaction - Designates a transaction between an accountholder and a merchant completed via the Internet where the transaction includes the use of transaction encryption such as SSL (Secure Sockets Layer), but authentication was not performed. The accountholder payment data was protected with a form of Internet security, such as SSL, but authentication was not performed. For Discover, indicates an e-commerce Card Transaction with data protection in which ProtectBuy for Cardholder authentication was not used.
8	Non-Secure Electronic Commerce Transaction - Designates a transaction between an accountholder and a merchant completed via the Internet where: * The transaction does not include the use of any transaction encryption such as SSL * Authentication is not performed * An accountholder certificate is not managed.
I	IVR Transaction (PINless Debit only) - Designates a transaction where the accountholder completes the sale via an interactive voice response (IVR) system.
R	Retail Transaction - Designates a transaction where the accountholder was present at a merchant location.
telephone	(Vantiv) The transaction is for a single telephone order.
mailorder	(Vantiv) The transaction is for a single mail-order transaction.

Field Name	Field Type	Description
error_code	long	Aria-assigned error identifier. 0 indicates no error.
error_msg	string	Description of any error that occurred. "OK" if there was no error.
proration_result_amount	double	Currency amount of any proration action resulting from the requested plan change. For plan assignments with an assignment directive of '1' (perform on anniversary date), or '2' (honor client default proration action) when the default is no proration, or '3' (force no proration), this field always returns '0'. If proration is performed, the value r eturned is either a positive currency value (for a charge) or a negative currency value (for a credit). If do_write is false, then any positive or negative value returned in this field is notational only, showing the proration effect if the requested plan assignment/de-assignment was actually performed.
invoice_no	long	Unique identifier of a given invoice.
supp_plan_line_items	hash
line_no	long	Specifies the sequential line number of this line item. Initial record value is always 1.
line_type	long	Specifies the type of charge or credit associated with this line item.
service_no	long	Specifies the Aria-assigned unique service identifier.
service_name	string	Specifies the name corresponding to this line item's service code.
line_units	double	Specifies the number of units of this service code billed on this line item. On a prorated invoice, line_units = line_base_units X proration_factor.
rate_per_unit	double	Specifies the rate per unit billed.
line_amount	double	Specifies the total charge associated with this line item.
line_base_units	double	Specifies the full, non-prorated number of units of the service code.
proration_factor	double	Specifies the percentage of the line_base_units billed.
description	string	Specifies the description of this line item.
date_range_start	string	Specifies the start date of the date range covered by this line item in yyyy-mm-dd format.
date_range_end	string	Specifies the end date of the date range covered by this line item in yyyy-mm-dd format.
credit_coupon_code	string	Specifies the coupon code applied to the invoice.
plan_no	long	Specifies the Aria-assigned service plan number under which this line item was billed.
plan_name	string	Specifies the name of the service plan associated with the plan_no.
client_service_id	string	A multidimensional array of client defiend Service id for this plan.
client_plan_id	string	Client defined Plan ID for which to query available child plans
total_charges_before_tax	double	Total amount to be charged to the account before taxes have been calculated.
total_tax_charges	double	Total taxes as calculated for the amount of the transaction.
total_charges_after_tax	double	Total amount to be charged to the account after taxes have been calculated.
total_credit	double	The total amount of the credit to be applied to the account
total_tax_credit	double	The tax amount of the credit to be applies
total_credit_before_tax	double	The credit to be applied before tax is taken into account
total	double	The grand total of this invoice
proration_credit_result_amount	double	The pro-rated credit amount for this invoice
proration_credit_amount	double	The pro-rated credit amount for this invoice
proration_tax_amount	double	The pro-rated tax credit amount for this invoice
expectd_activation_fee	double	The predicted activation fee based on activation fee charges on supplemental plans on this invoice
expectd_mthly_recurring_cost	double	The predicted monthly recurring cost of the items and plans on this invoice
expectd_annu_recurring_cost	double	The predicted annual recurring cost of the items and plans on this invoice
third_party_errors	hash	Errors from third-party systems like taxation engines are returned here. Aria-generated error codes are returned in the error_code and error_msg fields at the root level of the API return.
error_class	string	Type of error code being represented, such as taxation
error_code	string	Aria-assigned error identifier. 0 indicates no error.
error_msg	string	Description of any error that occurred. "OK" if there was no error.
proc_initial_auth_txn_id	string	Transaction ID from payment processor. If received as part of an auth request, it must be retained for future settlement and match the value from the auth response. It should also be used for future recurring transaction auths/settlement.

replace_supp_plan

Table of contents

Input Arguments

Output Arguments

Tags

Classifications

replace_supp_plan

Table of contents

Input Arguments

Output Arguments

Related articles

Tags

Classifications