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

{
    "number": "e74496da-c3e7-4a91-b382-514f638d2141", // uuid
    "user_email": "[e-mail]", // user email
    "balance": "100.00", // setting balance
    "debit_allowed": true, // wheter the balance might be negative or not
    "user": 414185,
    "currency": "eur"
}

Response

{
    "pk": 34,
    "number": "e74496da-c3e7-4a91-b382-514f638d2141",
    "user_email": "[e-mail]",
    "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/<pk>/

Request

{
    "balance": "130.00"
}

Response

{
    "pk": 40,
    "number": "e74496da-c3e7-4a91-b382-514f628a2641",
    "user_email": "[e-mail]",
    "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

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "pk": 10,
            "number": "3792b3e0ac0840b188a096d0198bc8b7",
            "user_email": "[e-mail]",
            "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

{
    "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

{
    "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

{
    "transaction_uuid": "e74496da-c3e7-4a91-b382-517c638d11425",
    "amount": "20",
    "invoice_number": "IN010" // not required
}

Response

{
    "pk": 2,
    "uuid": "51536d0f-10de-4ba3-98b6-6df05ede5b16",
    "amount": "20.00",
    "order": 189,
    "user": 414148,
    "user_email": "[e-mail]",
    "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

{
    "order_number": "010101010",
    "amount": "20",
    "invoice_number": "IN010" // not required
}

Response

{
    "pk": 2,
    "uuid": "51536d0f-10de-4ba3-98b6-6df05ede5b16",
    "amount": "20.00",
    "order": 189,
    "user": 414148,
    "user_email": "[e-mail]",
    "reference": "2352410252911715"
}