Configure Feeds¶
A feed defines how data should be loaded into a domain table, including specifying which columns are required and which columns should be associated with a semantic tag that indicates that column contains customer profile (PII) and transactions data.
Set the primary key¶
A primary key is a column in a data table that uniquely identifies each row in a data source or data table.
At least one field must be set as a primary key. Any feed that contains customer records or interaction records must have a field that can be associated with a primary key. This is typically an obvious field, like a customer ID or transaction ID, but some data sources are not as clear. You may tag more than one field as the primary key.
To set the primary key
From the Sources tab, open the menu for a feed, and then select Edit. The Feed Editor page opens.
From the Primary Key drop-down, select a field from the list.
Click Activate.
Tip
The number of records in a domain table may not match the number of records loaded by Amperity after loading data. Amperity uses an UPSERT process when loading data and determines priority based on the Last Updated Field. If a large difference exists take a close look at the primary key and determine if the primary key is the cause.
Apply semantic tags¶
Semantic tags must be defined for every feed that will provide profile data to Stitch. This ensures that data from rich sources of profile data are brought into Amperity in a consistent manner, which improves the outcome of the Stitch process.
Each group of semantic tags–customer profile semantic tags, interaction semantic tags, and key semantic tags–allow for a range of options.
Customer profiles¶
Personally identifiable information (PII) is any data that could potentially identify a specific individual. PII data includes details like names, addresses, email addresses, and other profile attributes, but can also include attributes like a loyalty number, customer relationship management (CRM) system identifiers, and foreign keys in customer data.
A PII semantic assigns consistency to customer data to ensure that PII data is more easily discovered across many sets of data.
Profile semantics should be applied to customer records that contain three (or more) good sources of PII data. Profile semantics should be applied to interaction records only when customer records are stored alongside transaction details and when there are three (or more) good sources of PII data.
The following table lists the tags available to this semantic group:
Semantic Name |
Datatype |
Description |
|---|---|---|
address |
String |
The address that is associated with the location of an individual customer record. For example: 123 Main Street. |
address2 |
String |
Additional address information, such as an apartment number or a post office box, that is associated with the location of an individual customer record. For example: Apt #9. |
birthdate |
Date |
The date of birth that is associated with an individual customer record. Tip A field that is tagged with the birthdate semantic tag will return an error when the feed is saved and the data type is not set to Date. |
city |
String |
The city that is associated with the location of an individual customer record. |
company |
String |
The company, typically an employer or small business, that is associated with an individual customer record. |
country |
String |
The country that is associated with the location of an individual customer record. Important A field to which the country semantic tag is applied is added to the Unified_Coalesced table, but is otherwise ignored by Stitch. |
create-dt |
Apply the create-dt semantic tag to columns in customer records that identify when the data was created. The field to which this semantic is applied must be a datetime field type. |
|
String |
The email address that is associated with an individual customer record. A customer record may be associated with multiple email addresses. |
|
full-name |
String |
A combination of given name (first name) and surname (last name) that is associated with an individual customer record and is stored as a combined value in a single field within customer data. A full name may include a middle name or initial. |
gender |
String |
The gender that is associated with an individual customer record. Supported values for fields associated with the gender semantic tag include:
|
generational-suffix |
String |
The suffix that identifies to which family generation a customer record belongs. For example: Jr., Sr. II, and III. Caution The generational-suffix semantic tag should only be applied once per feed and only to a field that contains the suffix separated from the first and last names. |
given-name |
String |
The first name that is associated with an individual customer record. Caution The given-name semantic tag may only be applied once per feed. |
phone |
String |
The phone number that is associated with an individual customer record. A customer record may be associated with multiple phone numbers. Tip A field that is tagged with the phone semantic tag will return an error when the feed is saved and the data type is not set to String. |
postal |
String |
The zip code or postal code that is associated with the location of an individual customer record. A full 9-digit zip code is derived from fields that contain zip code data. Tip A field that is tagged with the postal semantic tag will return an error when the feed is saved and the data type is not set to String. |
state |
String |
The state or province that is associated with the location of an individual customer record. |
surname |
String |
The last name that is associated with an individual customer record. Caution The surname semantic tag may only be applied once per feed. |
title |
String |
The title that precedes a full name that is associated with an individual customer record. For example: Mr., Mrs, and Dr. |
update-dt |
Apply the update-dt semantic tag to columns in customer records that identify when the data was last updated. The field to which this semantic is applied must be a datetime field type. At least one customer record must have this semantic tag applied to ensure that the update_dt column is created in the Unified_Coalesced table and to ensure that the Merged_Customers table behaves correctly. |
Itemized transactions¶
An itemized transactions semantic is a way to identify brands, channels, stores, orders, products, quantities, per-item costs, total costs, and so on. Use itemized transactions semantics when a data source contains one row per item.
Itemized transaction semantics should be applied to data sources that contain interaction records for customer transactions that contain details for each individual item in a transaction. Transaction semantics may applied alongside other semantics, depending on the data source, and are often applied alongside transaction semantics in the same data source. Use the built-in list of semantics when building a feed.
Itemized transaction semantics are prefixed with txn-item/ in the semantics drop-down menu in the Feed Editor.
Important
This collection of semantic tags is used by Amperity to build the Unified_Itemized_Transactions table. Each semantic tag is directly associated with a column in that table. For example, values identified by the is-cancellation, item-cost, and order-id semantic tags are added to the is_cancellation, item_cost, and order_id columns, respectively.
The Unified_Itemized_Transactions table contains every row of every stitched table with all transactional data summarized to the item level, and then coalesced into a single column for each unique combination of order ID and product ID. The order ID is associated with an Amperity ID.
Carefully review the data in the Unified_Itemized_Transactions table, including column values that are calculated from values in other columns in this table or the Unified_Transactions table, to verify their accuracy and to ensure that associated semantic tags have been applied correctly.
The following table lists the tags available to this semantic group (with required semantic tags noted by “ Required.” and recommended semantic tags noted by “ Recommended”):
Semantic Name |
Datatype |
Description |
|---|---|---|
[custom-semantic] |
String |
Required Use a foreign key (recommended) or a custom semantic tag (such as Important See fk-[namespace]. At least one field must have the [custom-semantic] or fk-[namespace] semantic tags applied to it to support downstream processing requirements for interaction records. You may apply more than one, or use a combination, of these semantic tags. When a custom semantic tag is added to itemized transactions data it:
|
currency |
String |
Optional Currency represents the type of currency that was used to pay for an item. For example: dollar. Note Currency must be consistent across all orders from the same data source. |
digital-channel |
String |
Optional The digital channel through which a transaction was made. For example: Facebook, Google Ads, email, etc. Note This semantic tag should only be used when purchase-channel specifies an online channel. |
fk-[namespace] |
String |
Required The fk-[namespace] semantic tag identifies a field as a foreign key. A foreign key semantic tag must be namespaced. For example: fk-customer, fk-interaction, fk-audience, or fk-brand. A namespaced foreign key must be present in interaction records that contain transactions data. A foreign key may used along with a customer ID. Important See [custom-semantic]. At least one field must have the fk-[namespace] or [custom-semantic] semantic tags applied to it to support downstream processing requirements for interaction records. You may apply more than one, or use a combination, of these semantic tags. When a foreign key is added to transactions data it:
|
is-cancellation |
Boolean |
Required A flag that indicates if the item was cancelled. Important The field to which the is-cancellation semantic is applied must represent a value that is Note The is-cancellation and is-return semantic tags may not be applied to the same field. |
is-return |
Boolean |
Required A flag that indicates if the item was returned. Important The field to which the is-return semantic is applied must represent a value that is Note The is-cancellation and is-return semantic tags may not be applied to the same field. |
item-cost |
Decimal |
Optional Item cost is the cost to produce all units of an item. Note This value must be greater than or equal to 0 for purchases, but less than or equal to 0 for returns or cancellations. |
item-discount-amount |
Decimal |
Optional Item discount amount is the discount amount that is applied to all units that are associated with a single item within a single transaction. This value should equal item quantity multipled by unit discount amounts. This value is used by Amperity for discount sensitivity analysis. Note This value must be greater than or equal to 0 for purchases, but less than or equal to 0 for returns or cancellations. |
item-discount-percent |
Decimal |
Optional Item discount percent is the percentage discount that is applied to all units that are associated with a single item within a single transaction. This value is used by Amperity for discount sensitivity analysis. Note This value must be between 0 and 1. |
item-list-price |
Decimal |
Optional Item list price is the manufacturer’s suggested retail price (MSRP) for all units of this item. The manufacturer’s suggested retail price (MSRP) is the price before shipping costs, taxes, and/or discounts have been applied. MSRP is sometimes referred to as the base price. This value should equal item revenue plus item discount amount. Note This value must be greater than or equal to 0 for purchases, but less than or equal to 0 for returns or cancellations. |
item-profit |
Decimal |
Optional Item profit represents the amount of profit that is earned when all units of an item are sold. Note This value must be greater than or equal to 0 for purchases, but less than or equal to 0 for returns or cancellations. |
item-quantity |
Integer |
Required Item quantity is the total number of items in an order. When an item has been returned or an order has been cancelled, item quantity is the total number of items that were returned and/or cancelled. Note This value must be less than or equal to 0 when is-return or is-cancellation are true. |
item-revenue |
Decimal |
Required The total revenue for all units of an item, after discounts are applied. When an item has been returned or the order has been cancelled, the total revenue for all items that were returned and/or cancelled. This value should equal item list price minus item discount amount. Note This value must be less than or equal to 0 when is-return or is-cancellation are true. |
item-subtotal |
Decimal |
Optional An item subtotal is the amount for an item, before discounts are applied. This value should equal unit list price times item quantity. This value is used by Amperity to calculate discounts for discount sensitivity analysis. Note This value must be greater than or equal to 0 for purchases, but less than or equal to 0 for returns or cancellations. |
item-tax-amount |
Decimal |
Optional An item tax amount is the total amount of taxes that are associated with the purchase of an item. Note This value must be greater than or equal to 0 for purchases, but less than or equal to 0 for returns or cancellations. |
order-datetime |
Datetime |
Required Order datetime is the date (and time) on which an order was placed. The order date:
Note Other dates associated with an order that are not specific to a transactions, such as dates associated with hotel stays and reservations, should be added to the Unified_Product_Catalog table. |
order-id |
String |
Required An order ID is the unique identifier for the order and links together all of the items that were part of the same transaction. When an item has been returned or when an order has been cancelled, the order ID is the unique identifier for the original order, including the returned or cancelled items. Note The order ID should never change, even when an item in the order is returned or cancelled. Important If order IDs are recycled and/or are otherwise not guaranteed to be unique over time, the unique identifier for the order must be updated to be a combination of the order ID and the date on which the order occurred. This must be done using domain SQL similar to: This field is the primary key. Each unique order ID:
Note For data that contains itemized transactions, where a single transaction includes more than one of the same item, the order ID will appear more than once. |
payment-method |
String |
Optional A payment method is how a customer chose to pay for the items they have purchased. For example: credit card, gift card, or cash. |
Product catalogs |
String |
Optional Product catalog semantics may be applied to data sources that contain product catalog data. There are two sets of product catalog semantic tags: txn-item/ and pc/.
Important The names of the semantic tags that are available for product catalogs are identical. For example: “product-brand”, “product-category”, and “product-gender”. The difference is the prefix that you choose to use and the pattern your tenant chooses for defining your product catalog within Amperity. You should determine which pattern you want to use early in your configuration and deployment process. Talk with your Amperity representative if you have questions about the best ways to approach this within your tenant. To review the descriptions for all of the product catalog semantic tags you may prefix with txn-item/ refer to the section in this topic about product catalog semantic tags. |
product-id |
String |
Required The unique identifier for a product. A stock keeping unit (SKU) is an identifier that captures all of the unique details of any individual product, including specific attributes that differentiate by color, size, material, and so on. For example, a shirt with the same color and material, but with three different sizes would be represented by three unique SKUs and would also be represented by three unique product IDs. For data that contains itemized transactions, where a single transaction includes more than one of the same product, the product ID must appear only once per order ID in the Unified_Itemized_Transactions table. Multiple instances of the same product must be added to the item quantity in the same row. Caution Every customer has their own definition for SKUs and product IDs. Be sure to understand this defintition before applying semantic tags to fields with product IDs to ensure they accurately reflect the customer’s definition. |
purchase-brand |
String |
Required The brand for which a transaction was made. Caution This semantic tag should only be used when interaction records contain transaction data for more than one brand. |
purchase-channel |
String |
Required A purchase channel is the channel from which a transaction was made. For example: in-store or online. |
store-id |
String |
Required A store ID is a unique identifier that is identified with the location of a store. |
unit-cost |
Decimal |
Optional Unit cost is the cost to produce a single unit of one item. Note This value must be greater than or equal to 0 for purchases, but less than or equal to 0 for returns or cancellations. |
unit-discount-amount |
Decimal |
Optional Unit discount amount is the discount amount that is applied to a single unit of one item. This discount is often applied to all units of the same item within a single transaction. This value is used by Amperity for discount sensitivity analysis. Note This value must be greater than or equal to 0 for purchases, but less than or equal to 0 for returns or cancellations. |
unit-list-price |
Decimal |
Optional Unit list price is the manufacturer’s suggested retail price (MSRP) for a single unit of an item. The manufacturer’s suggested retail price (MSRP) is the price before shipping costs, taxes, and/or discounts have been applied. MSRP is sometimes referred to as the base price. This value should equal the unit discount amount plus the unit subtotal. Note This value must be greater than or equal to 0 for purchases, but less than or equal to 0 for returns or cancellations. |
unit-profit |
Decimal |
Optional Unit profit represents the amount of profit that is earned when a single unit of an item is sold. Note This value must be greater than or equal to 0 for purchases, but less than or equal to 0 for returns or cancellations. |
unit-revenue |
Decimal |
Optional The total revenue for a single unit of an item. When an item has been returned or the order has been cancelled, the total revenue for a single unit of an item that was returned and/or cancelled. Note This value must be less than or equal to 0 when is-return or is-cancellation are true. |
unit-subtotal |
Decimal |
Optional A unit subtotal is the amount for a single unit of one item, before discounts have been applied. This value is used by Amperity to calculate discounts for discount sensitivity analysis. Note This value must be greater than or equal to 0 for purchases, but less than or equal to 0 for returns or cancellations. |
unit-tax-amount |
Decimal |
Optional A unit tax amount is the total amount of taxes that are associated with a single unit. Note This value must be greater than or equal to 0 for purchases, but less than or equal to 0 for returns or cancellations. |
Keys¶
Keys are used to identify signals in source data that can be applied during the Stitch process. For example, a table that contains customer records automatically assigns the pk semantic to any field identified as a primary key. For tables that contain interaction records, a foreign key is often used to associate important fields for interaction records to primary keys for customer records. This allows interaction records to be correlated with the Amperity ID as an outcome of the Stitch process even though interaction records are (typically) not processed by Stitch for the purpose of identity resolution.
The following table describes the keys that are used to tag data:
Semantic Name |
Datatype |
Icon |
Description |
|---|---|---|---|
bk-[label] |
String |
A blocking key defines a specific combination of characters to be used as a blocking strategy. For example, the first three characters in given-name, the first character in surname, and birthdate represent a blocking key. Tip A foreign key can be labled as a blocking key to force Stitch to score all records that match on the blocking key, but without assigning them a 5.0 score. |
|
ck |
String |
The ck semantic tag may be applied to a column that contains pre-existing, tenant-specific customer IDs. When customer keys are applied, Amperity compares them to the Amperity ID as part of the deduplication process. Tip What happens to customer keys in the Unified_Coalesced table?
|
|
fk-[namespace] |
String |
A foreign key is a column in a data table that acts as primary key and can be used for deterministic matching of records. A record pair is assigned an exact match score (5.0) when foreign keys contain identical values during pairwise comparison. The fk-[namespace] semantic tag identifies a field as a foreign key. A foreign key semantic tag must be namespaced. For example: fk-customer, fk-interaction, fk-audience, or fk-brand. A foreign key semantic tag may be applied to any column in any data source, but should be associated with a field that can also act as a primary key for that data source and is present in other tables. A foreign key may be used once within a table. A table may have more than one foreign key. For example, if a data source contains customer and audience identifiers, apply fk-customer to the customer identifier and fk-audience to the audience identifier. Tip What happens to foreign keys in the Unified_Coalesced table?
Note If foreign keys are linked together by a trivial duplicate they will appear in the Unified_Preprocessed_Raw table as a comma-separated list. |
|
pk |
String |
A primary key is a column in a data table that uniquely identifies each row in a data source or data table. The combination of data source and primary key allows Amperity to uniquely identify every row in every data table across the entirety of customer data input to Amperity. Tip What happens to primary keys in the Unified_Coalesced table?
|
|
sk |
String |
A separation key (sk) is used for deterministic unmatching of records. The sk-[semantic] semantic tag is a namespaced key that matches a customer profile semantic tag and is applied to a field that contains matching customer profile data. For example: sk-birthdate matches birthdate and sk-surname matches surname. Important Amperity derives separation keys for sk-given-name and sk-generational-suffix automatically. You may apply more than one separation key within a table; however, each unique separation key may only be applied once. All separation key semantic tags must be namespaced to match the profile semantic for the same field. Important A separation key may also be tagged as a foreign key. Tagging the same field as a foreign and separation key can be useful when customer data has a strong identifier that is also associated with an important profile semantic tag, such as phone or email. |
Product catalogs¶
Product catalog semantics may be applied to data sources that contain product catalog data. Product semantics may applied alongside other semantics, depending on the data source. Use the built-in list of semantics when building a feed. Product catalog semantics are prefixed with pc/ in the semantics drop-down menu in the Feed Editor. Use the combination of product semantic tags that best describes the structure of your product catalog.
Important
The Unified_Product_Catalog table represents the taxonomy for your products and brands. Attributes are added to the Unified_Product_Catalog table when pc/ semantic tags are applied to your data sources. All pc/ semantic tags are optional. Use the ones that best define the shape of your product catalog and best describe the individual items within it. The product ID is used as an input to AmpIQ predictive modeling.
The following table lists the tags available to this semantic group (with required semantic tags noted by “ Required.” and recommended semantic tags noted by “ Recommended”):
Semantic Name |
Datatype |
Description |
|---|---|---|
product-brand |
String |
Optional. The brand name of a product or item. |
product-brand-id |
String |
Optional. The ID for the brand name of a product or item. |
product-category |
String |
Recommended A category to which a product belongs. Use this semantic tag to identify how a customer categorizes individual products within their product catalog. |
product-category-id |
String |
Optional. The ID for the category to which a product belongs. |
product-class |
String |
Optional. The name of the class (or grouping) to which a product or item belongs. |
product-class-id |
String |
Optional. The ID for the name of the class (or grouping) to which a product or item belongs. |
product-collection |
String |
Optional. The name of the collection to which a product or item belongs. |
product-collection-id |
String |
Optional. The ID for the name of the collection to which a product or item belongs. |
product-color |
String |
Optional. The color of a product or item. |
product-color-id |
String |
Optional. The ID for the color of a product or item. |
product-department |
String |
Optional. The department to which a product or item belongs. |
product-department-id |
String |
Optional. The ID for the department to which a product or item belongs. |
product-description |
String |
Recommended A description of the product. |
product-division |
String |
Optional. The division to which a product or item belongs. |
product-division-id |
String |
Optional. The ID for the division to which a product or item belongs. |
product-fabric |
String |
Optional. The fabric used for a product or item. |
product-fabric-id |
String |
Optional. The ID for the fabric used for a product or item. |
product-gender |
String |
Recommended Apply this as a custom semantic tag to a fields that contain a list of gender options for products. For example: F, M, unisex, NULL (for unknown). |
product-group |
String |
Optional. The group to which a product or item belongs. |
product-id |
String |
Optional The unique identifier for a product. Important AmpIQ predictive modeling requires a product catalog to contain between 20-2000 unique product IDs. A product ID is often associated with a stock keeping unit (SKU). A stock keeping unit (SKU) is an identifier that captures all of the unique details of any individual product, including specific attributes that differentiate by color, size, material, and so on. For example, a shirt with the same color and material, but with three different sizes would be represented by three unique SKUs and would also be represented by three unique product IDs. Each customer has their own definition for product IDs and SKUs. Be sure to understand this defintition before applying semantic tags to fields with product IDs to ensure they accurately reflect the customer’s definition and meet the requirements for AmpIQ predictive modeling (if enabled). |
product-material |
String |
Optional. The material used for a product or item. |
product-material-id |
String |
Optional. The ID for the material used for a product or item. |
product-msrp |
String |
Optional. The manufacturer’s suggested retail price (MSRP) for a product or item. The manufacturer’s suggested retail price (MSRP) is the price before shipping costs, taxes, and/or discounts have been applied. MSRP is sometimes referred to as the base price. |
product-name |
String |
Optional. The name of the product or item. |
product-season |
String |
Optional. The season to which a product or item is associated. |
product-season-id |
String |
Optional. The ID for the season to which a product or item is associated. |
product-silhouette |
String |
Optional. |
product-size |
String |
Optional. The size of a product or item. |
product-size-id |
String |
Optional. The ID for the size of a product or item. |
product-sku |
String |
Optional. The stock keeping unit, or SKU, for the product or item. A stock keeping unit (SKU) is an identifier that captures all of the unique details of any individual product, including specific attributes that differentiate by color, size, material, and so on. |
product-style |
String |
Optional. The style of a product or item. |
product-subcategory |
String |
Recommended The subcategory or secondary variant to which a product belongs. |
product-subcategory-id |
String |
Optional. The ID for the subcategory or secondary variant to which a product belongs. |
product-subclass |
String |
Optional. The subclass to which a product or item is assigned. |
product-subclass-id |
String |
Optional. The ID for the subclass to which a product or item is assigned. |
product-subdepartment |
String |
Optional. The sub-department to which a product or item is assigned. |
product-subdepartment-id |
String |
Optional. The ID for the sub-department to which a product or item is assigned. |
product-type |
String |
Optional. The type assigned to a product or item. |
product-upc |
String |
Optional. The UPC code for the product or item. A Universal Product Code (UPC or UPC code) is a barcode that is widely used to track items in stores. |
Transactions¶
A transactions semantic is a way to identify brands, channels, stores, orders, products, quantities, per-item costs, total costs, and so on. Use transactions semantics when a data source contains one row per order.
Transactions semantics should be applied to data sources that contain interaction records for customer transactions. Transactions semantics may applied alongside other semantics, depending on the data source. Use the built-in list of semantics when building a feed. Transactions semantics are prefixed with txn/ in the semantics drop-down menu in the Feed Editor.
Important
This collection of semantic tags is used by Amperity to build the Unified_Transactions table. Each semantic tag is directly associated with a column in that table. For example, values identified by the digital-channel, order-discount-amount, and payment-method semantic tags are added to the digital_channel, order-discount-amount, and payment_method columns, respectively.
The Unified_Transactions table contains one row for each unique transaction record, with each order ID associated to an Amperity ID.
Carefully review the data in the Unified_Transactions table, including column values that are calculated from values in other columns in this table or the Unified_Itemized_Transactions table, to verify their accuracy and to ensure that associated semantic tags have been applied correctly.
The following table lists the tags available to this semantic group (with required semantic tags noted by “ Required.” and recommended semantic tags noted by “ Recommended”):
Semantic Name |
Datatype |
Description |
|---|---|---|
currency |
String |
Optional Currency represents the type of currency that was used to pay for an item. For example: dollar. Note Currency must be consistent across all orders from the same data source. |
customer-id |
String |
Required A custom semantic tag that is applied to interaction records to identify a field that is used in downstream processes to associate interaction records to the Amperity ID. A customer ID may appear once for each order ID in the transactions table. A customer ID may used along with a foreign key. Important See fk-[namespace]. At least one field must have the customer-id or fk-[namespace] semantic tags applied to it to support downstream processing requirements for interaction records. You may apply more than one, or use a combination, of these semantic tags. When a customer key is added to transactions data it:
|
digital-channel |
String |
Optional The digital channel through which a transaction was made. For example: Facebook, Google Ads, email, etc. Note This semantic tag should only be used when purchase-channel specifies an online channel. |
fk-[namespace] |
String |
Required The fk-[namespace] semantic tag identifies a field as a foreign key. A foreign key semantic tag must be namespaced. For example: fk-customer, fk-interaction, fk-audience, or fk-brand. A namespaced foreign key must be present in interaction records that contain transactions data. A foreign key may used along with a customer ID. Important See customer-id. At least one field must have the fk-[namespace] or customer-id semantic tags applied to it to support downstream processing requirements for interaction records. You may apply more than one, or use a combination, of these semantic tags. When a foreign key is added to transactions data it:
|
order-cancelled-quantity |
Integer |
Required The total number of items in the original transaction that were cancelled. This value should match the sum of all items in itemized transactions that were cancelled for the same order ID. Note This value must be less than or equal to 0 when is_cancelled is |
order-cancelled-revenue |
Decimal |
Required The total amount of revenue for all cancelled items in the transaction. Note This value must be less than or equal to 0. |
order-cost |
Decimal |
Optional Order cost represents the total cost of goods sold (COGS) for a single transaction. Cost of goods sold (COGS) are the direct costs of producing goods that are sold by a brand, including the costs of materials and labor to produce the item, but excluding indirect expenses like distribution or sales. Note This value must be greater than or equal to 0 for purchases, but less than or equal to 0 for returns or cancellations. Warning Only one of order-profit and order-cost may be present for a transaction. |
order-datetime |
Datetime |
Required Order datetime is the date (and time) on which an order was placed. The order date:
Note Other dates associated with an order that are not specific to a transactions, such as dates associated with hotel stays and reservations, should be added to the Unified_Product_Catalog table. |
order-discount-amount |
Decimal |
Optional Order discount amount is the total discount amount that is applied to the entire order. Note This value must be greater than or equal to 0 for purchases, but less than or equal to 0 for returns or cancellations. This value is used by Amperity for discount sensitivity analysis. Caution This value should match your definition of an order-level discount amount. For example, this value may be associated with order value and it may be associated with a subtotal. Use domain SQL to update this field for any desired calculation when this semantic tag cannot be applied to a single field. |
order-discount-percent |
Decimal |
Optional Order discount percent is the percentage discount that is applied to the order value for the entire transaction, in addition to any item or unit-specific discount percentages. This value may be used as an input to order discount amount. Note This value must be between 0 and 1. This value is used by Amperity for discount sensitivity analysis. Caution This value should match your definition of an order-level discount percentage. For example, this value may be associated with order value and it may be associated with a subtotal. Use domain SQL to update this field for any desired calculation when this semantic tag cannot be applied to a single field. |
order-id |
String |
Required An order ID is the unique identifier for the order and links together all of the items that were part of the same transaction. When an item has been returned or when an order has been cancelled, the order ID is the unique identifier for the original order, including the returned or cancelled items. Note The order ID should never change, even when an item in the order is returned or cancelled. Important If order IDs are recycled and/or are otherwise not guaranteed to be unique over time, the unique identifier for the order must be updated to be a combination of the order ID and the date on which the order occurred. This must be done using domain SQL similar to: This field is the primary key. Each unique order ID:
|
order-list-price |
Decimal |
Optional Order list price is the total value for a transaction, as defined by the manufacturer’s suggested retail price (MSRP) for all units of this item. The manufacturer’s suggested retail price (MSRP) is the price before shipping costs, taxes, and/or discounts have been applied. MSRP is sometimes referred to as the base price. This value should match the sum of item list price amounts in itemized transactions that are associated with the same order ID. Note This value must be greater than or equal to 0 for purchases, but less than or equal to 0 for returns or cancellations. |
order-profit |
Decimal |
Optional Order profit is the amount of profit that is earned from a single transaction. Note This value must be greater than or equal to 0 for purchases, but less than or equal to 0 for returns or cancellations. Warning Only one of order-profit and order-cost may be present for a transaction. |
order-quantity |
Integer |
Required Order quantity is the total number of individual items associated with the transaction. This value should match the sum of all items in itemized transactions that have not been returned or cancelled for the same order ID. Note This value must be greater than or equal to 0 for purchases, but less than or equal to 0 for returns or cancellations. |
order-returned-quantity |
Integer |
Required Order returned quantity is the total number of items in the original transaction that were returned. This value should match the sum of all items in itemized transactions that were returned for the same order ID. Note This value must be less than or equal to 0 when is_return is |
order-returned-revenue |
Decimal |
Required Order returned revenue total amount of revenue for all returned items in a transaction. This value should match the sum of revenue for all items in itemized transactions that were returned for the same order ID. Note This value must be less than or equal to 0 when is_return is |
order-revenue |
Decimal |
Required The total amount of revenue for all items in a transaction after discounts are applied, ignoring returns and/or cancellations. This value should match the sum of revenue for all items in itemized transactions that were not returned or cancelled for the same order ID. Note This value must be greater than or equal to 0 for purchases, but less than or equal to 0 for returns or cancellations. |
order-shipping-amount |
Decimal |
Optional The order shipping amount is the total cost of shipping all items in the same transaction. Note This value must be greater than or equal to 0 for purchases, but less than or equal to 0 for returns or cancellations. |
order-subtotal |
Decimal |
Optional An order subtotal is the amount for an order, before discounts are applied. This value should match the sum of item subtotal revenue in itemized transactions for the same order ID. |
order-tax-amount |
Decimal |
Optional An order tax amount is the total amount of taxes that are associated with an entire order. Note This value must be greater than or equal to 0 for purchases, but less than or equal to 0 for returns or cancellations. |
payment-method |
String |
Optional A payment method is how a customer chose to pay for the items they have purchased. For example: credit card, gift card, or cash. |
purchase-brand |
String |
Recommended The brand for which a transaction was made. Caution This semantic tag should only be used when interaction records contain transaction data for more than one brand. |
purchase-channel |
String |
Recommended A purchase channel is the channel from which a transaction was made. For example: in-store or online. |
store-id |
String |
Required A store ID is a unique identifier that is identified with the location of a store. |
sum-item-discount-amount |
Decimal |
Optional The sum of discount amounts is the total of all discount amounts that were applied to each item within a transaction. This value should match the sum of item discount amounts in the itemized transactions for the same order ID. Note This value must be greater than or equal to 0 for purchases, but less than or equal to 0 for returns or cancellations. |
sum-item-revenue |
Decimal |
Optional The sum of itemized revenue for the original order, not including returns and/or cancellations. This value may be used as an input to order revenue. This value should match the sum of item revenue in itemized transactions, not including returns or cancellations, for the same order ID. Note This value must be greater than or equal to 0 for purchases, but less than or equal to 0 for returns or cancellations. |
Select last updated field¶
Amperity requires each feed to specify a field that describes when each record was last updated. This field may be autogenerated (recommended) or may be associated with a field that has an integer or datetime field type.
Amperity uses this field to determine priority in situations where duplicate primary keys are present in the incoming data, such as with sets of batched files and with big data formats that are split across many individual files, such as Apache Avro and Apache Parquet.
The last updated field requires one of the following options:
A field that is automatically generated by Amperity. The Generate an updated field option generates a field at the time the file is loaded.
A field with an integer data type, usually some type of timestamp exported from customer data.
A field with a datetime data type.
This option is often associated with the field to which the update-dt semantic tag is applied. The update-dt field is used by Amperity for database merge rules and has no effect when Amperity determines priority unless it is also selected from the Last Updated Field drop-down menu.
Note
Amperity does not use a field with a date data type because that value is not granular enough to determine priority.
To set the last updated field
From the Sources tab, open the menu for a feed, and then select Edit. The Feed Editor page opens.
The last updated field is above the field list in the center of the page.
Under Last Updated Field, choose how Amperity will determine priority: automatically generated, a field with an integer data type (typically a primary key), or a field with a datetime data type (often the same field to which the update-dt merge rules semantic tag is applied).
Click Activate
Tip
The number of records in a domain table may not match the number of records loaded by Amperity after loading data. Amperity uses an UPSERT process when loading data and determines priority based on the Last Updated Field. If a large difference exists take a close look at the primary key and determine if the primary key is the cause.
Make available to Stitch¶
A domain table that contains customer records with semantic tags applied to records that contain PII data should be made available to Stitch. A domain table that is made available to Stitch may then be configured to be used by Stitch when processing that data for customer identity resolution.
Data in a domain table is made available to Stitch in two steps:
Enabling a setting when configuring a feed or a custom domain table. When enabled, the name of the domain table that is associated with the feed or custom domain table is added to a list of domain tables that are accessible to Stitch as a configuration setting.
A list of domain tables within Stitch configuration that have been made available. Each table must be enabled before it can be used by Stitch for customer identity resolution.
Tip
Only tables that contain PII data should be made available to Stitch. Tables that are later associated with Amperity IDs, such as those that contain transactions and itemized transactions data, should be associated to the Amperity ID by using a foreign key.
To make data available to Stitch
From the Sources tab, open the menu for a feed, and then select Edit. The Feed Editor page opens.
Under Domain Table select Make available to Stitch.
Click Activate.