• Entity Posting API
• >>
• Order

Entity Posting API - Order

If the OrderID does not exist, a new Order record will be created. If it does, it will be updated.

Triggered Updates:

• If the order is an update, the Ticket/Shop/Payment records which were loaded via that OrderID 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 Order Entity:

Order Entity level fields:

• ID attribute: Unique identifier for order
  String
  (required)
• SiteID attribute: Unique identifier for site that the order applies to
  String
  (required)
• 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 order 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 order was taken (link to SaleDevice entity)
  String
• SaleLocationId: Unique identifier for where the customer completed their order (link to SaleLocation entity)
  String
• StaffId: The ID of the staff member who completed the order (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) (link to Account in Customer entity)
  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 sold as a part of the order. 1 entity per ticket (min 1 ticket/shop required)
• ShopSales: List of the shop items sold as a part of the order. There may be multiples (Quantity field) of each
  item in each entity (min 1 ticket/shop required)


• AdditionalFees: List of fees applied to the overall order.
  (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)
  • Taxes: Option to break out the taxes applicable to the fee being applied


• AdditionalTaxes: List of taxes applied to the overall order.
  (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)


• Vouchers: List of vouchers that were used to part pay for the transaction.


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



TicketSale Entity level fields:

• ID attribute: Unique identifier for ticket line item in the order
  String
  (required)
• TicketTypeId: Unique identifier used for categorizing the type of ticket purchased (link to TicketType entity)
  String
  (required)
• PerformanceId: Unique identifier for the performance for which the type of ticket purchased (link to Performance entity)
  String
  (required)
• Quantity: The number of tickets of this ticket type purchased (default 1)
  Integer
• SalePrice: Amount actually paid by 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 SalePrice 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)
• VoucherId: ID of one of the vouchers listed against the order. Used to indicate which items the voucher was redeemed directly against
  String
• IsPass: Set to true if a pass was used for this ticket (default false)
  true/false
• IsFree: Set to true if a this ticket was a free ticket. This is also known as comped tickets (default false)
  true/false
• IsNoShow: Set to true if the ticket was purchased but the customer was not recorded as turning up to the movie (default false)
  true/false
• Deleted: Set to true if the specific ticket sale was previously posted to Showtime and now should be deleted. This is typically as a result of a Swap in the POS (default false)
  true/false
• SeatRow: SeatRow and SeatNum uniquely identify the chosen seat for the ticket purchased
  String
• SeatNum: SeatRow and SeatNum uniquely identify the chosen seat for the ticket purchased
  String
• SeatType: Base categorisation for type of seat selected
  String


• Taxes: List of taxes applied in the calculation of the price of the ticket purchased
  • 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)


• Fees: List of fees applied to the line item
  (separate from fees applied at the overall order 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 sale price applicible to this fee
    Integer
    (required)
    • Precision attribute: The number of Integer places in the amount field
      Integer
      (required)
  • Taxes: Option to break out the taxes applicable to the fee being applied


• Discounts: List of discounts applied in the calculation of the price of the ticket purchased
  • ID attribute: Unique identifier used for discount type (link to DiscountType entity)
    String
    (required)
    NOTE: can be empty, default to generic arbitrary 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 sale price was reduced by this discount
    Integer
    (required)
    • Precision attribute: The number of Integer places in the amount field
      Integer
      (required)



ShopSale Entity level fields:

• ID attribute: Unique identifier for shop line item in the order
  String
  (required)
• StockId: Unique identifier for the stock item being purchased (link to StockItem entity)
  String
  (required)
• Quantity: The number of this stock item being purchased
  Integer
  (required)
  • Precision attribute: The number of Integer places in the Quantity field
    Integer
• Deleted: Set to true if the specific shop sale was previously posted to Showtime and now should be deleted. This is typically as a result of a Swap in the POS (default false)
  true/false
• Cost: Amount the item(s) actually cost site to buy in
  Integer
  (required)
  • Precision attribute: The number of Integer places in the Cost field
    Integer
    (required)
• SalePrice: Amount actually paid by 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 Integer places in the SalePrice field
    Integer
    (required)
• VoucherId: ID of one of the vouchers listed against the order. Used to indicate which items the voucher was redeemed directly against
  String


• Taxes: List of taxes applied in the calculation of the price of the item(s) purchased
  • 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)


