The credits ledger (credits/*) and coupons (coupons/*): push and read balances, page through records, mint, verify and claim coupons.
Push credits to customer account. value is an integer (negative = a charge). The central incore ledger (the platform AI wallet) moves for master only; identity tokens never push.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
store | string | required | Store ID. |
id | string | required | Customer ID. |
value | number | required | Amount of credits to push. |
record | string | optional | Optional record ID to update. |
note | string | optional | Optional label stored on the credits record (e.g. what the charge was for). |
Response
object — Returns the new total value.
Sample request
{
"id": "user_123",
"value": 100,
"note": "Welcome bonus"
}Get customer credits value.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
store | string | required | Store ID. |
id | string | required | Customer ID. |
Response
object — Returns the credits object with value. Incore-ledger wallets settle their weekly free bucket on read and additionally carry free, free_tier, spent and free_expires (ms timestamp the current period ends).
Sample request
{
"id": "user_123"
}Master-only: force-settle a store's weekly free-credit bucket in the incore ledger and regrant it when the subscription plan changed (mid-week upgrade/downgrade/cancel effect). Idempotent per (period, plan) - redelivered tier events are no-ops. Called server-to-server by the tier order hook receiver.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
store | string | required | Must be the incore ledger (store: incore). |
id | string | required | The store id whose wallet to refresh. |
Response
object — Returns the settled wallet (value, free, free_tier, spent, free_period) plus free_expires.
Sample request
{
"id": "{storeId}"
}The store header must be incore (the ledger); id is the store whose wallet is refreshed.
List a customer's credit records (the per-user ledger).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
store | string | required | Store ID. |
id | string | required | Customer ID. |
query | object | optional | Firestore query filter (field -> operator/value). |
order_by | object | optional | Ordering (field -> 'asc' | 'desc'). |
limit | number | optional | Max number of records to return. |
offset | number | optional | Pagination offset (number or cursor). |
mask | array | optional | Field names to project from each record. |
Response
array — Returns the list of credit records.
Sample request
{
"id": "user_123",
"order_by": {
"timestamp": "desc"
},
"limit": 20
}Mint exactly one new code for a dynamic or generated coupon batch. Rejects static batches. Authorized by a master/owner token, or by presenting the batch's secret (bearer credential for external campaign tools).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
store | string | required | Store ID. |
id | string | required | Batch ID to mint a code for. |
customer | string | optional | Bind the minted code to a single customer id. |
limit | number | optional | Per-code use limit (falls back to the batch default, then 1). |
secret | string | optional | Batch bearer secret, when minting without a master/owner token. |
Response
object — Returns the newly minted code.
Sample request
{
"id": "spring-sale"
}Bulk-mint many codes for a dynamic or generated batch in chunked Firestore batched writes. Hard-capped at 10000 per request. Same auth as mint (master/owner token or the batch secret). Returns a summary (count + timing), not the codes.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
store | string | required | Store ID. |
id | string | required | Batch ID to mint codes for. |
count | number | required | How many codes to mint (1..10000). |
customer | string | optional | Bind every minted code to a single customer id. |
limit | number | optional | Per-code use limit (falls back to the batch default, then 1). |
secret | string | optional | Batch bearer secret, when minting without a master/owner token. |
Response
object — Returns {minted, requested, chunks, ms}.
Sample request
{
"id": "spring-sale",
"count": 500
}Read-only validation of a coupon code against the batch rule chain. Returns the computed effect or a machine-readable rejection reason. Never mutates.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
store | string | required | Store ID. |
code | string | required | Coupon code to validate (or a static batch id). |
customer | string | optional | Customer id, for customer-bound coupons. |
order_value | number | optional | Cart value, to check the minimum-order condition. |
products | array | optional | Cart product/category ids, to check applicability/restriction. |
secret | string | optional | Batch bearer secret, for token-less external callers. |
Response
object — Returns {valid, batch, effect?, reason?, unverified?}. effect is {type, value?, max_discount?, product?} plus, for batches carrying a subscription duration, duration (repeating|forever; absent = once) and duration_months - enough to render "-25% for 3 months" before checkout.
Sample request
{
"code": "SPRING25",
"order_value": 120
}Redeem a coupon in a transaction — re-runs the rule chain, increments usage and flips the code to claimed when its limit is reached. This is the primitive the order flow calls at checkout.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
store | string | required | Store ID. |
code | string | required | Coupon code to redeem (or a static batch id). |
customer | string | optional | Redeeming customer id (recorded as claimed_by). |
order | string | optional | Order id (recorded as claimed_order). |
order_value | number | optional | Cart value, to check the minimum-order condition. |
products | array | optional | Cart product/category ids, to check applicability/restriction. |
secret | string | optional | Batch bearer secret, for token-less external callers. |
Response
object — Returns {valid, batch, effect} on success; a 400 with {valid:false, reason} otherwise.
Sample request
{
"code": "SPRING25",
"customer": "user_123",
"order": "ord_123"
}