> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce/loyalty-accounts.md). # 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 This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://apidocs.akinon.com/commerce/loyalty-accounts.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.