This document outlines CrowdTwist’s batch file specifications to process purchase data for points. The file itself must be a JSON formatted batch file containing the different types of transaction data that will be detailed below.

File Naming Convention
Files must meet the following convention to be processed:
YYYYMMDD_<counter>_<client_id>_pos_<client_specific>.json

Where:

• YYYYMMDD represents the timestamp of the file with year, month, and day values according to the UTC time zone on the day the file is uploaded. If files are received with different dates, we cannot ensure they will be processed in date order. If files must be processed in order, the files must use the same date and the counter (see below).
• <counter> represents an incrementing value of 4 digits beginning with 0001 (i.e. 0001, 0002, 0152…). This counter value will be used to indicate the order of files to be processed for a given day. Multiple files with the same date and counters greater than 1 will be processed in counter order. If a file with counter 0002 is received, the file will not be processed until 0001 is uploaded.
• <client_id> represents a CrowdTwist generated client_id that will be provided at time of integration
• <client_specfic> represents any client-defined value

Example File Name:
20170623_0026_12_pos_ClientCommerce.json

File Specifications:

• Files must be sent via SFTP as a. json file type
• Transactions must be sent, and will be processed, in ascending order of date purchased
  • (i.e. return data should not appear above purchase data for a given transaction)
• File size must not exceed 50 MB
• Files must follow the naming convention outlined above
• Files must be properly formatted JSON
• All entries must be UTF-8

Error File Handling
The system will validate on the day and counter values for a given filename. If a file is received that contains an improper filename (incorrect day or <counter> value), processing will stop until a correctly formatted file is uploaded. For example, if a file is received with a <counter> value of 0003 before 0002 and 0001 are received, the file will not be processed until the previous files are received.

Transaction Error Handling:
A transaction may fail for any of the below example reasons:

• A transaction is improperly formatted
• A required field is missing
• A field contains an invalid data type
• A unique field has been duplicated (i.e. receipt_id)
• A corresponding receipt_id does not exist for a given fulfillment or return transaction

If transactions are sent in error, the system will log the errors in a downloadable file containing the failed JSON requests and continue processing the remaining transactions.

This error log will contain details on all failed transactions, including transactions that may have been sent out of order and need to be reprocessed (i.e. a return without a valid purchase) as well as errors that need to be reformatted (i.e. an invalid data type was sent). To reprocess any failed transaction, the client may resend the failed transactions with the same filename or in a subsequent batch file that conforms to the naming convention.

Input Parameters

PosData Object:
This object represents the entirety of the purchase, return, and fulfillment transactions contained in the file. It is structured as an array of POS_Objects.
NOTE: There should only be a single instance of PosData per batch file and the object must be the first JSON element in the batch file.

    {
      "type": "purchase",
      "data": {
        "receipt_id": "receipt1-0510",
        "order_id": "order-0510",
        "user_id": 46038266,
        "total": 119.64,
        "subtotal": 110.78,
        "date_purchased": "2017-05-08T10:25:43.511+00:00",
        "channel_id": 1,
        "currency": "USD",
        "custom_data": {
          "store_loc": "store1",
          "register_id": "register1",
          "cashier_id": "cashier1",
          "employee_id": "employee_123"
        },
        "items": [
          {
            "sku": "sku_1",
            "price": 21.22,
            "quantity": 2,
            "transaction_id": 2,
            "custom_data": {
              "color": "blue",
              "size": "Medium"
            }
          },
          {
            "sku": "sku_2",
            "price": 89.56,
            "quantity": 1,
            "transaction_id": 1,
            "custom_data": {
              "color": "blue",
              "size": "Medium"
            }
          }
        ],
        "tenders": [
          {
            "type": 1,
            "amount": 20
          },
          {
            "type": 2,
            "amount": 99.64
          }
        ],
        "coupons": [
          "86300822933634341429",
          "coupon123789"
        ]
      }
    },

    {
      "type": "purchase",
      "data": {
        "receipt_id": "receipt1-0510",
        "order_id": "order-0510",
        "user_id": 46038266,
        "total": 119.64,
        "subtotal": 110.78,
        "date_purchased": "2017-05-08T10:25:43.511+00:00",
        "channel_id": 1,
        "currency": "USD",
        "custom_data": {
          "store_loc": "store1",
          "register_id": "register1",
          "cashier_id": "cashier1",
          "employee_id": "employee_123"
        },
        "items": [
          {
            "sku": "sku_1",
            "price": 21.22,
            "quantity": 2,
            "transaction_id": 2,
            "custom_data": {
              "color": "blue",
              "size": "Medium"
            }
          },
          {
            "sku": "sku_2",
            "price": 89.56,
            "quantity": 1,
            "transaction_id": 1,
            "custom_data": {
              "color": "blue",
              "size": "Medium"
            }
          }
        ],
        "tenders": [
          {
            "type": 1,
            "amount": 20
          },
          {
            "type": 2,
            "amount": 99.64
          }
        ],
        "coupons": [
          "86300822933634341429",
          "coupon123789"
        ]
      }
    },

