Customer Store Credit

Check a customer's current store credit balances and add positive store credit to the customer's balance. Use these endpoints for trusted server-side integrations that need to read or grant credit for goodwill, returns, promotions, or external workflows.

Endpoints

GET /customers/{customerId}/store-credit
POST /customers/{customerId}/store-credit

Authentication

Requires a valid Admin API key.

Authorization: Bearer your_api_key_here

Idempotency

Every POST request must include an Idempotency-Key header. If you retry the same request with the same key, Tiquo returns the original transaction instead of issuing credit twice. If the same key is reused with different request details, the API returns 409 Conflict.

Idempotency-Key: credit-CUST-000001-2026-06-19-001

Get Current Balance

GET /customers/{customerId}/store-credit

Use the optional currency query parameter to return a single currency balance. If the customer has no balance in that currency, the API returns 0.

Example Request

curl "https://api.tiquo.app/api/v1/customers/CUST-000001/store-credit?currency=GBP" \
  -H "Authorization: Bearer your_api_key_here"

Response

{
  "success": true,
  "data": {
    "customerId": "k1234567890abcdef",
    "customerNumber": "CUST-000001",
    "balances": [
      { "currency": "GBP", "balance": 25 }
    ],
    "totalCurrencies": 1
  },
  "timestamp": "2026-06-19T10:30:00.000Z"
}

Add Store Credit

POST /customers/{customerId}/store-credit

The amount you send is added to the customer's current store credit balance for that currency.

Path Parameters

Parameter	Type	Required	Description
`customerId`	string	Yes	Customer number or document ID.

Request Body

Field	Type	Required	Description
`amount`	number	Yes	Positive amount to add. Maximum `1000000`; up to 2 decimal places.
`currency`	string	Yes	Three-letter ISO currency code, for example `GBP`.
`note`	string	No	Optional ledger note, up to 500 characters.

Example Request

curl -X POST "https://api.tiquo.app/api/v1/customers/CUST-000001/store-credit" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: credit-CUST-000001-2026-06-19-001" \
  -d '{
    "amount": 25.00,
    "currency": "GBP",
    "note": "Goodwill credit"
  }'

Response

New issuances return 201 Created. Idempotent retries return 200 OK with idempotentReplay: true.

{
  "success": true,
  "data": {
    "id": "k1234567890abcdef",
    "entityType": "customer",
    "customerId": "k9876543210fedcba",
    "currency": "GBP",
    "type": "issued",
    "amount": 25,
    "balanceAfter": 125,
    "note": "Goodwill credit",
    "idempotencyKey": "credit-CUST-000001-2026-06-19-001",
    "createdAt": 1767225600000,
    "idempotentReplay": false
  },
  "timestamp": "2026-06-19T10:30:00.000Z"
}

Error Responses

Status	Description
`400`	Invalid JSON, amount, currency, note, or idempotency key.
`401`	Missing or invalid API key.
`404`	Customer not found.
`409`	`Idempotency-Key` was reused with different request details.
`429`	Rate limit exceeded.

Customer Store Credit

En esta página