Campaigns

Base URL: $BUSINESS_API

List promotional credit campaigns

Logs

GET /campaigns

Newest first, one cursor page at a time. The response is the standard page (data, has_more, next_cursor); items repeats data for older clients.

Parameters

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Campaign page

Errors 400

Permissions invoices:read · Roles: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/campaigns" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Campaign page

Create a promotional credit campaign

Logs

POST /campaigns

Creates a promotional credit campaign in draft status; customers cannot redeem its code until the campaign is activated. name and a positive amount_minor are required; currency defaults to MZN and per_account_limit to 1. The code is stored only as a hash, and the response exposes only its first four characters as code_prefix. Requires the invoices:write permission.

Returns

201 Campaign created

Permissions invoices:write · Roles: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/campaigns" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{}'
Response 201

Campaign created

Get a promotional credit campaign

Logs

GET /campaigns/{id}

Returns one campaign with its status, credit amount, budget and amount spent, redemption count and limits, eligible charge kinds and validity window. The promo code itself is never returned, only its prefix. Returns 404 when the campaign is not in this tenant. Requires invoices:read.

Parameters

idstring · path · required

Id of the promotional campaign (prefix prc).

Returns

200 Campaign details

Permissions invoices:read · Roles: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/campaigns/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Campaign details

Activate a promotional credit campaign

Logs

POST /campaigns/{id}/activate

Moves a draft or paused campaign to active so its code can be redeemed; redemptions still respect starts_at, ends_at, the budget and the redemption limits. Activating a campaign in any other status returns 400 as an invalid state transition. Requires invoices:write.

Parameters

idstring · path · required

Id of the promotional campaign to activate (prefix prc).

Returns

200 Campaign activated

Permissions invoices:write · Roles: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/campaigns/{id}/activate" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Campaign activated

Pause a promotional credit campaign

Logs

POST /campaigns/{id}/pause

Moves an active campaign to paused, after which redemptions of its code are refused until it is activated again. Credits already granted are not affected. Pausing a campaign that is not active returns 400 as an invalid state transition. Requires invoices:write.

Parameters

idstring · path · required

Id of the promotional campaign to pause (prefix prc).

Returns

200 Campaign paused

Permissions invoices:write · Roles: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/campaigns/{id}/pause" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Campaign paused