PT EN

Campanhas promocionais

URL base: $BUSINESS_API

Listar campanhas promocionais

Registos

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.

Parâmetros

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Campaign page

Erros 400

Permissões invoices:read · Funções: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

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

Campaign page

Criar uma campanha promocional

Registos

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.

Devolve

201 Campaign created

Permissões invoices:write · Funções: admin, billing_clerk, finance, owner

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

Campaign created

Obter uma campanha promocional

Registos

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.

Parâmetros

idstring · caminho · obrigatório

Id of the promotional campaign (prefix prc).

Devolve

200 Campaign details

Permissões invoices:read · Funções: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

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

Campaign details

Activar uma campanha promocional

Registos

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.

Parâmetros

idstring · caminho · obrigatório

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

Devolve

200 Campaign activated

Permissões invoices:write · Funções: admin, billing_clerk, finance, owner

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

Campaign activated

Pausar uma campanha promocional

Registos

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.

Parâmetros

idstring · caminho · obrigatório

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

Devolve

200 Campaign paused

Permissões invoices:write · Funções: admin, billing_clerk, finance, owner

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

Campaign paused