{ "item": [ { "name": "v1", "description": "", "item": [ { "name": "auth", "description": "", "item": [ { "name": "login", "description": "", "item": [ { "id": "895b75af-d98e-478d-ba94-41612325716e", "name": "Authenticate user", "request": { "name": "Authenticate user", "description": { "content": "Authenticates a user with email and password. Returns access token and user details including assigned location(s).", "type": "text/plain" }, "url": { "path": ["v1", "auth", "login"], "host": ["{{baseUrl}}"], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"email\": \"\",\n \"password\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": null }, "response": [ { "id": "041b1723-4ef7-4010-bfda-6095c62d6684", "name": "Successful response", "originalRequest": { "url": { "path": ["v1", "auth", "login"], "host": ["{{baseUrl}}"], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"email\": \"\",\n \"password\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"access_token\": \"\",\n \"refresh_token\": \"\",\n \"expires_in\": \"\",\n \"token_type\": \"bearer\",\n \"user\": {\n \"id\": \"\",\n \"email\": \"\",\n \"user_type\": \"owner\",\n \"merchant_id\": \"\",\n \"merchant_name\": \"\",\n \"locations\": [\n {\n \"id\": \"\",\n \"name\": \"\",\n \"display_order\": \"\"\n },\n {\n \"id\": \"\",\n \"name\": \"\",\n \"display_order\": \"\"\n }\n ],\n \"location\": {\n \"id\": \"\",\n \"name\": \"\",\n \"display_order\": \"\"\n }\n }\n },\n \"meta\": {\n \"request_id\": \"\",\n \"timestamp\": \"\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "if (pm.response.code === 200) {", " const json = pm.response.json();", " if (json.success && json.data) {", " pm.environment.set(\"access_token\", json.data.access_token);", " pm.environment.set(\"refresh_token\", json.data.refresh_token);", " if (json.data.user && json.data.user.id) {", " pm.environment.set(\"staff_user_id\", json.data.user.id);", " }", " if (json.data.user && json.data.user.locations && json.data.user.locations.length > 0) {", " pm.environment.set(\"location_id\", json.data.user.locations[0].id);", " }", " }", "}" ] } } ], "protocolProfileBehavior": { "disableBodyPruning": true } } ] }, { "name": "me", "description": "", "item": [ { "id": "243b0cd0-8f9a-405d-b9a5-374ddf4fd035", "name": "Get current user", "request": { "name": "Get current user", "description": { "content": "Returns the current authenticated user's profile including location information.", "type": "text/plain" }, "url": { "path": ["v1", "auth", "me"], "host": ["{{baseUrl}}"], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "b95c4117-ec07-4b02-995e-b92f6103d60b", "name": "Successful response", "originalRequest": { "url": { "path": ["v1", "auth", "me"], "host": ["{{baseUrl}}"], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"id\": \"\",\n \"email\": \"\",\n \"user_type\": \"system_user\",\n \"merchant_id\": \"\",\n \"merchant_name\": \"\",\n \"locations\": [\n {\n \"id\": \"\",\n \"name\": \"\",\n \"display_order\": \"\"\n },\n {\n \"id\": \"\",\n \"name\": \"\",\n \"display_order\": \"\"\n }\n ],\n \"location\": {\n \"id\": \"\",\n \"name\": \"\",\n \"display_order\": \"\"\n }\n },\n \"meta\": {\n \"request_id\": \"\",\n \"timestamp\": \"\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] }, { "name": "refresh", "description": "", "item": [ { "id": "faf2b3d4-b9ac-4eff-a563-66dcce2205b3", "name": "Refresh access token", "request": { "name": "Refresh access token", "description": { "content": "Exchanges a refresh token for a new access token and refresh token pair.", "type": "text/plain" }, "url": { "path": ["v1", "auth", "refresh"], "host": ["{{baseUrl}}"], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"refresh_token\": \"{{refresh_token}}\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": null }, "response": [ { "id": "d6cca9bc-f76c-4810-b13c-43de68d202dc", "name": "Successful response", "originalRequest": { "url": { "path": ["v1", "auth", "refresh"], "host": ["{{baseUrl}}"], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"refresh_token\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"access_token\": \"\",\n \"refresh_token\": \"\",\n \"expires_in\": \"\",\n \"token_type\": \"bearer\"\n },\n \"meta\": {\n \"request_id\": \"\",\n \"timestamp\": \"\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "if (pm.response.code === 200) {", " const json = pm.response.json();", " if (json.success && json.data) {", " pm.environment.set(\"access_token\", json.data.access_token);", " pm.environment.set(\"refresh_token\", json.data.refresh_token);", " }", "}" ] } } ], "protocolProfileBehavior": { "disableBodyPruning": true } } ] } ] }, { "name": "cards", "description": "", "item": [ { "name": "lookup", "description": "", "item": [ { "id": "73085a78-3900-41f4-bf25-55ba9328c3f0", "name": "Look up card balance", "request": { "name": "Look up card balance", "description": { "content": "Looks up a card's balance and details by QR code data or barcode value. Accepts either qr_code_data (base64-encoded) or barcode_value (numeric display_id). Returns type-specific balance information for punch, cashback, or discount cards. This endpoint is read-only and does not create transactions.", "type": "text/plain" }, "url": { "path": ["v1", "cards", "lookup"], "host": ["{{baseUrl}}"], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"qr_code_data\": \"\",\n \"barcode_value\": \"1369836542\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": null }, "response": [ { "id": "077c4b68-a139-4205-a841-0c23f351bc8b", "name": "Successful response", "originalRequest": { "url": { "path": ["v1", "cards", "lookup"], "host": ["{{baseUrl}}"], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"qr_code_data\": \"\",\n \"barcode_value\": \"1369836542\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"card_instance_id\": \"\",\n \"card_type\": \"discount\",\n \"card_title\": \"\",\n \"merchant_name\": \"\",\n \"customer_name\": \"\",\n \"status\": \"expired\",\n \"balance\": {\n \"type\": \"punch\",\n \"current_punches\": \"\",\n \"punch_requirement\": \"\",\n \"progress_percent\": \"\",\n \"punches_to_next_reward\": \"\",\n \"pending_rewards\": \"\",\n \"claimed_rewards\": \"\",\n \"total_punches_lifetime\": \"\",\n \"reward_name\": \"\",\n \"reward_amount\": \"\"\n }\n },\n \"meta\": {\n \"request_id\": \"\",\n \"timestamp\": \"\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "if (pm.response.code === 200) {", " const json = pm.response.json();", " if (json.success && json.data && json.data.card_instance_id) {", " pm.environment.set(\"card_instance_id\", json.data.card_instance_id);", " }", "}" ] } } ], "protocolProfileBehavior": { "disableBodyPruning": true } } ] } ] }, { "name": "cashback", "description": "", "item": [ { "name": "redeem", "description": "", "item": [ { "id": "13fbc416-3525-4910-9124-87cc10fb1594", "name": "Redeem cashback balance", "request": { "name": "Redeem cashback balance", "description": { "content": "Redeems cashback balance against a purchase (FIFO order). Validates redemption amount against available balance, redeems from oldest earned cashback first, supports partial entry redemption, and returns breakdown of redeemed entries. Optionally (earn_on_remainder) earns cashback at the tier rate on the customer-paid remainder in the same atomic transaction and returns an additive earned block.", "type": "text/plain" }, "url": { "path": ["v1", "cashback", "redeem"], "host": ["{{baseUrl}}"], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"card_instance_id\": \"{{card_instance_id}}\",\n \"redemption_amount\": \"\",\n \"purchase_amount\": \"\",\n \"location_id\": \"{{location_id}}\",\n \"staff_user_id\": \"{{staff_user_id}}\",\n \"idempotency_key\": \"\",\n \"transaction_notes\": \"\",\n \"earn_on_remainder\": \"\",\n \"pos_reference_id\": \"\",\n \"pos_terminal_id\": \"\",\n \"pos_provider\": \"\",\n \"line_items\": [\n {\n \"name\": \"\",\n \"quantity\": 1,\n \"unit_price\": \"\",\n \"total_price\": \"\",\n \"external_product_id\": \"\",\n \"metadata\": {\n \"sedcc\": {},\n \"in5\": {},\n \"nisi_3d\": {},\n \"sitd\": {}\n }\n },\n {\n \"name\": \"\",\n \"quantity\": 1,\n \"unit_price\": \"\",\n \"total_price\": \"\",\n \"external_product_id\": \"\",\n \"metadata\": {\n \"do_5c9\": {},\n \"nonf7\": {}\n }\n }\n ]\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": null }, "response": [ { "id": "b5b987a7-95df-4f4b-8aa4-a5026841fcd5", "name": "Successful response", "originalRequest": { "url": { "path": ["v1", "cashback", "redeem"], "host": ["{{baseUrl}}"], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"card_instance_id\": \"\",\n \"redemption_amount\": \"\",\n \"purchase_amount\": \"\",\n \"location_id\": \"\",\n \"staff_user_id\": \"\",\n \"idempotency_key\": \"\",\n \"transaction_notes\": \"\",\n \"earn_on_remainder\": \"\",\n \"pos_reference_id\": \"\",\n \"pos_terminal_id\": \"\",\n \"pos_provider\": \"\",\n \"line_items\": [\n {\n \"name\": \"\",\n \"quantity\": 1,\n \"unit_price\": \"\",\n \"total_price\": \"\",\n \"external_product_id\": \"\",\n \"metadata\": {\n \"sedcc\": {},\n \"in5\": {},\n \"nisi_3d\": {},\n \"sitd\": {}\n }\n },\n {\n \"name\": \"\",\n \"quantity\": 1,\n \"unit_price\": \"\",\n \"total_price\": \"\",\n \"external_product_id\": \"\",\n \"metadata\": {\n \"do_5c9\": {},\n \"nonf7\": {}\n }\n }\n ]\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"transaction_id\": \"\",\n \"redeemed_amount\": \"\",\n \"new_balance\": \"\",\n \"final_purchase_amount\": \"\",\n \"redeemed_entries\": [\n {\n \"amount\": \"\",\n \"earned_date\": \"\",\n \"transaction_id\": \"\",\n \"expiration_date\": \"\"\n },\n {\n \"amount\": \"\",\n \"earned_date\": \"\",\n \"transaction_id\": \"\",\n \"expiration_date\": \"\"\n }\n ],\n \"earned\": {\n \"transaction_id\": \"\",\n \"purchase_amount\": \"\",\n \"cashback_rate\": \"\",\n \"cashback_earned\": \"\",\n \"new_balance\": \"\",\n \"tier_id\": \"\",\n \"currency\": \"\",\n \"tier_changed\": {\n \"old_tier_id\": \"\",\n \"new_tier_id\": \"\",\n \"new_rate\": \"\"\n }\n }\n },\n \"meta\": {\n \"request_id\": \"\",\n \"timestamp\": \"\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] } ] }, { "name": "customers", "description": "", "item": [ { "id": "e743c584-fc26-4edf-b240-e2e75a40b0b9", "name": "List merchant customers", "request": { "name": "List merchant customers", "description": { "content": "πŸ”’ **OWNER-ONLY endpoint.** Use a merchant **owner (admin)** `access_token` β€” log in at `v1/auth/login` with OWNER credentials. A **system-user / POS token is rejected here with 403 `OWNER_REQUIRED`.** These endpoints also require `{{merchant_id}}` (a merchant the owner owns); a merchant you don't own returns 403 `MERCHANT_NOT_AUTHORIZED`.\n\n---\n\nReturns a paginated, per-customer grouped list of a merchant's enrolled clients with card summaries. Supports search by name, email, phone, or barcode. Requires merchant owner (admin) credentials β€” system user tokens are rejected with 403 OWNER_REQUIRED. The merchant_id parameter must be a merchant the authenticated user owns.", "type": "text/plain" }, "url": { "path": ["v1", "customers"], "host": ["{{baseUrl}}"], "query": [ { "disabled": false, "description": { "content": "(Required) Merchant whose customers to list β€” must be owned by the authenticated user", "type": "text/plain" }, "key": "merchant_id", "value": "{{merchant_id}}" }, { "disabled": false, "description": { "content": "Page number (default 1)", "type": "text/plain" }, "key": "page", "value": "" }, { "disabled": false, "description": { "content": "Items per page (default 10, max 50)", "type": "text/plain" }, "key": "page_size", "value": "" }, { "disabled": false, "description": { "content": "Search by name, email, phone, or barcode (min 3 characters)", "type": "text/plain" }, "key": "search", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "3c9ecd0c-1771-4187-a438-6036ea032b0d", "name": "Successful response", "originalRequest": { "url": { "path": ["v1", "customers"], "host": ["{{baseUrl}}"], "query": [ { "disabled": false, "description": { "content": "(Required) Merchant whose customers to list β€” must be owned by the authenticated user", "type": "text/plain" }, "key": "merchant_id", "value": "" }, { "disabled": false, "description": { "content": "Page number (default 1)", "type": "text/plain" }, "key": "page", "value": "" }, { "disabled": false, "description": { "content": "Items per page (default 10, max 50)", "type": "text/plain" }, "key": "page_size", "value": "" }, { "disabled": false, "description": { "content": "Search by name, email, phone, or barcode (min 3 characters)", "type": "text/plain" }, "key": "search", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"customers\": [\n {\n \"customer_id\": \"\",\n \"card_count\": \"\",\n \"first_enrollment_date\": \"\",\n \"cards\": [\n {\n \"card_instance_id\": \"\",\n \"barcode_value\": \"\",\n \"card_name\": \"\",\n \"card_type\": \"\",\n \"status\": \"\",\n \"current_balance\": \"\",\n \"enrollment_date\": \"\",\n \"max_balance\": \"\",\n \"currency_symbol\": \"\"\n },\n {\n \"card_instance_id\": \"\",\n \"barcode_value\": \"\",\n \"card_name\": \"\",\n \"card_type\": \"\",\n \"status\": \"\",\n \"current_balance\": \"\",\n \"enrollment_date\": \"\",\n \"max_balance\": \"\",\n \"currency_symbol\": \"\"\n }\n ],\n \"customer_name\": \"\",\n \"email\": \"\"\n },\n {\n \"customer_id\": \"\",\n \"card_count\": \"\",\n \"first_enrollment_date\": \"\",\n \"cards\": [\n {\n \"card_instance_id\": \"\",\n \"barcode_value\": \"\",\n \"card_name\": \"\",\n \"card_type\": \"\",\n \"status\": \"\",\n \"current_balance\": \"\",\n \"enrollment_date\": \"\",\n \"max_balance\": \"\",\n \"currency_symbol\": \"\"\n },\n {\n \"card_instance_id\": \"\",\n \"barcode_value\": \"\",\n \"card_name\": \"\",\n \"card_type\": \"\",\n \"status\": \"\",\n \"current_balance\": \"\",\n \"enrollment_date\": \"\",\n \"max_balance\": \"\",\n \"currency_symbol\": \"\"\n }\n ],\n \"customer_name\": \"\",\n \"email\": \"\"\n }\n ],\n \"total_count\": \"\",\n \"total_pages\": \"\",\n \"current_page\": \"\"\n },\n \"meta\": {\n \"request_id\": \"\",\n \"timestamp\": \"\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "name": "{customerId}", "description": "", "item": [ { "id": "627fed1b-e601-4b31-98b0-7bd9e1222fcf", "name": "Get merchant customer", "request": { "name": "Get merchant customer", "description": { "content": "πŸ”’ **OWNER-ONLY endpoint.** Use a merchant **owner (admin)** `access_token` β€” log in at `v1/auth/login` with OWNER credentials. A **system-user / POS token is rejected here with 403 `OWNER_REQUIRED`.** These endpoints also require `{{merchant_id}}` (a merchant the owner owns); a merchant you don't own returns 403 `MERCHANT_NOT_AUTHORIZED`.\n\n---\n\nReturns one client's profile and all their cards under the verified merchant. A customer exists if they have any card instance of any status; post-erase the customer still exists with archived cards listed and every profile field null. Requires merchant owner (admin) credentials β€” system user tokens are rejected with 403 OWNER_REQUIRED. The merchant_id parameter must be a merchant the authenticated user owns.", "type": "text/plain" }, "url": { "path": ["v1", "customers", ":customerId"], "host": ["{{baseUrl}}"], "query": [ { "disabled": false, "description": { "content": "(Required) Merchant that owns the customer β€” must be owned by the authenticated user", "type": "text/plain" }, "key": "merchant_id", "value": "{{merchant_id}}" } ], "variable": [ { "type": "any", "value": "", "key": "customerId", "disabled": false, "description": { "content": "(Required) Customer id β€” the customer_id shared by all of a client's card instances", "type": "text/plain" } } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "a814663b-ee2b-4ea5-b54e-d3efbe2bce60", "name": "Successful response", "originalRequest": { "url": { "path": ["v1", "customers", ":customerId"], "host": ["{{baseUrl}}"], "query": [ { "disabled": false, "description": { "content": "(Required) Merchant that owns the customer β€” must be owned by the authenticated user", "type": "text/plain" }, "key": "merchant_id", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"customer_id\": \"\",\n \"profile\": {\n \"customer_name\": \"\",\n \"email\": \"\",\n \"phone\": \"\",\n \"birthday\": \"\",\n \"gender\": \"\",\n \"enrollment_date\": \"\"\n },\n \"cards\": [\n {\n \"card_instance_id\": \"\",\n \"barcode_value\": \"\",\n \"card_name\": \"\",\n \"card_type\": \"\",\n \"status\": \"\",\n \"current_balance\": \"\",\n \"enrollment_date\": \"\",\n \"max_balance\": \"\",\n \"currency_symbol\": \"\"\n },\n {\n \"card_instance_id\": \"\",\n \"barcode_value\": \"\",\n \"card_name\": \"\",\n \"card_type\": \"\",\n \"status\": \"\",\n \"current_balance\": \"\",\n \"enrollment_date\": \"\",\n \"max_balance\": \"\",\n \"currency_symbol\": \"\"\n }\n ]\n },\n \"meta\": {\n \"request_id\": \"\",\n \"timestamp\": \"\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "f471cac8-94cb-4ae2-a905-e093b9d7a6a3", "name": "Update merchant customer profile", "request": { "name": "Update merchant customer profile", "description": { "content": "πŸ”’ **OWNER-ONLY endpoint.** Use a merchant **owner (admin)** `access_token` β€” log in at `v1/auth/login` with OWNER credentials. A **system-user / POS token is rejected here with 403 `OWNER_REQUIRED`.** These endpoints also require `{{merchant_id}}` (a merchant the owner owns); a merchant you don't own returns 403 `MERCHANT_NOT_AUTHORIZED`.\n\n---\n\nUpdates a client's contact/demographic profile fields (customer_name, email, phone, birthday, gender) across all of the customer's card profiles under the verified merchant. email/phone/birthday/gender accept null to clear; unknown or forbidden keys are rejected. Requires merchant owner (admin) credentials β€” system user tokens are rejected with 403 OWNER_REQUIRED. The merchant_id parameter must be a merchant the authenticated user owns.", "type": "text/plain" }, "url": { "path": ["v1", "customers", ":customerId"], "host": ["{{baseUrl}}"], "query": [ { "disabled": false, "description": { "content": "(Required) Merchant that owns the customer β€” must be owned by the authenticated user", "type": "text/plain" }, "key": "merchant_id", "value": "{{merchant_id}}" } ], "variable": [ { "type": "any", "value": "", "key": "customerId", "disabled": false, "description": { "content": "(Required) Customer id β€” the customer_id shared by all of a client's card instances", "type": "text/plain" } } ] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"customer_name\": \"\",\n \"email\": \"\",\n \"phone\": \"\",\n \"birthday\": \"2965-80-22\",\n \"gender\": \"male\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": null }, "response": [ { "id": "1b721604-2050-4b7a-9a2b-874e48282e80", "name": "Successful response", "originalRequest": { "url": { "path": ["v1", "customers", ":customerId"], "host": ["{{baseUrl}}"], "query": [ { "disabled": false, "description": { "content": "(Required) Merchant that owns the customer β€” must be owned by the authenticated user", "type": "text/plain" }, "key": "merchant_id", "value": "" } ], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"customer_name\": \"\",\n \"email\": \"\",\n \"phone\": \"\",\n \"birthday\": \"2965-80-22\",\n \"gender\": \"male\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"updated\": \"\"\n },\n \"meta\": {\n \"request_id\": \"\",\n \"timestamp\": \"\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "0414928a-5539-4da5-ba92-4ac0a3c9c7f4", "name": "Delete merchant customer data", "request": { "name": "Delete merchant customer data", "description": { "content": "πŸ”’ **OWNER-ONLY endpoint.** Use a merchant **owner (admin)** `access_token` β€” log in at `v1/auth/login` with OWNER credentials. A **system-user / POS token is rejected here with 403 `OWNER_REQUIRED`.** These endpoints also require `{{merchant_id}}` (a merchant the owner owns); a merchant you don't own returns 403 `MERCHANT_NOT_AUTHORIZED`.\n\n---\n\nErases a client's profile PII, archives their cards, and deletes push registrations and merchant-scoped sessions under the verified merchant. Transactions and login identity are retained β€” this is merchant-scoped client removal, NOT a GDPR-complete erasure. Apple Wallet passes receive no final push (they pick up the archived state on their next pass poll); Google Wallet is updated. Idempotent: a repeat call returns zero counts. Requires merchant owner (admin) credentials β€” system user tokens are rejected with 403 OWNER_REQUIRED. The merchant_id parameter must be a merchant the authenticated user owns.", "type": "text/plain" }, "url": { "path": ["v1", "customers", ":customerId"], "host": ["{{baseUrl}}"], "query": [ { "disabled": false, "description": { "content": "(Required) Merchant that owns the customer β€” must be owned by the authenticated user", "type": "text/plain" }, "key": "merchant_id", "value": "{{merchant_id}}" } ], "variable": [ { "type": "any", "value": "", "key": "customerId", "disabled": false, "description": { "content": "(Required) Customer id β€” the customer_id shared by all of a client's card instances", "type": "text/plain" } } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "DELETE", "body": {}, "auth": null }, "response": [ { "id": "616fdd59-2de5-4d30-b504-28ee4be43540", "name": "Successful response", "originalRequest": { "url": { "path": ["v1", "customers", ":customerId"], "host": ["{{baseUrl}}"], "query": [ { "disabled": false, "description": { "content": "(Required) Merchant that owns the customer β€” must be owned by the authenticated user", "type": "text/plain" }, "key": "merchant_id", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "DELETE", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"cards_archived\": \"\",\n \"profiles_deleted\": \"\",\n \"push_registrations_deleted\": \"\",\n \"sessions_deleted\": \"\"\n },\n \"meta\": {\n \"request_id\": \"\",\n \"timestamp\": \"\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] } ] }, { "name": "products", "description": "", "item": [ { "id": "8af5dd22-93f7-47fe-b79e-0cf4fb971390", "name": "List merchant products", "request": { "name": "List merchant products", "description": { "content": "Returns a paginated list of products in the merchant's catalog. Supports filtering by POS provider, category, status, and text search.", "type": "text/plain" }, "url": { "path": ["v1", "products"], "host": ["{{baseUrl}}"], "query": [ { "disabled": false, "description": { "content": "Page number (default 1)", "type": "text/plain" }, "key": "page", "value": "" }, { "disabled": false, "description": { "content": "Items per page (default 20, max 100)", "type": "text/plain" }, "key": "page_size", "value": "" }, { "disabled": false, "description": { "content": "Filter by POS provider", "type": "text/plain" }, "key": "pos_provider", "value": "" }, { "disabled": false, "description": { "content": "Filter by category name", "type": "text/plain" }, "key": "category_name", "value": "" }, { "disabled": false, "description": { "content": "Filter by status", "type": "text/plain" }, "key": "status", "value": "inactive" }, { "disabled": false, "description": { "content": "Search products by name or barcode", "type": "text/plain" }, "key": "search", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "1a5dcd9d-73a3-4e65-8d35-605bf5d7e08b", "name": "Successful response", "originalRequest": { "url": { "path": ["v1", "products"], "host": ["{{baseUrl}}"], "query": [ { "disabled": false, "description": { "content": "Page number (default 1)", "type": "text/plain" }, "key": "page", "value": "" }, { "disabled": false, "description": { "content": "Items per page (default 20, max 100)", "type": "text/plain" }, "key": "page_size", "value": "" }, { "disabled": false, "description": { "content": "Filter by POS provider", "type": "text/plain" }, "key": "pos_provider", "value": "" }, { "disabled": false, "description": { "content": "Filter by category name", "type": "text/plain" }, "key": "category_name", "value": "" }, { "disabled": false, "description": { "content": "Filter by status", "type": "text/plain" }, "key": "status", "value": "inactive" }, { "disabled": false, "description": { "content": "Search products by name or barcode", "type": "text/plain" }, "key": "search", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"products\": [\n {\n \"id\": \"\",\n \"external_id\": \"\",\n \"pos_provider\": \"\",\n \"name\": \"\",\n \"status\": \"\",\n \"created_at\": \"\",\n \"updated_at\": \"\",\n \"description\": \"\",\n \"category_name\": \"\",\n \"price\": \"\",\n \"sku\": \"\",\n \"barcode\": \"\",\n \"metadata\": {\n \"voluptate_d17\": {},\n \"deserunt__58\": {}\n }\n },\n {\n \"id\": \"\",\n \"external_id\": \"\",\n \"pos_provider\": \"\",\n \"name\": \"\",\n \"status\": \"\",\n \"created_at\": \"\",\n \"updated_at\": \"\",\n \"description\": \"\",\n \"category_name\": \"\",\n \"price\": \"\",\n \"sku\": \"\",\n \"barcode\": \"\",\n \"metadata\": {\n \"exf4\": {}\n }\n }\n ],\n \"pagination\": {\n \"page\": \"\",\n \"page_size\": \"\",\n \"total_items\": \"\",\n \"total_pages\": \"\",\n \"has_next\": \"\",\n \"has_previous\": \"\"\n }\n },\n \"meta\": {\n \"request_id\": \"\",\n \"timestamp\": \"\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "name": "sync", "description": "", "item": [ { "id": "1fad44cb-a383-4add-a470-0d72a3bc52b1", "name": "Sync products from a POS system", "request": { "name": "Sync products from a POS system", "description": { "content": "Batch upsert products into the merchant's product catalog. Products are matched by (merchant_id, pos_provider, external_id). Existing products are updated, new ones are created.", "type": "text/plain" }, "url": { "path": ["v1", "products", "sync"], "host": ["{{baseUrl}}"], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"pos_provider\": \"\",\n \"products\": [\n {\n \"external_id\": \"\",\n \"name\": \"\",\n \"description\": \"\",\n \"category_name\": \"\",\n \"price\": \"\",\n \"sku\": \"\",\n \"barcode\": \"\",\n \"status\": \"active\",\n \"metadata\": {\n \"veniam_4e_\": {}\n }\n }\n ]\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": null }, "response": [ { "id": "f29014d3-47db-4631-8992-60187690f435", "name": "Successful response", "originalRequest": { "url": { "path": ["v1", "products", "sync"], "host": ["{{baseUrl}}"], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"pos_provider\": \"\",\n \"products\": [\n {\n \"external_id\": \"\",\n \"name\": \"\",\n \"description\": \"\",\n \"category_name\": \"\",\n \"price\": \"\",\n \"sku\": \"\",\n \"barcode\": \"\",\n \"status\": \"active\",\n \"metadata\": {\n \"veniam_4e_\": {}\n }\n }\n ]\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"total_count\": \"\",\n \"created_count\": \"\",\n \"updated_count\": \"\"\n },\n \"meta\": {\n \"request_id\": \"\",\n \"timestamp\": \"\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] } ] }, { "name": "rewards", "description": "", "item": [ { "name": "claim", "description": "", "item": [ { "id": "887dfba1-0421-43ab-9a3c-9cfdf5f37605", "name": "Claim punch card reward", "request": { "name": "Claim punch card reward", "description": { "content": "Claims the oldest pending reward for a punch card (FIFO order). Validates that the card exists and is active, is a punch card, has pending rewards available, and the oldest reward hasn't expired.", "type": "text/plain" }, "url": { "path": ["v1", "rewards", "claim"], "host": ["{{baseUrl}}"], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"card_instance_id\": \"{{card_instance_id}}\",\n \"location_id\": \"{{location_id}}\",\n \"staff_user_id\": \"{{staff_user_id}}\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": null }, "response": [ { "id": "ff32cac7-61e8-47ca-ba4b-75ee9899a91e", "name": "Successful response", "originalRequest": { "url": { "path": ["v1", "rewards", "claim"], "host": ["{{baseUrl}}"], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"card_instance_id\": \"\",\n \"location_id\": \"\",\n \"staff_user_id\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"transaction_id\": \"\",\n \"reward_id\": \"\",\n \"reward_name\": \"\",\n \"reward_amount\": \"\",\n \"earned_at\": \"\",\n \"pending_rewards_remaining\": \"\"\n },\n \"meta\": {\n \"request_id\": \"\",\n \"timestamp\": \"\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] } ] }, { "name": "transactions", "description": "", "item": [ { "name": "history", "description": "", "item": [ { "id": "97ffb461-88e7-4909-af16-d0e1aa1189d6", "name": "Get transaction history", "request": { "name": "Get transaction history", "description": { "content": "Retrieves paginated transaction history for a card instance. Supports filtering by transaction type and date range.", "type": "text/plain" }, "url": { "path": ["v1", "transactions", "history"], "host": ["{{baseUrl}}"], "query": [ { "disabled": false, "description": { "content": "UUID of the card instance", "type": "text/plain" }, "key": "card_instance_id", "value": "{{card_instance_id}}" }, { "disabled": false, "description": { "content": "Page number (default 1)", "type": "text/plain" }, "key": "page", "value": "" }, { "disabled": false, "description": { "content": "Items per page (default 20, max 100)", "type": "text/plain" }, "key": "page_size", "value": "" }, { "disabled": false, "description": { "content": "Filter by transaction type", "type": "text/plain" }, "key": "transaction_type", "value": "" }, { "disabled": false, "description": { "content": "Start date filter (ISO 8601)", "type": "text/plain" }, "key": "from_date", "value": "" }, { "disabled": false, "description": { "content": "End date filter (ISO 8601)", "type": "text/plain" }, "key": "to_date", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "64d2322b-0ed3-4511-9bd8-cccecfaa68ef", "name": "Successful response", "originalRequest": { "url": { "path": ["v1", "transactions", "history"], "host": ["{{baseUrl}}"], "query": [ { "disabled": false, "description": { "content": "UUID of the card instance", "type": "text/plain" }, "key": "card_instance_id", "value": "" }, { "disabled": false, "description": { "content": "Page number (default 1)", "type": "text/plain" }, "key": "page", "value": "" }, { "disabled": false, "description": { "content": "Items per page (default 20, max 100)", "type": "text/plain" }, "key": "page_size", "value": "" }, { "disabled": false, "description": { "content": "Filter by transaction type", "type": "text/plain" }, "key": "transaction_type", "value": "" }, { "disabled": false, "description": { "content": "Start date filter (ISO 8601)", "type": "text/plain" }, "key": "from_date", "value": "" }, { "disabled": false, "description": { "content": "End date filter (ISO 8601)", "type": "text/plain" }, "key": "to_date", "value": "" } ], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"transactions\": [\n {\n \"id\": \"\",\n \"transaction_type\": \"cashback_redeemed\",\n \"created_at\": \"\",\n \"description\": \"\",\n \"purchase_amount\": \"\",\n \"reward_amount\": \"\",\n \"balance_after\": \"\",\n \"tier_id\": \"\",\n \"location_name\": \"\"\n },\n {\n \"id\": \"\",\n \"transaction_type\": \"tier_changed\",\n \"created_at\": \"\",\n \"description\": \"\",\n \"purchase_amount\": \"\",\n \"reward_amount\": \"\",\n \"balance_after\": \"\",\n \"tier_id\": \"\",\n \"location_name\": \"\"\n }\n ],\n \"pagination\": {\n \"page\": \"\",\n \"page_size\": \"\",\n \"total_items\": \"\",\n \"total_pages\": \"\",\n \"has_next\": \"\",\n \"has_previous\": \"\"\n }\n },\n \"meta\": {\n \"request_id\": \"\",\n \"timestamp\": \"\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] }, { "name": "record", "description": "", "item": [ { "id": "37fab35d-9800-435a-afa1-dfcc88c09ab5", "name": "Record a purchase transaction", "request": { "name": "Record a purchase transaction", "description": { "content": "Records a single purchase for punch, cashback, or discount cards. Punch Cards add punches and earn rewards when threshold reached. Cashback Cards calculate and credit cashback based on tier rate. Discount Cards calculate discount applied to purchase. Supports idempotency to prevent duplicate processing.", "type": "text/plain" }, "url": { "path": ["v1", "transactions", "record"], "host": ["{{baseUrl}}"], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"location_id\": \"{{location_id}}\",\n \"staff_user_id\": \"{{staff_user_id}}\",\n \"purchase_amount\": \"\",\n \"qr_code_data\": \"\",\n \"card_instance_id\": \"{{card_instance_id}}\",\n \"punch_count\": 1,\n \"transaction_notes\": \"\",\n \"idempotency_key\": \"\",\n \"pos_reference_id\": \"\",\n \"pos_terminal_id\": \"\",\n \"client_timestamp\": \"\",\n \"pos_provider\": \"\",\n \"line_items\": [\n {\n \"name\": \"\",\n \"quantity\": 1,\n \"unit_price\": \"\",\n \"total_price\": \"\",\n \"external_product_id\": \"\",\n \"metadata\": {\n \"qui_1c4\": {},\n \"veniam__\": {},\n \"reprehenderit_04e\": {}\n }\n },\n {\n \"name\": \"\",\n \"quantity\": 1,\n \"unit_price\": \"\",\n \"total_price\": \"\",\n \"external_product_id\": \"\",\n \"metadata\": {\n \"sunt_c71\": {},\n \"sed_8b\": {}\n }\n }\n ]\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": null }, "response": [ { "id": "35a9d345-30be-4338-9e80-a0dfbf17ff2a", "name": "Successful response", "originalRequest": { "url": { "path": ["v1", "transactions", "record"], "host": ["{{baseUrl}}"], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"location_id\": \"\",\n \"staff_user_id\": \"\",\n \"purchase_amount\": \"\",\n \"qr_code_data\": \"\",\n \"card_instance_id\": \"\",\n \"punch_count\": 1,\n \"transaction_notes\": \"\",\n \"idempotency_key\": \"\",\n \"pos_reference_id\": \"\",\n \"pos_terminal_id\": \"\",\n \"client_timestamp\": \"\",\n \"pos_provider\": \"\",\n \"line_items\": [\n {\n \"name\": \"\",\n \"quantity\": 1,\n \"unit_price\": \"\",\n \"total_price\": \"\",\n \"external_product_id\": \"\",\n \"metadata\": {\n \"qui_1c4\": {},\n \"veniam__\": {},\n \"reprehenderit_04e\": {}\n }\n },\n {\n \"name\": \"\",\n \"quantity\": 1,\n \"unit_price\": \"\",\n \"total_price\": \"\",\n \"external_product_id\": \"\",\n \"metadata\": {\n \"sunt_c71\": {},\n \"sed_8b\": {}\n }\n }\n ]\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"transaction_id\": \"\",\n \"card_type\": \"cashback\",\n \"transaction_type\": \"cashback_expired\",\n \"idempotent\": \"\",\n \"result\": {\n \"type\": \"punch\",\n \"punches_added\": \"\",\n \"new_punch_count\": \"\",\n \"punch_requirement\": \"\",\n \"punches_remaining\": \"\",\n \"rewards_earned\": \"\",\n \"reward_earned\": \"\",\n \"reward_id\": \"\",\n \"reward_name\": \"\",\n \"reward_amount\": \"\"\n },\n \"tier_changed\": {\n \"old_tier_id\": \"\",\n \"new_tier_id\": \"\",\n \"new_rate\": \"\"\n }\n },\n \"meta\": {\n \"request_id\": \"\",\n \"timestamp\": \"\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] }, { "name": "refund", "description": "", "item": [ { "id": "999adecb-3266-4bae-94d8-2358edf8f528", "name": "Refund a transaction", "request": { "name": "Refund a transaction", "description": { "content": "Reverses a prior transaction addressed by its card_transactions id. Cashback accruals support partial refunds via refund_amount (cumulative-share clawback, may drive the balance negative into debt); punch, discount, and redemption transactions are full-refund only. Idempotent per merchant via idempotency_key.", "type": "text/plain" }, "url": { "path": ["v1", "transactions", "refund"], "host": ["{{baseUrl}}"], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"transaction_id\": \"\",\n \"idempotency_key\": \"\",\n \"refund_amount\": \"\",\n \"staff_user_id\": \"{{staff_user_id}}\",\n \"location_id\": \"{{location_id}}\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": null }, "response": [ { "id": "0455b923-9452-40ed-95d7-5be7a10b2f63", "name": "Successful response", "originalRequest": { "url": { "path": ["v1", "transactions", "refund"], "host": ["{{baseUrl}}"], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"transaction_id\": \"\",\n \"idempotency_key\": \"\",\n \"refund_amount\": \"\",\n \"staff_user_id\": \"\",\n \"location_id\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"refund_transaction_id\": \"\",\n \"idempotent\": \"\",\n \"original_transaction_id\": \"\",\n \"refunded_amount\": \"\",\n \"refunded_so_far\": \"\",\n \"remaining_refundable\": \"\",\n \"flags\": [\n \"\",\n \"\"\n ],\n \"cashback_clawed\": \"\",\n \"new_balance\": \"\",\n \"punches_removed\": \"\",\n \"rewards_revoked\": \"\",\n \"tier_changed\": {\n \"old_tier_id\": \"\",\n \"new_tier_id\": \"\",\n \"new_rate\": \"\"\n }\n },\n \"meta\": {\n \"request_id\": \"\",\n \"timestamp\": \"\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] }, { "name": "sync", "description": "", "item": [ { "id": "63cb2892-9f34-4b2f-8a93-975388378426", "name": "Sync offline transactions", "request": { "name": "Sync offline transactions", "description": { "content": "Batch sync offline POS transactions. Processes up to 100 transactions per request. Each transaction requires an idempotency_key for deduplication. Returns HTTP 200 if all succeed, 207 if mixed results.", "type": "text/plain" }, "url": { "path": ["v1", "transactions", "sync"], "host": ["{{baseUrl}}"], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"transactions\": [\n {\n \"qr_code_data\": \"\",\n \"location_id\": \"\",\n \"staff_user_id\": \"\",\n \"purchase_amount\": \"\",\n \"idempotency_key\": \"\",\n \"punch_count\": 1,\n \"transaction_notes\": \"\",\n \"pos_reference_id\": \"\",\n \"pos_terminal_id\": \"\",\n \"client_timestamp\": \"\",\n \"pos_provider\": \"\",\n \"line_items\": [\n {\n \"name\": \"\",\n \"quantity\": 1,\n \"unit_price\": \"\",\n \"total_price\": \"\",\n \"external_product_id\": \"\",\n \"metadata\": {\n \"officia__\": {}\n }\n },\n {\n \"name\": \"\",\n \"quantity\": 1,\n \"unit_price\": \"\",\n \"total_price\": \"\",\n \"external_product_id\": \"\",\n \"metadata\": {\n \"excb3\": {}\n }\n }\n ]\n }\n ],\n \"pos_provider\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": null }, "response": [ { "id": "8351685b-3fdd-4eaf-8388-b81e11971802", "name": "Successful response", "originalRequest": { "url": { "path": ["v1", "transactions", "sync"], "host": ["{{baseUrl}}"], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"transactions\": [\n {\n \"qr_code_data\": \"\",\n \"location_id\": \"\",\n \"staff_user_id\": \"\",\n \"purchase_amount\": \"\",\n \"idempotency_key\": \"\",\n \"punch_count\": 1,\n \"transaction_notes\": \"\",\n \"pos_reference_id\": \"\",\n \"pos_terminal_id\": \"\",\n \"client_timestamp\": \"\",\n \"pos_provider\": \"\",\n \"line_items\": [\n {\n \"name\": \"\",\n \"quantity\": 1,\n \"unit_price\": \"\",\n \"total_price\": \"\",\n \"external_product_id\": \"\",\n \"metadata\": {\n \"officia__\": {}\n }\n },\n {\n \"name\": \"\",\n \"quantity\": 1,\n \"unit_price\": \"\",\n \"total_price\": \"\",\n \"external_product_id\": \"\",\n \"metadata\": {\n \"excb3\": {}\n }\n }\n ]\n }\n ],\n \"pos_provider\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": \"\",\n \"data\": {\n \"total_count\": \"\",\n \"success_count\": \"\",\n \"error_count\": \"\",\n \"results\": [\n {\n \"idempotency_key\": \"\",\n \"result\": {\n \"success\": \"\",\n \"idempotent\": \"\",\n \"transaction_id\": \"\",\n \"card_type\": \"cashback\",\n \"error\": \"\",\n \"message\": \"\"\n }\n },\n {\n \"idempotency_key\": \"\",\n \"result\": {\n \"success\": \"\",\n \"idempotent\": \"\",\n \"transaction_id\": \"\",\n \"card_type\": \"discount\",\n \"error\": \"\",\n \"message\": \"\"\n }\n }\n ]\n },\n \"meta\": {\n \"request_id\": \"\",\n \"timestamp\": \"\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] } ] } ] }, { "name": "health", "description": "", "item": [ { "id": "ccb755cd-5674-41e2-b8fb-dc6a9ca69eb3", "name": "Health check", "request": { "name": "Health check", "description": { "content": "Returns the API health status. No authentication required.", "type": "text/plain" }, "url": { "path": ["health"], "host": ["{{baseUrl}}"], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "c5b42af9-6979-41de-aa30-96a88eaa8431", "name": "Successful response", "originalRequest": { "url": { "path": ["health"], "host": ["{{baseUrl}}"], "query": [], "variable": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": \"ok\",\n \"timestamp\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] } ], "event": [], "variable": [ { "key": "baseUrl", "value": "https://api.forloy.com/api" } ], "info": { "_postman_id": "209f831c-97cd-4e6b-8d88-c682b60340e8", "name": "Forloy Public API", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "description": { "content": "External API for third-party integrators (POS, CRM, kiosks, etc.) to perform loyalty operations on behalf of merchants.\n\n## Authentication\nAll endpoints require a valid access token in the Authorization header:\n```\nAuthorization: Bearer \n```\nObtain tokens via the `/v1/auth/login` endpoint.\n\n## Response Format\nAll endpoints return a consistent JSON envelope:\n```json\n{\n \"success\": true|false,\n \"data\": { ... },\n \"error\": { \"code\": \"...\", \"message\": \"...\" },\n \"meta\": { \"request_id\": \"req_...\", \"timestamp\": \"...\" }\n}\n```\n\n## Card Types\n- **punch**: Earn punches toward free rewards\n- **cashback**: Earn percentage back on purchases\n- **discount**: Get percentage off purchases\n\nContact Support:\n Name: Forloy API Support\n\n## User types & authentication\n\nEvery request sends `Authorization: Bearer {{access_token}}`. Get a token from **POST `v1/auth/login`**, then set `access_token` in your environment (the Login request auto-saves it).\n\n- **System-user (POS) token** β€” the default for the scan / transaction endpoints (cards, transactions, cashback, rewards, products). Logging in with POS credentials yields this token.\n- **Merchant owner (admin) token** β€” REQUIRED for the owner-only **Customer Management** endpoints (`v1/customers…`). Log in with OWNER credentials to get it. A system-user token is rejected there with **403 `OWNER_REQUIRED`**. These endpoints also need `{{merchant_id}}` set to a merchant the owner owns (otherwise **403 `MERCHANT_NOT_AUTHORIZED`**).\n", "type": "text/plain" } }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{access_token}}", "type": "string" } ] } }