--- title: "Get Store Credits" method: GET path: "/user_credits" tags: ["Store Credits"] --- # Get Store Credits `GET /user_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):
GET /v1/user_credits?end_at_after=2026-05-19T00:00:00Z&end_at_before=2026-06-18T23:59:59Z&limit=200
→ { 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:
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...
→ { items: [200 more items, still within filter], last_id: "69faf974..." }

...repeat until items.length < limit OR last_id 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. ## Query parameters - `created_at_after` string, date-time - `created_at_before` string, date-time - `end_at_after` string, date-time - `end_at_before` string, date-time - `page` integer - `per_page` integer - `limit` integer - `previous_id` string - `excludes[]` string[] - `fields[]` string[] ## Response `200` OK
Response shape depends on mode: offset (neither `limit` nor `previous_id` provided) returns `pagination`; cursor (`limit` or `previous_id` provided) returns `last_id`. - object - `items` StoreCredit[] - `_id` string — Record ID
紀錄 ID - `customer_id` string — Customer ID
顧客 ID - `credit_balance` integer — Credit balance after this record
此紀錄後的購物金餘額 - `remarks` string — Credit Change Reason
購物金更動原因 - `value` integer — Credit Movement
購物金款項 - `end_at` string — Expiry Date
到期日 - `performer_id` string — ID of the staff who created this record
創建紀錄的管理員的ID - `performer_name` string — Staff who created this record
創建紀錄的管理員 - `fulfillment_balance` integer — Fulfillment Balance
購物金餘額 - `type` 'manual_credit' | 'welcome_credit' | 'birthday_credit' | 'auto_reward' | 'applied_credit' | 'user_credit_expired' | 'welcome_member_referral_credit' | 'member_referral_credit' | 'order_split_revert' | 'member_info_quick_completion_credit' | 'product_review_reward' | 'return_order_revert' | 'order_edit_revert' — Store credit type
購物金類型
----
manual_credit: 手動增減購物金（店家手動發送、回補來自取消訂單/退貨訂單）
welcome_credit: 新加入會員購物金
birthday_credit: 生日購物金
auto_reward: 購物金回饋
applied_credit: 套用購物金在訂單
user_credit_expired: 購物金過期
welcome_member_referral_credit: 透過推薦連結註冊成功
member_referral_credit: 推薦新顧客進行消費
order_split_revert: 回補購物金（來自拆單）
product_review_reward: 商品評價獎賞
member_info_quick_completion_credit: 會員資料獎賞
return_order_revert: 退貨單回補購物金
order_edit_revert: 訂單編輯回補購物金 - `created_at` string — Record creation date
創建紀錄日期 - `customer_ref_user_id` string — Third party custom customer id
第三方儲存之顧客ID - `status` 'active' | 'removed' | 'expired' | 'used' | 'redeemed' — Status
購物金狀態 - `is_redeem` boolean — Whether the store credit is redeemed
購物金是否已經被兌換 - `order_id` string — The ID of the order where the store credit earned from
賺取購物金的訂單的ID - `value_dollar` object — The value of the store credit displayed in dollar
以元表示購物金的價值 - `cents` integer - `currency_symbol` string - `currency_iso` string - `label` string - `dollars` number - `user_credit_rule_id` string — The ID of user_credit_rule - `order_number` string — Order number
訂單號碼 - `merchant_order_number` string — The order number set by the merchant
店家自定義訂單號 - `order_created_by` string — Order created by
此訂單的建立者 - `pagination` Paginatable - `current_page` integer — The current page number
當前分頁 - `per_page` integer — Number of result per page
每頁顯示 n 筆資料
(Default: 24) - `total_count` integer — Number of result in total
資料總量 - `total_pages` integer — Number of pages in total
總頁數量 - `last_id` string, 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。請同時檢查兩個條件。 --- [API](https://skmtc.net/shoplineapp/apis/shopline-open-api.md) · [All operations](https://skmtc.net/shoplineapp/apis/shopline-open-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/shoplineapp/shopline-open-api/versions/1675ac12cde7/schema)