Skip to main content

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": "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​

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

Request​

{
    "balance": "130.00"
}

Response​

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

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

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

{
    "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": "iso@iso.com",
    "reference": "2352410252911715"
}