openapi: 3.2.0 info: title: Data Loyalty API version: '1.0' description: The Loyalty Data API provides App partners with the ability to access data regarding members sales to help aggregate loyalty points. Currently the API allows apps to register their members and are notified on every transaction performed. contact: {} servers: - url: https://api.tyro.com/connect description: Production tags: - name: Loyalty paths: /loyalty/activities/{loyaltyActivityId}: parameters: - name: loyaltyActivityId in: path description: ID of loyalty activity to retrieve required: true schema: type: string get: summary: Get loyalty activity by Id responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/loyalty-activity' examples: Without sale object: value: id: 99fdaa02-4cb4-4948-a79e-4b69e4008feb locationId: e429f245-4dcb-4961-9d27-c40538e990b2 memberId: foo@bar.com payment: origin: paymentId: e429f245-4dcb-4961-9d27-c40538e990b2 paymentSource: EFTPOS type: PURCHASE zonedDateTime: '2021-10-11T11:00:01+11:00' breakdown: goodsAndServices: amount: '299' currency: AUD cashout: amount: '0' currency: AUD tip: amount: '0' currency: AUD surcharge: amount: '0' currency: AUD total: amount: '299' currency: AUD sale: null With sale object: value: id: 99fdaa02-4cb4-4948-a79e-4b69e4008feb locationId: e429f245-4dcb-4961-9d27-c40538e990b2 memberId: foo@bar.com payment: origin: paymentId: e429f245-4dcb-4961-9d27-c40538e990b2 paymentSource: EFTPOS type: PURCHASE zonedDateTime: '2021-05-02T08:28:13+10:00' breakdown: goodsAndServices: amount: '299' currency: AUD cashout: amount: '0' currency: AUD tip: amount: '0' currency: AUD surcharge: amount: '0' currency: AUD total: amount: '299' currency: AUD sale: value: tax: amount: 0 currency: AUD type: SALE items: - id: '1' sku: cherry-pie name: Cherry total: amount: 0 currency: AUD quantity: 1 unitPrice: amount: 0 currency: AUD unitPriceTax: amount: 0 currency: AUD staff: id: '1' table: seats: 1 number: '11' bookingId: 6dca53a9-04c7-46aa-991c-cfdf51a8f652 total: amount: -2 currency: AUD origin: saleId: abc-def-123 source: type: MEANDU status: CLOSED payments: - method: EFTPOS goodsAndServicesAmount: amount: 0 currency: AUD subtotal: amount: 0 currency: AUD discounts: - amount: 1 currency: AUD - amount: 1 currency: AUD locationId: pizza-shop closedZonedDateTime: '2021-05-02T08:28:13+10:00' openedZonedDateTime: '2022-05-02T08:28:13+10:00' '401': description: When you don't have a valid access token. '404': description: When the provided `loyaltyActivityId` does not exist. content: application/json: schema: type: object properties: error: type: string description: The error message. examples: Missing property: value: error: 'No sale was found for id: a72ca942-1cf7-47c8-8808-dd5aa095e81a' description: This endpoint retrieves a loyalty activity for a registered member. operationId: get-loyalty-activity-by-id security: - JWT: [] parameters: - $ref: '#/components/parameters/header-bearer-token' tags: - Loyalty components: parameters: header-bearer-token: schema: type: string default: Bearer {$$.env.access_token} in: header name: Authorization required: true schemas: money-positive-aud: title: Money Positive Amount type: object properties: amount: type: integer description: This is the amount in smallest currency unit. e.g 12520 (in cents) is $125.20 example: 12520 minimum: 0 currency: type: string default: AUD enum: - AUD example: AUD description: This is always AUD required: - amount - currency line-item: type: object title: Line Item description: This object represents a line item within a sale. properties: id: type: string description: A unique id representing the item within the overall order, i.e. 2 of the same items will have unique ids. name: type: string category: type: string description: type: string sku: type: string description: The Id of the item that is aligned with the Id of the item in the POS. barcode: type: string modifiers: type: array description: 'A list of modifications to be made to the parent item. Each object in this array is a [`Line Item`](#/components/schemas/line-item)' items: $ref: '#/components/schemas/line-item' unitPrice: allOf: - $ref: '#/components/schemas/money-positive-aud' - description: The single unit price (in cents) including tax but excluding discounts (if any) unitPriceTax: allOf: - $ref: '#/components/schemas/money-positive-aud' - description: The single unit amount (in cents) of tax collected by the merchant unitCost: allOf: - $ref: '#/components/schemas/money-positive-aud' - description: The single unit cost (in cents) paid by the merchant unitCostTax: allOf: - $ref: '#/components/schemas/money-positive-aud' - description: The single unit amount (in cents) of tax paid by the merchant discounts: type: array description: A list of discounts applied to the line item (this is not a per unit discount). e.g if the line item has a quantity of 3, and each item has a 20 cent discount, you could include one discount of 60 cents in the list, or three 20 cent discounts in the list. items: $ref: '#/components/schemas/money-positive-aud-with-description' sale: title: Sale info description: Provides additional information about the sale. Only present when top-level sale type is COMBINATION. Allows a POS to record a sale that contains item/s that are returned or exchanged as part of the sale. type: object properties: type: type: string enum: - SALE - REFUND surcharges: type: array description: A list of surcharges applied to the line item (this is not a per unit surcharge). e.g if the line item has a quantity of 5, and each item has a $2 surcharge, you could include one surcharge of $10 in the list, or five $2 surcharges in the list. items: $ref: '#/components/schemas/money-positive-aud-with-description' quantity: type: number minimum: 0 exclusiveMinimum: 0 description: The number of units of this item in the sale. It can be fractional. tax: allOf: - $ref: '#/components/schemas/money-positive-aud' - description: The amount (in cents) of tax collected by the merchant for this line item total: allOf: - $ref: '#/components/schemas/money-positive-aud' - description: The total (in cents) of this line item after tax, discounts, surcharges, modifiers and rounding have been applied. required: - id - name - sku - unitPrice - unitPriceTax - quantity - tax - total loyalty-activity: title: Loyalty Activity object type: object properties: id: type: string description: The Id of the loyalty activitiy in the Tyro Connect system. example: 0f448ac1-862a-4c7b-bdb4-a3b7cdbf6149 locationId: type: string description: The Id of the location as specified by the Tyro Connect system. memberId: type: string description: The identifier of the member who is associated with this activity. This value corresponds to the origin.memberId provided during member registration. payment: type: object properties: origin: type: object properties: paymentId: type: string description: Payment Identifier generated from the payment source. It refers to the `transaction.receipt` (from Tyro eCommerce APIs) or otherwise referred to as the RRN. paymentSource: type: string enum: - EFTPOS - ONLINE type: type: string enum: - PURCHASE - REFUND - CASHOUT - OPEN_PRE_AUTH - CLOSE_PRE_AUTH - VOID mode: type: string description: EFTPOS integration type. It will always be `NOT_APPLICABLE` for `ONLINE` payments. enum: - INTEGRATED - STANDALONE - NOT_APPLICABLE zonedDateTime: type: string format: date-time breakdown: type: object properties: goodsAndServices: allOf: - $ref: '#/components/schemas/money-positive-aud' - description: This is the amount paid by the card holder for their goods and/or services. This amount does not include any tip, surcharge, or cash out. cashout: allOf: - $ref: '#/components/schemas/money-positive-aud' - description: If the cardholder withdrew cash as part of the transaction this value represents how much cash was given to the cardholder. tip: allOf: - $ref: '#/components/schemas/money-positive-aud' - description: If the cardholder left a tip this value represents how much the tip was. surcharge: allOf: - $ref: '#/components/schemas/money-positive-aud' - description: If the cardholder was charged a surcharge this value represents how much the surcharge was. total: allOf: - $ref: '#/components/schemas/money-positive-aud' - description: The total amount that was paid by the cardholder. sale: type: object properties: locationId: type: string description: This is the Tyro Connect defined location Id. It is a globally unique identifier that is used to identify a merchants individual site origin: type: object description: Identifiers and reference numbers that were generated by the POS. required: - saleId - locationId properties: saleId: type: string description: The Id of the sale generated by the POS. This value should allow for partner systems to reconcile this sale with the POS. locationId: type: string description: The Id of the store according to the POS locationName: type: string description: This is the human readable name of the location. source: type: object description: Information about the source of the sale. required: - type properties: type: type: string enum: - DELIVEROO - DOORDASH - GOOGLE - HEYYOU - HUNGRYHUNGRY - MEANDU - MENULOG - MRYUM - ORDERUP - OTHER - POS - UBEREATS description: An enum describing the source type of the sale. other: type: string description: The source of the sale if the source type is OTHER. type: type: string enum: - SALE - REFUND - VOID default: SALE description: An enum describing what kind of sale took place. status: type: string enum: - CLOSED default: CLOSED description: An enum describing the status of the sale. In the future the API will support more values for this field. openedZonedDateTime: type: string format: date-time example: '2018-05-02T08:28:13+10:00' description: The time the sale was opened on the POS. The format of the date time is the notation as defined by [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6) closedZonedDateTime: type: string description: The time the sale was closed on the POS. The format of the date time is the notation as defined by [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6) example: '2018-05-02T08:28:13+10:00' format: date-time customer: type: object properties: id: type: string name: type: string register: type: object description: 'Information about which register in the venue was used ' properties: id: type: string name: type: string staff: type: object description: Details about the staff member who performed the transaction required: - id properties: id: type: string description: The id of the staff member in the POS system. Please **do not** put the staff members name here section: type: object description: The section within the venue where the sale took place. properties: id: type: string description: The POS system's Id of the section name: type: string description: The readable name of the section. E.g. Front bar, drive through for hospitality or for retail men's clothes, womens shoes etc. table: type: object description: Optional information about the table where in the venue the sale took place. properties: number: type: string description: The table number or table id. This field accepts alphanumeric characters e.g `MAIN-33` example: MAIN-33 seats: type: integer description: The number of PAX where were seated at the table required: - number bookingId: type: string description: The booking ID defined by Tyro Connect to identify a reservation items: type: array items: $ref: '#/components/schemas/line-item' discounts: type: array items: $ref: '#/components/schemas/money-positive-aud-with-description' surcharges: type: array items: $ref: '#/components/schemas/money-positive-aud-with-description' tax: allOf: - $ref: '#/components/schemas/money-positive-aud' - description: The total amount (in cents) of tax collected for this sale by the merchant. payments: type: array items: type: object properties: acquirer: type: object description: Details about the financial instituition that processed the payment. This object is only supplied when the `method` is `EFTPOS` properties: name: type: string description: The name of the Financial Institution that processed the payment. If it was Tyro Payments who processed the transaction, this value is `TYRO` pattern: ^[A-Z]+$ example: TYRO transactionReference: type: string description: A reference number that can be used to look up the transaction in the acquirer's system. terminalId: type: string description: The Financial Institution's id of the payment terminal that performed the transaction required: - name - transactionReference - terminalId method: type: string enum: - EFTPOS - CASH - GIFT_CARD - POINTS goodsAndServicesAmount: allOf: - $ref: '#/components/schemas/money-positive-aud' - description: The amount (in cents) being paid for the goods and services tipAmount: allOf: - $ref: '#/components/schemas/money-positive-aud' - description: The tip amount added on top of the goods and services cashoutAmount: allOf: - $ref: '#/components/schemas/money-positive-aud' - description: The cashout amount requested on top of the goodsAndServicesAmount surchargeAmount: allOf: - $ref: '#/components/schemas/money-positive-aud' - description: The surcharge amount (in cents) charged by the merchant to process the payment method required: - method - goodsAndServicesAmount total: allOf: - $ref: '#/components/schemas/money-positive-aud' - description: 'The total (in cents) of this sale. It must calculate to: sum(items[].total) - discounts + surcharges' subtotal: allOf: - $ref: '#/components/schemas/money-positive-aud' - description: 'The subtotal (in cents) of this sale. It must calculate to: sum(items[].total)' required: - locationId - origin - source - type - openedZonedDateTime - closedZonedDateTime - staff - tax - payments required: - id - locationId - origin - payment money-positive-aud-with-description: title: Money Positive Amount With Description allOf: - $ref: '#/components/schemas/money-positive-aud' - type: object properties: description: type: string description: A description of what this amount of money represents example: Tuesday Happy Hour Discount securitySchemes: JWT: type: openIdConnect openIdConnectUrl: https://auth.connect.tyro.com/.well-known/openid-configuration