Transaction Cards
  • 01 Feb 2023
  • 10 Minutes To Read
  • PDF

Transaction Cards

  • PDF

Transactions represent a variable list of activities pertaining to the Customer (e.g., orders, hotel stays). As mentioned in the Auto-linking, Basic Search, and Detailed Lookup guide, transactions are an Array of transaction objects to be sent back in response to a Detailed Lookup request. These are presented as cards on the left side of the Customer Profile.

This guide gives detailed information on transactions and their use.

Overview

Implement multiple types of Transaction Cards to ingest and display Customer data. This also allows you to implement as many Transaction Cards as you need. Suppose you have five Shopify stores; you can display Customer transaction data from each Shopify store in their own unique Transaction ORDER Card. 

You can also have different Transaction Cards. For example, a hotel business can have an ORDER card for their merchandise Shopify store and a STAY card to display hotel reservations. 

Choose a Transaction type

The choice of transaction type dictates how Gladly displays the data.

Note - Transactions and the Customer API

You cannot set or retrieve transactions via the GET Customer or PATCH Customer APIs. Transactions can only be set through a response to a Detailed Lookup request.

Supported Transaction Types

  • ORDER: Orders
  • FLIGHT: Flights
  • STAY: Hotel stays
  • SUBSCRIPTION: Subscriptions
  • GENERIC: All other transactions

Transaction Card label

Each Transaction Type has a default card label displayed to the Agent on Gladly: 

  • ORDER: Orders
  • FLIGHT: Reservations
  • STAY: Stays
  • SUBSCRIPTION: Subscriptions
  • GENERIC: Transaction

By default, the label for each card reflects the number of records associated with each type. For example, if a Customer has 8 orders, the ORDER card label will say 8 Orders. If the Customer has one three-night reservation, the STAY card label will say 1 Stay

You may choose to change the card label to something that makes sense to your business (e.g., the name of your e-store brand). If you choose to customize the card label, it will no longer show the number of records for the card.

Availability

ORDER cards will appear automatically in the Customer Profile without Professional Services assistance when e-commerce apps like Shopify or BigCommerce are added through the Apps page. Other Transaction Types require Professional Services assistance for configuration before the card can appear in Gladly. Any additional customization beyond the first ORDER card also requires Professional Services assistance.

Visibility

Transaction Cards are not visible in the Customer Profile unless there's transaction data. For example, the ORDER Transaction Card will not be visible on a Customer's Profile if the Customer has no orders.

Use of custom Lookup Adaptors with Transaction Cards

Apps added through Gladly have default values to look up Customer data to display in Gladly. If you build a custom Lookup Adaptor to allow you to pull additional Customer data to Gladly not readily available with our integrated apps, make sure your Lookup Adaptor is passing the correct attributes to Gladly. Only then can our Professional Services team configure which card the attribute appears.

Multiple Transaction Cards

There's no additional action required if you only use one Transaction Type. For example, just one ORDER card for a single Shopify instance. To have multiple cards requires additional review:

  • If using a custom Lookup Adaptor, you must make sure the Lookup Adaptor is passing the correct attributes back to Gladly. You'll need to pass a transaction attribute that helps distinguish what data should be displayed in each card (e.g., brand name, geography, etc.). Work with Gladly Professional Services to add additional cards beyond the first. They can ensure the cards are pulling data from the correct instance and show in the correct card.
  • If you already have an out-of-the-box app in Gladly (e.g., Shopify) and you add another out-of-the-box app (e.g., another Shopify store), the transactions from both apps will be displayed on the same transaction card. If it makes sense for your business, work with Gladly Professional Services to add another Transaction Card for the newest app you've added in Gladly.

Transaction Attributes

Each transaction is an object within an array and can be extended to have its own set of single-level key value pairs.

An exception is made for ORDER type transactions that support an Array of product objects as documented below.

ORDER Transactions

Each ORDER type transaction object uses the following default structure and template. 

Tip - Displaying custom order attributes beyond the default ORDER template
Each order and product object may be extended with additional one-level deep custom attributes to show to your Agents. If you're interested in configuring more custom attributes at the order or product level, let Gladly Support know.
Tip - Setup WISMO on Sidekick
WISMO (Where Is My Order) can be set up on Sidekick to showcase the latest order status and tracking information to Customers. Learn more about WISMO and its many benefits here!

Agent View

When first displayed, orders are collapsed. Agents can manually expand each Order by clicking on it.

This is how the reserved keys map to the layout:

Customer View (WISMO on Sidekick)

If you've enabled WISMO on Sidekick, Customers will see the following in Sidekick for their latest order when interacting with it:

Hover over clipped text

Hover over to view clipped text.

Order Object Structure

If any of the reserved fields below are not sent as part of your Detailed Lookup response, the spaces for them will be left blank.

