About semantic tags

A semantic is a way to apply a common understanding to individual points of data across multiple data sources, even when data sources have different schemas, naming conventions, and levels of data quality.

A semantic type is directly associated with data values that appear in customer data tables. Semantic types exist for columns that contain values like first names, email addresses, home addresses, cities, phone numbers, and so on. Amperity has many built-in semantic types, including groupings for personally identifiable information (PII), transactions, itemized transactions, and other consumer behaviors.

The following semantic groups are available for tagging fields in customer records and interaction records:

• Blocklist

• Compliance

• Custom

• Database

• Email events

• Email summary

• Fiscal calendar

• Transactions

• Keys

• Loyalty programs

• Opt-in preferences

• Product catalog

• Profile (PII)

• Stitch labels

How semantic tags work

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.

Semantic tagging works like this:

1. A field in the customer’s system named “fname” stores an individual’s given name.

2. A field in the customer’s system named “lname” stores the same individual’s last name.

3. A field in the customer’s system named “primary-phone” stores a phone number.

4. A field in the customer’s system named “date” stores an individual’s birthdate.

5. And so on.

For those semantic tags, the feed should apply semantic tags like this:

Input field	Semantic tag
fname	given-name
lname	surname
primary-phone	phone
date	birthdate
…	…

This same pattern is applied to every customer data source that is brought into Amperity and it results in every single semantically-tagged field being analyzed by Amperity during the Stitch process in exactly the same way.

Amperity has built-in semantic tags for personally-identifiable information (PII), transactions, and behaviors. In addition, custom semantic tagging may be applied to fields when adding them can help identify unique individuals across massive data sets.

Profile semantic tags are used by Amperity for identity resolution, which is the process that builds a unified customer profile for all of your unique customers. All other semantic tags, such as for transactions and itemized transactions, are used to associate your customer’s interactions with your brand to their individual customer profiles.

What semantic tags does Stitch rely on?

Stitch relies on the following semantic tags to be applied to customer records:

• given-name (first name) and surname (last name). In some cases, a full-name is inferred (if not available).

• Other important profile details, such as birthdate, email, and phone.

• The address, address2, city, state, and postal tags are combined to represent a complete physical address.

• Other location details, such as country and company.

• Additional profile details, when available, such as gender, generational-suffix (Jr., Sr., III, etc.), and title.

Stitch uses foreign keys to associate individual customers to their interactions with your brands.

Blocklist

A bad-values blocklist contains known values that appear frequently in data and should be excluded from the Stitch process.

The following table describes recommended patterns to use when defining semantic tags for a bad-values blocklist. Blocklist semantics are prefixed with blv/ in the semantics drop-down menu in the Feed Editor.

Semantic name	Datatype	Description
blv/datasource	String	Apply to the datasource column in the bad-values blocklist table.
blv/semantic	String	Apply to the semantic column in the bad-values blocklist table.
blv/value	String	Apply to the value column in the bad-values blocklist table.

Compliance

The following table describes the semantic tags that are used for CCPA and/or GDPR compliance workflows. Compliance semantics are prefixed with compliance/ in the semantics drop-down menu in the Feed Editor.

Column	Description
id	Required Semantic tag: compliance/request-id A unique identifier for an inbound request. This identifier is used for validation purposes, allowing compliance actions to be easily linked to specific requests.
type	Required Semantic tag: compliance/request-type The request type for the compliance action. May be one of: dsar Default. Generate a report without deleting data. delete Delete rows that are found by the request strategy. delete_pii Delete only personally identifiable information (PII) from rows that are found by the request strategy. Important The delete_pii request type will only delete columns that are tagged with the compliance/pii semantic tag.
strategy	Required Semantic tag: compliance/request-strategy The request strategy for the compliance action. May be one of: exact Default. Find all rows that exactly match the compliance request. connected_pii Find all rows that exactly match the compliance request along with any row in a stitched table that shares an Amperity ID with those records.
email	Optional Semantic tag: compliance/request-email Find all records that match an email address. This action is case-insensitive. The values in this field will be checked against any source table that has the email semantic tag.
phone	Optional Semantic tag: compliance/request-phone Find all records that match a phone number. The values in this field will be checked against any source table that has the phone semantic tag.
address	Optional Semantic tags: compliance/request-address compliance/request-address2 compliance/request-city compliance/request-state compliance/request-postal compliance/request-country The values in these fields will be checked against any source table that has the address, address2, city, state, postal, and/or country semantic tags. If a source table only has some of these values tagged, the missing values will be treated as NULL. Note An address group contains multiple fields, but is a single entity for a compliance action. In order to match to records in source tables, ALL values must match. Address standardization should be applied upstream of Amperity so that address can be reliably used to identify source records.
custom-key	Optional Semantic tag: compliance/request-custom-key Find all records that match a custom value. This action is case-insensitive. The values in this field will be checked against any source table that has the compliance/custom-key semantic tag.

