# loyale Documentation

> Documentation for loyale

Append .md to any documentation page URL to get its markdown version.

## Guides
- [Getting Started](https://docs.loyale.io/docs/webhooks.md)
- [Setup](https://docs.loyale.io/docs/webhooks-setup.md)
- [Topics](https://docs.loyale.io/docs/topics.md)
- [Topic 6](https://docs.loyale.io/docs/topic-6.md)
- [Topic 10](https://docs.loyale.io/docs/topic-10.md)
- [TransactionResultView](https://docs.loyale.io/docs/transactionresultview.md)
- [ApiTransactionResultView](https://docs.loyale.io/docs/apitransactionresultview.md)

## API Reference
- [Using your Scheme](https://docs.loyale.io/reference/using-your-scheme.md): Send the X-Scheme header with every request
- [Pagination](https://docs.loyale.io/reference/pagination.md)
- [Enums](https://docs.loyale.io/reference/enums.md)
- [Dates and Times](https://docs.loyale.io/reference/dates-and-times.md)
- [Forgot Password](https://docs.loyale.io/reference/post_api-v2-account-forgotpassword.md): This endpoint allows the customer to request a reset password email.
- [Change password](https://docs.loyale.io/reference/post_api-v2-account-changepassword.md): This endpoint allows the customer to change their password
- [Get Activity](https://docs.loyale.io/reference/get_api-v2-activity-customerid.md): This endpoint returns a list of customer’s activity. These can be filtered, sorted and paged by the query parameters passed.
- [Get Token](https://docs.loyale.io/reference/post_api-v2-auth-token.md): This endpoint returns the authentication token for the customer.
- [Get Brand by ID](https://docs.loyale.io/reference/get_api-v2-brand-brandid.md): This endpoint returns one brand by the id.
- [Get Brands](https://docs.loyale.io/reference/get_api-v2-brand.md): This endpoint returns a list of brands. These can be filtered, sorted and paged by the query parameters passed.
- [Get Contacts Match](https://docs.loyale.io/reference/post_api-v2-contact-match.md): This endpoint returns a list of matched mobile numbers in the scheme.
- [Get Coupons Linked](https://docs.loyale.io/reference/get_api-v2-couponslinked.md): This endpoint returns a list of coupons linked to the customer. These can be filtered, sorted and paged by the query parameters passed.
- [Get Coupon Linked by ID](https://docs.loyale.io/reference/get_api-v2-couponslinked-linkedcouponid.md): This endpoint returns one coupon linked by the id.
- [Get Coupon Usage](https://docs.loyale.io/reference/get_api-v2-couponslinked-usage.md): This endpoint returns a list of coupons linked that were used by the customer. These can be filtered, sorted and paged by the query parameters passed.
- [Get Customer by ID](https://docs.loyale.io/reference/get_api-v2-customer-customerid.md): This endpoint returns one customer by the id.
- [Post Customer](https://docs.loyale.io/reference/post_api-v2-customer.md): This endpoint allows the customer to create their account.
- [Update Customer](https://docs.loyale.io/reference/put_api-v2-customer.md): This endpoint allows the customer to update their account.
- [Suspend Customer](https://docs.loyale.io/reference/put_api-v2-customer-suspend-customerid.md): This endpoint allows the customer to suspend their account.
- [Leave Scheme](https://docs.loyale.io/reference/post_api-v2-customer-leavescheme-schemeid.md): This endpoint allows the customer to leave a scheme.
- [Join Scheme](https://docs.loyale.io/reference/post_api-v2-customer-joinscheme-schemeid.md): This endpoint allows the customer to join a scheme.
- [Delete Customer](https://docs.loyale.io/reference/post_api-v2-customer-terminateaccount-customerid.md): This endpoint allows the customer to delete their account.
- [Post Profile Picture](https://docs.loyale.io/reference/post_api-v2-customer-profilepicture.md): This endpoint allows the customer to save their profile picture.
- [Delete Profile Picture](https://docs.loyale.io/reference/put_api-v2-customer-removeprofilepicture.md): This endpoint allows the customer to delete their profile picture.
- [Get Balance](https://docs.loyale.io/reference/get_api-v2-customer-balance.md): This endpoint returns the customer’s points and monetary balance.
- [Get Levels](https://docs.loyale.io/reference/get_api-v2-customer-levels.md): This endpoint returns the customer's levels.
- [External Event Trigger](https://docs.loyale.io/reference/post_api-externaleventtrigger.md): This endpoint allows the customer to trigger an external event.
- [Get Gift Cards Linked](https://docs.loyale.io/reference/get_api-v2-giftcardslinked.md): This endpoint returns a list of gift cards linked to the customer. These can be filtered, sorted and paged by the query parameters passed.
- [Get Gift Card Linked by ID](https://docs.loyale.io/reference/get_api-v2-giftcardslinked-giftcardlinkedid.md): This endpoint returns one gift card linked by the id.
- [Get Gift Card Usage](https://docs.loyale.io/reference/get_api-v2-giftcardslinked-usage.md): This endpoint returns a list of gift cards linked that were used by the customer. These can be filtered, sorted and paged by the query parameters passed.
- [Get Group by ID](https://docs.loyale.io/reference/get_api-v2-group-groupid.md): This endpoint returns one group by the id.
- [Get Groups](https://docs.loyale.io/reference/get_api-v2-group.md): This endpoint returns a list of groups. These can be filtered, sorted and paged by the query parameters passed.
- [Filtering and Sorting for Get Currencies](https://docs.loyale.io/reference/filtering-and-sorting-for-get-currencies.md): You can filter and sort Currencies by the following properties.
- [Get Currencies](https://docs.loyale.io/reference/get_api-v2-helpers-currency.md): This endpoint returns a list of currencies. These can be filtered, sorted and paged by the query parameters passed.
- [Filtering and Sorting for Get Countries](https://docs.loyale.io/reference/filtering-and-sorting-for-get-countries.md): You can filter and sort Countries by the following properties.
- [Get Countries](https://docs.loyale.io/reference/get_api-v2-helpers-countries.md): This endpoint returns a list of countries. These can be filtered, sorted and paged by the query parameters passed.
- [Filtering and Sorting for Get Towns](https://docs.loyale.io/reference/filtering-and-sorting-for-get-towns.md): You can filter and sort Towns by the following properties.
- [Get Towns](https://docs.loyale.io/reference/get_api-v2-helpers-towns.md): This endpoint returns a list of towns. These can be filtered, sorted and paged by the query parameters passed
- [Get Level by ID](https://docs.loyale.io/reference/get_api-v2-level-levelid.md): This endpoint returns one level by the id.
- [Get Levels](https://docs.loyale.io/reference/get_api-v2-level.md): This endpoint returns a list of levels. These can be filtered, sorted and paged by the query parameters passed.
- [Post a new message](https://docs.loyale.io/reference/post_api-v2-message.md): Sends an email message to the Customer whose Id matches the one passed in the customerId parameter in the body of the request and saves the message in the database. The status parameter is an enum which corresponds to 0 = New, 1 = WaitingForCustomer and 3 = Solved.
- [Get Outlet by ID](https://docs.loyale.io/reference/get_api-v2-outlet-outletid.md): This endpoint returns one outlet by the id.
- [Get Outlets](https://docs.loyale.io/reference/get_api-v2-outlet.md): This endpoint returns a list of outlets. These can be filtered, sorted and paged by the query parameters passed.
- [Get Post Linked by ID](https://docs.loyale.io/reference/get_api-v2-postslinked-postlinkedid.md): This endpoint returns one post linked by the id
- [Get Posts Linked](https://docs.loyale.io/reference/get_api-v2-postslinked.md): This endpoint returns a list of posts linked to the customer. These can be filtered, sorted and paged by the query parameters passed.
- [Post Push Token](https://docs.loyale.io/reference/post_api-v2-pushtoken.md): This endpoint allows the customer to save a new push token.
- [Replace Push Token](https://docs.loyale.io/reference/post_api-v2-pushtoken-replace.md): This endpoint allows the customer to replace their existing push token with a new one.
- [Delete Push Token](https://docs.loyale.io/reference/delete_api-v2-pushtoken-token.md): This endpoint allows the customer to delete a push token.
- [Get Push Token by Value](https://docs.loyale.io/reference/get_api-v2-pushtoken-bytoken-token.md): This endpoint returns one push token by the value.
- [Get Scheme by ID](https://docs.loyale.io/reference/get_api-v2-scheme-schemeid.md): This endpoint returns one scheme by the id.
- [Get Transaction by ID](https://docs.loyale.io/reference/get_api-v2-transaction-transactionid.md): This endpoint returns one transaction by the id.
- [Get Gain Rate](https://docs.loyale.io/reference/get_api-v2-transaction-gainrate.md): This endpoint returns the gain rate based on the outlet id passed.
- [Get Transactions Grouped](https://docs.loyale.io/reference/get_api-v2-transaction-grouped.md): This endpoint returns a list of transactions grouped. These can be filtered, sorted and paged by the query parameters passed.
- [Get Transactions](https://docs.loyale.io/reference/get_api-v2-transaction.md): This endpoint returns a list of transactions. These can be filtered, sorted and paged by the query parameters passed.
- [Get additional customer fields](https://docs.loyale.io/reference/get_api-pos-additionalcustomerfields-list.md): Returns additional customer fields for the supplied X-Scheme header. Results can be filtered, sorted and paged using the query parameters.
- [Get an additional customer field](https://docs.loyale.io/reference/get_api-pos-additionalcustomerfields-id.md): Returns one additional customer field by id for the supplied X-Scheme header.
- [Get a customer's additional field by key](https://docs.loyale.io/reference/get_api-pos-additionalcustomerfields-key-customerid.md): Returns one additional customer field for the supplied customer, key and X-Scheme header.
- [Create an additional customer field](https://docs.loyale.io/reference/post_api-pos-additionalcustomerfields.md): Creates an additional customer field for the supplied customer and X-Scheme header. The field is always created as non-internal.
- [Update an additional customer field](https://docs.loyale.io/reference/put_api-pos-additionalcustomerfields.md): Updates the customer's additional field for the supplied key and X-Scheme header. If the field does not already exist, the current service behavior creates it as non-internal.
- [Get List of Coupons Linked](https://docs.loyale.io/reference/get_api-pos-couponslinked-list.md): This endpoint returns a list of coupons linked to the customer. These can be filtered, sorted and paged by the query parameters passed.
- [Get Coupon Linked](https://docs.loyale.io/reference/get_api-pos-couponslinked-byidentifier.md): This endpoint returns one coupon linked.
- [Use Multiple Coupons](https://docs.loyale.io/reference/post_api-pos-couponslinked-usecoupons.md): This endpoint allows you to send an array of coupon barcodes to get marked as used
- [Use a Coupon Linked](https://docs.loyale.io/reference/post_api-pos-couponslinked-use.md)
- [Post Customer](https://docs.loyale.io/reference/post_api-pos-customer.md): This endpoint allows you to create a customer account.
- [Place a customer account on hold.](https://docs.loyale.io/reference/put_api-pos-customer-suspend.md)
- [Reactivate a suspended customer.](https://docs.loyale.io/reference/put_api-pos-customer-activate.md)
- [Set the Deleted flag of a Customer to true](https://docs.loyale.io/reference/delete_api-pos-customer.md)
- [Filtering and Sorting of Get Customers](https://docs.loyale.io/reference/filtering-and-sorting-of-get-customers.md): You can filter and sort Customers by the following properties.
- [Update Customer](https://docs.loyale.io/reference/put_api-pos-customer-customerid.md): This endpoint allows you to update a customer account.
- [Get List of Customers](https://docs.loyale.io/reference/get_api-pos-customer-list.md): This endpoint returns a list of customers. These can be filtered, sorted and paged by the query parameters passed.
- [Get Customer](https://docs.loyale.io/reference/get_api-pos-customer-byidentifier.md): This endpoint returns one customer by the identifier passed. This can be either the id, barCode, email or mobile number of the customer.
- [Get Customer Balance](https://docs.loyale.io/reference/get_api-pos-customer-balance.md): This endpoint returns the balance of a customer by the identifier.
- [Get Customer Levels](https://docs.loyale.io/reference/get_api-pos-customer-levels.md): This endpoint returns the levels of a customer by the identifier.
- [Get Customer Offers](https://docs.loyale.io/reference/get_api-pos-customer-offers.md)
- [Create a Guest Customer](https://docs.loyale.io/reference/post_api-pos-customer-guest.md): This endpoint allows you to create a guest customer account.
- [Join a Guest to the Scheme](https://docs.loyale.io/reference/put_api-pos-customer-guestjoin-customerid.md): Joins the guest account to the scheme
- [External Event Trigger](https://docs.loyale.io/reference/post_api-pos-externaleventtrigger.md): This endpoint allows the customer to trigger an external event.
- [Post Transaction Simulate](https://docs.loyale.io/reference/post_api-pos-simulate.md): Requires: Admin Token {companyId} will be an id identifying the franchise this request is being made from, provided by Loyale. {companyId} will be an id identifying the outlet this request is being made from, provided by Loyale. {wsId} will be an id identifying the POS this request is being made from.This can be provided by us and is used for informational purposes only. {userDetail} is to be filled out by the user detail. In this case either ID Card, Mobile, Barcode.  In Body, you will send: {   "saleTotal": "string",   "cashRedeemed": "string",   "saleCurrency": "string",   "chitNumber": "string",   "schemeId": "3fa85f64 - 5717 - 4562 - b3fc - 2c963f66afa6",   "lineItems": [     {       "id": "string",       "quantity": 0,       "unitPrice": "string",       "description": "string",       "groupId": "string"     }   ],   "couponsUsed": [     "couponBarcode"   ] }  SaleTotal is the total of the sale, in case of return SaleTotal would be the negative total of the sale return (ie: ‘-1.50’) cashRedeemed is the part of the sale which was redeemed. This means that cash redeemed will be 0 if there was no redemption, or equal to SaleTotal if the whole sale was a redemption. saleCurrency should be set to EUR chitNumber is to be any unique identifier from your end so we identify the transaction. schemeId is the same schemId you send in the header lineItems can be filled in the format specified above, or left an empty array if no details about line items will be passed to loyale. couponsUsed can be filled in the format specified above, or left an empty array if no details about line items will be passed to loyale.  You will receive back:  {   "saleTotal": "string",   "cashRedeemed": "string",   "saleCurrency": "string",   "chitNumber": "string",   "pointsBefore": 0,   "pointsDelta": 0,   "pointsFinal": 0,   "monetaryValueBefore": 0,   "monetaryValueAfter": 0 }
- [Generate a GiftCardLinked based on the giftCardId given.](https://docs.loyale.io/reference/post_api-pos-giftcard-purchased.md)
- [Get a List of Purchasable Gift Cards](https://docs.loyale.io/reference/get_api-pos-giftcard-purchasable.md): This endpoint returns a list of gift cards which can be purchased. These can be filtered, sorted and paged by the query parameters passed.
- [Get List of Gift Cards Linked](https://docs.loyale.io/reference/get_api-pos-giftcardslinked-list.md): This endpoint returns a list of gift cards linked to the customer. These can be filtered, sorted and paged by the query parameters passed.
- [Get Gift Card Linked](https://docs.loyale.io/reference/get_api-pos-giftcardslinked-byidentifier.md): This endpoint returns one gift card linked.
- [Use a Gift Card Linked](https://docs.loyale.io/reference/post_api-pos-giftcardslinked-use.md)
- [Activate a list of Gift Cards Linked](https://docs.loyale.io/reference/put_api-pos-giftcardslinked-activate.md)
- [Generate a list of Gift Cards Linked](https://docs.loyale.io/reference/post_api-pos-giftcardslinked-generate.md)
- [Get Transaction by ID](https://docs.loyale.io/reference/get_api-pos-transaction-transactionid.md): This endpoint returns one transaction by the id.
- [Get Transactions](https://docs.loyale.io/reference/get_api-pos-transaction.md): This endpoint returns a list of transactions. These can be filtered, sorted and paged by the query parameters passed.
- [Get SkuItem](https://docs.loyale.io/reference/get_api-pos-skuitem-byidentifier.md): Returns a SKU Item found by id or barcode.
- [Getting Started](https://docs.loyale.io/reference/getting-started-1.md): Replacement for Integration API
- [Create a Terminal Cloud session](https://docs.loyale.io/reference/createterminalpossession.md): Create a Terminal Cloud payment session for terminal. The request includes terminal, POS, amount, reference, receipt, and optional line-item details. Line item totals must match the request amount when line items are provided.
- [Delete a Terminal Cloud session](https://docs.loyale.io/reference/deleteterminalpossession.md): Delete a Terminal Cloud payment session by session ID. Use this endpoint to cancel or remove a session that should no longer be available to the payment terminal. Only pending sessions can be cancelled.
- [Retrieve a Terminal Cloud session](https://docs.loyale.io/reference/getterminalpossession.md): Retrieve a Terminal Cloud payment session by session ID. The response includes the terminal, POS, amount, state, references, receipt, and related session data. Keep polling this request until state is succeeded or failed.
- [Return a full transaction](https://docs.loyale.io/reference/returnfulltransaction-1.md): Return a full transaction using its unique ID.  The response will include details about the processed refund, including line items, amounts refunded, and points adjustments. Use this endpoint when you want to return an entire transaction rather than specific items.
- [Return a specific line item from a transaction](https://docs.loyale.io/reference/returnlineitem-1.md): Return a specific line item from a transaction using the unique transaction ID and the SKU of the item.  You need to specify the quantity of the item being returned. The system will calculate the refund and points adjustments for the returned item(s).
- [Return a custom transaction](https://docs.loyale.io/reference/returncustomtransaction-1.md): Process a custom refund that is dynamically calculated without referencing any existing transaction.  This is useful when performing a return on the fly, where the points and refund details are computed based on the current setup.
- [Process a transaction](https://docs.loyale.io/reference/processtransaction-1.md): Create a composite transaction that may include multiple line items and payment methods.     Exactly one of 'outletId' or 'outlet' must be provided. When using 'outlet', both 'outlet.name' and 'outlet.externalCode' are required.     Optional flat string metadata can be supplied via 'metadata' and will be attached to the created transaction records.     To request non-redeemable pending points instead of immediate issuance, set 'createAsPendingTransaction=true' in the request body (optional 'autoCancelAfterMinutes' to suggest expiry, or 'autoPromoteAfterMinutes' to automatically promote to redeemable). These options are mutually exclusive.     The response will contain the transaction status, including points earned, points redeemed,     the customer's points balance before and after the transaction, the accepted coupon barcodes,     and the effective payment methods.     In case of a failed transaction, an error message will be returned.     Transactions are processed asynchronously, and the status can be checked later using the URL provided in the response.     The request accepts either a customer ID or a customer barcode. You can pass a unique ID for the transaction, or one will be generated automatically if not provided.      To simulate a transaction without processing it, set the 'simulate' query parameter to 'true'.
- [Retrieve transaction status by unique ID](https://docs.loyale.io/reference/gettransactionstatus-1.md): Retrieve the status of a composite transaction using its unique identifier.      The response will include the current status of the transaction and any relevant details,      such as whether the transaction has been processed successfully or if it is still pending.
- [Cancel pending points for a transaction](https://docs.loyale.io/reference/cancelpendingpoints.md): Cancel pending points before they become redeemable.      Useful for reversals or fraud checks while the points are still in a non-redeemable state.
- [Promote pending points to a redeemable balance](https://docs.loyale.io/reference/promotependingpoints.md): Promote a pending points accrual to the customer's redeemable balance once any grace period has passed.
- [Submit a points adjustment](https://docs.loyale.io/reference/submitadjustment.md): Submit a positive or negative points adjustment for asynchronous processing. 'points' is always a positive integer; 'transactionType' determines whether points are added or removed. 'uniqueId' is the caller-provided idempotency key within the scheme. Retrying the same request is safe. Reusing a unique ID with different adjustment data is rejected during processing.

## Pages
- [Automation Double Points](https://docs.loyale.io/page/automation-double-points.md)
- [Design Guidelines - Customer Facing UI](https://docs.loyale.io/page/designing-for-loyale.md)

## Changelog
- [Deprecation of Coupons and Gift Cards POS API Endpoints](https://docs.loyale.io/changelog/deprecation-of-coupons-and-gift-cards-pos-api-endpoints.md)
- [Deprecation of POS API Endpoints](https://docs.loyale.io/changelog/deprecation-of-pos-api-endpoints.md)
- [New Pagination Settings](https://docs.loyale.io/changelog/new-pagination-settings.md)
- [Change in Webhook Behaviour](https://docs.loyale.io/changelog/change-in-webhook-behaviour.md)
- [POS API Customer Post](https://docs.loyale.io/changelog/pos-api-customer-post.md)
- [CSV Exports change in date time format](https://docs.loyale.io/changelog/csv-exports-change-in-date-time-format.md)
- [Reports export being moved to use email export](https://docs.loyale.io/changelog/reports-export-being-moved-to-use-email-export.md)
- [Change in Agent Backoffice Access](https://docs.loyale.io/changelog/change-in-agent-backoffice-access.md)
- [Change in Agent Authorization Access](https://docs.loyale.io/changelog/change-in-authorisation.md)
- [Updated TransactionResultView](https://docs.loyale.io/changelog/updated-transactionresultview.md)