Skip to content

Commit a9e2e53

Browse files
soldatov-sssoldatov-ss
committed
add more documentation about promoter and getting started
1 parent 9dd0795 commit a9e2e53

File tree

5 files changed

+180
-11
lines changed

5 files changed

+180
-11
lines changed

‎docs/getting_started.rst‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
Getting Started
2+
==================
3+
4+
1. Create a Referral Program
5+
6+
After installation, you can create a new referral program using the provided management command. If this program is set to active, any previous active referral programs will be deactivated automatically.
7+
8+
.. code-block:: bash
9+
10+
python manage.py create_referral_program --name="My Referral Program" --commission-rate=5.00 --min-withdrawal-balance=10.00
11+
12+
2. Set Up Environment Variables
13+
14+
In order to generate referral links, you need to set up the following environment variables in your `.env` file:
15+
16+
.. code-block:: bash
17+
18+
BASE_REFERRAL_LINK=http://localhost:8000/
19+
20+
This variable will be used to construct the referral links. Ensure that the base URL reflects your application's domain or local environment.

‎docs/index.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ Welcome to django-referral-system's documentation!
1111
:caption: Contents:
1212

1313
installation
14+
getting_started
15+
promoter
1416

1517

1618
Key Features

‎docs/installation.rst‎

Lines changed: 0 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -34,12 +34,3 @@ Follow these steps to install and set up `django-referral-system`:
3434
.. code-block:: bash
3535
3636
python manage.py migrate
37-
38-
5. Create a Referral Program:
39-
40-
After installation, you can create a new referral program using the provided management command.
41-
If this program is set to active, any previous active referral programs will be deactivated automatically.
42-
43-
.. code-block:: bash
44-
45-
python manage.py create_referral_program --name="My Referral Program" --commission-rate=5.00 --min-withdrawal-balance=10.00

‎docs/promoter.rst‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
Promoter Logic
2+
==============
3+
4+
5+
1. Promoter Creation
6+
--------------------
7+
8+
A promoter is created by associating a `User` with a referral token and referral link. Promoters are responsible for sending out referral links, tracking referrals, and earning commissions.
9+
10+
You can retrieve or create a promoter for a user using the following API action:
11+
12+
- **Retrieve Promoter**: This endpoint retrieves or creates a promoter for the authenticated user.
13+
14+
.. code-block:: bash
15+
16+
GET http://localhost:8000/referrals/promoter
17+
Accept: application/json
18+
Authorization: Bearer your_token
19+
20+
21+
Example response:
22+
23+
.. code-block:: json
24+
25+
{
26+
"id": 2,
27+
"user": 1,
28+
"referralToken": "6B86B273FF",
29+
"referralLink": "http://localhost:8000/?ref=6B86B273FF",
30+
"currentBalance": 0,
31+
"totalEarned": 0,
32+
"totalPaid": 0,
33+
"created": "2024-08-24T12:12:03.374694Z",
34+
"updated": "2024-09-08T09:11:15.032367Z",
35+
"linkClicked": 0,
36+
"minWithdrawalBalance": "20.00",
37+
"commissionRate": 15.0
38+
}
39+
40+
2. Setting the Payout Method
41+
-----------------------------
42+
43+
Promoters can set their preferred payout method using the following API action:
44+
45+
- **Set Payout Method**: This endpoint allows promoters to set their payout method (e.g., Wise, Crypto) and payment address (email or wallet address).
46+
47+
.. code-block:: bash
48+
49+
PATCH http://localhost:8000/referrals/set-payout-method/
50+
Content-Type: application/json
51+
Authorization: Bearer your_token
52+
53+
{
54+
"method": "wise",
55+
"payment_address": "[email protected]"
56+
}
57+
58+
59+
Example response:
60+
61+
.. code-block:: json
62+
63+
{
64+
"id": 2,
65+
"user": 1,
66+
"referralToken": "6B86B273FF",
67+
"referralLink": "http://localhost:8000/?ref=6B86B273FF",
68+
"activePayoutMethod": {
69+
"method": "wise",
70+
"paymentAddress": "[email protected]"
71+
},
72+
"currentBalance": 0,
73+
"totalEarned": 0,
74+
"totalPaid": 0,
75+
"created": "2024-08-24T12:12:03.374694Z",
76+
"updated": "2024-09-08T09:11:15.032367Z",
77+
"linkClicked": 0,
78+
"minWithdrawalBalance": "20.00",
79+
"commissionRate": 15.0
80+
}
81+
82+
The promoter’s payout method is used when processing their earnings.
83+
84+
3. Tracking Referrals and Earnings
85+
-----------------------------------
86+
87+
Once a promoter is created, they can start sharing their referral link. The system tracks clicks on the referral link and the earnings generated from those referrals. Promoters can retrieve their recent earnings and view a breakdown of their performance over the last 7 days.
88+
89+
To view the promoter's recent earnings:
90+
91+
.. code-block:: bash
92+
93+
GET http://localhost:8000/referrals/promoter-recent-earnings
94+
Accept: application/json
95+
Authorization: Bearer your_token
96+
97+
Example response:
98+
99+
.. code-block:: json
100+
101+
[
102+
{
103+
"day": "Mon",
104+
"value": 50
105+
},
106+
{
107+
"day": "Tue",
108+
"value": 0
109+
},
110+
{
111+
"day": "Wed",
112+
"value": 30
113+
},
114+
{
115+
"day": "Thu",
116+
"value": 70
117+
},
118+
{
119+
"day": "Fri",
120+
"value": 20
121+
},
122+
{
123+
"day": "Sat",
124+
"value": 0
125+
},
126+
{
127+
"day": "Sun",
128+
"value": 10
129+
}
130+
]
131+
132+
The response contains a list of the last 7 days, with each day showing the corresponding earnings value. Even if no earnings occurred on a particular day, it is still represented with a value of `0`. The earnings are grouped by the day of the week when they were created.
133+
134+
4. Incrementing Link Clicks
135+
----------------------------
136+
137+
Every time a referral link is clicked, the system can increment the count of link clicks for the promoter. This can be done via the following API action:
138+
139+
.. code-block:: bash
140+
141+
POST http://localhost:8000/referrals/increment-link-clicked/
142+
Content-Type: application/json
143+
Authorization: Bearer your_token
144+
145+
{
146+
"referral_token": "6B86B273FF"
147+
}
148+
149+
150+
Example response:
151+
152+
.. code-block:: json
153+
154+
{
155+
"message": "Link clicked count incremented successfully"
156+
}

‎referrals/services/referral_service.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -190,7 +190,7 @@ def handle_purchase_subscription(user: User,
190190
logger.info(f"User {user.email} became an active referral of {promoter.user.email}")
191191
return commission
192192
except ObjectDoesNotExist:
193-
logger.error(f"User with ID {user.id} has no referral associated.")
193+
logger.warning(f"User with ID {user.id} has no referral associated.")
194194

195195
@staticmethod
196196
@transaction.atomic
@@ -221,7 +221,7 @@ def handle_user_refund(user: User, amount_refunded: int, amount_paid: int,
221221
logger.info(f"User {user.email} has been refunded {amount_refunded}.")
222222
return commission
223223
except ObjectDoesNotExist:
224-
logger.error(f"User with ID {user.id} has no referral associated.")
224+
logger.warning(f"User with ID {user.id} has no referral associated.")
225225

226226

227227
referral_service = ReferralService()

0 commit comments

Comments
 (0)