Note

Source keys and linkage tables identify which source table records were used to create a custom domain table record. They do not trace individual fields, so compliance/pii semantic tags should be applied directly to the source tables, not on the custom domain tables, if the delete_pii compliance type is used.

Custom

A custom semantic is a string that is applied as a semantic tag when configuring a feed. Some use cases for custom semantics include specifying keys (primary, customer, and foreign), assigning ordinals or namespaces to email and phone PII semantics, or arbitrary strings to capture specific customer use cases.

The following table describes recommended patterns to use when defining custom semantics:

Custom Semantic Pattern	Description
itemized transactions	All custom semantics that are associated with itemized transactions must be prefixed with txn-item/.
keys	Keys are used to identify signals in source data that can be applied during the Stitch process.
loyalty-id	The identifier for a loyalty program that is associated with a customer. A loyalty ID may be associated with a customer key (ck) or a foreign key (fk-[namespace]), but otherwise follows all patterns associated with PII semantics. Tip Use additional custom semantic tags when the data contains more information about loyalty programs. Keep the prefix loyalty-, and then append an appropriate string to improve the user experience with downstream workflows. For example, if the data contains a field for loyalty points, use a custom semantic named loyalty-points to tag that field.
PII	All custom semantics that are associated with transactions should be prefixed with the PII semantic to which the custom semantic is most closely associated. For example: email-personal and email-work are most closely associated with the email semantic. Note In general, the use of custom semantics for PII is limited to namespace or ordinal variation of email and phone.
product	All custom semantics that are associated with products must be prefixed with pc/.

Database

A field in a database table may be flagged as required, as unique, or as both required and unique. These flags are validated by Amperity. When the validation conditions are not met a warning is raised.

Use flags to help ensure that data within Amperity remains healthy and to help ensure that downstream workflows are built on top of the correct data. Database field semantics are preceded by a db/ in the drop-down menu for semantics in the Database Editor.

Warning

Validation warnings appear in the Notifications pane as part of the notification for a database update. Each validation warning specifies the table name and the field name that failed validation.

The following semantics may be used to tag fields as required, as unique, or as both required and unique in database tables:

Semantic name	Datatype	Description
required		Indicates if the field is required to have a non-NULL value. Note This tag is assigned automatically to all fields that contain the Amperity ID. A field that is assigned the required semantic requires every value for that field within the same table to have a non-NULL value, but does not require values to be unique. NULL values will cause an error during validation. All other values, including zero-length strings, will pass validation. Note A field may be assigned the db/required and db/unique semantics. Use this only for fields that must be present and unique, such as for the Amperity ID.
unique		Indicates if the field is required to be a unique field in the customer 360 database. A field that is assigned the unique semantic requires every value for that field within the same table to be unique. Fields with NULL values are ignored by validation, but all other values, including zero-length strings, must pass. Note A field may be assigned the db/required and db/unique semantics. Use this only for fields that must be present and unique, such as for the Amperity ID.

Email engagement

Email engagement semantic tags capture email events data, such as clicks, opens, bounces, opt-ins, opt-outs, and conversions from any email service provider (ESP) data source.

1. Use email events semantic tags when raw email events data is sent directly to Amperity.

   Caution

   The data volume for email events data can be very large. Talk with your Amperity representative before applying email events semantic tags to raw email events data.

2. Use email summary semantic tags when data is aggregated prior to sending it to Amperity.

Email events

