You can use the Alert API to create receipts for items customers have
purchased or returned. After creating a receipt with the Alert API, the receipt is added to the customer’s wallet. Up to 100 of the customer’s most recent receipts for purchases are displayed in their wallet, along with any
corresponding receipts for returns.
If you have created an Alert Loyalty program in Alert CMS, you can also award or subtract loyalty points based on customers’ purchases or returns.
You do not need an Alert Loyalty program to use the Receipts API.
You can send receipts to Alert for the following customers:
• Customers who are currently using your app.
• Customers who have an authentication account with you, but are not using your Alert-based app. If these customers later start to use your Alert-based app and their authentication accounts are linked to their Alert accounts, they will be able to view all receipts you created for them along with the loyalty points they have accumulated.
The workflow below describes how you can use the Receipts API to create receipts for a customer’s purchases and returns. The workflow also describes how a customer’s transactions affect her loyalty points, if applicable.
1 Determine how much of the customer’s payment can be converted into loyalty points.
2 Create a receipt using the purchase’s transaction ID and the amount of the customer’s payment that can be converted into loyalty points.
The receipt is added to the customer’s wallet and the loyalty points from the purchase are displayed as pending points. After the return period has passed, points from this purchase are added to the customer’s loyalty points.
The Alert Loyalty program based on purchases behaves differently from a social loyalty program, where points are immediately added to a customer’s account after she completes an activity.
3 If the customer returns an item, create a new receipt with the same transaction ID as the receipt with the original purchase.
Customers can make multiple returns, so there may be multiple receipts with the same transaction ID. However, receipts for purchasing items should have unique transaction IDs.
If the item is returned within the return period, the points previously awarded for buying the item are subtracted from the customer’s pending points.
For examples of a receipt for purchased items and a receipt for returned items, see Receipt examples, page 160.
To create a receipt, you must use an HTTP POST request to send the content of the receipt to the Alert Platform. The request includes a URL format and a JSON object, described below.
Prerequisite
• Your application must use an existing Alert administration session token, or create a new one. For the request format to obtain a session token, see Obtaining an Alert administration session token, page 105.
Request format for creating receipts The format of the request URL is described below.
• To create a single receipt, use the following URL format:
Request type: POST
HTTP Header: Content-Type:application/json https://api.alert.com/admin/receipt/create?
token=admin_session_token
• To create multiple receipts, use the following URL format:
Request type: POST
HTTP Header: Content-Type:application/json https://api.alert.com/admin/receipts/create?
token=admin_session_token
where admin_session_token is the Alert administration session token.
© 2014 MicroStrategy, Inc. Creating and managing receipts: Receipts API 151 If you are creating a single receipt, the request body must contain a JSON object with the contents of the receipt. If you are creating multiple receipts, the request body must contain a JSON array of receipt objects.
It is recommended that you send a maximum of 100 receipt objects in a single request.The structure of the receipt object is shown below, with required name/value pairs displayed in bold:
{
"order_detail": [ //array of items in the order { //item 1
"card_number": string,
"amount": double,
"change": double },
"payments": [ //array of payment objects { //payment object 1
...
}, ...
{ //payment object n ...
} ] }
Depending on whether the receipt is for purchased items or returned items, certain name/value pairs will change signs. For a list of which name/value pairs are positive or negative, see Positive and negative name/value pairs in the receipt JSON, page 157.
Depending on your business rules, the values for certain name/value pairs, such as total_price, may be calculated from other name/value pairs. For a list of name/value pairs that are commonly calculated from other name/
value pairs, recommended formulas, and example JSON, see Calculating name/value pairs in the receipt object, page 158.
© 2014 MicroStrategy, Inc. Creating and managing receipts: Receipts API 153 The name/value pairs used in the receipt JSON object are described in the table below.
If you do not send optional name/value pairs or if the value is null, the name/value pair is not displayed in your Alert app.
Name Data type Required / Optional Description
auid integer Required. Note that
only one of auid, customer_id, or member_id is permitted.
If the customer does not use your Alert app, only
customer_id is permitted.
The customer’s Alert user ID.
customer_id integer The customer’s authentication account ID
in your customer database. If you have not linked your customers’ authentication accounts with their Alert accounts, a new Alert account is created.
For information on linking customers’
authentication accounts with their Alert accounts, refer to Chapter 4, The Alert Partner API.
member_id integer If the customer has a loyalty membership
with you that is linked to their Alert account, the customer’s membership ID.
For information on linking customers’
loyalty memberships with their Alert accounts, refer to Chapter 4, The Alert Partner API.
transaction_id string Required The transaction ID, as entered in your data warehouse.
• If the receipt is for purchased items, it should have a unique transaction ID.
• If the receipt is for returned items, it must have the same transaction ID as the receipt for purchased items.
order_type string Required The type of the order. The permissible values are:
• ONLINE: Indicates that the purchase was made online.
• STORE: Indicates that the purchase was made in a store.
• PHONE: Indicates that the purchase was made over the phone.
order_timestamp integer Required The date and time of the order, formatted as a UNIX timestamp.
To obtain a UNIX timestamp for a date, you must convert the date to UTC, then calculate the number of seconds that have elapsed between 00:00:00 UTC 1/1/1970 and the date. For example, the UNIX timestamp for midnight UTC on December 10, 2010 is 1291939200.
order_detail array Required An array of items in the order. Each item is a JSON object, which includes information such as color and size.
This array must contain at least one item.
The structure of the item objects is described in The order_detail array, page 155.
shop_id string Optional The ID of the store location where the purchase was made.
The ID of the store location is the ID stored in your database. For information on adding store locations to the Alert Platform, see Creating and managing your store locations: Store Location API, page 107.
source integer Optional Indicates where the purchase was made.
The permissible values are:
• 1: Indicates that the purchase was made in a physical store.
• 2: Indicates that the purchase was made using the Shop tab in the Alert mobile app.
• 3: Indicates that the purchase was made online, through a web browser.
discount double Optional The discount applied to the transaction’s sub-total. For receipts with returned items, the value is positive. The value is negative otherwise. For example, if purchases that total over $100 receive a $20 discount, the value is -20.
The value is independent of the value for discount for individual items in the order_detail array.
sub_total double Required The sub-total for the transaction. The sub-total is typically the sum of all amount values in the order_detail array.
amount_for_points double Optional The total amount of money spent in this transaction that is eligible for loyalty points.
For example, if a customer has bought a product worth $150, $100 of which is available for loyalty points, the value of amount_for_points is 100.
If the receipt is for returned items, amount_
for_points is negative.
If you have not created a purchase-based loyalty program in Alert, this field is not Name Data type Required / Optional Description
© 2014 MicroStrategy, Inc. Creating and managing receipts: Receipts API 155
The order_detail array
The order_detail array contains the JSON objects for each item in the purchase. The name/value pairs for the item object are described in the table below.
tax double Optional The tax amount for the purchase, if
applicable.
shipping_fee double Optional The amount charged for shipping the order, if applicable.
shipping_method string Optional The shipping method, if applicable.
total_price double Required The total price for the transaction, after discount, taxes, and shipping fees are added.
payment object Optional. Note that
only one of payment or payments is permitted.
The payment details for the transaction, such as payment method. The structure of the payment object is described in The payment object, page 156.
payments array An array of payment objects. Use this
when a customer pays for their purchase with a combination of payment methods.
For example, a customer may use a $30 gift card and $20 cash to buy a $50 item.
The structure of the payment object is described in The payment object, page 156.
Name Data type Required / Optional Description
Name Data type Required / Optional Description
variation_id string Required The item ID, as stored in your product database.
description string Optional The item name, or a description of the item.
image string Optional The URL for an image of the item.
color string Optional The color of the item.
size string Optional The size of the item.
unit_price double Required The price of the item. The value is always positive or 0.
quantity double Required The quantity of items. For purchased items, the value is positive. For returned items, the value is negative.
The payment object
The payment object contains the payment information for the transaction. It is not displayed in the Alert app.
discount double Optional The discount applied to an item. If the receipt is for returned items, the value is positive.
Otherwise, it is negative. For example, if a customer buys a $20 shirt with a $2 discount, the value is -2.
The value is independent of the value for discount in the root level of the receipt object, outside the order_detail array.
amount double Required The net amount charged for the item. For example, the total cost of the items bought plus the discount.
Name Data type Required / Optional Description
Name Data type Required / Optional Description
payment_type string Required The payment method, with a maximum length of 20 characters.
You can choose how you describe the payment method. Some examples are as follows:
• CASH: Indicates that the purchase was made with cash.
• CREDIT: Indicates that the purchase was made with a credit card.
• DEBIT: Indicates that the purchase was made with a debit card.
• STORE CREDIT: Indicates that the purchase was made with store credit.
• GIFT CARD: Indicates that the purchase was made with a gift card
card_holder string Optional The name of the card holder.
This name/value pair is not applicable for cash transactions.
card_number string Optional The card number, with a maximum length of 20 characters.
This name/value pair is not applicable for cash transactions.
amount double Optional The amount paid using this payment method. If the receipt is for returned items, the value is negative.
change double Optional The change given back to the customer.
© 2014 MicroStrategy, Inc. Creating and managing receipts: Receipts API 157
Positive and negative name/value pairs in the receipt JSON Certain name/value pairs in the receipt JSON object are positive or negative depending on whether the receipt is for purchased or returned items. The change in signs allows you to use the same formulas when calculating the values of certain name/value pairs, such as total_price. For calculation guidelines, see Calculating name/value pairs in the receipt object, page 158.
The table below summarizes the key differences between receipts for purchased items and receipts for returned items, based on the name/value pairs in the receipt JSON.
A receipt may contain either purchased items or returned items, but not both. For receipts that contain returned items, the transaction ID is the same as the receipt with the original purchase. However,
receipts with purchased items should have unique transaction IDs.
Of the name/value pairs listed above, only unit_price does not change sign. The value for unit_price is always positive.
Name Value for purchases Value for returns
unit_price positive positive
quantity positive negative
amount
(in order_detail array)
positive negative
tax positive negative
shipping_fee positive 0
(The customer pays a third-party carrier to ship their returned items or you cover the cost of shipping.)
discount negative positive
sub_total positive negative
total_price positive negative
amount_for_points positive negative
amount
(in payment object)
positive negative
change negative 0
(Customers returning items are typically refunded with exact change.)
Depending on the transaction, the value of any of the name/value pairs listed above, except quantity, may be 0.
The name/value pairs are described in more detail in Request format for creating receipts, page 150.
Calculating name/value pairs in the receipt object
Some of the name/value pairs in the receipt object may be calculated from other name/value pairs. For example, total_price is generally the sum of sub_total, discount, tax, and shipping_fee.
In general, your calculations should only involve adding and/or multiplying name/value pairs. Any subtraction is taken into account by the sign of the name/value pair. For example, if you are calculating the result of taking a
$20 discount off a purchase sub-total of $100, the value of sub_total is 100 while the value of discount is -20. The calculation is then sub_total + discount, or 100 + (-20).
For a list of which name/value pairs are positive or negative depending on whether the receipt is for purchased or returned items, see Positive and negative name/value pairs in the receipt JSON, page 157.
Name/value pairs that are calculated from other name/value pairs are listed below, along with recommended formulas used to define their value.
Depending on your business rules, your formulas may differ.
• amount (in the order_detail array): The value is typically the total cost of items, quantity * unit_price, plus discount in the order_
detail array.
• sub_total: The value is typically the sum of all amount values in the order_detail array.
• tax: The value depends on your state laws. Generally, if tax is applied, the value is a certain percent (sales tax percentage) of the sum of sub_
total, discount, and shipping_fee.
• total_price: The value is typically the sum of sub_total, discount, tax, and shipping_fee.
For example JSON that follows the positive/negative sign requirements in Positive and negative name/value pairs in the receipt JSON, page 157 and the calculation guidelines above, see Receipt examples, page 160.
© 2014 MicroStrategy, Inc. Creating and managing receipts: Receipts API 159
Response format for creating receipts
Once the request is processed by the Alert Platform, a JSON response object is sent, in the following format:
{
The following table describes the name/value pairs in the response JSON object.
Error objects in the failed array
The failed array is an array of error objects containing the transaction IDs for receipts that could not be sent, and details about the error. The structure of the error objects is shown below:
{
Name Data type Description
error object Contains details of global errors, such as application errors or database errors.
type string The type of error. If no errors were encountered, the value is none.
code integer The error code. The possible values are as follows:
• 0: No errors were encountered.
• 202: The request body is not formatted as a JSON object.
• 611: One or more of the name/value pairs in the request body is an incorrect type, e.g. order_timestamp is a string with a double value instead of an integer.
• 621: A system error occurred.
response object Contains the status of the operation.
failed array An array of error objects, containing transaction IDs for any receipts that could not be created. If all receipts were successfully created, an empty array is sent. The structure of the error objects is described in Error objects in the failed array, page 159.
imported integer The number of receipts that were successfully imported into the Alert Platform.
"transaction_id": string,
"code": integer,
"type": string,
"inner_error": string }
The name/value pairs in the error object are described in the table below.
Receipt examples
The sections below include examples of the receipt JSON for purchased items and returned items. These examples are created according to the positive/negative sign requirements in Positive and negative name/value pairs in the receipt JSON, page 157 and calculation guidelines for name/
value pairs described in Calculating name/value pairs in the receipt object, page 158.
Name Data type Description
transaction_id string The transaction ID.
code integer The error code. The possible values are as follows:
1 619: The receipt is invalid, for one or more of the following reasons:
• The payment type (payment_type) of the credit or debit card number (card_number) is longer than 20 characters.
• The store location ID is invalid.
• The receipt contains a mix of purchases and returns. Receipts must contain either all purchases or all returns. In terms of
implementation, the values for quantity in the order_detail array should either be all positive or all negative.
• The receipt is for returned items, but the transaction ID does not match any existing receipts. Receipts for returned items must have the same transaction ID as the receipt with the original purchase.
• The receipt is for purchased items, but another receipt with the same transaction ID already exists. Receipts for purchased items must have unique transaction IDs.
• The transaction’s location (source) is not one of the permissible values. The permissible values are 1, 2, and 3. See the Request format for creating receipts, page 150.
• The receipt is for returned items, but the customer (customer_id) is different from the receipt with the original purchase.
• The receipt is for returned items (quantity < 0), but the customer is gaining loyalty points (amount_for_points > 0), or vice versa.
2 1203: A required name/value pair is missing.
type string The type of error.
inner_error string A description of the error that occurred.
© 2014 MicroStrategy, Inc. Creating and managing receipts: Receipts API 161
• Example: Receipt for purchased items, page 161
• Example: Receipt for returned items, page 164
Example: Receipt for purchased items
In this example, a customer bought four items of clothing from a store’s
In this example, a customer bought four items of clothing from a store’s