# Loyalty Accounts This guide covers the types of the loyalty account and how to interact with them using APIs. Loyalty Accounts are used for managing store credits of users in a commerce system. Before using loyalty accounts, users need to ensure that a Dynamic Setting called `LOYALTY_MONEY_ENABLED` is set to True. The Loyalty account operates on a currency-based system. When a user creates an order, the loyalty money for that order is calculated by considering the user's loyalty accounts in the same currency as the order. These loyalty money is then withdrawn in a sequential manner until they either fully cover the order's cost or are depleted. ### Loyalty Account Types There are three types of accounts that must be created before using this feature: **SALE\_ACCOUNT** Money is transferred from this account when the account is used to pay for an order. * Default UUID: 71c07edb-d531-49f1-aec6-b26a971104e4 * Setting to change UUID in settings.py: `LOYALTY_SALE_ACCOUNT_UUID` **BANK\_ACCOUNT** Money is transferred from this account when creating a gift card. * Default UUID: Bank * Setting to change UUID in settings.py: `LOYALTY_BANK_ACCOUNT_UUID` **REFUND\_ACCOUNT** Money is transferred from this account when an order is refunded. * Default UUID: ae73f88d-0fea-42d6-a695-36217b9b091b * Setting to change UUID in settings.py: `LOYALTY_REFUND_ACCOUNT_UUID` *** ### `POST` Creating Loyalty Account **Path:** `https://{omnitron}/api/v1/remote/{commerce_channel_id}/loyalty_account/` **Request** ```js { "number": "e74496da-c3e7-4a91-b382-514f638d2141", // uuid "user_email": "john.doe@akinon.com", // user email "balance": "100.00", // setting balance "debit_allowed": true, // wheter the balance might be negative or not "user": 414185, "currency": "eur" } ``` **Response** ```js { "pk": 34, "number": "e74496da-c3e7-4a91-b382-514f638d2141", "user_email": "john.doe@akinon.com", "balance": "100.00", "debit_allowed": true, "created_date": "2023-10-24T10:57:04.761432Z", "modified_date": "2023-10-24T10:57:04.761461Z", "user": 414185, "currency": "eur" } ``` *** ### `PATCH` Updating Loyalty Accounts **Path:** `https://{omnitron}/api/v1/remote/{commerce_channel_id}/loyalty_account//` **Request** ```json { "balance": "130.00" } ``` **Response** ```json { "pk": 40, "number": "e74496da-c3e7-4a91-b382-514f628a2641", "user_email": "john.doe@akinon.com", "balance": "130.00", "debit_allowed": true, "created_date": "2023-10-25T08:09:42.312892Z", "modified_date": "2023-10-25T08:40:45.368986Z", "user": 414185 } ``` Add the fields that need to be updated to the request. ### `GET` Listing Loyalty Accounts **Path:** `https://{omnitron}/api/v1/remote/{commerce_channel_id}/loyalty_account/` **Response** ```json { "count": 1, "next": null, "previous": null, "results": [ { "pk": 10, "number": "3792b3e0ac0840b188a096d0198bc8b7", "user_email": "john.doe@akinon.com", "balance": "0.00", "debit_allowed": false, "created_date": "2023-10-23T14:15:12.433363Z", "modified_date": "2023-10-23T14:34:12.185468Z", "user": 414185, "currency": "try" } ] } ``` *** ### `GET` Listing Loyalty Transfers **Path:** `https://{omnitron}/api/v1/remote/{commerce_channel_id}/loyalty_transfer/` When an order is paid using loyalty points, transfers are recorded. Here's an example of a response with two loyalty transfers: * $138.40 charged from the order owner. * $138.40 transferred to the sale account. **Response** ```json { "count": 1, "next": null, "previous": null, "results": [ { "amount": "-14.00", "transaction": { "order": "2428483542614519", "created_date": "2023-10-23T14:12:56.846147Z" }, "created_date": "2023-10-23T14:12:56.849493Z", "currency": "try" } ] } ``` *** ### `POST` Creating Loyalty Transfer **Path:** `https://{omnitron}/api/v1/remote/{commerce_channel_id}/loyalty_account/6/create_transfer/` Transfers loyalty points from a source account to a destination account. **Request** ```json { "amount": "20", "source_account": 9, "destination_account": 6 } ``` **Response** Empty response. *** ### `POST` Refunding in Loyalty **Path:** `https://{omnitron}/api/v1/remote/{commerce_channel_id}/loyalty-transactions/refund/` Users can transfer a desired amount from the sale account to the order owner's account with the refund process. In the request below, the transaction UUID of the loyalty transaction in the order and the desired amount are passed. If `invoice_number` is sent, a new account will be created with the information below: * **Number:** `IN010` * **User:** Order owner **Request** ```json { "transaction_uuid": "e74496da-c3e7-4a91-b382-517c638d11425", "amount": "20", "invoice_number": "IN010" // not required } ``` **Response** ```json { "pk": 2, "uuid": "51536d0f-10de-4ba3-98b6-6df05ede5b16", "amount": "20.00", "order": 189, "user": 414148, "user_email": "iso@iso.com", "reference": "2352410252911715" } ``` *** ### `POST` Cross Refunding in Loyalty **Path:** `https://{omnitron}/api/v1/remote/{commerce_channel_id}/loyalty-transactions/cross-refund/` The same refunding process as above can be done with the following request: **Request** ```json { "order_number": "010101010", "amount": "20", "invoice_number": "IN010" // not required } ``` **Response** ```json { "pk": 2, "uuid": "51536d0f-10de-4ba3-98b6-6df05ede5b16", "amount": "20.00", "order": 189, "user": 414148, "user_email": "iso@iso.com", "reference": "2352410252911715" } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://apidocs.akinon.com/commerce/loyalty-accounts.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.