v1

latestOpenAPI 3.0.02026-07-26318168886.7 KB

Store Credits

Get Store Credits

To get customers store credits. 獲取商店購物金紀錄。 Strongly recommended: use cursor-based pagination (limit + previous_id) instead of offset (page + per_page). 強烈建議使用 cursor 翻頁（limit + previous_id），不要用 page + per_page。 How to switch to cursor / 如何切換： simply pass limit (and previous_id from the previous response's last_id for next pages). Response will return last_id instead of pagination. 帶 limit 即啟用 cursor，後續頁帶上一次的 last_id 作為 previous_id。Response 回 last_id 取代 pagination。 Filters + cursor coexist / 篩選 + cursor 同時使用： Filter params (end_at_after, end_at_before, created_at_*) apply BEFORE cursor. Every page returns items already matching the filter — cursor paginates within the filtered set. 篩選參數先套用，cursor 在篩選後的結果集內翻頁。每頁回的都是符合篩選條件的資料。 Example — fetch all credits expiring in the next 30 days / 撈未來 30 天到期名單： Page 1 — pass filter + limit (no previous_id on first page): <code>GET /v1/user_credits?end_at_after=2026-05-19T00:00:00Z&end_at_before=2026-06-18T23:59:59Z&limit=200</code> → { items: [200 items, all expiring 2026-05-19 ~ 2026-06-18], last_id: "6a056255..." } Page 2 — repeat filter + pass previous_id from previous last_id: <code>GET /v1/user_credits?end_at_after=2026-05-19T00:00:00Z&end_at_before=2026-06-18T23:59:59Z&limit=200&previous_id=6a056255...</code> → { items: [200 more items, still within filter], last_id: "69faf974..." } ...repeat until <code>items.length < limit</code> OR <code>last_id</code> is null (whichever comes first): → { items: [...remaining items, fewer than limit...], last_id: null } Stop condition / 停止條件： items.length < limit OR last_id === null. Note: when total count is an exact multiple of limit, last_id may still be non-null on the final full page; the next call will return empty items with last_id = null. Always check both conditions. 注意：當總筆數剛好是 limit 倍數時，最末頁 last_id 仍會回非 null；下一次呼叫才會回空陣列 + last_id = null。請同時檢查兩個條件。 Offset mode is retained only for backward compatibility and will not receive new improvements.

get/user_credits

Query parameters

created_at_afterstring date-time

Filter store credits by those created after specific time (inclusive). 取得 created_at 大於等於指定時間的購物金。 Accepts ISO 8601 format. Use UTC (Z suffix) to avoid timezone ambiguity. 接受 ISO 8601 格式，建議帶 Z 明確指 UTC，避免時區歧義。

created_at_beforestring date-time

Filter store credits by those created before specific time (inclusive). 取得 created_at 小於等於指定時間的購物金。 Accepts ISO 8601 format. Use UTC (Z suffix) to avoid timezone ambiguity. 接受 ISO 8601 格式，建議帶 Z 明確指 UTC，避免時區歧義。

end_at_afterstring date-time

Filter store credits expiring after specific time (inclusive). 取得 end_at 大於等於指定時間的購物金（撈「快到期」名單時可帶 now）。 Accepts ISO 8601 format. Use UTC (Z suffix) to avoid timezone ambiguity. 接受 ISO 8601 格式，建議帶 Z 明確指 UTC。

end_at_beforestring date-time

Filter store credits expiring before specific time (inclusive). 取得 end_at 小於等於指定時間的購物金（撈「快到期」名單時可帶 now + N days）。 Accepts ISO 8601 format. Use UTC (Z suffix) to avoid timezone ambiguity. 接受 ISO 8601 格式，建議帶 Z 明確指 UTC。

pageinteger

Page Number (offset mode). 頁數 Ignored when limit or previous_id is provided (cursor mode).

per_pageinteger

Numbers of items per page (offset mode). 每頁顯示 n 筆資料 Ignored in cursor mode; use limit instead.

limitinteger

Cursor mode page size (default 24, max 999). cursor 模式每次回傳筆數。 Presence of this param enables cursor mode (response returns last_id instead of pagination). 帶 limit 即啟用 cursor，response 不再含 pagination。 Larger values reduce total round trips for large batch jobs (e.g. fetching 60k records with limit=999 takes ~60 calls vs ~2500 with limit=24). 大批次任務建議用較大值以減少請求次數。

previous_idstring

Cursor for the next page: the _id from the previous response's last_id. 上一頁回傳的 last_id。第一頁不需帶。 Presence of this param also enables cursor mode. Recommended for large batch / external integrations (avoids ES offset depth limit).

excludes[]string[]

Could exclude certain parameters in the response 結果要排除哪些參數

[
  "items.id"
]

fields[]string[]

Could only show certain parameters in the response 結果只顯示哪些參數

[
  "items.id"
]

Response

OK Response shape depends on mode: offset (neither limit nor previous_id provided) returns pagination; cursor (limit or previous_id provided) returns last_id.

last_idstring nullable

Present only in cursor mode (limit or previous_id provided). Cursor signal for the next page (pass as previous_id on next call). null when current page returned fewer than limit items. Caveat: on the boundary case where total count is an exact multiple of limit, last_id may still be non-null on the final full page; the next call will return empty items with last_id = null. Treat both items.length < limit AND last_id === null as end-of-stream signals. 下一頁 cursor signal。當回傳筆數 < limit 時為 null。注意：總筆數剛好是 limit 倍數時，最末滿頁 last_id 仍非 null，下一次呼叫才會回空陣列 + null。請同時檢查兩個條件。

Example response

{
  "items": [
    {
      "_id": "5f55ad58d9ce6d003c1fd62f",
      "customer_id": "5f47c96a86a983001614a834",
      "credit_balance": 160,
      "remarks": "hello",
      "value": 20,
      "end_at": "2021-11-30T00:00:00.000+00:00",
      "performer_id": "61ad96bda6633e004cafe7db",
      "performer_name": "staff1",
      "fulfillment_balance": 10,
      "type": "manual_credit",
      "created_at": "2020-09-07T03:47:44.061Z",
      "customer_ref_user_id": "MEMBR000000000000019034194",
      "status": "active",
      "order_id": "621701406dcff70039642cde",
      "value_dollar": {
        "cents": 999999999,
        "currency_symbol": "NT$",
        "currency_iso": "TWD",
        "label": "NT$999,999,999",
        "dollars": 999999999
      },
      "user_credit_rule_id": "583d630a69702d70850c0000",
      "order_number": "2019052707260498"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 24,
    "total_count": 1,
    "total_pages": 1
  },
  "last_id": "5f1e837c1be895004582ad47"
}