Email events associate email summary statistics to brands, email addresses, regions, event types, event dates and times, and sender IDs.

Apply email event semantic tags to data sources that contain data for raw email events. Use the built-in list of semantics when building a feed or custom domain table. Email event semantics are prefixed with email-event/ in the semantics drop-down menu in the Feed Editor.

Important

Email events semantic tags should only be applied to data sources that provide at least 15 months of raw email events data. The storage requirements for this type of data can be significant. Talk with your Amperity representative about your downstream use cases prior to applying email events semantic tags to raw email events data sources.

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
brand	String	Required. The brand or company from which an email was sent.
campaign-id	String	The unique ID for a campaign.
campaign-name	String	The name of the campaign.
email	String	Required. The email address to which an email was sent.
event-datetime	Datetime	Required. The date and time at which email event occurred.
event-type	String	Required. The type of email event. Possible values: Open Click Sent Optin Bounce Converted Unsubscribe Important The values for email event types must spelled as expected to ensure the Email Engagement Summary can properly summarize email events. For example: “Optin” may not be “Opt-in”.
region	String	The region or location from which an email was sent. The region or location is typically associated to a single brand.
send-id	String	Required. The unique identifier for the email that was sent to an email address at a specific date and time. If a data source does not provide a send ID a unique key is generated.
treatment-id	String	The ID for the treatment group to which the associated campaign was sent.
treatment-name	String	The name of the treatment group to which the associated campaign was sent. One or more treatment groups, along with a control group, are used to measure the quality of a campaign.

Email summary

Email summary statistics provide fields that summarize customer engagement with your brand. Individual statistics include brand, email address, counts for opens and clicks by day (1, 3, 5, 7, and 14) and by month (3, 6, 9, and 12), engagement frequency, and engagement status.

Apply email summary semantic tags to data sources that contain email summary data for how customers interact with emails sent to them from your brands. Use the built-in list of semantics when building a feed. Email summary semantics are prefixed with email-summary/ in the semantics drop-down menu in the Feed Editor.

Warning

Email summary semantic tags cannot be applied to raw email events data.

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
brand	String	Required. The brand or company from which an email was sent.
email	String	Required. The email address to which an email was sent.
email-click-rate-lifetime	Decimal	The rate at which a link in any email message was clicked.
email-clicks-last-x-days	Integer	The number of email clicks in the last 1, 3, 5, 7, or 14 days.
email-clicks-last-x-months	Integer	The number of email clicks in the last 3, 6, 9, or 12 months.
email-clicks-lifetime	Integer	The number of times a link in an email was clicked from within the email events data that is provided to Amperity.
email-open-rate-lifetime	Decimal	The rate at which any email message was opened.
email-opens-last-x-days	Integer	The number of email opens in the last 1, 3, 5, 7, or 14 days.
email-opens-last-x-months	Integer	The number of email opens in the last 3, 6, 9, or 12 months.
email-opens-lifetime	Integer	The number of all email opens from within the email events data that is provided to Amperity.
engagement-frequency-last-15-months	String	A classification that measures engagement frequency click rates for email addresses that have received a low volume of emails. Possible values: Non-recipient (0 received emails) New (fewer than 5 received emails) Active (currently engaging with received emails) Inactive (not currently engaging with received emails) Important Send rates must be available.
engagement-status-last-15-months	String	A classification that measures click rates for email addresses that have received a low volume of emails. Possible values: Non-recipient (0 received emails) New (fewer than 5 received emails) Low (modeled open rate is in the lower third) Medium (modeled open rate is in the middle third) High (modeled open rate is in the upper third) Important Send rates must be available.
first-email-click-datetime	Datetime	The date and time at which an email was first clicked.
first-email-open-datetime	Datetime	The date and time at which an email was first opened.
first-email-send-datetime	Datetime	The date and time at which an email was sent.
most-recent-bounce-datetime	Datetime	The date and time for the most recent bounced email.
most-recent-email-click-datetime	Datetime	The date and time at which a customer most recently clicked a link or offer within an opened email.
most-recent-email-open-datetime	Datetime	The date and time at which a customer most recently opened an email.
most-recent-email-optin-datetime	Datetime	The date and time at which a customer most recently opted-in to receiving email.
most-recent-email-optout-datetime	Datetime	The date and time at which a customer most recently opted-out from receiving email.
most-recent-email-send-datetime	Datetime	The date and time at which an email was most recently sent.
region	String	The region or location from which an email was sent. The region or location is typically associated to a single brand.

