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

Test the API

Enter your Admin API key, the customer identifier, and any required request values, then select Send.

The POST tester sends a live production request and adds store credit to the customer. Use a unique Idempotency-Key. Your API key is stored only in this browser's local storage, so use the tester on a trusted device.

Authorization

BearerAuth

AuthorizationBearer <token>

API key from the Tiquo dashboard (Settings > API)

In: header

Path Parameters

customerId*string

Customer number or document ID

Query Parameters

currency?string

Optional 3-letter ISO currency code to return one balance.

Match^[A-Za-z]{3}$

Length3 <= length <= 3

Response Body

`application/json`

curl -X GET "https://api.tiquo.app/api/v1/customers/string/store-credit"

{
  "success": true,
  "data": {
    "customerId": "string",
    "customerNumber": "string",
    "balances": [
      {
        "currency": "GBP",
        "balance": 25.5
      }
    ],
    "totalCurrencies": 0
  },
  "timestamp": "2019-08-24T14:15:22Z"
}

{
  "success": false,
  "error": "string",
  "timestamp": "2019-08-24T14:15:22Z"
}

{
  "success": false,
  "error": "string",
  "timestamp": "2019-08-24T14:15:22Z"
}

{
  "success": false,
  "error": "string",
  "timestamp": "2019-08-24T14:15:22Z"
}

{
  "success": false,
  "error": "string",
  "timestamp": "2019-08-24T14:15:22Z"
}

Authorization

BearerAuth

AuthorizationBearer <token>

API key from the Tiquo dashboard (Settings > API)

In: header

Path Parameters

customerId*string

Customer number or document ID

Header Parameters

Idempotency-Key*string

Unique key for this store-credit issuance attempt. Reusing the same key with the same request returns the original transaction; reusing it with different request details returns 409.

Match^[A-Za-z0-9._:-]+$

Length1 <= length <= 128

Request Body

application/json

amount*number

Positive amount to add to the balance.

Multiple Of0.01

Range0 < value <= 1000000

currency*string

Match^[A-Za-z]{3}$

Length3 <= length <= 3

note?string

Optional note for the ledger entry.

Lengthlength <= 500

[key: string]?never

Response Body

`application/json`

curl -X POST "https://api.tiquo.app/api/v1/customers/string/store-credit" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "amount": 1000000,    "currency": "GBP"  }'

{
  "success": true,
  "data": {
    "id": "string",
    "entityType": "customer",
    "customerId": "string",
    "companyId": "string",
    "currency": "string",
    "type": "issued",
    "amount": 0,
    "balanceAfter": 0,
    "note": "string",
    "idempotencyKey": "string",
    "createdAt": 0,
    "idempotentReplay": true
  },
  "timestamp": "2019-08-24T14:15:22Z"
}

{
  "success": true,
  "data": {
    "id": "string",
    "entityType": "customer",
    "customerId": "string",
    "companyId": "string",
    "currency": "string",
    "type": "issued",
    "amount": 0,
    "balanceAfter": 0,
    "note": "string",
    "idempotencyKey": "string",
    "createdAt": 0,
    "idempotentReplay": true
  },
  "timestamp": "2019-08-24T14:15:22Z"
}

{
  "success": false,
  "error": "string",
  "timestamp": "2019-08-24T14:15:22Z"
}

{
  "success": false,
  "error": "string",
  "timestamp": "2019-08-24T14:15:22Z"
}

{
  "success": false,
  "error": "string",
  "timestamp": "2019-08-24T14:15:22Z"
}

{
  "success": false,
  "error": "string",
  "timestamp": "2019-08-24T14:15:22Z"
}

{
  "success": false,
  "error": "string",
  "timestamp": "2019-08-24T14:15:22Z"
}

{
  "success": false,
  "error": "string",
  "timestamp": "2019-08-24T14:15:22Z"
}

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

200application/json

400application/json

401application/json

404application/json

500application/json

200application/json

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`