Management Science Associates, Inc.

RSS Shared File Format

March 2023
The following layout represents MSA’s Shared File Format for Retailer Scan Solution (RSS) data. All fields must be included on the file transmitted by the Data
Provider to MSA. However, fields indicating ‘Program Specific’ in the Required column below may be blank, depending on the program in which the Data Provider
is participating. Conditional fields indicate those that are required based on population of related fields, as indicated in the Master Description column. Please
contact your program representative if additional information is required.

MSA RSS Shared File Format

Technical
Position Required Master Description Conditional
Specifications
Outlet Name
1 All N Alphanumeric
Outlet Name associated with the physical location.
Outlet Number
Unique identifier for each outlet submitted.
2 All N Alphanumeric
Normally identifies various outlets in a multi-outlet establishment.
A manufacturer account number is not acceptable in this field.
Outlet Address 1
3 All Outlet physical location address. N Alphanumeric
Must contain street number and name. Cannot be a PO Box.
Outlet Address 2
Additional outlet physical location address attributes when needed otherwise this field can be blank
4 All N Alphanumeric
Please provide if it adds clarity to the physical location of the outlet. For example: Suite #123
PO Box is acceptable in this field.
Outlet City
5 All N Alphanumeric
Outlet’s physical city location.
Outlet State
6 All Two-digit state code for each outlet for which data is being sent. N Alphanumeric
This should be formatted as upper-case letters only.

Outlet Zip Code

7 All Outlet's physical zip code location 5-digit Zip or 5-digit Zip + 4. N Alphanumeric
Does not need to have a space or a dash if using the full zip code.

Transaction Date/Time
This is a timestamp for each Market Basket Transaction ID recorded. The field will indicate the date and
8 All time the transaction takes place. N Alphanumeric
• Format is yyyy-mm-dd-hh:mm:ss where the time is in military time format. I.e. 23:45:56
• This must be the same across all items (scan transaction IDs) within a market basket.

1
 MSA RSS Shared File Format
Technical
Position Required Master Description Conditional
Specifications
Market Basket Transaction ID
Each Market Basket will have a unique identifier.
9 All N Alphanumeric
• If more than one tobacco item is purchased by a consumer, this number will be repeated for
each tobacco item in that market basket.
Scan Transaction ID
10 All Unique identifier for each scanned product. The scan transaction ID is what makes each item within a N Alphanumeric
market basket unique.
Register ID
11 All ID of the terminal used for the transaction. Unique identifier for each terminal in the individual outlets. N Alphanumeric
• For example, if an outlet has two terminals, there must be two unique Register IDs.
Quantity
This field will indicate the number of units for a given product (UPC) that were scanned.
Numeric
12 All • The value can be negative indicating a returned item. N
Whole Number
• If the transaction UPC is a bundled item, the quantity should refer to the number of bundles
sold, not the number of items included in the bundle.
Price
This field will indicate the UPC final selling price per selling unit less sales tax and any discounts that may
have been applied.
Numeric
13 All • If there are promotions applied to the transaction, price should reflect all applied discounts. N
Decimal Number
• If 2 or more of the same products are purchased, indicate the price of one individual sale unit.
• Price should not be reported as a negative number.

UPC Code
The universal product code on the package being sold/scanned. UPC must be reported as a 6, 8, 10, 11,
12 or 14-digit code.
14 All • A SKU is not acceptable as a UPC in this field. N Numeric
• UPC should be reported as scanned.
• Please include the necessary check digit if/when the UPC format requires it.

UPC Description
The description of the UPC code being sold/scanned. This field is important in the processing of
product information.
15 All N Alphanumeric
• It must contain an accurate description of the product associated with the UPC code.
• Key product elements include, but are not limited to brand name, flavor, and size.

2
 MSA RSS Shared File Format