Fiscal calendar

A fiscal calendar is a yearly accounting period that aligns the weeks and months in a calendar year with holidays and a brand’s marketing goals to align the business for an entire calendar year. A common fiscal calendar used by brands is the 4-5-4 fiscal calendar.

A 4-5-4 calendar divides years into months using a 4 weeks - 5 weeks - 4 weeks pattern. Each week starts on a Sunday and ends on a Saturday. Each quarter has the same number of days. A 4-5-4 calendar can be useful for comparing like days for sales reporting purposes.

Fiscal calendar semantics should be applied to data sources that contain the days, weeks, months, and holidays that define your brand’s fiscal calendar. Fiscal calendar semantics are prefixed with fiscal/ in the semantics drop-down menu in the Feed Editor.

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
calendar-date	Date	Required The standard calendar date. Important The field to which this semantic tag is applied must also be the primary key for the table.
day-of-week	String	Optional The day of the week on which this calendar date falls.
fiscal-month	String	Required The fiscal month that is associated with the calendar date.
fiscal-quarter	String	Required The fiscal quarter that is associated with the calendar date.
fiscal-week-number	Integer	Required The week within the fiscal year on which the calendar date falls. This field indicates on which month a fiscal year starts.
fiscal-week-start	Date	Required The start of the fiscal week on which the calendar date falls.
fiscal-year	Integer	Required The fiscal year that is associated with the calendar date.
holiday-sale-name	String	Optional The holiday date (or date range) into which this calendar date falls.

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.

• Blocking keys (bk)

• Customer keys (ck)

• Foreign keys (fk)

• Primary keys (pk)

• Separation keys (sk)

Blocking keys (bk)

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.

You can define custom blocking labels using bk-[label], and then use them as a blocking strategy for Stitch.

Caution

Use blocking keys carefully and be sure to verify that Stitch results contain the desired outcome.

Customer keys (ck)

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.

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

Foreign keys (fk)

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.

Amperity is configured by default to prioritize foreign key matching over separation key unmatching.

The most common use cases for foreign keys associate fields that act like primary keys within interaction records to the primary keys within customer records, such as:

• A customer identifier for transactions and itemized transactions associated to the primary key in a loyalty table.

• A strong identifier within clickstream data to the primary key in a customer profile table.

Use foreign keys to define meaningful connections across all types of data sources to enable deterministic matching of record pairs during pairwise comparison.

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.

Important

A foreign key may also be tagged as a separation key. A foreign key applies when two records have the same value for the key. A separation key applies when two records have different values for the key.

Tagging the same field as both foreign and separation keys 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.

Tip

In an unusual case where a foreign key is associated with a field to which a profile (PII) semantic tag is applied be sure to configure the column created by the foreign key in customer 360 database tables to hide values from users without permission to view PII.

Primary keys (pk)

A primary key is a column in a data table that uniquely identifies each row in a data source or data table.

Caution

Amperity allows you to assign the pk semantic tag to more than one field in the Feed Editor. This is because with some data sources, such as data that contains events – clickstream, email, web activity, mobile app activity, and so on – often contain many fields that could be used like a primary key.

A domain table can have only one primary key. When the pk semantic tag is applied to more than one field in the Feed Editor, those values are concatenated into a primary key, which is stored in the _pk field in the domain table. You should limit the number of fields to which the pk semantic tag is applied.

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.

Separation keys (sk)

Amperity is configured by default to prioritize foreign key matching over separation key unmatching. Prioritizing separation key unmatching can help prevent address overclustering problems for groups of records with similar names and similar households.

Note

To use separation keys you must configure the classifier for Stitch model selection to be set to :general-ordinal-sk-priority.

Use a separation key (sk) for deterministic unmatching of records. This prevents Stitch from matching certain types of records during pairwise comparison, which is a step in the Stitch process that scores all of the possible connections between all records in a group 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.

