Entity Posting API - Refund

We treat refunds exactly the same as orders with negating totals as opposed to positive ones. The original order will remain in the system and we do not maintain any link between the two because from an reporting point of view, it is only important the totals are correct.

If the RefundID does not exist, a new Refund record will be created. If it does, it will be updated.

Triggered Updates:

If the refund is an update, the Ticket/Shop/Payment records which were loaded via that RefundID and SiteID will be updated

Standard ShowTimeAnalytics Message Parameters:

DataSupplierID: Assigned unique identifier for your account
String
(required)
MessageSequence: Unique sequence number incremented for each message posted
Long
(required)
CallbackUrl: Data Supplier defined URL that result of processing the message is posted back to
String
(required)

Fields for Refund Entity:

Refund Entity level fields:

ID attribute: Unique identifier for refund
String
(required)
SiteID attribute: Unique identifier for site that the refund applies to
String
(required)
IsVoid: Set to true if the refund is actually a voided transaction. Applies to all line items. If specific line items should be marked as a void, this same flag can be set at a line item level (default false)
true/false
Currency: The Currency value that defines the amount fields in each subsequent entity (default to site's currency)
ISO-4217 Code e.g. USD
TransactionTimestamp: DateTime when the refund took place
ISO-8601 datetime
(required)
CinemaDate: If POS has specific rules to set reporting date on an order, this field can be used to overwrite Showtime derived date
yyyy-mm-dd
SaleDeviceId: Unique identifier for the mechanism through which the refund was taken (link to SaleDevice entity)
Integer
SaleLocationId: Unique identifier for where the refund for the customer was completed (link to SaleLocation entity)
Integer
StaffId: The ID of the staff member who completed the refund (link to Staff entity)
String

Customers can be associated with an order in many ways. If the customer is registered in the POS system, we simply pass the ID which will be treated as the primary customer. The secondary approach is for online bookings which for customers who are not registered but we have captured their email address. If the cinema uses an external loyalty program, customers are associated with orders via the Customer Account Movement records. Optional fields

CustomerId: Unique identifier of the primary customer for the order (link to Customer entity)
String
CustomerEmail: Customer contact email address
String
CustomerName: Customer name
String
CustomerLastName: Customer last name
String
CustomerAccountId: Unique identifier of the customer account associated with this transaction (typically this will be Loyalty or Membership card number)
String
CustomerAccountType: The categorization of the customer account associated with the order
String
MarketingAcceptEmail: Indicator whether customer agreed to be contacted by email address
true/false
ThirdPartyOrderReference: Where order was placed in a 3rd party app, their ID for later cross reference
String

TicketSales: List of the tickets refunded as a part of the refund. 1 entity per ticket (min 1 ticket/shop required)
ShopSales: List of the shop items refunded as a part of the refund. There may be multiples (Quantity field) of each
item in each entity (min 1 ticket/shop required)

AdditionalFees: List of fees refunded as a part of the overall refund.
(separate from fees applied on the individual line item level)
- ID attribute: Unique identifier used for fee type (link to FeeType entity)
  String
  (required)
- Quantity: The number of fees of this type applied (default 1)
  Integer
- Type: Base categorisation for fee type
  String
- Amount: The amount of the sale price applicible to this fee
  Integer
  (required)
  - Precision attribute: The number of Integer places in the amount field
    Integer
    (required)

AdditionalTaxes: List of taxes refunded as a part of the overall refund.
(separate from taxes applied on the individual line item level)
- ID attribute: Unique identifier used for tax type (link to TaxType entity)
  String
  (required)
- Quantity: The number of taxes of this type applied (default 1)
  Integer
- Type: Base categorisation for tax type
  String
- Amount: The amount of the sale price applicible to this tax
  Integer
  (required)
  - Precision attribute: The number of Integer places in the amount field
    Integer
    (required)

Payments: List of payment types used to refund for the transaction. Can be a combination of many types

TicketSale Entity level fields:

ID attribute: Unique identifier for ticket line item in the refund
String
(required)
TicketTypeId: Unique identifier used for categorizing the type of ticket refunded (link to TicketType entity)
String
(required)
PerformanceId: Unique identifier for the performance for which the type of ticket refunded (link to Performance entity)
String
(required)
Quantity: The number of tickets of this ticket type purchased (default 1)
Integer
SalePrice: Amount actually refunded to the customer for the ticket
Integer
(required)
NOTE: This should include all Taxes and Discounts applicable to this ticket line item but NOT Fees
- Precision attribute: The number of Integer places in the RefundAmount field
  Integer
  (required)
SalePriceDrp: If POS has specific rules to set Distributor Reported Price (DRP) on an order, this field can be used to overwrite Showtime derived value
Integer
- Precision attribute: The number of Integer places in the SalePriceDrp field
  Integer
  (required)
SeatRow: SeatRow and SeatNum uniquely identify the chosen seat for the ticket refunded
String
SeatNum: SeatRow and SeatNum uniquely identify the chosen seat for the ticket refunded
String
SeatType: Base categorisation for type of seat selected
String

Taxes: List of taxes applied in the calculation of the amount of the ticket refunded
- ID attribute: Unique identifier used for tax type (link to TaxType entity)
  String
  (required)
- Quantity: The number of taxes of this type applied (default 1)
  Integer
- Type: Base categorisation for tax type
  String
- Amount: The amount of the redunded amount applicible to this tax
  Integer
  (required)
  - Precision attribute: The number of decimal places in the amount field
    Integer
    (required)

Fees: List of fees refunded with the refunded ticket.
(separate from fees applied at the overall refund level)

NOTE: These Fees are NOT included in the calculation of the SalePrice of the ticket
- ID attribute: Unique identifier used for fee type (link to FeeType entity)
  String
  (required)
- Quantity: The number of fees of this type applied (default 1)
  Integer
- Type: Base categorisation for fee type
  String
- Amount: The amount of the redunded amount applicible to this fee
  Integer
  (required)
  - Precision attribute: The number of decimal places in the amount field
    Integer
    (required)
- Taxes: Option to break out the taxes applicable to the fee being applied

Discounts: List of discounts reversed in the calculation of the amount of the ticket refunded
- ID attribute: Unique identifier used for discount type (link to DiscountType entity)
  String
  (required)
  NOTE can be empty, default to generic arbitary discount. Loyalty redeemed is treated as a discount applied.
- Quantity: The number of discounts of this type applied (default 1)
  Integer
- Type: Base categorisation for discount type
  String
- Amount: The amount the redunded amount reversed by this discount
  Integer
  (required)
  - Precision attribute: The number of decimal places in the amount field
    Integer
    (required)

ShopSale Entity level fields:

ID attribute: Unique identifier for shop line item in the refund
String
(required)
StockId: Unique identifier for the stock item being refunded (link to StockItem entity)
String
(required)
Quantity: The number of this stock item being refunded
Integer
(required)
- Precision attribute: The number of Integer places in the Quantity field
  Integer
Cost: Amount the item(s) being refudnded actually cost site to buy in
Integer
(required)
- Precision attribute: The number of decimal places in the Cost field
  Integer
  (required)
SalePrice: Amount actually refunded to the customer for the item(s)
Integer
(required)
NOTE: This should include all Taxes and Discounts applicable to this shop sale line item but NOT Fees
- Precision attribute: The number of decimal places in the SalePrice field
  Integer
  (required)

Taxes: List of taxes applied in the calculation of the amount of the item(s) refunded
- ID attribute: Unique identifier used for tax type (link to TaxType entity)
  String
  (required)
- Quantity: The number of taxes of this type applied (default 1)
  Integer
- Type: Base categorisation for tax type
  String
- Amount: The amount of the redunded amount applicible to this tax
  Integer
  (required)
  - Precision attribute: The number of decimal places in the amount field
    Integer
    (required)

Fees: List of fees refunded with the refunded shop line item(s).
(separate from fees applied at the overall refund level)

NOTE: These Fees are NOT included in the calculation of the SalePrice of the item(s)
- ID attribute: Unique identifier used for fee type (link to FeeType entity)
  String
  (required)
- Quantity: The number of fees of this type applied (default 1)
  Integer
- Type: Base categorisation for fee type
  String
- Amount: The amount of the redunded amount applicible to this fee
  Integer
  (required)
  - Precision attribute: The number of decimal places in the amount field
    Integer
    (required)

Discounts: List of discounts reversed in the calculation of the amount of the item(s) refunded
- ID attribute: Unique identifier used for discount type (link to DiscountType entity)
  String
  (required)
  NOTE can be empty, default to generic arbitary discount. Loyalty redeemed is treated as a discount applied.
- Quantity: The number of discounts of this type applied (default 1)
  Integer
- Type: Base categorisation for discount type
  String
- Amount: The amount the redunded amount reversed by this discount
  Integer
  (required)
  - Precision attribute: The number of decimal places in the amount field
    Integer
    (required)

Components: If the sale was for a combination offer, list all the individual compontent stock items that were sold as a part of that offer
ID attribute: Unique identifier used for component
String
(required)
StockId: Unique identifier for the component stock item (link to StockItem entity)
String
(required)
Quantity: The number of this component stock item
Integer
(required)
- Precision attribute: The number of Integer places in the Quantity field
  Integer
Cost: Amount the component item(s) actually cost site to buy in
Integer
(required)
- Precision attribute: The number of Integer places in the Cost field
  Integer
  (required)
SalePrice: Portion of the Combo SalePrice refunded to the customer attributable to this specific component item(s)
Integer
(required)
- Precision attribute: The number of Integer places in the SalePrice field
  Integer
  (required)

Payment Entity level fields:

ID attribute: Unique identifier for part or full payment against the refund
String
(required)
Type: Base categorisation for payment type
String
Total: Amount refunded using this type. NOTE: This amount will always be in the same Currency as the refund Currency
Integer
(required)
- Precision attribute: The number of decimal places in the Total field
  Integer
  (required)
TenderedCurrency: It is possible to refund in a Currency other than the Currency against the refund. This field is the actual Currency handed over whereas Total field is the converted amount.
ISO-4217 Code e.g. USD
(required)
TenderedAmount: The amount of the TenderedCurrency handed over to the customer
Integer
(required)
- Precision attribute: The number of decimal places in the TenderedAmount field
  Integer
  (required)

PLEASE NOTE: All field and attribute names are case sensitive

Message Structure - XML:

POST https://{{CIRCUIT_URL}}/data/pos/

POST - XML

<?xml version="1.0" encoding="UTF-8"?>
<ShowTimeAnalytics dataSupplierId="XXX" messageSequence="XXX">
	<CallbackUrl>https://XXX</CallbackUrl>
	<Refunds>
		<Refund id="XXX" siteId="XXX">
			<IsVoid>true/false</IsVoid>
			<Currency>XXX</Currency>
			<TransactionTimestamp>XXX</TransactionTimestamp>
			<CinemaDate>XXX</CinemaDate>
			<SaleLocationId>XXX</SaleLocationId>
			<SaleDeviceId>XXX</SaleDeviceId>
			<SaleDeviceMeta>XXX</SaleDeviceMeta>
			<StaffId>XXX</StaffId>
			<CustomerId>XXX</CustomerId>
			<CustomerEmail>XXX</CustomerEmail>
			<CustomerName>XXX</CustomerName>
			<CustomerLastName>XXX</CustomerLastName>
			<CustomerAccountId>XXX</CustomerAccountId>
			<CustomerAccountType>XXX</CustomerAccountType>
			<ThirdPartyOrderReference>XXX</ThirdPartyOrderReference>
			<MarketingAcceptEmail>XXX</MarketingAcceptEmail>
			<TicketSales>
				<TicketSale id="XXX">
					<TicketTypeId>XXX</TicketTypeId>
					<Quantity>XXX</Quantity>
					<PerformanceId>XXX</PerformanceId>
					<SalePrice precision="XXX">XXX</SalePrice>
					<SalePriceDrp precision="XXX">XXX</SalePriceDrp>
					<SeatRow>XXX</SeatRow>
					<SeatNum>XXX</SeatNum>
					<SeatType>XXX</SeatType>
					<IsVoid>true/false</IsVoid>
					<Taxes>
						<Tax id="XXX">
							<Amount precision="XXX">XXX</Amount>
							<Quantity precision="XXX">XXX</Quantity>
							<Type>XXX</Type>
						</Tax>
					</Taxes>
					<Fees>
						<Fee id="XXX">
							<Amount precision="XXX">XXX</Amount>
							<Quantity precision="XXX">XXX</Quantity>
							<Type>XXX</Type>
							<Taxes>
							    <Tax id="XXX">
							        <Amount precision="XXX">XXX</Amount>
							        <Quantity precision="XXX">XXX</Quantity>
							        <Type>XXX</Type>
							    </Tax>
							</Taxes>
						</Fee>
					</Fees>
					<Discounts>
						<Discount id="XXX">
							<Amount precision="XXX">XXX</Amount>
							<Quantity precision="XXX">XXX</Quantity>
							<Type>XXX</Type>
						</Discount>
					</Discounts>
				</TicketSale>
			</TicketSales>
			<ShopSales>
				<ShopSale id="XXX">
					<StockId>XXX</StockId>
					<Quantity precision="XXX">XXX</Quantity>
					<Cost precision="XXX">XXX</Cost>
					<SalePrice precision="XXX">XXX</SalePrice>
					<IsVoid>true/false</IsVoid>
					<Taxes>
						<Tax id="XXX">
							<Amount precision="XXX">XXX</Amount>
							<Quantity precision="XXX">XXX</Quantity>
							<Type>XXX</Type>
						</Tax>
					</Taxes>
					<Fees>
						<Fee id="XXX">
							<Amount precision="XXX">XXX</Amount>
							<Quantity precision="XXX">XXX</Quantity>
							<Type>XXX</Type>
							<Taxes>
							    <Tax id="XXX">
							        <Amount precision="XXX">XXX</Amount>
							        <Quantity precision="XXX">XXX</Quantity>
							        <Type>XXX</Type>
							    </Tax>
							</Taxes>
						</Fee>
					</Fees>
					<Discounts>
						<Discount id="XXX">
							<Amount precision="XXX">XXX</Amount>
							<Quantity precision="XXX">XXX</Quantity>
							<Type>XXX</Type>
						</Discount>
					</Discounts>
					<Components>
						<Component id="XXX">
							<StockId>XXX</StockId>
							<Quantity precision="XXX">XXX</Quantity>
							<Cost precision="XXX">XXX</Cost>
							<SalePrice precision="XXX">XXX</SalePrice>
							<IsVoid>true/false</IsVoid>
						</Component>
					</Components>
				</ShopSale>
			</ShopSales>
			<AdditionalFees>
				<Fee id="XXX">
					<Amount precision="XXX">XXX</Amount>
					<Quantity precision="XXX">XXX</Quantity>
					<Type>XXX</Type>
					<Taxes>
					    <Tax id="XXX">
					        <Amount precision="XXX">XXX</Amount>
					        <Quantity precision="XXX">XXX</Quantity>
					        <Type>XXX</Type>
					    </Tax>
					</Taxes>
				</Fee>
			</AdditionalFees>
			<AdditionalTaxes>
				<Tax id="XXX">
					<Amount precision="XXX">XXX</Amount>
					<Quantity precision="XXX">XXX</Quantity>
					<Type>XXX</Type>
				</Tax>
			</AdditionalTaxes>
			<Payments>
				<Payment id="XXX">
					<Type>XXX</Type>
					<Total precision="XXX">XXX</Total>
					<TenderedCurrency>XXX</TenderedCurrency>
					<TenderedAmount precision="XXX">XXX</TenderedAmount>
				</Payment>
			</Payments>
		</Refund>
	</Refunds>
</ShowTimeAnalytics>

Callback Post Fields:

DataSupplierID: Unique identifier for your account, same as passed in post message
MessageSequence: Unique sequence number for message, same as passed in post message
ID attribute: Unique identifier for refund, same as passed in post message
Status: Processing result flag - ok/error
Error: If the status flag is "error", list of warning messages during processing

Message Structure - XML:

<?xml version="1.0" encoding="UTF-8"?>
<ShowTimeAnalyticsResponse dataSupplierId="XXX" messageSequence="XXX">
    <Responses>
        <Response id="XXX" siteId="XXX" entity="Refund">
            <Status>XXX</Status>
            <Warnings>
            	<Warning>XXX</Warning>
            </Warnings>
            <Errors>
            	<Error>XXX</Error>
            </Errors>
        </Response>
    </Responses>
</ShowTimeAnalyticsResponse>

ShowTime Analytics API Documentation - Developers

Entity Posting API - Refund

Triggered Updates:

Standard ShowTimeAnalytics Message Parameters:

Fields for Refund Entity:

Refund Entity level fields:

TicketSale Entity level fields:

ShopSale Entity level fields:

Payment Entity level fields:

Message Structure - XML:

POST - XML

Callback Post Fields:

Message Structure - XML: