Skip to content

Get a customer's plan

GET
/customers/{customer_id}/plan
curl --request GET \
--url 'https://api.poweredbyaura.com/v1/customers/CUS-204871/plan?campaign_id=cmp_01JA9TQ4W2D8M5X4N6B1C0VEKA' \
--header 'Authorization: Bearer <token>'

Where one customer stands on their plan: its size, this period’s data, what keeps it and when the period ends. Use it to build your own plan screen, or use the plan card instead.

For a customer in the comparison group, status is not_offered: don’t show them the plan.

customer_id
required
string

Your own ID for the customer, as you send it in actions.

Example

CUS-204871
campaign_id
string

The campaign whose plan to return. Required when the customer is in more than one campaign.

Example

cmp_01JA9TQ4W2D8M5X4N6B1C0VEKA

The customer’s plan.

Media typeapplication/json
object
id
required
string
object
required
string
Allowed value: plan
campaign_id
required
string
customer_id
required
string
name
required

The plan’s name as customers see it.

string
status
required

not_offered: the customer is in the comparison group. offered: the plan was offered, after its start action or by an offer, and waits for the customer to accept. active: accepted, and this period is kept or still open. at_risk: the warning has gone out and this period’s action isn’t in yet. cancelled: a period ended without its action. ended: the customer held the plan for its full length, or the campaign ended.

string
Allowed values: not_offered offered active at_risk cancelled ended
phone_number
required

The number that gets the data. null until the customer accepts.

string | null
network_id
required
string | null
value
required
One of:
object
amount
required

Amount in the currency’s minor unit (kobo for NGN).

integer
currency
required

ISO 4217 currency code.

string
/^[A-Z]{3}$/
cadence
required

How often the plan’s data arrives, and so how long each period is.

string
Allowed values: daily weekly monthly
monthly_gb
required

An amount of mobile data in gigabytes (GB), as set in the plan, to at most two decimal places.

number
multiple of 0.01
delivery_gb
required

An amount of mobile data in gigabytes (GB), as set in the plan, to at most two decimal places.

number
multiple of 0.01
current_period
required

The period in progress. null when the plan isn’t running.

object
number
required

Which period of the plan this is, from 1.

integer
starts_at
required
string format: date-time
ends_at
required
string format: date-time
warning_at
required

When plan.at_risk goes out if the period isn’t kept by then.

string format: date-time
kept
required

Whether this period’s action is in.

boolean
actions_needed
required

The actions that keep this period, with their readable names for your screens.

Array<object>
object
key
required
string
name
required
string
delivered_gb
required

An amount of mobile data in gigabytes (GB), as set in the plan, to at most two decimal places.

number
multiple of 0.01
this_month
required
object
delivered_gb
required

An amount of mobile data in gigabytes (GB), as set in the plan, to at most two decimal places.

number
multiple of 0.01
grows
required

When the plan grows next, if a plan that grows is on.

object
after_period
required
integer
delivery_gb
required

An amount of mobile data in gigabytes (GB), as set in the plan, to at most two decimal places.

number
multiple of 0.01
offered_at
required

When the plan was offered, by its start action or by an offer.

string | null format: date-time
accepted_at
required

When the customer accepted and the plan started.

string | null format: date-time
ended_at
required
string | null format: date-time
end_reason
required
string | null
Allowed values: missed_period held_full_length campaign_ended
can_restart_from
required

When a cancelled plan can start again, in Lagos time. null when it can’t restart.

string | null format: date
number_change_from
required

The first day the customer can change their number again.

string | null format: date
terms
required

The plan terms the customer agrees to when they accept. text already has the plan’s name, amounts and your app’s name filled in: show it unchanged on your own plan screen, and send version as terms_version when the customer accepts. The plan card shows the same text.

object
version
required

The terms’ version.

string
text
required

The terms as plain text, ready to show.

string
url
required

The same terms as a web page.

string format: uri
test
required
boolean

Examples

Exampleactive

An active weekly plan, kept this week

{
"id": "pln_01JAC4XB7Q2W9D8M5X4N6B1C0V",
"object": "plan",
"campaign_id": "cmp_01JA9TQ4W2D8M5X4N6B1C0VEKA",
"customer_id": "CUS-204871",
"name": "Your 6GB plan from Your Savings App",
"status": "active",
"phone_number": "+2348000000001",
"network_id": "net_ng_a",
"value": {
"amount": 400000,
"currency": "NGN"
},
"cadence": "weekly",
"monthly_gb": 6,
"delivery_gb": 1.5,
"current_period": {
"number": 3,
"starts_at": "2026-10-18T23:00:00Z",
"ends_at": "2026-10-25T22:59:59Z",
"warning_at": "2026-10-23T22:59:59Z",
"kept": true,
"actions_needed": [
{
"key": "weekly_deposit",
"name": "Weekly deposit"
}
],
"delivered_gb": 1.5
},
"this_month": {
"delivered_gb": 4.5
},
"grows": null,
"offered_at": "2026-10-06T09:12:00Z",
"accepted_at": "2026-10-06T09:15:40Z",
"ended_at": null,
"end_reason": null,
"can_restart_from": null,
"number_change_from": "2026-10-06",
"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. If a week ends without a deposit, the plan stops. …",
"url": "https://app.poweredbyaura.com/plan-terms/2026-10-21"
},
"test": false
}
Aura-Request-Id
string
Example
req_7Kp2Vx9QmR4t