A record pair is assigned a non-matching score (0.0) when separation keys contain conflicting values during pairwise comparison. A record pair is split into two clusters when both pairs contain a non-NULL value.

Note

The following separation keys do not consider approximately matched values to be conflicting values:

• sk-given-name For example, Mike and Michael are not conflicting values.

• sk-birthdate For example, 1981-09-08 and 1981-08-09 are not conflicting values.

• sk-generational-suffix

Tip

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.

Loyalty programs

Loyalty programs help brands increase customer loyalty and provide incentives for customers to opt-in to email and SMS communication.

Adding this data to Amperity can help your brand understand the value of your loyalty program and run more effective campaigns based on how your customers interact with your loyalty program and your brand.

Amperity provides the following groups of semantic tags for use with loyalty programs:

• Loyalty events

• Loyalty profiles

Loyalty events

Apply loyalty events semantic tags to data sources that contain data that captures customer interactions with your brand’s loyalty program. Loyalty events semantics are prefixed with loy-event/ in the semantics drop-down menu in the Feed Editor.

Note

Loyalty events are unique by Amperity ID and event datetime when:

1. The fk-loyalty-id semantic tag is applied to the same source field as the loy-event/loyalty-id field.

2. The loy-event/email semantic tag is applied to fields that contain email addresses.

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
loyalty-id	String	Required. The unique ID for a loyalty profile. Important Apply the fk-loyalty-id foreign key to this field.
accrual-amount	Integer	The loyalty rewards amount that was accrued.
accrual-datetime	Datetime	The date and time at which loyalty rewards were accrued.
award-id	String	The unique ID for an award that is associated with a redemption or accrual event.
current-balance	Integer	The loyalty rewards balance that is associated with the current loyalty event.
current-tier	String	The loyalty tier that is associated with the current loyalty event.
email	String	The email address that is associated with a loyalty ID. Important In addition to the loy-event/email semantic tag, apply the email customer profile semantic tag to this field.
event-datetime	Datetime	Required. The date and time at which a loyalty event occurred. Note For transactions that represent accruals this value can also represent the date and time of the transaction.
event-description	String	A description of the loyalty event.
event-type	String	Required. The loyalty event type. May be one of the following values: “redemption”, “opt-out”, or “tier change”, or a custom event type.
expiration-datetime	Datetime	The date and time at which loyalty awards accrue or the loyalty tier changes.
order-datetime	Datetime	The date and time at which an order that used accrued or redeemed loyalty rewards was made.
order-id	String	The unique ID for an order that is associated with a redemption or accrual event.
previous-point-balance	Integer	The loyalty rewards balance that is associated with the previous loyalty event.
previous-tier	String	The loyalty tier that is associated with the previous loyalty event.
redemption-amount	Decimal	The loyalty rewards amount that was redeemed.
redemption-datetime	Datetime	The date and time at which loyalty rewards were redeemed.
reservation-datetime	Datetime	The date and time at which a reservation that used accrued or redeemed loyalty rewards was made.
reservation-id	String	The unique ID for a reservation that is associated with a redemption or accrual event.
tier-end-datetime	Datetime	The date and time at which the current loyalty tier ends (or ended).
tier-start-datetime	Datetime	The date and time at which the current loyalty tier starts (or started).

Loyalty profiles

Apply loyalty profile semantic tags to data sources that contain data that provides details about customers who belong to your brand’s loyalty program. Loyalty profile semantics are prefixed with loy/ in the semantics drop-down menu in the Feed Editor.

Note

Loyalty profiles are unique by Amperity ID when:

1. The fk-loyalty-id semantic tag is applied to the same source field as the loy/loyalty-id field.

2. The loy/email semantic tag is applied to fields that contain email addresses.

