Offline Imports

When it is not possible to establish a real-time data stream from a source, such as an offline system or certain CRM providers, Velocidi supports data onboarding through secure file uploads.

Overview#

For confidentiality, safety and security reasons, CRM data files should be uploaded to a dedicated location for each partner, from where it is picked up for processing. This location is normally a unique Amazon S3 bucket. Files can be uploaded using any Amazon S3 compatible software, including Amazon's own AWS CLI. Authentication details are provided separately and consist of an access key and a password. When uploading files to S3, files can be uploaded to the root folder of the S3 bucket. Multiple files might reside in the same folder, if needed.

Amazon S3 secures data transmissions using HTTPS and most tools have encryption enabled by default.

Load External Attribute Data Files#

Onboarding external user attributes from a CRM system or a third-party provider is possible when you have users identified with a User ID such as an email address, phone number, subscriber id, or another CRM ID of any kind. To make this data usable on other platforms (Browsers, Mobile apps, etc) you must first have built a pool of Cross-Channel Matches in order to make the connection at the individual user level between the CRM ID and the platform ID (such as a cookie).

Data Types#

Event Data#

Velocidi can receive periodic data uploads with data from events collected from users, such as page views, in-app activity, or e-commerce behavior. These types of data files should always contain a timestamp of the event, including time-zone information, as well as the event details (more information about Events and standard naming conventions is available in the Collection documentation)

CRM Data#

Velocidi accepts CRM data of various kinds, such as age (DoB or Age bands), gender, household income, location or any data that might be relevant to leverage with Velocidi.

When uploading static data you may use CSV and JSON. There is no limit to the number of fields per entry.

Orders#

Export your CRM orders and import them into the CDP.

Use cases:

  • Bootstrap your system with historic order data;
  • Ensure the orders used by the CDP are in sync with your CRM orders;
  • Complement your collected order tracking events with details private to the CRM backend.

Supported schemas#

We currently have support for the following 1st and 3rd party formats:

Velocidi CSV#

This format is intended for CSV imports where each line is a Velocidi's Order/LineItem objects serialized to CSV (Example file).

Relevant notes:

  • All Line items for the same Order must be listed sequentially;
  • Given an order with an arbitrary number of rows, only the first row is used to extract Order details and all rows are used to extract Line item details. This means that Orders with more than 1 Line item do not need to populate the order columns for all columns and can be left empty.