{
  "type": "ORDER",
  "createdAt": "2020-08-01T12:00:00.000Z",
  "orderNumber": "1832",
  "itemCount": 5,
  "customerOrderUrl": "https://retail.com/edit/order/1832",
  "status": "Completed",
  "orderLink": "https://retail.com/admin/orders/1832",
  "orderTotal": "$50",
  "note": "This order is a gift purchase with an extended returns window.",
  "orderStatus": "Completed",
  "fulfillments": [
    {
      "productIds": ["12345", "54321"],
      "estimatedDeliveryDate": "2020-08-10T12:00:00.000Z",
      "trackingUrl": "http://track.dhl-usa.com/TrackByNbr.asp?ShipmentNumber=00064735172",
      "trackingNumber": "00064735172",
      "status": "delivered"
    }
  ],
  "products": [
    {
      "id": "12345",
      "name": "Socks",
      "status": "fulfilled",
      "productId": "alphanumeric values",
      "sku": "alphanumeric values",
      "imageUrl": "https://www.image.com/1"
    },
    {
      "id": "54321",
      "name": "Scarf",
      "status": "fulfilled",
      "sku": "alphanumeric values",
      "imageUrl": "https://www.image.com/2"
    }
  ]
}

Attribute NameTypeRequiredVisible ToNotes
typestringYesN/A - internal Gladly identifierMust be ORDER.
createdAtdateNoAgentThe date order was created.

For WISMO, this field is used to find the latest order to display information for. If it is not included for any orders, then the first order in the list of orders will display. 
orderNumberstringYes for WISMOAgent and Customer (via WISMO on Sidekick)The order number and a unique identifier for the order.
statusstringNoAgentOrder status.
orderLinkurlNoAgentURL for the order in your OMS for Agents to view/edit.
orderTotalstringNoAgent and Customer (via WISMO on Sidekick)Amount formatted with the currency symbol
currencyCodeenumNoAgent and Customer (via WISMO on Sidekick)Currency code for the order total, following https://en.wikipedia.org/wiki/ISO_4217 If this is not present, currency type will be inferred from the symbol provided in orderTotal.
itemCountnumberNoCustomer (via WISMO on Sidekick)Number of items in the order. This is the only field that should be sent over as an integer vs. a string. 
customerOrderUrlurlNoCustomer (via WISMO on Sidekick)Customer-facing URL displayed in Sidekick when WISMO is enabled.
notestringNoAgentOrder note
products[]ProductNoAgent

First imageUrl shown to Customer via WISMO on Sidekick if fulfillments[] is populated and this is the most recent order.
List of products in the order.
fulfillments[]FulfillmentNo - but highly recommended for WISMOAgent and Customer (via WISMO on Sidekick)List of fulfillments associated with the order. 

[]Product Structure (nested within order)

The products Array is optional:

  1. For Agents, products will display underneath order information if the Array is included as part of the DETAILED lookup response
  2. For Customers, the first product's imageUrl of the latest order (sorted by createdAt descending) will be displayed on Sidekick if WISMO is enabled. However, please note that the imageUrl and products Array are not required for WISMO to function!

Any additional attributes you send in each product object in the products array will display under the product status so long as Gladly has allowed them to be displayed.

Attribute NameTypeRequiredVisible ToNotes
namestringNoAgentName of product displayed to Agent.
idstringYesAgentProduct ID.
statusstringNoAgentStatus of line item.
skustringNoAgentSKU ID of line item displayed to Agent.
imageUrlurlNoAgent
  • Image URL of product displayed to Agent. Must be in HTTPS format.
  • For Customer, will display the first imageUrl in the products Array for this order if it is the latest order (via WISMO on Sidekick) - regardless of what is in fulfillments[n].productIds.

[]Fulfillment Structure (nested within order)

  1. For Agents, Gladly will display all fulfillment objects connected to orders returned underneath each order
  2. For Customers, Gladly will display the first 3 fulfillment objects connected to the latest order only if WISMO is enabled on Sidekick and the Customer interacts with WISMO. Although fulfillments is not required for WISMO to function, it is highly recommended to include at least the trackingNumber and trackingUrl to provide customers with helpful information. That is, an order will still display (e.g., orderNumber, orderTotal) on Sidekick so long as it's the latest order, even without fulfillments[] information. 

The fulfillments array does not currently allow for any additional custom attributes to be displayed to either the Agent or Customer.

Attribute NameTypeRequiredVisible ToNotes
estimatedDeliveryDatedateNoAgent and CustomerEstimated delivery date of shipment.
productIdsarray of StringsNoAgent (for full list of products in shipment)List of product IDs in this shipment. Product IDs must correspond to the id in the products Array for this order object.
trackingUrlurlNoAgent and CustomerShipment tracking URL (e.g., to DHL).
trackingNumberstringNoAgent
  • Tracking number.
  • For Customer, this will only display if the trackingUrl is also supplied.
statusstring NoAgent and CustomerCurrent status of fulfillment shipment.

FLIGHT Transactions

When first displayed, flights are collapsed.

Each flight can be manually expanded by an Agent.

To accomplish this, each FLIGHT type transaction object uses the following structure. You can extend each transaction object further with more attributes, though you will need to engage with Professional Services to configure them to display in the Gladly Customer Profile.

If any of the below reserved fields are not sent as part of your Detailed Lookup response, the spaces for them will be left blank.

