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

  1. From the Sources tab, open the menu for a feed, and then select Edit. The Feed Editor page opens.

  2. From the Primary Key drop-down, select a field from the list.

  3. 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.

email

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:

  • F

  • FEMALE (is normalized to F)

  • M

  • MALE (is normalized to M)

  • MAN (is normalized to M)

  • NONE (is treated as NULL)

  • WOMAN (is normalized to F)

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.”):

Semantic Name

Datatype

Description

[custom-semantic]

String

Required

Use a foreign key (recommended) or a custom semantic tag (such as customer-id) within interaction records to associate them to the Amperity ID.

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:

  • Must be a unique customer identifier that can be used to join interaction records (transactions and itemized transactions) to tables that contain the Amperity ID.

  • Must be unique for each order ID in the Unified_Itemized_Transactions table.

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 by 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:

  • Must match a foreign key in a table that is output by Stitch.

  • Must be well-distributed across the data source (a high percentage of values must not be 0).

  • Must be unique for each order ID in the Unified_Itemized_Transactions table.

  • May contain a NULL value.

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 TRUE when items are cancelled and FALSE when items are purchases and NULL when the value is unknown.

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 TRUE when items are returns and FALSE when items are purchases and NULL when the value is unknown.

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

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:

  • Must have a consistent time zone across all dates in the transactions data.

  • Should be a local time zone.

  • Should be a timestamp, which is converted to datetime automatically when a date is present in the timestamp.

  • When is-return is TRUE, the date and time on which the order was returned.

  • When is-cancellation is TRUE, the date and time on which the order was cancelled.

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: CONCAT(order_id, order_date).

This field is the primary key. Each unique order ID:

  • Must be associated with the pk semantic tag.

  • Must be the unique ID for the original order when items in the order have been returned or when the order is cancelled.

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-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

Optional

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

Optional

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

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?

  • Records may have NULL customer keys; NULL customer keys are ignored by Stitch.

  • There may be only one customer key per data source.

  • There may be multiple customer keys per Amperity ID. This is because customer keys may also be tagged as foreign keys.

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?

  • Records may have NULL foreign keys.

  • There may be multiple foreign keys in the data source, but there may not be duplicate foreign keys.

  • There may be multiple foreign keys per Amperity ID.

  • There should not be multiple Amperity IDs per foreign key.

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?

  • Each record in the Unified_Coalesced table must have a primary key.

  • A primary key is unique within a data source, but that primary key may not be unique across all data sources.

  • There can be only one primary key per data source; each record in the Unified_Coalesced table can be uniquely identified by the pair of values defined in the “datasource” and “pk” columns.

  • Each record in the Unified_Coalesced table may only be associated with a single Amperity ID.

sk

String

A separation key (sk) is used for deterministic unmatching of records.

The sk-[semantic] semantic tag is a separation key that is applied to profile data.

Important

By default, Amperity derives separation keys for sk-given-name and sk-generational-suffix.

More than one separation key may be applied within a table. All separation key semantic tags must be namespaced to match the profile semantic for the same field. For example: sk-birthdate matches birthdate and sk-surname matches surname.

A separation key may not be applied more than once within the same table.

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 should 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 semantics are prefixed with pc/ in the semantics drop-down menu in the Feed Editor.

Note

What is the Unified_Product_Catalog table? The Unified_Product_Catalog table represents the taxonomy for your products and brands. You may apply product catalog semantic tags to any table that contains the taxonomy for your products and brands, and then use the product identifier as the basis for AmpIQ predictive modeling.

The following table lists the semantic tags for products:

Semantic Name

Datatype

Description

product-category

String

Optional

A category to which the product belongs. Use this semantic tag to identify how a customer categorizes individual products within their product catalog.

product-gender

String

Optional

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-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-description

String

Optional

A description of the product.

product-subcategory

String

Optional

A subcategory or secondary variant to which a product belongs.

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.”):

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:

  • Must be a unique customer ID that can be used to join interaction records (transactions and itemized transactions) to tables that contain the Amperity ID.

  • Must be unique for each order ID in the Unified_Transactions table.

digital-channel

String

Optional

The digital channel by 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:

  • Must match a foreign key in a table that is output by Stitch.

  • Must be well-distributed across the data source (a high percentage of values must not be 0).

  • Must be unique for each order ID in the Unified_Transactions table.

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 TRUE.

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:

  • Must have a consistent time zone across all dates in the transactions data.

  • Should be a local time zone.

  • Should be a timestamp, which is converted to datetime automatically when a date is present in the timestamp.

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: CONCAT(order_id, order_date).

This field is the primary key. Each unique order ID:

  • Must be associated with the pk semantic tag.

  • Must appear only once in the Unified_Transactions.

  • Must match at least one order ID from the Unified_Itemized_Transactions table. (The order ID in that table may be associated to multiple items within a single transaction.)

order-list-price

Decimal

Optional

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 TRUE.

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 TRUE.

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

Optional

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

Optional

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:

  1. A field that is automatically generated by Amperity. The Generate an updated field option generates a field at the time the file is loaded.

  2. A field with an integer data type, usually some type of timestamp exported from customer data.

  3. 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

  1. From the Sources tab, open the menu for a feed, and then select Edit. The Feed Editor page opens.

  2. The last updated field is above the field list in the center of the page.

  3. 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).

  4. 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:

  1. 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.

  2. 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

  1. From the Sources tab, open the menu for a feed, and then select Edit. The Feed Editor page opens.

  2. Under Domain Table select Make available to Stitch.

  3. Click Activate.