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.
| Field | Type | Description |
|---|---|---|
| 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_type | required Varchar(50) | Only two values are allowed: individual-shipment or bulk-shipment.
|
| SKU_id | required Alphanumeric | The unique identifier of the product being ordered. Virtual Incentives will provide a list of active SKUs to the client. |
| Program_id | required 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. |
| Quantity | required 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_price | required 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. |
| optional 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_name | optional 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_name | optional 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). |
| Company | optional 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_1 | optional 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_2 | optional 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). |
| City | optional 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/Province | optional 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 Code | optional 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. |
| Country | optional 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. |
| Message | optional 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. |
| Subject | optional 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). |
| Valediction | optional 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.” |
| Title | optional 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). |
| Sender | optional 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). |
| UDF3 | optional 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. |
| UDF4 | optional 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. |
| UDF5 | optional 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. |
| UDF6 | optional 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. |
| UDF7 | optional 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. |
| UDF8 | optional 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. |
| UDF9 | optional 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. |
| UDF10 | optional 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. |
| Phone | optional 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 Country | optional 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. |