3. The loy/birthdate semantic tag is applied to fields that contain birthdates.

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
loyalty-id	String	Required. The unique ID for a loyalty profile. Important Apply the fk-loyalty-id foreign key to this field.
birthdate	Date	The date of birth for the customer who belongs to the loyalty profile. Important In addition to the loy/birthdate semantic tag, apply the birthdate customer profile semantic tag to this field.
current-balance	Integer	The customer’s current rewards balance.
current-balance-expiration-datetime	Datetime	The date and time at which a customer’s current rewards balance will expire.
current-tier	String	The name of the rewards tier to which a customer belongs.
current-tier-expiration-datetime	Datetime	The date and time at which a customer’s membership in their current rewards tier will end.
current-tier-start-datetime	Datetime	The date and time at which a customer’s membership in their current rewards tier started.
email	String	The email address that is associated with a loyalty ID. Important In addition to the loy/email semantic tag, apply the email customer profile semantic tag to this field.
is-opted-in	Boolean	Required. Indicates if the customer associated with the loyalty ID has given consent to being contacted by your loyalty program.
latest-opt-out-datetime	Datetime	The date and time at which a customer most recently opted out from being contacted by your loyalty program.
latest-opted-in-datetime	Datetime	Required. The date and time at which a customer most recently opted in to being contacted by your loyalty program.
latest-update-datetime	Datetime	The date and time at which the information associated with the loyalty profile was updated.
lifetime-balance	Integer	The lifetime reward balance associated with the loyalty ID.
next-tier	String	The name of the next loyalty tier to which, pending points accumulation, a customer will belong.
sign-up-channel	String	The channel through which the customer signed up for the loyalty program.
sign-up-method	String	The method used by the customer to sign-up for the loyalty program.
spend-to-keep-tier	Decimal	The amount of money a customer must spend to stay in their current loyalty tier.
spend-to-next-tier	Decimal	The amount of money a customer must spend to move to the next loyalty tier.

Opt-in preferences

Semantic tags for opt-in preferences capture your customer’s opt-in status. Use them to determine when and how your brand can use email and SMS to communicate with your customers.

1. Use email opt-in semantic tags for data sources that contain your customer’s opt-in preferences, the programs they have opted-in to, and their preferences for how your brand should communicate with them using their email address.

2. Use SMS opt-in semantic tags for data sources that contain your customer’s opt-in preferences, the programs they have opted-in to, and their preferences for how your brand should communicate with them using their phone number.

Email opt-in status

Apply email opt-in status semantic tags to data sources that contain data that indicates when customers have given their consent to your brand for using their email address as part of your marketing campaign. Email opt-in status semantics are prefixed with email-opt/ in the semantics drop-down menu in the Feed Editor.

Warning

Tables that contain data for email opt status should not also be tagged with foreign key or customer profile semantic tags. Only use email-opt/ semantic tags with tables that contain email opt status data. An Amperity ID will be available in the Email Opt Status table in the customer 360 database.

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
brand	String	Recommended (when your tenant has data for multiple brands). The brand to which the opt-in status applies.
email	String	Required. The email address that is associated with a customer. A customer may have more than one email address.
email-frequency	String	The preferred frequency for email messages.
email-program	String	The email program to which the customer has opted-in.
is-email-opted-in	Boolean	Required. Indicates whether a customer has given consent to being contacted by your brand using the customer’s email address. Important The field to which this semantic tag is applied must have a Boolean data type. If the data source to which you want to apply this tag is not a Boolean, use a custom domain table to shape the data into a Boolean data type, and then apply this semantic tag.
language-preference	String	The customer’s preferred language for email messages.
region	String	The region to which the opt-in status applies.

SMS opt-in status

Apply SMS opt-in status semantic tags to data sources that contain data that indicates when customers have given their consent to your brand for using their phone number as part of your marketing campaign. SMS opt-in status semantics are prefixed with sms-opt/ in the semantics drop-down menu in the Feed Editor.

Warning

Tables that contain data for email opt status should not also be tagged with foreign key or customer profile semantic tags. Only use sms-opt/ semantic tags with tables that contain SMS opt status data. An Amperity ID will be available in the SMS Opt Status table in the customer 360 database.

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
brand	String	Recommended (when your tenant has data for multiple brands). The brand to which the opt-in status applies.
is-sms-opted-in	Boolean	Required Indicates whether a customer has opted-in to being contacted by your brand using the customer’s phone number. Important The field to which this semantic tag is applied must have a Boolean data type. If the data source to which you want to apply this tag is not a Boolean, use a custom domain table to shape the data into a Boolean data type, and then apply this semantic tag.
language-preference	String	The customer’s preferred language for SMS messages.
phone	String	Required The phone number that is associated with a customer. A customer may have more than one phone number.
region	String	The region to which the opt-in status applies.
sms-frequency	String	The preferred frequency for SMS communications.
sms-program	String	The SMS program to which the customer has opted-in.