Text
Text
Text
Text
{
  "departureTime": "2017-04-01T08:00:00",
  "destination": "SFO",
  "flightNumber": "12345",
  "origin": "SEA",
  "pnrCode": "A12345",
  "status": "ON TIME",
  "type": "FLIGHT"
}

This is how the above reserved keys map to the layout:
flight_expanded_mapping.png

STAY Transactions

When first displayed, stays are collapsed.

Any stay that is current or in the future is grouped in the Current & Future panel. 

An Agent can manually expand each stay. Agents can also hover over each stay to view their image address and neighborhood

Current Stay

Other stays are in the Previous panel.

Tooltip

View clipped stay details.

stay_hover.png

To accomplish this, each STAY type transaction object uses the following structure. You can extend each product or transaction object further with more attributes, though you will need to engage with Professional Services to configure them to display in the Gladly Customer Profile. 

If any of the below reserved fields are not sent as part of your Detailed Lookup response, the spaces for them will be left blank.

Text
Text
Text
Text
{
    "type": "STAY",
    "checkInTime": "2021-01-01T00:00:00.000Z",
    "checkOutTime": "2021-10-01T00:00:00.000Z",
    "timezone": "Pacific Standard Time",
    "url": "https://www.gladly.com",
    "title": "Reservation 1",
    "address": "San Francisco",
    "neighborhood": "Financial District"
  }

This is how the above reserved keys map to the layout:
stay_mapping.png

SUBSCRIPTION Transactions

When first displayed, subscription transactions are collapsed:

Agents can expand each transaction to see details such as Status, Billing Frequency, Product, and more. The most recent canceled transaction will be at the top of the list if there are multiple canceled transactions.

Agents are also now empowered to update Customer subscriptions. When they hover over Product, they can see an associated image. Agents can also cancel active subscriptions and reactivate canceled subscriptions.

To accomplish this, each SUBSCRIPTION type transaction object uses the following structure. You may extend each product or transaction object further with more attributes, though you will need to engage with Professional Services to configure them to display in the Gladly Customer Profile.

If any of the below reserved fields are not sent as part of your Detailed Lookup response, the spaces for them will be left blank.

{
    "type": "SUBSCRIPTION",
    "subscriptionId": "1234567",
    "status": "Active",
    "createdAt": "2020-08-01T12:00:00.000Z",
    "updatedAt": "2020-08-01T12:00:00.000Z",
    "billingIntervalUnit": "day", //one of: day, week, month, quarter, or year
    "billingIntervalNumber": "4",
    "nextBillingAt": "2020-08-01T12:00:00.000Z",
    "cancellationDate": "2020-08-01T12:00:00.000Z",
    "cancellationReason": "text for cancellation reason",
    "quantity": "5",
    "price": "$10",
    "products": [
        {
          "name": "Shoes",
  	      "productId": "12345",
  	      "sku": "54321",
  	      "imageUrl": "https://www.image.com/1"
        }
      ]
}

Note - Billing Fields
While billingIntervalUnit and billingIntervalNumber both exist as individual fields, if both are present and valid, they are combined into billingFrequency. 
This is how the above reserved keys map to the layout:
Attribute NameTypeRequired
typeSet this to static String "SUBSCRIPTION" Yes
subscriptionIdStringYes
statusOne of String:
Active
Cancelled
Expired
Future
In Trial
Non-Renewing
Paused
Yes
createdAtDateNo
updatedAtDateNo
billingIntervalUnitOne of String:
day
week
month
quarter
year
No - if you'd like to display this information, you must also send billingIntervalNumber

Once you populate this information, you'll also need to ask the Gladly Support team to display an attribute called billingFrequency (with label name Billing Frequency) in your Subscriptions transactions panel.
billingIntervalNumberString containing an integer (e..g: "4" and NOT 4)No - if you'd like to display this information, you must also send billignIntervalUnit
nextBillingAtDateNo
cancellationDateDateNo
cancellationReasonStringNo
quantityString containing an integerNo
priceStringNo
productsArrayNo

Product (nested within Subscription)

Attribute NameTypeRequired
namestringNo
productIdstringNo
skustringNo
imageUrlimage URL for product in subscriptionNo

GENERIC Transactions

Generic transactions display as boxes that cannot be expanded or collapsed, like such:
generic.png

To accomplish this, each GENERIC type transaction object uses the following structure. You may extend each product or transaction object further with more attributes, though you will need to engage with Professional Services to configure them to display in the Gladly Customer Profile. If any of the below reserved fields are not sent as part of your Detailed Lookup response, the spaces for them will be left blank.

Text
Text
Text
Text
{
  "type": "GENERIC"
  ....
}

Any additional attributes you send in each GENERIC type object will display in the box so long as Gladly has allowed them to be displayed. For example, in the screenshot above, the transactions array looks like this:

Text
Text
Text
Text
[{
  "type": "GENERIC"
  "name": "RES 1"
}, {
  "type": "GENERIC"
  "name": "RES 2"
}]

Was this article helpful?

What's Next