• Fees: List of fees applied to the line item
  (separate from fees applied at the overall order 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 sale price applicible to this fee
    Integer
    (required)
    • Precision attribute: The number of Integer places in the amount field
      Integer
      (required)
  • Taxes: Option to break out the taxes applicable to the fee being applied


• Discounts: List of discounts applied in the calculation of the price of the item(s) purchased
  • 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 sale price was reduced by this discount
    Integer
    (required)
    • Precision attribute: The number of Integer 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 paid by the customer attributable to this specific component item(s)
  Integer
  (required)
  • Precision attribute: The number of Integer places in the SalePrice field
    Integer
    (required)

Worked example of splitting combos into component parts:

- Combo consisting of a medium popcorn and medium cola sells for $8
- Sale price of medium popcorn on its own is $6 & Sale price of medium cola on its own is $4
- Total price of individual items purchased separately would have been $10. Selling for $8 represents a 20% discount
- Actual selling price for the popcorn component is $6 less 20% = $4.80
- Actual selling price for the cola component is $4 less 20% = $3.20




Voucher redemption fields:

• ID attribute: Unique identifier for voucher redeemed against the order. May be same as code.
  String
  (required)
• Code: The voucher code displayed to the customer
  String
• Type: Base categorisation for voucher
  String
• Total: Amount redeemed by using this voucher. NOTE: This amount will always be in the same Currency as the order Currency
  Integer
  (required)
  • Precision attribute: The number of Integer places in the Total field
    Integer
    (required)
• DateIssued: Date when the voucher was issued to the customer
  yyyy-MM-dd
• ExpiryDate: Date when the voucher was due to expire
  yyyy-MM-dd




Payment Entity level fields:

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

PLEASE NOTE: All field and attribute names are case sensitive

Message Structure - XML:

<?xml version="1.0" encoding="UTF-8"?>
<ShowTimeAnalytics dataSupplierId="XXX" messageSequence="XXX">
	<CallbackUrl>https://XXX</CallbackUrl>
	<Orders>
		<Order id="XXX" siteId="XXX">
			<Currency>XXX</Currency>
			<TransactionTimestamp>XXX</TransactionTimestamp>
			<CinemaDate>XXX</CinemaDate>
			<SaleLocationId>XXX</SaleLocationId>
			<SaleDeviceId>XXX</SaleDeviceId>
			<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>
					<VoucherId>XXX</VoucherId>
					<IsPass>true/false</IsPass>
					<IsFree>true/false</IsFree>
					<IsNoShow>true/false</IsNoShow>
					<Deleted>true/false</Deleted>
					<SeatRow>XXX</SeatRow>
					<SeatNum>XXX</SeatNum>
					<SeatType>XXX</SeatType>
					<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>
					<VoucherId>XXX</VoucherId>
					<Deleted>true/false</Deleted>
					<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>
						</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>
			<Vouchers>
				<Voucher id="XXX">
					<Code>XXX</Code>
					<Type>XXX</Type>
					<Total precision="XXX">XXX</Total>
					<DateIssued>XXX</DateIssued>
					<ExpiryDate>XXX</ExpiryDate>
				</Voucher>
			</Vouchers>
			<Payments>
				<Payment id="XXX">
					<Type>XXX</Type>
					<Total precision="XXX">XXX</Total>
					<TenderedCurrency>XXX</TenderedCurrency>
					<TenderedAmount precision="XXX">XXX</TenderedAmount>
				</Payment>
			</Payments>
		</Order>
	</Orders>
</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 order, 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="Order">
            <Status>XXX</Status>
            <Warnings>
            	<Warning>XXX</Warning>
            </Warnings>
            <Errors>
            	<Error>XXX</Error>
            </Errors>
        </Response>
    </Responses>
</ShowTimeAnalyticsResponse>