SapaganDocs sapagan.com

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)

Accepted keys Server key

Parameters

NameInTypeNotes
scopeIdquerystring (uuid)
limitqueryinteger
curl -X GET "$SAPAGAN_URL/v1/billing/audit" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key

curl -X GET "$SAPAGAN_URL/v1/billing/catalogue" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden. Errors use the error body.

Example response 200

{
  "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

Accepted keys Server key

Request body

FieldTypeNotes
reason requiredstringmin 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"
  }'

Responses

200 OK, 400 Invalid request, 403 Forbidden, 409 Conflict. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key

Parameters

NameInTypeNotes
periodquerystring required
curl -X GET "$SAPAGAN_URL/v1/billing/netting?period=%3Cperiod%3E" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 400 Invalid request, 403 Forbidden. Errors use the error body.

Example response 200

{
  "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

Accepted keys Server key

Parameters

NameInTypeNotes
periodquerystring required
curl -X GET "$SAPAGAN_URL/v1/billing/netting.csv?period=%3Cperiod%3E" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 400 Invalid request, 403 Forbidden. Errors use the error body.

PATCH /v1/billing/plans/{code}#

Rename a plan, change its description, or stop sellers choosing it (owner); audited

Accepted keys Server key

Parameters

NameInTypeNotes
codepathstring required

Request body

FieldTypeNotes
namestringmin 1, max 80
descriptionstring or nullmax 500
activeboolean
reason requiredstringmin 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"
  }'

Responses

200 OK, 400 Invalid request, 403 Forbidden, 404 Not found. Errors use the error body.

Example response 200

{
  "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

Accepted keys Server key

Request body

FieldTypeNotes
product required"plan_monthly" | "topup_campaign"
planCode requiredstringmin 1, max 32
channel"push" | "email" | "inapp"
amountIdr requiredintegermin 0, max 100000000
validityPeriodsintegermin 1, max 12
effectiveFromstring (date-time)
notestringmax 500
reason requiredstringmin 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"
  }'

Responses

201 Created, 400 Invalid request, 403 Forbidden, 404 Not found. Errors use the error body.

Example response 201

{
  "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

Accepted keys Server key

curl -X GET "$SAPAGAN_URL/v1/billing/settings" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden. Errors use the error body.

Example response 200

{
  "operatorCreditMaxIdr": 1,
  "operatorCreditDailyMaxIdr": 1,
  "carryNegativeNet": true
}

PUT /v1/billing/settings#

Change the billing settings (owner), with a reason; audited

Accepted keys Server key

Request body

FieldTypeNotes
operatorCreditMaxIdrintegermin 0, max 100000000
operatorCreditDailyMaxIdrintegermin 0, max 100000000
carryNegativeNetboolean
reason requiredstringmin 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"
  }'

Responses

200 OK, 400 Invalid request, 403 Forbidden. Errors use the error body.

Example response 200

{
  "operatorCreditMaxIdr": 1,
  "operatorCreditDailyMaxIdr": 1,
  "carryNegativeNet": true
}

GET /v1/billing/statements#

Statements of the workspace for a period

Accepted keys Server key

Parameters

NameInTypeNotes
periodquerystring required
curl -X GET "$SAPAGAN_URL/v1/billing/statements?period=%3Cperiod%3E" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden. Errors use the error body.

Example response 200

{
  "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

Accepted keys Server key

Parameters

NameInTypeNotes
statementIdpathstring (uuid) required

Request body

FieldTypeNotes
reference requiredstringmin 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>"
  }'

Responses

200 OK, 400 Invalid request, 403 Forbidden, 404 Not found, 409 Conflict. Errors use the error body.

Example response 200

{
  "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

Accepted keys Server key

Request body

FieldTypeNotes
period requiredstring
reasonstringmax 2000
curl -X POST "$SAPAGAN_URL/v1/billing/statements/issue" \
  -H "Authorization: Bearer $SAPAGAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "period": "<period>"
  }'

Responses

200 OK, 400 Invalid request, 403 Forbidden, 409 Conflict. Errors use the error body.

Example response 200

{
  "period": "<period>",
  "statements": 1,
  "totalIdr": 1
}

GET /v1/scope/ledger#

The store's ledger lines of one period (a statement's detail)

Accepted keys Store key Store token

Parameters

NameInTypeNotes
periodquerystring required
curl -X GET "$SAPAGAN_URL/v1/scope/ledger?period=%3Cperiod%3E" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden, 404 Not found. Errors use the error body.

Example response 200

{
  "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

Accepted keys Store key Store token

curl -X GET "$SAPAGAN_URL/v1/scope/plan" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden, 404 Not found. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Store key Store token

Request body

FieldTypeNotes
planCode requiredstringmin 1, max 32
expectedPriceIdstring (uuid)
expectedMonthlyIdrintegermin 0
expectedProrationIdrintegermin 0
curl -X POST "$SAPAGAN_URL/v1/scope/plan/change" \
  -H "Authorization: Bearer $SAPAGAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "planCode": "<planCode>"
  }'

Responses

200 OK, 400 Invalid request, 403 Forbidden, 404 Not found, 409 Conflict. Errors use the error body.

Example response 200

{
  "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).

Accepted keys Store key Store token

Request body

FieldTypeNotes
channel required"push" | "email" | "inapp"
campaigns requiredintegermin 1, max 20
expectedPriceIdstring (uuid)
expectedUnitIdrintegermin 0
curl -X POST "$SAPAGAN_URL/v1/scope/topups" \
  -H "Authorization: Bearer $SAPAGAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "push",
    "campaigns": 1
  }'

Responses

200 OK, 201 Created, 400 Invalid request, 403 Forbidden, 404 Not found, 409 Conflict, 422 Unprocessable. Errors use the error body.

Example response 200

{
  "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)

Accepted keys Server key

Parameters

NameInTypeNotes
idpathstring required
curl -X GET "$SAPAGAN_URL/v1/scopes/user-42/billing" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden, 404 Not found. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key

Parameters

NameInTypeNotes
idpathstring required

Request body

FieldTypeNotes
amountIdrintegermin 0, max 100000000
campaignsintegermin 0, max 1000
channel"push" | "email" | "inapp"
reason requiredstringmin 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"
  }'

Responses

201 Created, 400 Invalid request, 403 Forbidden, 404 Not found. Errors use the error body.

Example response 201

{
  "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

Accepted keys Server key

Parameters

NameInTypeNotes
idpathstring required

Request body

FieldTypeNotes
planCode requiredstringmin 1, max 32
when required"now" | "next_period"
chargeboolean
reason requiredstringmin 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"
  }'

Responses

200 OK, 400 Invalid request, 403 Forbidden, 404 Not found, 409 Conflict. Errors use the error body.

Example response 200

{
  "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

Accepted keys Server key

Parameters

NameInTypeNotes
idpathstring required

Request body

FieldTypeNotes
reason requiredstringmin 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"
  }'

Responses

200 OK, 400 Invalid request, 403 Forbidden, 404 Not found, 409 Conflict. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key

Parameters

NameInTypeNotes
idpathstring required

Request body

FieldTypeNotes
entryId requiredstring (uuid)
amountIdr requiredintegermin 0, max 100000000
revokeCampaignsintegermin 0, max 10000
reason requiredstringmin 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"
  }'

Responses

201 Created, 400 Invalid request, 403 Forbidden, 404 Not found, 409 Conflict. Errors use the error body.

Example response 201

{
  "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>"
}