ColumnRequiredTypeDescriptionDetailsExample
orderIdRequiredStringOrder identifierMust be unique by Orderor123
userIdTypeRequiredStringThe type of user identifier (e.g. "email")email
userIdRequiredStringThe user identifierjohn@email.com
currencyRequiredStringThe currency used in monetary valuesCheck the supported currenciesEUR
totalRequiredDoubleTotal value of the order with all discounts already considered, including subtotal, tax and shippingtotal = subtotal + tax + shipping102.5
subtotalRequiredDoubleThe value of the order, when tax and shipping are excludedsubtotal = total - tax - shipping85
taxRequiredDoubleThe total applied tax value for the order11.5
shippingRequiredDoubleThe total shipping costs for the order6
discountRequiredDoubleThe total discounted value for the order5
refundRequiredDoubleThe total refunded value for the order0
paymentMethodStringThe payment methodVisa
shippingMethodStringThe shipping methodUPS
shippingCountryStringThe destination countryFrance
promotionsList of StringsVouchers applied in the purchase.Strings separated by ;WINTERSALE
createdAtRequiredDateTimeWhen the order was createdDate format: ISO-86012020-09-16T10:38:06+0100
lastUpdatedDateTimeWhen the order was last updatedDate format: ISO-86012020-09-16T20:13:31+0100
lineItem_idStringA unique identifier for the line item within the orderIf undefined, a new one will be generated using the orderId and productIdli125zc
lineItem_productIdRequiredStringProduct identifierp125zc
lineItem_itemGroupIdStringIdentifier for a group of products that come in different versions (variants)p125
lineItem_nameStringProduct nameMy Product
lineItem_skuRequiredStringProduct SKUp125zc-5
lineItem_brandStringProduct brandNike
lineItem_productTypeStringProduct categoryShirts
lineItem_currencyRequiredStringThe currency used in monetary valuesCheck the supported currenciesEUR
lineItem_totalRequiredDoubleTotal value of the line item with all discounts already considered, including subtotal, tax and shippingtotal = subtotal + tax + shipping102.5
lineItem_subtotalRequiredDoubleThe value of the line item, when tax and shipping are excludedsubtotal = total - tax - shipping85
lineItem_taxRequiredDoubleThe total applied tax value for the line item11.5
lineItem_shippingRequiredDoubleThe total shipping costs for the line item6
lineItem_discountRequiredDoubleThe total discounted value for the line item5
lineItem_refundRequiredDoubleThe total refunded value for the line item0
lineItem_quantityRequiredIntNumber of purchased items1
lineItem_promotionsList of StringsVouchers applied in the purchase or displayed together with the productStrings separated by ;WINTERSALE
lineItem_adultBooleanWhether the product includes sexually suggestive content.Must be true or false. Defaults to falsefalse
lineItem_subscriptionDurationLongIf the purchase relates to a subscription, captures the subscription duration, in milliseconds.15552000000
lineItem_statusRequiredStringLine item status.
  • placed the order has been placed but the item is yet to be paid
  • paid the item has been paid but not yet delivered
  • fulfilled the item has been paid and delivered
  • refunded the item has been refunded
  • cancelled the order has been modified to exclude this line item
  • Supported status: placed, paid, fulfilled, refunded, cancelledfulfilled

    There's an example file available, showing how each field can be used.

    Velocidi JSON#

    This format is intended for JSON lines imports where each line is a Velocidi's Order object serialized to JSON.

    {
    "id": "String",
    "userId": {
    "idType": "String",
    "id": "String"
    },
    "currency": "String (Currency)",
    "total": "Double",
    "subtotal": "Double",
    "tax": "Double",
    "shipping": "Double",
    "discount": "Double",
    "refund": "Double",
    "paymentMethod": "Optional String",
    "shippingMethod": "Optional String",
    "shippingCountry": "Optional String",
    "promotions": ["String"],
    "createdAt": "DateTime ISO8601",
    "lastUpdated": "DateTime ISO8601",
    "lineItems": [
    {
    "orderId": "String",
    "id": "String",
    "itemGroupId": "Optional String",
    "name": "String",
    "sku": "String",
    "brand": "String",
    "productType": "String",
    "currency": "String",
    "total": "Double",
    "subtotal": "Double",
    "tax": "Double",
    "shipping": "Double",
    "discount": "Double",
    "quantity": "Int",
    "promotions": ["String"],
    "adult": false,
    "subscriptionDuration": "Optional Duration",
    "status": {
    "refundedValue": "Double (if status is Refunded)",
    "status": "String (Placed|Paid|Fulfilled|Cancelled|Refunded)"
    }
    }
    ]
    }

    Shopify CSV#

    Velocidi supports CSV order exports from Shopify. The documentation for generating a Shopify export can be found here. Please ensure you select Export orders to export all order information, instead of Export transaction histories, which only exports the transactions.

    Relevant notes:

    • Shopify uses the Name column to distinguish between different orders inside the CSV file, so it must be unique per Order;
    • All Line items for the same Order must be listed sequentially;
    • Given an order with an arbitrary number of rows, only the first row is used to extract Order details and all rows are used to extract Line item details. This means that Orders with more than 1 Line item do not need to populate the order columns for all columns and can be left empty.

    Velocidi will consider the following attributes while importing a Shopify file:

    ColumnRequiredTypeDetails
    NameRequiredStringMust be unique by Order and can be the same as Id
    EmailRequiredString
    IdRequiredString
    CurrencyRequiredStringCheck the supported currencies
    TotalRequiredDouble
    SubtotalRequiredDouble
    TaxesRequiredDouble
    Payment MethodString
    Financial StatusRequiredStringSupported status: paid, pending, refunded, partially_refunded, voided
    Refunded AmountRequiredDouble
    Discount AmountRequiredDouble
    Discount CodeString
    Shipping MethodString
    Shipping CountryString
    ShippingRequiredDouble
    Created atRequiredDateTimeDate format: yyyy-MM-dd HH:mm:ss Z
    Paid atDateTimeDate format: yyyy-MM-dd HH:mm:ss Z
    Fulfilled atDateTimeDate format: yyyy-MM-dd HH:mm:ss Z
    Lineitem quantityRequiredInt
    Lineitem nameRequiredString
    Lineitem priceRequiredDouble
    Lineitem discountRequiredDouble
    Lineitem fulfillment statusRequiredStringSupported status: pending, fulfilled
    Lineitem skuRequiredString
    VendorString

    Customers#

    UNDER CONSTRUCTION

    We're still working on this portion of the documentation.

    Products#

    UNDER CONSTRUCTION

    We're still working on this portion of the documentation.

    Last updated on