Technical
Position Required Master Description Conditional
Specifications
Unit of Measure
16 All The description of the type of selling unit sold Example: Pack, Carton, Can, Roll. N Alphanumeric
*See appendix for a full list of suggested values.
Promotion Flag
This flag will be set to “Y” when any product transaction includes a promotion. If there is no promotion
associated with the scan transaction ID the promotion flag should be set to “N”.
Promotions include: Must be Y or N:
• Outlet and/or Manufacturer funded Multi-packs (fields 21, 22).
Y – If a promotion is
• Account promotions (single pack or can discounts/ extended markdowns/etc, Fields 23 & 29). reported
17 All N
• Manufacturer product bundles, and Money off (sometimes referred to as VAP) promotions.
• Coupons or Loyalty Offers (fields 24, 25, 34). N- If no promotion is
reported
Promotion do not include:
• Manufacturer buy-downs
• Pre-priced items
Outlet Multi-Pack Flag Must be Y or N:
This flag will be set to “Y” when any product transaction includes an outlet sponsored multi-pack
Y – If an outlet multi-
purchase. pack promo is
• An Outlet Multi-Pack purchase is defined as an Outlet funded promotion where the customer reported
18 All N
must purchase 2 or more units to receive a discount.
N- If no outlet multi-
If no outlet multi-pack promotion is associated with the scan transaction ID, the flag should be set to pack promo is
“N”. reported
Outlet Multi-Pack Quantity
The minimum number of Consumer Units required to be purchased to qualify the transaction as an
Outlet funded Multi-Pack transaction.

NOTE: When reporting sales of this type of item, you must report the minimum number of items that
Program- Numeric
19 must be purchased to qualify the transaction to be discounted. Therefore, the expected value would be Y
Specific Whole Number
greater than or equal to “2”.

This field does NOT represent the total number of units purchased by the customer.

Required when Outlet Multi-Pack Flag is set to Y

3
 MSA RSS Shared File Format
Technical
Position Required Master Description Conditional
Specifications
Outlet Multi-Pack Discount Amount
The per sales unit discount provided for the units sold.
Program- Numeric
20 • For example, the Outlet Multi-Pack Discount Amount would be $0.25 on a Buy 2, save $0.50 Y
Decimal Number
Specific
promotion.
Required when Outlet Multi-pack Flag is set to Y
Account Promotion Name
The description of the account sponsored, single unit/UPC discount program being funded.
Program-
21 • This field does not apply to Outlet Multi-pack promotions. Y Alphanumeric
Specific
Required when Account Discount Amount is supplied
Account Discount Amount
The per sales unit dollar discount for an account funded promotion, that is single-unit in nature (not a
Program- Numeric
22 multipack), excluding sales taxes. Y
Specific Decimal Number

Required when Account Promotion Name is supplied

Manufacturer Discount Amount
This represents the single pack, manufacturer-funded discount amount. Must be reported at the per
Program- sales unit amount Numeric
23 N
Specific • This includes Money off (VAP) or Bundle pack savings amount. Decimal Number
• This will coincide with the Manufacturer Promotion Description.
• This does not include the buy-down amount.
Coupon PID
Program-
24 The number of the scanned coupon or digital coupon (UPC-A or GS-1 code) N Alphanumeric
Specific
If more than one coupon is used, all PIDs must be listed
Coupon Amount
This field represents:
• Amount of money discounted from the sales price of the item once the scanned or digital
Program- coupon(s) is applied to the scan transaction. Numeric
25 Y
Specific o For retailer or Manufacturer loyalty offers, report the per sales unit discount amount Decimal Number
associated with the Loyalty ID.

Required when Coupon PID and/or Coupon Description is populated

4
 MSA RSS Shared File Format
Technical
Position Required Master Description Conditional
Specifications
Manufacturer Multi-pack Flag Must be Y or N:
This flag will be set to “Y” when any product transaction includes a Manufacturer sponsored multi-pack Y – If a manufacturer
purchase. multi-pack
• A Manufacturer Multi-Pack purchase is defined as a manufacturer funded promotion where the promotion is
26 All customer must purchase 2 or more units to receive a discount. N reported
• If there is no manufacturer multi-pack promotion associated with the scan transaction ID, the
flag should be set to “N”. N- If no
manufacturer multi-
pack promotion is
reported
Manufacturer Multi-pack Quantity
The minimum number of Consumer Units that are required to be purchased for the transaction to
qualify for the Manufacturer Multi-Pack transaction.

NOTE: When reporting sales of this type of item, you must report the minimum number of items that
Program- Numeric
27 must be purchased to qualify the transaction to be discounted. Therefore, the expected value would be Y
Specific Whole Number
greater than or equal to “2”.

