API reference
Billing
Marketplace workspaces only. Store plans, top-ups, the ledger and statements.
Marketplace workspaces only. Store plans, top-ups, the ledger and statements.
GET /v1/billing/audit#
Billing audit trail: catalogue, prices, plans set, credits, refunds, statements (newest first)
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
scopeId | query | string (uuid) | |
limit | query | integer |
curl -X GET "$SAPAGAN_URL/v1/billing/audit" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/billing/audit`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"entries": [
{
"id": "user-42",
"scopeId": "<scopeId>",
"action": "<action>",
"actor": "<actor>",
"reason": "Checked with the owner",
"before": null,
"after": null,
"occurredAt": "<occurredAt>"
}
]
}GET /v1/billing/catalogue#
Plans with the prices in force and scheduled, and every price version (workspace keys and console)
timeZone is the workspace's: billing periods are its calendar months; currentPeriod is the month now.
curl -X GET "$SAPAGAN_URL/v1/billing/catalogue" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/billing/catalogue`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"timeZone": "<timeZone>",
"currentPeriod": "<currentPeriod>",
"plans": [
{
"code": "<code>",
"tier": "free",
"rank": 1,
"name": "order_placed",
"description": "<description>",
"active": true,
"monthlyPrice": {
"id": "user-42",
"product": "plan_monthly",
"planCode": "<planCode>",
"channel": "push",
"amountIdr": 1,
"validityPeriods": 1,
"version": 1,
"effectiveFrom": "<effectiveFrom>",
"note": "Looks good"
},
"topups": {
"push": {
"id": "user-42",
"product": "plan_monthly",
"planCode": "<planCode>",
"channel": "push",
"amountIdr": 1,
"validityPeriods": 1,
"version": 1,
"effectiveFrom": "<effectiveFrom>",
"note": "Looks good"
},
"email": {
"id": "user-42",
"product": "plan_monthly",
"planCode": "<planCode>",
"channel": "push",
"amountIdr": 1,
"validityPeriods": 1,
"version": 1,
"effectiveFrom": "<effectiveFrom>",
"note": "Looks good"
},
"inapp": {
"id": "user-42",
"product": "plan_monthly",
"planCode": "<planCode>",
"channel": "push",
"amountIdr": 1,
"validityPeriods": 1,
"version": 1,
"effectiveFrom": "<effectiveFrom>",
"note": "Looks good"
}
},
"scheduled": [
{
"id": "user-42",
"product": "plan_monthly",
"planCode": "<planCode>",
"channel": "push",
"amountIdr": 1,
"validityPeriods": 1,
"version": 1,
"effectiveFrom": "<effectiveFrom>",
"note": "Looks good"
}
]
}
],
"prices": [
{
"id": "user-42",
"product": "plan_monthly",
"planCode": "<planCode>",
"channel": "push",
"amountIdr": 1,
"validityPeriods": 1,
"version": 1,
"effectiveFrom": "<effectiveFrom>",
"note": "Looks good",
"createdBy": "<createdBy>",
"createdAt": "<createdAt>"
}
]
}POST /v1/billing/catalogue/seed#
Load the PRD v2 draft plans and prices into a workspace that has none (owner); audited
Request body
| Field | Type | Notes |
|---|---|---|
reason required | string | min 3, max 2000 |
curl -X POST "$SAPAGAN_URL/v1/billing/catalogue/seed" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"reason": "Checked with the owner"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/billing/catalogue/seed`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"reason": "Checked with the owner"
}),
});
const data = await res.json();Responses
{
"plans": [
{
"code": "<code>",
"tier": "free",
"rank": 1,
"name": "order_placed",
"description": "<description>",
"active": true,
"monthlyPrice": {
"id": "user-42",
"product": "plan_monthly",
"planCode": "<planCode>",
"channel": "push",
"amountIdr": 1,
"validityPeriods": 1,
"version": 1,
"effectiveFrom": "<effectiveFrom>",
"note": "Looks good"
},
"topups": {
"push": {
"id": "user-42",
"product": "plan_monthly",
"planCode": "<planCode>",
"channel": "push",
"amountIdr": 1,
"validityPeriods": 1,
"version": 1,
"effectiveFrom": "<effectiveFrom>",
"note": "Looks good"
},
"email": {
"id": "user-42",
"product": "plan_monthly",
"planCode": "<planCode>",
"channel": "push",
"amountIdr": 1,
"validityPeriods": 1,
"version": 1,
"effectiveFrom": "<effectiveFrom>",
"note": "Looks good"
},
"inapp": {
"id": "user-42",
"product": "plan_monthly",
"planCode": "<planCode>",
"channel": "push",
"amountIdr": 1,
"validityPeriods": 1,
"version": 1,
"effectiveFrom": "<effectiveFrom>",
"note": "Looks good"
}
},
"scheduled": [
{
"id": "user-42",
"product": "plan_monthly",
"planCode": "<planCode>",
"channel": "push",
"amountIdr": 1,
"validityPeriods": 1,
"version": 1,
"effectiveFrom": "<effectiveFrom>",
"note": "Looks good"
}
]
}
]
}GET /v1/billing/netting#
The payout-netting export of a period for Toco finance (P2-14), JSON
Every ledger line of the period per store, the store's net (sum of its lines) and deduction (max(0, net)), and totals. Act only on final: true (the period is closed and every store has a statement). CSV: GET /v1/billing/netting.csv.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
period | query | string required |
curl -X GET "$SAPAGAN_URL/v1/billing/netting?period=%3Cperiod%3E" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/billing/netting?period=%3Cperiod%3E`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"format": "sapagan.payout-netting.v1",
"workspaceId": "<workspaceId>",
"period": "<period>",
"timeZone": "<timeZone>",
"currency": "IDR",
"paymentMethod": "payout_netting",
"final": true,
"closedAt": "<closedAt>",
"generatedAt": "<generatedAt>",
"totals": {
"stores": 1,
"lines": 1,
"chargesIdr": 1,
"creditsIdr": 1,
"netIdr": 1,
"deductIdr": 1
},
"stores": [
{
"scopeId": "<scopeId>",
"storeExternalId": "<storeExternalId>",
"storeName": "<storeName>",
"statementId": "<statementId>",
"status": "open",
"netIdr": 1,
"deductIdr": 1,
"settlementRef": "<settlementRef>",
"lines": [
{
"lineId": "<lineId>",
"kind": "plan_charge",
"amountIdr": 1,
"campaigns": 1,
"channel": "<channel>",
"reversesId": "<reversesId>",
"description": "<description>",
"createdAt": "<createdAt>"
}
]
}
]
}GET /v1/billing/netting.csv#
The payout-netting export of a period as CSV: one row per ledger line
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
period | query | string required |
curl -X GET "$SAPAGAN_URL/v1/billing/netting.csv?period=%3Cperiod%3E" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/billing/netting.csv?period=%3Cperiod%3E`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
PATCH /v1/billing/plans/{code}#
Rename a plan, change its description, or stop sellers choosing it (owner); audited
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
code | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
name | string | min 1, max 80 |
description | string or null | max 500 |
active | boolean | |
reason required | string | min 3, max 2000 |
curl -X PATCH "$SAPAGAN_URL/v1/billing/plans/<code>" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"reason": "Checked with the owner"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/billing/plans/<code>`, {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"reason": "Checked with the owner"
}),
});
const data = await res.json();Responses
{
"code": "<code>",
"name": "order_placed",
"description": "<description>",
"active": true
}POST /v1/billing/prices#
A new price version (owner): applies to charges made from effectiveFrom (default now); earlier charges keep theirs; audited
Request body
| Field | Type | Notes |
|---|---|---|
product required | "plan_monthly" | "topup_campaign" | |
planCode required | string | min 1, max 32 |
channel | "push" | "email" | "inapp" | |
amountIdr required | integer | min 0, max 100000000 |
validityPeriods | integer | min 1, max 12 |
effectiveFrom | string (date-time) | |
note | string | max 500 |
reason required | string | min 3, max 2000 |
curl -X POST "$SAPAGAN_URL/v1/billing/prices" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"product": "plan_monthly",
"planCode": "<planCode>",
"amountIdr": 0,
"reason": "Checked with the owner"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/billing/prices`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"product": "plan_monthly",
"planCode": "<planCode>",
"amountIdr": 0,
"reason": "Checked with the owner"
}),
});
const data = await res.json();Responses
{
"id": "user-42",
"product": "plan_monthly",
"planCode": "<planCode>",
"channel": "push",
"amountIdr": 1,
"validityPeriods": 1,
"version": 1,
"effectiveFrom": "<effectiveFrom>",
"note": "Looks good",
"createdBy": "<createdBy>",
"createdAt": "<createdAt>"
}GET /v1/billing/settings#
Billing settings: what an operator may credit without an owner (per call, per day), and whether a negative net is carried forward
curl -X GET "$SAPAGAN_URL/v1/billing/settings" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/billing/settings`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"operatorCreditMaxIdr": 1,
"operatorCreditDailyMaxIdr": 1,
"carryNegativeNet": true
}PUT /v1/billing/settings#
Change the billing settings (owner), with a reason; audited
Request body
| Field | Type | Notes |
|---|---|---|
operatorCreditMaxIdr | integer | min 0, max 100000000 |
operatorCreditDailyMaxIdr | integer | min 0, max 100000000 |
carryNegativeNet | boolean | |
reason required | string | min 3, max 2000 |
curl -X PUT "$SAPAGAN_URL/v1/billing/settings" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"reason": "Checked with the owner"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/billing/settings`, {
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"reason": "Checked with the owner"
}),
});
const data = await res.json();Responses
{
"operatorCreditMaxIdr": 1,
"operatorCreditDailyMaxIdr": 1,
"carryNegativeNet": true
}GET /v1/billing/statements#
Statements of the workspace for a period
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
period | query | string required |
curl -X GET "$SAPAGAN_URL/v1/billing/statements?period=%3Cperiod%3E" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/billing/statements?period=%3Cperiod%3E`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"period": "<period>",
"statements": [
{
"id": "user-42",
"scopeId": "<scopeId>",
"period": "<period>",
"totalIdr": 1,
"chargesIdr": 1,
"creditsIdr": 1,
"lineCount": 1,
"paymentMethod": "payout_netting",
"status": "issued",
"issuedAt": "<issuedAt>",
"settledAt": "<settledAt>",
"settlementRef": "<settlementRef>",
"storeName": "<storeName>",
"storeExternalId": "<storeExternalId>"
}
]
}POST /v1/billing/statements/{statementId}/settle#
Toco's acknowledgement (P2-14) that a statement was deducted from the payout, with Toco's reference; once; audited
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
statementId | path | string (uuid) required |
Request body
| Field | Type | Notes |
|---|---|---|
reference required | string | min 1, max 200 |
curl -X POST "$SAPAGAN_URL/v1/billing/statements/<statementId>/settle" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"reference": "<reference>"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/billing/statements/<statementId>/settle`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"reference": "<reference>"
}),
});
const data = await res.json();Responses
{
"id": "user-42",
"scopeId": "<scopeId>",
"period": "<period>",
"totalIdr": 1,
"chargesIdr": 1,
"creditsIdr": 1,
"lineCount": 1,
"paymentMethod": "payout_netting",
"status": "issued",
"issuedAt": "<issuedAt>",
"settledAt": "<settledAt>",
"settlementRef": "<settlementRef>"
}POST /v1/billing/statements/issue#
Close an ended period: book missing plan charges, then one statement per store; idempotent; audited
Request body
| Field | Type | Notes |
|---|---|---|
period required | string | |
reason | string | max 2000 |
curl -X POST "$SAPAGAN_URL/v1/billing/statements/issue" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"period": "<period>"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/billing/statements/issue`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"period": "<period>"
}),
});
const data = await res.json();Responses
{
"period": "<period>",
"statements": 1,
"totalIdr": 1
}GET /v1/scope/ledger#
The store's ledger lines of one period (a statement's detail)
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
period | query | string required |
curl -X GET "$SAPAGAN_URL/v1/scope/ledger?period=%3Cperiod%3E" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scope/ledger?period=%3Cperiod%3E`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"period": "<period>",
"lines": [
{
"id": "user-42",
"period": "<period>",
"kind": "plan_charge",
"amountIdr": 1,
"campaigns": 1,
"channel": "push",
"validUntilPeriod": "<validUntilPeriod>",
"description": "<description>",
"createdAt": "<createdAt>"
}
]
}GET /v1/scope/plan#
The store's plan, usage this period, reset date, plans to compare, top-ups on sale, this period's lines and statements
curl -X GET "$SAPAGAN_URL/v1/scope/plan" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scope/plan`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"period": "<period>",
"timeZone": "<timeZone>",
"periodStartsAt": "<periodStartsAt>",
"resetsAt": "<resetsAt>",
"tier": "free",
"plan": {
"code": "<code>",
"name": "order_placed",
"tier": "free",
"rank": 1,
"source": "plan",
"since": "<since>",
"monthlyPriceIdr": 1,
"byToco": true,
"paysMonthlyIdr": 1
},
"scheduled": {
"toPlanCode": "<toPlanCode>",
"toPlanName": "<toPlanName>",
"effectiveAt": "<effectiveAt>",
"monthlyPriceIdr": 1,
"byToco": true
},
"usage": [
{
"channel": "push",
"used": 1,
"extra": 1,
"credits": 1,
"quota": 1,
"remaining": 1
}
],
"allowedChannels": [
"push"
],
"reachCap": 1,
"plans": [
{
"code": "<code>",
"tier": "free",
"rank": 1,
"name": "order_placed",
"description": "<description>",
"active": true,
"monthlyPrice": {
"id": "user-42",
"product": "plan_monthly",
"planCode": "<planCode>",
"channel": "push",
"amountIdr": 1,
"validityPeriods": 1,
"version": 1,
"effectiveFrom": "<effectiveFrom>"
},
"topups": {
"push": {
"id": "user-42",
"product": "plan_monthly",
"planCode": "<planCode>",
"channel": "push",
"amountIdr": 1,
"validityPeriods": 1,
"version": 1,
"effectiveFrom": "<effectiveFrom>"
},
"email": {
"id": "user-42",
"product": "plan_monthly",
"planCode": "<planCode>",
"channel": "push",
"amountIdr": 1,
"validityPeriods": 1,
"version": 1,
"effectiveFrom": "<effectiveFrom>"
},
"inapp": {
"id": "user-42",
"product": "plan_monthly",
"planCode": "<planCode>",
"channel": "push",
"amountIdr": 1,
"validityPeriods": 1,
"version": 1,
"effectiveFrom": "<effectiveFrom>"
}
},
"scheduled": [
{
"id": "user-42",
"product": "plan_monthly",
"planCode": "<planCode>",
"channel": "push",
"amountIdr": 1,
"validityPeriods": 1,
"version": 1,
"effectiveFrom": "<effectiveFrom>"
}
],
"limits": {
"reachCap": 1,
"monthlyQuota": {
"push": 1,
"email": 1,
"inapp": 1
},
"dailyMax": 1
},
"upgradeQuoteIdr": 1
}
],
"topups": [
{
"channel": "push",
"priceId": "<priceId>",
"priceIdr": 1,
"validityPeriods": 1
}
],
"maxTopupCampaigns": 1,
"periodTotalIdr": 1,
"previousOpen": {
"period": "<period>",
"totalIdr": 1,
"lines": 1
},
"paymentMethod": "payout_netting",
"lines": [
{
"id": "user-42",
"period": "<period>",
"kind": "plan_charge",
"amountIdr": 1,
"campaigns": 1,
"channel": "push",
"validUntilPeriod": "<validUntilPeriod>",
"description": "<description>",
"createdAt": "<createdAt>"
}
],
"statements": [
{
"id": "user-42",
"period": "<period>",
"totalIdr": 1,
"chargesIdr": 1,
"creditsIdr": 1,
"lineCount": 1,
"paymentMethod": "payout_netting",
"status": "issued",
"issuedAt": "<issuedAt>",
"settledAt": "<settledAt>"
}
]
}POST /v1/scope/plan/change#
Change the store's plan: an upgrade applies now with a prorated charge, a downgrade at the next period
Choosing the plan the store is on while a downgrade is waiting cancels the downgrade (downgrade_cancelled). Otherwise 409 already_on_plan.
Request body
| Field | Type | Notes |
|---|---|---|
planCode required | string | min 1, max 32 |
expectedPriceId | string (uuid) | |
expectedMonthlyIdr | integer | min 0 |
expectedProrationIdr | integer | min 0 |
curl -X POST "$SAPAGAN_URL/v1/scope/plan/change" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"planCode": "<planCode>"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scope/plan/change`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"planCode": "<planCode>"
}),
});
const data = await res.json();Responses
{
"outcome": "upgraded",
"toPlanCode": "<toPlanCode>",
"effectiveAt": "<effectiveAt>",
"charge": {
"id": "user-42",
"period": "<period>",
"kind": "plan_charge",
"amountIdr": 1,
"campaigns": 1,
"channel": "push",
"validUntilPeriod": "<validUntilPeriod>",
"description": "<description>",
"createdAt": "<createdAt>"
}
}POST /v1/scope/topups#
Buy extra campaigns of one channel for the current period, at the store's plan's top-up price; Idempotency-Key required
The key is also the ledger's: the same request charges once (a replay answers the first response). Not sold on free (409 topup_not_available) nor for a channel the store may not use (409 channel_not_allowed).
Request body
| Field | Type | Notes |
|---|---|---|
channel required | "push" | "email" | "inapp" | |
campaigns required | integer | min 1, max 20 |
expectedPriceId | string (uuid) | |
expectedUnitIdr | integer | min 0 |
curl -X POST "$SAPAGAN_URL/v1/scope/topups" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"channel": "push",
"campaigns": 1
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scope/topups`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"channel": "push",
"campaigns": 1
}),
});
const data = await res.json();Responses
{
"line": {
"id": "user-42",
"period": "<period>",
"kind": "plan_charge",
"amountIdr": 1,
"campaigns": 1,
"channel": "push",
"validUntilPeriod": "<validUntilPeriod>",
"description": "<description>",
"createdAt": "<createdAt>"
},
"replayed": true
}GET /v1/scopes/{id}/billing#
A store's plan, usage, ledger (newest first), statements and plan history (workspace keys and console)
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
curl -X GET "$SAPAGAN_URL/v1/scopes/user-42/billing" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scopes/user-42/billing`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"period": "<period>",
"timeZone": "<timeZone>",
"periodStartsAt": "<periodStartsAt>",
"resetsAt": "<resetsAt>",
"tier": "free",
"plan": {
"code": "<code>",
"name": "order_placed",
"tier": "free",
"rank": 1,
"source": "plan",
"since": "<since>",
"monthlyPriceIdr": 1,
"byToco": true,
"paysMonthlyIdr": 1
},
"scheduled": {
"toPlanCode": "<toPlanCode>",
"toPlanName": "<toPlanName>",
"effectiveAt": "<effectiveAt>",
"monthlyPriceIdr": 1,
"byToco": true
},
"usage": [
{
"channel": "push",
"used": 1,
"extra": 1,
"credits": 1,
"quota": 1,
"remaining": 1
}
],
"allowedChannels": [
"push"
],
"reachCap": 1,
"plans": [
{
"code": "<code>",
"tier": "free",
"rank": 1,
"name": "order_placed",
"description": "<description>",
"active": true,
"monthlyPrice": {
"id": "user-42",
"product": "plan_monthly",
"planCode": "<planCode>",
"channel": "push",
"amountIdr": 1,
"validityPeriods": 1,
"version": 1,
"effectiveFrom": "<effectiveFrom>",
"note": "Looks good"
},
"topups": {
"push": {
"id": "user-42",
"product": "plan_monthly",
"planCode": "<planCode>",
"channel": "push",
"amountIdr": 1,
"validityPeriods": 1,
"version": 1,
"effectiveFrom": "<effectiveFrom>",
"note": "Looks good"
},
"email": {
"id": "user-42",
"product": "plan_monthly",
"planCode": "<planCode>",
"channel": "push",
"amountIdr": 1,
"validityPeriods": 1,
"version": 1,
"effectiveFrom": "<effectiveFrom>",
"note": "Looks good"
},
"inapp": {
"id": "user-42",
"product": "plan_monthly",
"planCode": "<planCode>",
"channel": "push",
"amountIdr": 1,
"validityPeriods": 1,
"version": 1,
"effectiveFrom": "<effectiveFrom>",
"note": "Looks good"
}
},
"scheduled": [
{
"id": "user-42",
"product": "plan_monthly",
"planCode": "<planCode>",
"channel": "push",
"amountIdr": 1,
"validityPeriods": 1,
"version": 1,
"effectiveFrom": "<effectiveFrom>",
"note": "Looks good"
}
],
"limits": {
"reachCap": 1,
"monthlyQuota": {
"push": 1,
"email": 1,
"inapp": 1
},
"dailyMax": 1
},
"upgradeQuoteIdr": 1
}
],
"topups": [
{
"channel": "push",
"priceId": "<priceId>",
"priceIdr": 1,
"validityPeriods": 1
}
],
"maxTopupCampaigns": 1,
"periodTotalIdr": 1,
"previousOpen": {
"period": "<period>",
"totalIdr": 1,
"lines": 1
},
"paymentMethod": "payout_netting",
"scopeId": "<scopeId>",
"lines": [
{
"id": "user-42",
"period": "<period>",
"kind": "plan_charge",
"amountIdr": 1,
"campaigns": 1,
"channel": "push",
"validUntilPeriod": "<validUntilPeriod>",
"description": "<description>",
"createdAt": "<createdAt>",
"priceId": "<priceId>",
"planChangeId": "<planChangeId>",
"reversesId": "<reversesId>",
"paymentMethod": "payout_netting",
"idempotencyKey": "<idempotencyKey>",
"reason": "Checked with the owner",
"actor": "<actor>"
}
],
"statements": [
{
"id": "user-42",
"scopeId": "<scopeId>",
"period": "<period>",
"totalIdr": 1,
"chargesIdr": 1,
"creditsIdr": 1,
"lineCount": 1,
"paymentMethod": "payout_netting",
"status": "issued",
"issuedAt": "<issuedAt>",
"settledAt": "<settledAt>",
"settlementRef": "<settlementRef>"
}
],
"planHistory": [
{
"id": "user-42",
"fromPlanCode": "<fromPlanCode>",
"toPlanCode": "<toPlanCode>",
"kind": "upgrade",
"effectiveAt": "<effectiveAt>",
"monthlyPriceIdr": 1,
"status": "active",
"requestedBy": "<requestedBy>",
"reason": "Checked with the owner",
"createdAt": "<createdAt>",
"cancelledAt": "<cancelledAt>"
}
]
}POST /v1/scopes/{id}/credits#
A manual credit with a reason: rupiah off the period's total, extra campaigns of one channel this period, or both; audited
Idempotency-Key required (the console sends one per form): a double submit books one line. An operator session may credit up to the workspace's limits (GET /v1/billing/settings); above them 409 credit_limit and an owner gives it.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
amountIdr | integer | min 0, max 100000000 |
campaigns | integer | min 0, max 1000 |
channel | "push" | "email" | "inapp" | |
reason required | string | min 3, max 2000 |
curl -X POST "$SAPAGAN_URL/v1/scopes/user-42/credits" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"reason": "Checked with the owner"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scopes/user-42/credits`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"reason": "Checked with the owner"
}),
});
const data = await res.json();Responses
{
"id": "user-42",
"period": "<period>",
"kind": "plan_charge",
"amountIdr": 1,
"campaigns": 1,
"channel": "push",
"validUntilPeriod": "<validUntilPeriod>",
"description": "<description>",
"createdAt": "<createdAt>",
"priceId": "<priceId>",
"planChangeId": "<planChangeId>",
"reversesId": "<reversesId>",
"paymentMethod": "payout_netting",
"idempotencyKey": "<idempotencyKey>",
"reason": "Checked with the owner",
"actor": "<actor>"
}POST /v1/scopes/{id}/plan#
Set a store's plan now or from the next period, with a reason; charge books the prorated difference of a change now; audited
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
planCode required | string | min 1, max 32 |
when required | "now" | "next_period" | |
charge | boolean | |
reason required | string | min 3, max 2000 |
curl -X POST "$SAPAGAN_URL/v1/scopes/user-42/plan" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"planCode": "<planCode>",
"when": "now",
"reason": "Checked with the owner"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scopes/user-42/plan`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"planCode": "<planCode>",
"when": "now",
"reason": "Checked with the owner"
}),
});
const data = await res.json();Responses
{
"outcome": "upgraded",
"toPlanCode": "<toPlanCode>",
"effectiveAt": "<effectiveAt>",
"charge": {
"id": "user-42",
"period": "<period>",
"kind": "plan_charge",
"amountIdr": 1,
"campaigns": 1,
"channel": "push",
"validUntilPeriod": "<validUntilPeriod>",
"description": "<description>",
"createdAt": "<createdAt>"
}
}POST /v1/scopes/{id}/plan/cancel#
Cancel a store's waiting plan change (a scheduled downgrade), with a reason; audited
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
reason required | string | min 3, max 2000 |
curl -X POST "$SAPAGAN_URL/v1/scopes/user-42/plan/cancel" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"reason": "Checked with the owner"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scopes/user-42/plan/cancel`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"reason": "Checked with the owner"
}),
});
const data = await res.json();Responses
{
"cancelled": true,
"toPlanCode": "<toPlanCode>"
}POST /v1/scopes/{id}/refunds#
Refund (part of) a charge line with a reason (owner), optionally taking back its campaigns; never more than the line; audited
Idempotency-Key required (the console sends one per form): a double submit books one refund.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
entryId required | string (uuid) | |
amountIdr required | integer | min 0, max 100000000 |
revokeCampaigns | integer | min 0, max 10000 |
reason required | string | min 3, max 2000 |
curl -X POST "$SAPAGAN_URL/v1/scopes/user-42/refunds" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"entryId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
"amountIdr": 0,
"reason": "Checked with the owner"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scopes/user-42/refunds`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"entryId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
"amountIdr": 0,
"reason": "Checked with the owner"
}),
});
const data = await res.json();Responses
{
"id": "user-42",
"period": "<period>",
"kind": "plan_charge",
"amountIdr": 1,
"campaigns": 1,
"channel": "push",
"validUntilPeriod": "<validUntilPeriod>",
"description": "<description>",
"createdAt": "<createdAt>",
"priceId": "<priceId>",
"planChangeId": "<planChangeId>",
"reversesId": "<reversesId>",
"paymentMethod": "payout_netting",
"idempotencyKey": "<idempotencyKey>",
"reason": "Checked with the owner",
"actor": "<actor>"
}