Skip to content

Offer a plan to a customer

POST
/offers
curl --request POST \
--url https://api.poweredbyaura.com/v1/offers \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "reference": "off-552018", "campaign_id": "cmp_01JAE3M8Q4W7T2K9R5F1H6P3NB", "customer_id": "CUS-204871", "phone_number": "+2348000000001", "source": "october_offer" }'

For campaigns that start plans by offer. Offers the plan to one customer, with no action needed first. The customer accepts it on the plan card, or on your own screen, and the plan starts with the first week’s data.

The first time you report a customer, Aura places them at random in the offer group or the comparison group. Don’t show the plan to customers in the comparison group: group is comparison and the plan is not_offered. Keep sending their actions, so the results can show what the plan caused.

An offer stays open until the customer accepts or the campaign ends. reference makes the request safe to retry, exactly as for actions.

Media typeapplication/json
object
reference
required

Your unique ID for this offer. Letters, numbers, -, _, . and :, up to 64 characters.

string
/^[A-Za-z0-9._:-]{1,64}$/
campaign_id
required
string
customer_id
required

Your own ID for the customer. Up to 64 characters. Never send names.

string
<= 64 characters
phone_number
required

The customer’s number on your records, in E.164 format. When they accept, they can choose another of their numbers for the data.

string
source

Optional. Where the offer went out, such as a campaign in your app, for the cost per new customer by source.

string
<= 64 characters
metadata

Up to 20 keys of your own, returned on the offer and in webhooks.

object
<= 20 properties
key
additional properties
string
<= 500 characters

Examples

Exampleoffer
{
"reference": "off-552018",
"campaign_id": "cmp_01JAE3M8Q4W7T2K9R5F1H6P3NB",
"customer_id": "CUS-204871",
"phone_number": "+2348000000001",
"source": "october_offer"
}

An offer with this reference and the same body already exists. It is returned as it is now.

Media typeapplication/json
object
id
required
string
object
required
string
Allowed value: offer
reference
required
string
campaign_id
required
string
customer_id
required
string
phone_number
required
string
source
string | null
group
required

The customer’s group. Don’t show the plan to customers in the comparison group.

string
Allowed values: offer comparison
plan
required
object
id
required
string
object
required
string
Allowed value: plan
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
current_period
required
object
ends_at
required
string format: date-time
kept
required
boolean
created_at
required
string format: date-time
test
required
boolean
metadata
required
object
key
additional properties
string

Examples

Exampleoffered

A plan offered, waiting for the customer to accept

{
"id": "off_01JAE3N2T7K4W9R1F6H3P8QX5L",
"object": "offer",
"reference": "off-552018",
"campaign_id": "cmp_01JAE3M8Q4W7T2K9R5F1H6P3NB",
"customer_id": "CUS-204871",
"phone_number": "+2348000000001",
"source": "october_offer",
"group": "offer",
"plan": {
"id": "pln_01JAE3N2T7K4W9R1F6H3P8QX5M",
"object": "plan",
"status": "offered",
"current_period": null
},
"created_at": "2026-10-20T09:30:00Z",
"test": false,
"metadata": {}
}
Aura-Request-Id
string
Example
req_7Kp2Vx9QmR4t

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

Aura-Idempotent-Replay
string
Allowed value: true

Always true on a replayed response.

The offer was made, or the customer was placed in the comparison group.

Media typeapplication/json
object
id
required
string
object
required
string
Allowed value: offer
reference
required
string
campaign_id
required
string
customer_id
required
string
phone_number
required
string
source
string | null
group
required

The customer’s group. Don’t show the plan to customers in the comparison group.

string
Allowed values: offer comparison
plan
required
object
id
required
string
object
required
string
Allowed value: plan
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
current_period
required
object
ends_at
required
string format: date-time
kept
required
boolean
created_at
required
string format: date-time
test
required
boolean
metadata
required
object
key
additional properties
string

Examples

Exampleoffered

A plan offered, waiting for the customer to accept

{
"id": "off_01JAE3N2T7K4W9R1F6H3P8QX5L",
"object": "offer",
"reference": "off-552018",
"campaign_id": "cmp_01JAE3M8Q4W7T2K9R5F1H6P3NB",
"customer_id": "CUS-204871",
"phone_number": "+2348000000001",
"source": "october_offer",
"group": "offer",
"plan": {
"id": "pln_01JAE3N2T7K4W9R1F6H3P8QX5M",
"object": "plan",
"status": "offered",
"current_period": null
},
"created_at": "2026-10-20T09:30:00Z",
"test": false,
"metadata": {}
}
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.

An offer with this reference exists with a different body. Nothing changed.

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

Example

{
"error": {
"code": "invalid_request"
}
}
Aura-Request-Id
string
Example
req_7Kp2Vx9QmR4t

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

The offer can’t be made: the campaign starts plans after an action, isn’t live for this key, or the customer already has an offer or a plan in it. Nothing changed.

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

{
"error": {
"code": "campaign_starts_with_action",
"message": "This campaign starts plans after an action. Report the action instead of sending an offer.",
"param": "campaign_id",
"retryable": false,
"request_id": "req_7Jd2Rk5NwB9t"
}
}
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.

Something went wrong on Aura’s side. Retry with the same reference; it is safe.

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

Exampleinternal
{
"error": {
"code": "internal_error",
"message": "Something went wrong on our side. Retry with the same reference.",
"retryable": true,
"request_id": "req_6Gt1Mz5RcW3p"
}
}
Aura-Request-Id
string
Example
req_7Kp2Vx9QmR4t

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