This field does NOT represent the total number of units purchased by the customer.

Required when Manufacturer Multi-Pack Flag is set to Y

Manufacturer Multi-pack Discount Amount
The per sales unit discount provided for the units sold.
Program- Numeric
28 • For example, the Manufacturer Multi-Pack Discount Amount would be $0.25 on a Buy 2, save Y
Decimal Number
Specific
$.50 promotion.
Required when Manufacturer Multi-Pack Flag is set to Y
Manufacturer Promotion Description
The name of the discount program given on a single UPC, funded by the Manufacturer.
Program- • For example, a bundle UPC promotion would still be reported here, since it is a single UPC.
29 Y Alphanumeric
Specific • This would describe the discount given in the Manufacturer Discount Amount field.

Required when Manufacturer Discount Amount is populated

Manufacturer Buy-down Description
Program-
30 Description of the specific buy-down being applied to the transaction. Y Alphanumeric
Specific
Required when Manufacturer Buy-down Amount is populated

5
 MSA RSS Shared File Format
Technical
Position Required Master Description Conditional
Specifications
Manufacturer Buy-down Amount
Program- Numeric
31 Dollar Amount applied to the transaction per one sale unit. Y
Specific Decimal Number
Required when Manufacturer Buy-Down Description is populated
Manufacturer Multi-Pack Description
Program- Alphanumeric
32 The name or required verbiage of the multi-pack program funded by the Manufacturer. Y
Specific
Required when Manufacturer Multi-Pack Flag is set to Y
Account Loyalty ID Number
The unique account loyalty or reward card number associated with EACH consumer.
Program- • This DOES NOT include any consumer’s personal information such as name, phone number, or
33 N Alphanumeric
Specific address.
• This field should be included on all transactions within a market basket when a loyalty ID is
used on a purchase.
Coupon Description
This field can be used for:
Program-
34 • The description of the coupon offer. Y Alphanumeric
Specific
• Loyalty offer descriptions not associated with coupons; manufacturer and outlet-sponsored.
Required when Coupon Amount is populated

6
 Appendix
Available File Formats:

• Comma Delimited File with Header

• Comma Delimited File without Header
• Pipe Delimited File with Header
• Pipe Delimited File without Header
• JSON
The below table is a guideline for how to report units of measure by category:

TOBACCO CATEGORY UNITS OF MEASURE

Cigarettes Pack, Carton, Case

Cigars/Little cigars Each (for single sticks of cigars), Pack, Box, Case

Nicotine Modern Oral (NMO) Pack, Carton

MEASURE Nicotine Replacement Therapy (NRT) Pack, Carton

Moist tobacco or Snus Can, Tin, Tub, Roll, Sleeve, Box, Case.

Pipe Tobacco Bag, Tub, Canister, Case

E-cigs and Vapor Each (for single sticks E-cigs), Pack, Kit, Bottle,
Cartridge, Box, Case

Tubes Tubes, Pack, Carton, Box, Case

Roll Your Own (RYO) Pack, Bag, Canister, Box, Case

Loose tobacco Pouch, Pack, Canister, Bag, Box, Case

Papers/Wraps Booklet, Pack, Box, Case

Premium Cigars Each (for single sticks of cigars), Bundle, Pack,

Box, Case

7
Additional Unit of Measure notes:
• You may use 2PK, 3PK, etc. but only to describe bundles (2 or more individual items packed/cellophane together)
• 5PK can be used to describe sales of half cartons
• EACH should primarily be used for premium cigars or E-cigs as they are sold by the individual item.
• Sizes (oz., ml, etc.) and/or Counts (1CT, 2CT, 10CT, etc.) are not valid UOM
• Please try to keep consistency when reporting UOM for items within the same tobacco category

Additional Technical Specifications:

Each Outlet must have uniquely identifiable transaction data defined through combining these fields:

1. Transaction Date & Time 3. Scan Transactions ID 5. Outlet #

2. Market Basket Transaction ID 4. Register ID

When an account is not reporting data within any of the fields, the field must be blank with no spaces or programming in between the delimiter.

“.zip” files are not an acceptable format that can be sent to MSA our system will not be able to process the files.