A unique ID for this request. Quote it when you contact Aura.

The request is malformed or a field is invalid. Fix it before retrying.

Media typeapplication/json
object
error
required
object
code
required

A stable, machine-readable code. New codes may be added in v1, so treat an unknown code by its HTTP status and retryable flag. The first block is shared with the Data Reselling API.

string
Allowed values: invalid_request invalid_phone_number invalid_api_key ip_not_allowed not_found reference_conflict rate_limited internal_error unknown_campaign unknown_action campaign_not_live campaign_required plan_not_offered already_accepted already_offered campaign_starts_with_action number_change_too_soon number_on_another_plan
message
required

A human-readable explanation. Do not parse it; use code.

string
param

The request field the error is about, when there is one.

string
retryable
required

Whether the same request can succeed if you retry it later.

boolean
request_id
required
string
details

Extra facts about the error, such as the existing action.

object
key
additional properties
any

Examples

ExampleinvalidPhoneNumber
{
"error": {
"code": "invalid_phone_number",
"message": "phone_number must be in E.164 format, such as +2348000000001.",
"param": "phone_number",
"retryable": false,
"request_id": "req_9Qd4Hs1XvB7n"
}
}
Aura-Request-Id
string
Example
req_7Kp2Vx9QmR4t

A unique ID for this request. Quote it when you contact Aura.

The API key is missing, wrong or revoked.

Media typeapplication/json
object
error
required
object
code
required

A stable, machine-readable code. New codes may be added in v1, so treat an unknown code by its HTTP status and retryable flag. The first block is shared with the Data Reselling API.

string
Allowed values: invalid_request invalid_phone_number invalid_api_key ip_not_allowed not_found reference_conflict rate_limited internal_error unknown_campaign unknown_action campaign_not_live campaign_required plan_not_offered already_accepted already_offered campaign_starts_with_action number_change_too_soon number_on_another_plan
message
required

A human-readable explanation. Do not parse it; use code.

string
param

The request field the error is about, when there is one.

string
retryable
required

Whether the same request can succeed if you retry it later.

boolean
request_id
required
string
details

Extra facts about the error, such as the existing action.

object
key
additional properties
any

Examples

ExampleinvalidKey
{
"error": {
"code": "invalid_api_key",
"message": "The API key is missing, wrong or revoked.",
"retryable": false,
"request_id": "req_4Lm8Tc2VqZ7k"
}
}
Aura-Request-Id
string
Example
req_7Kp2Vx9QmR4t

A unique ID for this request. Quote it when you contact Aura.

Nothing with this ID exists in your account, in this mode (test or live).

Media typeapplication/json
object
error
required
object
code
required

A stable, machine-readable code. New codes may be added in v1, so treat an unknown code by its HTTP status and retryable flag. The first block is shared with the Data Reselling API.

string
Allowed values: invalid_request invalid_phone_number invalid_api_key ip_not_allowed not_found reference_conflict rate_limited internal_error unknown_campaign unknown_action campaign_not_live campaign_required plan_not_offered already_accepted already_offered campaign_starts_with_action number_change_too_soon number_on_another_plan
message
required

A human-readable explanation. Do not parse it; use code.

string
param

The request field the error is about, when there is one.

string
retryable
required

Whether the same request can succeed if you retry it later.

boolean
request_id
required
string
details

Extra facts about the error, such as the existing action.

object
key
additional properties
any

Examples

ExamplenotFound
{
"error": {
"code": "not_found",
"message": "No customer with ID 'CUS-204871' has been reported to this campaign.",
"retryable": false,
"request_id": "req_5Nk3Ry8BwH1c"
}
}
Aura-Request-Id
string
Example
req_7Kp2Vx9QmR4t

A unique ID for this request. Quote it when you contact Aura.

Too many requests. Wait for Retry-After seconds, then retry.

Media typeapplication/json
object
error
required
object
code
required

A stable, machine-readable code. New codes may be added in v1, so treat an unknown code by its HTTP status and retryable flag. The first block is shared with the Data Reselling API.

string
Allowed values: invalid_request invalid_phone_number invalid_api_key ip_not_allowed not_found reference_conflict rate_limited internal_error unknown_campaign unknown_action campaign_not_live campaign_required plan_not_offered already_accepted already_offered campaign_starts_with_action number_change_too_soon number_on_another_plan
message
required

A human-readable explanation. Do not parse it; use code.

string
param

The request field the error is about, when there is one.

string
retryable
required

Whether the same request can succeed if you retry it later.

boolean
request_id
required
string
details

Extra facts about the error, such as the existing action.

object
key
additional properties
any

Examples

ExamplerateLimited
{
"error": {
"code": "rate_limited",
"message": "Too many requests. Retry after 2 seconds.",
"retryable": true,
"request_id": "req_2Vb7Nx4KtJ9q"
}
}
Aura-Request-Id
string
Example
req_7Kp2Vx9QmR4t

A unique ID for this request. Quote it when you contact Aura.

RateLimit-Limit
integer

Requests allowed in the current window.

RateLimit-Remaining
integer

Requests left in the current window.

RateLimit-Reset
integer

Seconds until the current window resets.

Retry-After
integer

Seconds to wait before retrying.