Product catalog

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 predictive modeling.

Tip

You may choose to apply product catalog semantic tags directly to data sources that contain itemized transaction data using a txn-item/ as the prefix instead of pc/.

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 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 definition before applying semantic tags to fields with product IDs to ensure they accurately reflect the customer’s definition and meet the requirements for 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.

Profile (PII)

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 a customer, such as “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 a customer, such as “Apt #9”.
birthdate	Date	The date of birth that is associated with a customer. 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 a customer.
company	String	The company, typically an employer or small business, that is associated with a customer.
country	String	The country that is associated with the location of a customer. 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 a customer. A customer may have more than one email address.
full-name	String	A combination of given name (first name) and surname (last name) for a customer. May include a middle name or initial.
gender	String	The gender that is associated with a customer. 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) X NONBINARY (is normalized to X) NON-BINARY (is normalized to X) ENBY (is normalized to X) NB (is normalized to X) OTHER (is normalized to X)
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 a customer. Caution The given-name semantic tag may only be applied once per feed.
phone	String	The phone number that is associated with a customer. A customer may have more than one phone number. 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 a customer. 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 a customer.
surname	String	The last name that is associated with a customer. 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 a customer, such as “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 in the source system. 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.

Stitch labels

Stitch labels identify when a single customer record was incorrectly merged together (overclustered) or when two customer records were incorrectly split apart (underclustered).

The following table describes recommended patterns to use when defining semantic tags for Stitch labels.

Stitch Labels Semantic Pattern	Description
sl/datasource	Apply this semantic tag to the datasource column.
sl/label-id	Apply this semantic tag to the label_id column.
sl/partition-id	Apply this semantic tag to the partition_id column.
sl/semantic	Apply this semantic tag to columns that are associated with the matching value, for example to a column that matches the email semantic tag.
sl/value	Apply this semantic tag to the value column.

Subscriber status

Subscriber status – whether a customer has opted-in or opted-out to receiving communication – can be difficult to track when it is not consolidated into a single table within your customer 360 database. Use subscriber status semantic tags to consolidate email and/or phone subscriber status information into a single table.

The following semantic tags consolidate your customers’ email and phone subscriber status:

• Email

• Phone (SMS)

Email

Use email subscriber status semantic tags to consolidate opt-in and opt-out data for email addresses into a single table. Email semantics are prefixed with email-opt/ in the semantics drop-down menu in the Feed Editor.

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
brand	String	The brand or company from which an email was sent.
email	String	Required The email address to which a marketing may (or may not) be sent.
is-email-opted-in	Boolean	Required Indicates if the customer associated with an email address has opted-in or opted-out to receiving email from your brand. Note You may need to use a custom domain table to ensure that the field that returns your customers email opt status is a Boolean field. Apply this semantic tag to the field in the custom domain table.
region	String	The region or location from which an email was sent. The region or location is typically associated to a single brand.

Phone (SMS)

Use phone (SMS) subscriber status semantic tags to consolidate opt-in and opt-out data for phone numbers into a single table. Phone (SMS) semantics are prefixed with sms-opt/ in the semantics drop-down menu in the Feed Editor.

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
brand	String	The brand or company from which an email was sent.
is-sms-opted-in	Boolean	Required Indicates if the customer associated with a phone number has opted-in or opted-out to receiving messages from your brand. Note You may need to use a custom domain table to ensure that the field that returns your customers phone opt status is a Boolean field. Apply this semantic tag to the field in the custom domain table.
phone	String	Required The phone number to which a marketing may (or may not) be sent.
region	String	The region or location from which an email was sent. The region or location is typically associated to a single brand.

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 records for individual items in a transaction. Itemized transaction semantics may applied alongside other semantics, depending on the 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 rows of 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 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: The total amount per order appears as the same amount on each row. The pro-rated amount per line item appears as either a different amount or 0 per row. 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.