Skip to content

The plan card

The plan card is a page Aura hosts, in your brand, that opens inside your app. It shows the customer their plan: this week’s data, what keeps it and when the week ends. On it, the customer accepts the plan, chooses which of their numbers gets the data, and can change the number later.

When the customer taps to see their plan, your server creates a link and your app opens it in a web view:

Terminal window
curl https://api.poweredbyaura.com/v1/customers/CUS-204871/plan-card-links \
-H "Authorization: Bearer $AURA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"campaign_id": "cmp_01JA9TQ4W2D8M5X4N6B1C0VEKA",
"return_url": "yourapp://home"
}'
{
"object": "plan_card_link",
"url": "https://plan.poweredbyaura.com/c/pcl_01JAD2V7K9M3T6R8F1H4P5QX2N?sig=9f2c7d1e",
"expires_at": "2026-10-20T09:52:00Z"
}
  • Create links on your server, never in the app, so your secret key never leaves your server.
  • Each link opens once. It expires 10 minutes after it is created if nobody opens it. Create a new one each time the customer taps.
  • return_url is where the card’s Done button takes the customer, such as a screen in your app.

A customer in the comparison group has no plan to show: the call returns 422 plan_not_offered. Don’t show them a way in to the card.

The plan is Show
offered An invitation to accept, which opens the card.
active or at_risk A way to see the plan, and, when at risk, what keeps it this week.
cancelled or ended Nothing, or when the customer can start again, from can_restart_from.
not_offered Nothing.

The webhooks tell you when each of these changes.

If you would rather show the plan in your own design, three endpoints do what the card does.

GET /customers/{customer_id}/plan returns everything the card shows: the plan’s name, its size (delivery_gb and monthly_gb), current_period with its readable actions_needed and ends_at, value, what the plan is worth a month at the retail price on the customer’s network, in kobo, and terms, the plan terms the customer agrees to:

"terms": {
"version": "2026-10-21",
"text": "Your 6GB plan from Your Savings App gives you 1.5GB of mobile data each week while you save at least ₦5,000 each week. …",
"url": "https://app.poweredbyaura.com/plan-terms/2026-10-21"
}

terms.text is plain text with the plan’s name, amounts and your app’s name already filled in, and it is the same text the plan card shows. Every plan in a webhook carries it too.

POST /customers/{customer_id}/plan/accept records that the customer accepted, which version of the plan terms you showed them, and which number gets the data:

{
"campaign_id": "cmp_01JA9TQ4W2D8M5X4N6B1C0VEKA",
"phone_number": "+2348000000001",
"terms_version": "2026-10-21",
"accepted_at": "2026-10-20T09:41:12+01:00"
}

The plan comes back active and its first data is on the way, exactly as when the customer accepts on the card.

POST /customers/{customer_id}/plan/phone-number moves the plan to another of the customer’s numbers. The next delivery goes to the new number. A plan’s number can change at most once a month; number_change_from on the plan gives the first day it can change again.

When accepting or changing number is refused

Section titled “When accepting or changing number is refused”
HTTP code What it means
400 invalid_request A field is invalid, or terms_version isn’t the current version of the plan’s terms. param names the field.
422 already_accepted The customer has already accepted this plan.
422 plan_not_offered The customer is in the comparison group.
422 number_on_another_plan That number already holds this plan for another customer. Ask for another number.
422 number_change_too_soon The number changed less than a month ago. details.available_from gives the date.

A number can hold the same plan for more than one customer only if you have switched on stacking for your account or the campaign.

The API and webhooks carry phone numbers in full, because they run server to server. Keep them on your servers. In the dashboard, phone numbers are masked.