Sales feed crawler configurations

A sales feed crawler is a type of feed crawler that is used to index commerce-specific data from documents such as:

  • Text files containing delimiters.

  • CSV files.

  • JSON string files.

To configure a sales feed crawler, follow the procedure for configuring a feed crawler, and select Sales feed crawler when prompted for a connector type.

Note

Sales feed analytics are calculated daily. Do not upload files to the sales feed crawler more than once a day. We recommend that you upload sales feed files to the crawler once a week.

The following configurations must be present in a sales feed crawler:

Tags

In a sales feed crawler, the extractor must be configured with one or both of the following tags. They are used to distinguish online and offline purchases.

  • web - this tag is used for online transactions.

  • store - this tag is used for offline transactions.

If your domain does not send web transaction events to the events API, you can upload events in a file.

Extractor logic

The extractor logic for a sales feed crawler is similar to that of a feed crawler, but includes fields such as transaction key, event types, and entity types.

Important

To ensure your data is processed correctly, you must not alter the transaction_key, entity_type, and event_type fields in the extractor logic.

Transaction key

A sales feed crawler uses a transaction_key to group events in a session with just that session, or with a single customer. These keys are preconfigured in the sales feed crawler, and do not need to be edited. However, you can use custom values for sales feed sessionization by updating the extractor mapping to override the value.

Note

In a sales feed crawler, only the JavaScript extractor type is supported.

  • If the uploaded file includes a user_id, Search uses that as the transaction key.

  • If the uploaded file does not include a user_id, Search combines the order_id and order_date to create a new, unique key instead.

Either or both will be considered the uuid.list.

Event types

In the extractor function, event_types are used to break the order event into subevents, like entity_page_view and cart_add. This improves datasets for use in recommendations, personalization, and recipes. This list does not need to be edited.

Entity types

In the extractor function, the entity_type is set as product by default. To ensure the catalog is linked correctly, this must be the same as the name of the product entity.

Field names

The following fields are supported in a sales feed crawler, and mandatory fields are noted in the Mandatory column. If your sales feed file does not include these field names, you can change them in the file, or use the extractor code to transform and map them.

Table 1. Field Names

Search field

Description

Mandatory

conversion_id

The unique number or ID associated with the conversion event. For example, the order ID.

Yes

document_id

Unique index document ID. In commerce, this is usually sku or product_id. You can view this ID in the Content Collection section of the Search user interface.

Yes

group_by

A unique string that identifies a group of SKUs. If a product is the same as SKU, then it can be the same value as the SKU value.

For example, all the size variations of a given shirt size and color might fall into this category. When not specified, all products sharing a particular URL are grouped together.

No

entity_type

The type of entity (product/content/category and so on).

Yes

date

Date and time when the conversion happened.

Yes

price

Catalog price when conversion happened.

Yes

sale_price

Price at which the conversion happened (includes discounts).

Yes

quantity

Quantity of the document_id converted.

Yes

order_total

Total amount of the order (if more than one document_id is converted, this is the same for multiple rows.)

Yes

user_id

Unique ID associated with the user or customer who made the purchase. Typically, this is the ID assigned to the customer in your CRM system.

This is the same user ID used in events (user.id) for analytics, that is: order:confirm, user:login and user:info events.

No

user_eid

The hash (md5 or SHA256) of the user's email address, or other ID used by the email service provider.

No

user_email

User or customer email address.

No

billing_zipcode

Zip code of the customer's billing address.

No

billing_region

State or region of the customer's billing address.

No

billing_country

Country of the customer's billing address.

No

store_id

Unique ID of the store where the conversion was made.

No

store_zipcode

Zip code of the store where the conversion was made.

No

store_region

State or region of the store where the conversion was made.

No

store_country

Country of the store where the conversion was made.

No



Do you have some feedback for us?

If you have suggestions for improving this article,