There should be no header row in order files. Records containing fields exceeding the prescribed limits, violating the required data type or missing a required field will not be processed. Each record in an order file is comprised of the following fields, in order. If a field is not submitted, the comma should still be included.

FieldTypeDescription
Item_id (UDF1)required
Varchar(100)
Item_id appears in the response or error file so that the client can track completion of orders. This field can repeat. It is recommended that this field correspond to the unique identifier such as an order number. See Order File Format Notes for reloadable orders.
Unique_identifier (UDF2)required (empty)
Varchar(100)
Unique_identifier appears in the response or error file so that the client can track completion of orders. This field should be unique and never repeat. It is recommended that this field correspond to the individual recipient of a virtual or physical card, or in the case of a bulk order, a unique identifier in an order detail table. See Order File Format Notes for reloadable orders.
Order_typerequired
Varchar(50)
Only two values are allowed: individual-shipment or bulk-shipment.
  • individual-shipment: Individual orders are meant to be delivered either by email or by mail to an individual, one card at a time.
  • bulk-shipment: Bulk orders are meant to be delivered either by email or by mail in groups or packages of one or more cards. In the case of a bulk shipment by mail of physical cards, the client receives a package of physical cards.
SKU_idrequired
Alphanumeric
The unique identifier of the product being ordered. Virtual Incentives will provide a list of active SKUs to the client.
Program_idoptional
Integer
Supplied by Virtual Incentives. Identifier that corresponds to the program to be used for funding, branding, and product selection. If this field is omitted, the API attempts to locate the correct Program ID by a reverse SKU Lookup.
Quantityrequired
Integer
1 for individual-shipment of virtual and physical cards. 2 or greater for bulk-shipment of virtual and physical cards (except for subsequent records for bulk-shipment of physical order in which case the value should be 1. See Example 5 in Order File Format Notes for an example.
Item_pricerequired
Float(6,2)
This is the face value of one card. If the quantity field is not 1, this field should still be the individual face value of a single card. Only use this field for open-loop cards, because closed-loop cards have prices that are inherent to a particular SKU. The price should be within the range of acceptable values listed in the SKUs table. Real numbers are accepted.
Emailoptional
Varchar(100)
Email address of the recipient.

Note: Required under the following circumstance: Individual shipment for a SKU for a virtual card if Virtual Incentives performs fulfillment. These email addresses are where the recipient redemption email will be sent.
First_nameoptional
Varchar(50) or Varchar(10)
First name of recipient (see Section 2 of the Order File Format Notes for bulk orders and Section 3 for reloadable orders). In the case of a physical card, the First name is limited to 10 characters. In the case of a virtual, the First name is limited to 50 characters.

Note: Required under the following circumstances: Individual shipment for a SKU for a physically shipped card. Bulk shipment for a SKU for a physically shipped card for the first record of the order and for subsequent records for the order. Individual shipment for a SKU for a virtual card when Virtual Incentives performs fulfillment. For subsequent records for bulk shipments of physical cards, it can be a short message like “Thank” (in conjunction with “You” as the last name).
Last_nameoptional
Varchar(50) or Varchar(10)
Last name of the recipient (see Section 2 of the Order File Format Notes for bulk orders and Section 3 for reloadable orders). In the case of a physical card, the Last name is limited to 10 characters. In the case of a virtual, the Last name is limited to 50 characters.

Note: Required under the following circumstances: Individual shipment for a SKU for a physically shipped card. Bulk shipment for a SKU for a physically shipped card for the first record of the order and for subsequent records for the order. Individual shipment for a SKU for a virtual card when Virtual Incentives performs fulfillment. For subsequent records for bulk shipments of physical cards, it can be a short message like “You” (in conjunction with “Thank” as the first name).
Companyoptional
Varchar(50)
Company or attention line of recipient (see Section 2 of the Order File Format Notes for bulk orders and Section 3 for reloadable orders).
Address_1optional
Varchar(50)
Street address 1 of recipient (see Section 2 of the Order File Format Notes for bulk orders and Section 3 for reloadable orders).

Note: Required under the following circumstances: Individual shipment for a SKU for a physically shipped card and bulk shipment of a physically shipped card.
Address_2optional
Varchar(50)
Street address 2 of recipient (see Section 2 of the Order File Format Notes for bulk orders and Section 3 for reloadable orders).
Cityoptional
Varchar(50)
City to which the physical card will be delivered (see Section 2 of the Order File Format Notes for bulk orders and Section 3 for reloadable orders).

Note: Required under the following circumstances: Individual shipment for a SKU for a physically shipped card and bulk shipment of a physically shipped card.
State/Provinceoptional Varchar(2)2-letter USPO abbreviation for delivery of a card to the United States or 2-digit province code for delivery to Canada. Virtual Incentives only delivers physical cards within the United States and Canada. (See Section 2 of the Order File Format Notes for bulk orders and Section 3 for reloadable orders.)

Note: Required under the following circumstances: Individual shipment for a SKU for a physically shipped card and bulk shipment of a physically shipped card.
Zip/Postal Codeoptional
Varchar(10)
5-digit or 9-digit USPO zip code for delivery of a card to the United States or Canadian postal code for delivery to Canada. Virtual Incentives only delivers physical cards within the United States and Canada. (See Section 2 of the Order File Format Notes for bulk orders and Section 3 for reloadable orders.)

Note: Only Required under the following circumstances: Individual shipment for a SKU for a physically shipped card and bulk shipment of a physically shipped card.
Countryoptional
Varchar(2)
United States or Canada. 2-digit country code (US or CA) for the delivery of a card to the United States or Canada. Virtual Incentives only delivers physical cards within the United States and Canada. (See Section 2 of the Order File Format Notes for bulk orders and Section 3 for reloadable orders.)

Note: Only required under the following circumstances: Individual shipment for a SKU for a physically shipped card and bulk shipment of a physically shipped card.
Messageoptional
Varchar(2000) or Varchar(21)
For physical cards this field is limited to 21 characters and appears at the bottom of the card (commonly known as 4th line embossing), but only for Visa SKUs. For MasterCard, this field is limited to 19 characters. For virtual cards, this field is limited to 170 characters and is included in the redemption email that the recipient receives. Messages containing commas (e.g. Thanks, for all the hard work) should be quoted (e.g. "Thanks, for all the hard work").

Note: Only used for physical Visa SKUs and all virtual SKUs for which Virtual Incentive performs fulfillment.
Subjectoptional
Varchar(100)
Subject of the email the recipient receives for individual shipment of virtual cards that Virtual Incentives delivers.

Note: Only used for virtual SKUs for which Virtual Incentive performs fulfillment (see Section 3 of the Order File Format Notes).
Valedictionoptional
Varchar(50)
Valediction of the email that the recipient receives for individual shipment of virtual cards that Virtual Incentives delivers. Valediction is defined as a word or phrase of farewell used to end a letter or a message. Examples: “Regards,”, ”Sincerely,”, ”Best Wishes for the New Year.”
Titleoptional
Varchar(50)
Title of sender. Title of the email that the recipient receives for individual shipment of virtual cards that Virtual Incentives delivers. Examples: “CEO”,”VP of Sales.”

Note: Only used for virtual SKUs for which Virtual Incentive performs fulfillment (see Section 3 of the Order File Format Notes).
Senderoptional
Varchar(50)
Sender of the email that the recipient receives for individual shipment of virtual cards that Virtual Incentives delivers. Examples: “Bill Smith” or ”The Sales Department.”

Note: Only used for virtual SKUs for which Virtual Incentive performs fulfillment (see Section 3 of the Order File Format Notes).
UDF3optional
Varchar(1000)
User defined field for additional information about the reward. Information passed in this field can be configured to display on the reward email and/or reward landing page.
UDF4optional
Varchar(1000)
User defined field for additional information about the reward. Information passed in this field can be configured to display on the reward email and/or reward landing page.
UDF5optional
Varchar(1000)
User defined field for additional information about the reward. Information passed in this field can be configured to display on the reward email and/or reward landing page.
UDF6optional
Varchar(4000)
User defined field for additional information about the reward. Information passed in this field can be configured to display on the reward email and/or reward landing page.
UDF8optional
Varchar(4000)
User defined field for additional information about the reward. Information passed in this field can be configured to display on the reward email and/or reward landing page.
UDF9optional
Varchar(4000)
User defined field for additional information about the reward. Information passed in this field can be configured to display on the reward email and/or reward landing page.
UDF10optional
Varchar(4000)
User defined field for additional information about the reward. Information passed in this field can be configured to display on the reward email and/or reward landing page.
Phoneoptional
Varchar(20)
Mobile phone number of the recipient. Used for SMS reward delivery. The number must be supplied as digits only.

Note: Required if reward delivery is SMS, or phone country is provided.
Phone Countryoptional
Varchar(2)
Mobile phone number country of origin. This is the 2-character country code (ISO 3166-2).

Note: Required if reward delivery is SMS, or phone number is provided.