Fields for a Subscription Update Request {#batch-ref-fields-subscription-update} ================================================================================ This table describes the required and optional fields for specifying a subscription update request. Field names are listed in the table as they appear in batch file templates. An asterisk after a field name indicates that the field is required for an authorization request. When you create a batch file based on a template, remove any asterisks from field names. | Column | Field Name | Description | Required? | Data Type | Length | |--------|-------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|-----------------------|-----------| | A | merchantReferenceCode\* | Merchant-generated order reference or tracking number. | Required | String | 50 | | B | recurringSubscriptionInfo_subscriptionID\* | Subscription ID that is returned to you when a subscription is created. Include this field in your request when you update a subscription or an individual payment, or when you retrieve subscription information. Also see Processing a Payment or Credit with a Subscription for information about using a subscription ID when initiating a one-time payment or credit. | Required | String | 26 | | C | purchaseTotals_currency\* | Currency used for the order. | Required | String | 5 | | D | recurringSubscriptionInfo_amount\* | Amount of the subscription payments, for example, 19.95. For on-demand subscriptions, this value can be 0. Create: Required for installment and recurring subscription; optional for on-demand subscriptions. | Required | String | 15 | | E | purchaseTotals_grandTotalAmount | Grand total for the order. You must include either this field or `item_#_unitPrice` in your request. If you use `TSYS Acquiring Solutions` as your payment processor, you can set this field to 0 to check whether the card is lost or stolen. | Optional | String | 15 | | F | billTo_firstName | Customer's first name. The value should be the same as the one that appears on the card. | Optional | String | 60 | | G | billTo_lastName | Customer's last name. The value should be the same as the one that appears on the card. | Optional | String | 60 | | H | billTo_customerID | Your identifier for the customer. | Optional | String | 50 | | I | billTo_email\* | Customer's email address, including the full domain name. For example: jdoe@example.com | Required | String | 255 | | J | billTo_street1 | First line of the billing street address. | Optional | String | 60 | | K | billTo_street2 | Second line of the billing street address. Used for additional address information. For example: Attention: Accounts Payable | Optional | String | 60 | | L | billTo_city | City of the billing address. | Optional | String | 50 | | M | billTo_state | State or province of the billing address. Use the two-character codes. | Optional | String | 2 | | N | billTo_country | Country of the billing address. Use the two-character ISO codes. | Optional | String | 2 | | O | billTo_postalCode | Postal code for the billing address. The postal code must consist of 5 to 9 digits. For a 9-digit postal code, use this format: * \[5 digits\]\[dash\]\[4 digits\] If the value of billTo_country is CA, the postal code must follow these rules: * If the number of characters is greater than 3, the first 3 characters must be in this format: \[alpha\]\[numeric\]\[alpha\] * If the number of characters is 7, the last 3 characters must be in this format: \[numeric\]\[alpha\]\[numeric\] | Optional | String | 10 | | P | card_accountNumber | Customer's credit card number. | Optional | String (Numbers Only) | 20 | | Q | billTo_phoneNumber | Customer's phone number. | Optional | String | 15 | | R | billTo_company | Customer's Company Name. | Optional | String | 60 | | S | card_expirationMonth | Two-digit month in which the credit card expires. Format: MM. Possible values: 01 through 12. The leading 0 is required. | Optional | String | 2 | | T | card_expirationYear | Four-digit year in which the credit card expires. Format: YYYY. | Optional | String | 4 | | U | card_cardType | Type of card to authorize. This field is required if the card type is JCB (007), and optional for all other card types. Possible values: * 001: Visa * 002: MasterCard * 003: American Express * 004: Discover * 005: Diners Club * 007: JCB | Optional | String | 3 | | V | subscription_title | Name or title of the subscription. | Optional | String | 60 | | W | recurringSubscriptionInfo_approvalRequired | Whether the subscription uses approval-required payments. For more information, see Automatic or Approval-Required Payments. Possible values: * true: Payments must be approved before processing * false (default): Payments do not need to be approved before processing | Optional | String | 5 | | X | recurringSubscriptionInfo_automaticRenew | Whether to automatically renew the payment schedule for the subscription. Possible values: * true: (default) Subscription schedule renewed automatically * false: Subscription schedule not renewed automatically WARNING: The default is automatic renewal. When creating an installment subscription, make sure to set this to false, or else `Cybersource` will incorrectly continue billing the customer after the last installment payment. | Optional | String | 5 | | Y | recurringSubscriptionInfo_numberOfPaymentsToAdd | Number of payments to add to an existing installment subscription. | Optional | Integer | 3 | | Z | comments | Optional comments you have about the authorization. These comments will not be shown to the customer. | Optional | String | 255 | | AA | merchantDefinedData_field1 | Four fields that you can use to store information. NOTE: If you are creating a profile based on an authorization, the merchant-defined data fields do not get transferred to the new profile. | Optional | String | 64 | | AB | merchantDefinedData_field2 | Four fields that you can use to store information. NOTE: If you are creating a profile based on an authorization, the merchant-defined data fields do not get transferred to the new profile. | Optional | String | 64 | | AC | merchantDefinedData_field3 | Four fields that you can use to store information. NOTE: If you are creating a profile based on an authorization, the merchant-defined data fields do not get transferred to the new profile. | Optional | String | 64 | | AD | merchantDefinedData_field4 | Four fields that you can use to store information. NOTE: If you are creating a profile based on an authorization, the merchant-defined data fields do not get transferred to the new profile. | Optional | String | 64 | | AE | merchantSecureData_field1 | Storage fields for any type of data. No validation is performed on this field except size check. The data is encrypted before it is stored. | Optional | NA | 100 Bytes | | AF | merchantSecureData_field2 | Storage fields for any type of data. No validation is performed on this field except size check. The data is encrypted before it is stored. | Optional | NA | 100 Bytes | | AG | merchantSecureData_field3 | Storage fields for any type of data. No validation is performed on this field except size check. The data is encrypted before it is stored. | Optional | NA | 100 Bytes | | AH | merchantSecureData_field4 | Storage fields for any type of data. No validation is performed on this field except size check. The data is encrypted before it is stored. | Optional | NA | 2K Bytes | | AI | shipTo_firstName | First name of the person receiving the shipment. | Optional | String | 60 | | AJ | shipTo_lastName | Last name of the person receiving the shipment. | Optional | String | 60 | | AK | shipTo_company | Name of Company receiving the shipment. | Optional | String | 60 | | AL | shipTo_street1 | First line of the address to which to ship the product. | Optional | String | 60 | | AM | shipTo_street2 | Second line of the address to which to ship the product. | Optional | String | 60 | | AN | shipTo_city | City to which to ship the product. | Optional | String | 50 | | AO | shipTo_state | State or province to which to ship the product. Use the two-character codes. | Optional | String | 2 | | AP | shipTo_country | Country to which to ship the product. Use the two-character ISO codes. | Optional | String | 2 | | AQ | shipTo_postalCode | Postal code for the shipping address. The postal code must consist of 5 to 9 digits. For a 9-digit postal code, use this format: * \[5 digits\]\[dash\]\[4 digits\] If the value of shipTo_country is CA, the postal code must follow these rules: * If the number of characters is greater than 3, the first 3 characters must be in this format: \[alpha\]\[numeric\]\[alpha\] * If the number of characters is 7, the last 3 characters must be in this format: \[numeric\]\[alpha\]\[numeric\] | Optional | String | 10 | [Fields in a Data Record for a Subscription Update Request]