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.
Opening the card
Section titled “Opening the card”When the customer taps to see their plan, your server creates a link and your app opens it in a web view:
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_urlis 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.
When to show it
Section titled “When to show it”| 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.
Building your own plan screen
Section titled “Building your own plan screen”If you would rather show the plan in your own design, three endpoints do what the card does.
Show the plan
Section titled “Show the plan”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.
Accept
Section titled “Accept”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.
Change the number
Section titled “Change the number”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.
Phone numbers
Section titled “Phone numbers”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.
© 2026 PressOne Africa Limited ·poweredbyaura.com ·Privacy ·Terms