[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 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:
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 canceled.
Important
The field to which the is-cancellation semantic is applied must represent a value that is TRUE when items are canceled 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 multiplied 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 canceled, item quantity is the total number of items that were returned and/or canceled.
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 canceled, the total revenue for all items that were returned and/or canceled.
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 canceled.
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 |
Required
Order discount amount is the total discount amount that is applied to the entire order.
This tag provides the following data:
Note
This field appears as a positive for a purchase and a 0 for a cancellation or return for minimum, maximum, and total order discount amounts in the Unified Transactions 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 canceled, the order ID is the unique identifier for the original order, including the returned or canceled items.
Note
The order ID should never change, even when an item in the order is returned or canceled.
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).
|
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/.
You may use txn-item/ product catalog semantic tags when product catalog data appears within data sources that contain details about your product catalog when it exists alongside details about orders and items.
Fields to which txn-item/ product catalog semantic tags are applied will be built into the Unified Itemized Transactions table in your customer 360 database.
You may use pc/ product catalog semantic tags in any data source that contains details about your product catalog. Fields to which the pc/ product catalog semantic tags are applied will be built into the Unified Product Catalog table.
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 definition 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 canceled, the total revenue for a single unit of an item that was returned and/or canceled.
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.
|
