Skip to content

How a plan runs

A plan is what one customer holds in one campaign. It starts when the customer accepts it, and they keep it by doing the plan’s action each week. This page follows a weekly plan; daily and monthly plans work the same way, per day or per month.

Each campaign starts its plans in one of two ways, shown in the campaign’s starts_with.

starts_with is action. The plan is offered when you report the action marked starts_plan, such as a first deposit. That action earns the first week’s data, which waits for the customer to accept: its reward is waiting_for_customer and the plan is offered.

If the customer hasn’t accepted by the end of that week, the waiting data lapses with customer_not_accepted, and nothing is charged.

starts_with is offer. You pick the customers and offer them the plan, with no action needed first:

Terminal window
curl https://api.poweredbyaura.com/v1/offers \
-H "Authorization: Bearer $AURA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"reference": "off-552018",
"campaign_id": "cmp_01JAE3M8Q4W7T2K9R5F1H6P3NB",
"customer_id": "CUS-204871",
"phone_number": "+2348000000001",
"source": "october_offer"
}'

The answer, 201, carries the customer’s group and the plan, offered. An offer stays open until the customer accepts or the campaign ends. Your reference makes the call safe to retry, exactly as for actions.

HTTP code What it means
422 campaign_starts_with_action This campaign starts plans after an action. Report the action instead.
422 already_offered The customer already has an offer or a plan in this campaign. details.plan_id names it.
422 campaign_not_live The campaign isn’t live for this key.

Offers can also be uploaded as a CSV file or sent from the dashboard. The same rules against bonus hunters apply to offers: one reward per phone number, the campaign’s limits, and only you choose who gets an offer.

The customer accepts on the plan card, or on your own screen, and chooses which of their numbers gets the data. Then:

  1. The plan starts, with status active, and Aura sends plan.started.
  2. Aura checks the number’s network and delivers the first week’s data straight away.
  3. Accepting counts as keeping the week it happens in, so the plan’s action is first needed the following week.

Weeks run Monday to Sunday, and days midnight to midnight, in Lagos time. A monthly plan’s month runs from the day it started. The week in progress is the plan’s current_period:

Field What it holds
number Which week of the plan this is, from 1.
starts_at, ends_at When the week starts and ends, in UTC.
warning_at When plan.at_risk goes out if the week isn’t kept by then.
kept Whether this week’s action is in.
actions_needed The actions that keep the week, with their readable names for your screens.
delivered_gb The data delivered for this week so far.

An action marked keeps_plan keeps the plan for the week it happens in and earns that week’s data. One reward per week: a second action in a kept week earns nothing, with already_rewarded, and still counts in your results.

At warning_at, Aura sends plan.at_risk for each customer who hasn’t done this week’s action, and the plan’s status becomes at_risk. Tell the customer in your app and your own channels that the plan cancels unless they act before the week ends.

The warning goes out 48 hours before a weekly or monthly period ends, and 6 hours before a daily one. You can change both in the dashboard.

If a week ends without its action, the plan cancels: status becomes cancelled, Aura sends plan.cancelled, and the customer gets nothing the next week. Aura waits for late actions for 2 hours after the week ends before it decides.

The customer can start a new plan from the next month, unless you turn restarts off for the campaign. can_restart_from gives the date.

When a customer keeps their plan through a whole month, Aura sends plan.renewed, with recap holding the data delivered and the weeks kept in the month just ended.

A plan that grows is off by default. When you switch it on, the plan moves up to a bigger size after a number of weeks kept, and Aura sends plan.resized, with previous holding the size before. The campaign’s grows shows when and to what size.

A plan ends, with status ended, when the customer has held it for the campaign’s full length (periods), or when the campaign ends. end_reason says which. Actions after that earn nothing and still count in your results.

status What it means
not_offered The customer is in the comparison group. Don’t show them the plan.
offered The plan was offered, after its start action or by an offer, and waits for the customer to accept.
active Accepted, and this week is kept or still open.
at_risk The warning has gone out and this week’s action isn’t in yet.
cancelled A week ended without its action.
ended The customer held the plan for its full length, or the campaign ended.

GET /customers/{customer_id}/plan returns one customer’s plan as it is now: its name, size, this week’s data, what keeps it and when the week ends. Use your own customer ID. If the customer is in more than one campaign, add campaign_id; without it you get 400 campaign_required.