Purchase Object Definition:
This object represents an entire purchase for one receipt, and includes all data related to a transaction. If items are being purchased that require a delayed point award upon fulfillment, the is_awaiting_fulfillment flag must be changed for that item. More details can be found in the “fulfillment object” request examples. The format for the purchase request body can be found here.

Purchase Item Object Definition
This object represents the data related to SKU(s) purchased during a purchase transaction. Further documentation on the purchase item JSON structure can also be found here.

Example:

{
  "pos_data": [
    {
      "type": "purchase",
      "data": {
        "receipt_id": "receipt1-0510",
        "order_id": "order-0510",
        "user_id": 46038266,
        "total": 119.64,
        "subtotal": 110.78,
        "date_purchased": "2017-05-08T10:25:43.511+00:00",
        "channel_id": 1,
        "currency": "USD",
        "custom_data": {
          "store_loc": "store1",
          "register_id": "register1",
          "cashier_id": "cashier1",
          "employee_id": "employee_123"
        },
        "items": [
          {
            "sku": "sku_1",
            "price": 21.22,
            "quantity": 2,
            "transaction_id": 2,
            "custom_data": {
              "color": "blue",
              "size": "Medium"
            }
          },
          {
            "sku": "sku_2",
            "price": 89.56,
            "quantity": 1,
            "transaction_id": 1,
            "custom_data": {
              "color": "blue",
              "size": "Medium"
            }
          }
        ],
        "tenders": [
          {
            "type": 1,
            "amount": 20
          },
          {
            "type": 2,
            "amount": 99.64
          }
        ],
        "coupons": [
          "86300822933634341429",
          "coupon123789"
        ]
      }
    },
    {
      "type": "purchase",
      "data": {
        "receipt_id": "receipt2-0510",
        "order_id": "order-0510",
        "user_id": 46038266,
        "total": 119.64,
        "subtotal": 75,
        "date_purchased": "2017-05-08T08:25:43.511+00:00",
        "channel_id": 1,
        "currency": "USD",
        "custom_data": {
          "store_loc": "store1",
          "register_id": "register1",
          "cashier_id": "cashier1",
          "employee_id": "employee_123"
        },
        "items": [
          {
            "sku": "sku_1",
            "price": 75,
            "quantity": 2,
            "transaction_id": 2,
            "custom_data": {
              "color": "blue",
              "size": "Medium"
            },
            "is_awaiting_fulfillment": true
          }
        ],
        "tenders": [
          {
            "type": 1,
            "amount": 75
          }
        ]
      }
    }
  ]
}

{
  "pos_data": [
    {
      "type": "purchase",
      "data": {
        "receipt_id": "receipt1-0510",
        "order_id": "order-0510",
        "user_id": 46038266,
        "total": 119.64,
        "subtotal": 110.78,
        "date_purchased": "2017-05-08T10:25:43.511+00:00",
        "channel_id": 1,
        "currency": "USD",
        "custom_data": {
          "store_loc": "store1",
          "register_id": "register1",
          "cashier_id": "cashier1",
          "employee_id": "employee_123"
        },
        "items": [
          {
            "sku": "sku_1",
            "price": 21.22,
            "quantity": 2,
            "transaction_id": 2,
            "custom_data": {
              "color": "blue",
              "size": "Medium"
            }
          },
          {
            "sku": "sku_2",
            "price": 89.56,
            "quantity": 1,
            "transaction_id": 1,
            "custom_data": {
              "color": "blue",
              "size": "Medium"
            }
          }
        ],
        "tenders": [
          {
            "type": 1,
            "amount": 20
          },
          {
            "type": 2,
            "amount": 99.64
          }
        ],
        "coupons": [
          "86300822933634341429",
          "coupon123789"
        ]
      }
    },
    {
      "type": "purchase",
      "data": {
        "receipt_id": "receipt2-0510",
        "order_id": "order-0510",
        "user_id": 46038266,
        "total": 119.64,
        "subtotal": 75,
        "date_purchased": "2017-05-08T08:25:43.511+00:00",
        "channel_id": 1,
        "currency": "USD",
        "custom_data": {
          "store_loc": "store1",
          "register_id": "register1",
          "cashier_id": "cashier1",
          "employee_id": "employee_123"
        },
        "items": [
          {
            "sku": "sku_1",
            "price": 75,
            "quantity": 2,
            "transaction_id": 2,
            "custom_data": {
              "color": "blue",
              "size": "Medium"
            },
            "is_awaiting_fulfillment": true
          }
        ],
        "tenders": [
          {
            "type": 1,
            "amount": 75
          }
        ]
      }
    }
  ]
}