The basics of requests and responses (JSON)

Request basics

• Protocol: HTTPS required (HTTP is rejected)
• Format: both request body and response are JSON
• Character encoding: UTF-8
• Authentication: Authorization: Bearer {access_token}

Required and recommended headers

Authorization: Bearer eyJhbGciOi...    ← required
Content-Type: application/json          ← required for POST/PUT
Accept: application/json                ← recommended
User-Agent: MyApp/1.2.3                 ← recommended (for identification in support inquiries)
Idempotency-Key: 01HV6N3M2K...          ← recommended for POST/PUT (prevents duplicates)

The basic structure of a response

A single resource

{
  "id": "rcp_xyz789",
  "object": "receipt",
  "created_at": "2026-04-27T10:15:23Z",
  "store_id": "str_abc123",
  "total_amount": 3850,
  "currency": "JPY"
}

A list (paginated)

{
  "object": "list",
  "data": [
    { "id": "rcp_001", ... },
    { "id": "rcp_002", ... }
  ],
  "has_more": true,
  "next_cursor": "cur_xxx"
}

Pagination (cursor-based)

List APIs are cursor-based. Retrieve the next page with ?limit=50&cursor={previous next_cursor}.

• Default limit: 20, maximum: 100
• If has_more: false, it is the last page
• The cursor is valid for 6 hours
• The order is, as a rule, newest first (created_at DESC)

Filtering

Filter with query parameters.

GET /v1/receipts?store_id=str_abc&issued_after=2026-04-01&issued_before=2026-04-30

Supported comparison operators:
?total_amount[gte]=1000     ← greater than or equal to 1000
?total_amount[lt]=5000      ← less than 5000
?status[in]=issued,refunded ← either one

Date/time format

• All in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ)
• Responses are always in UTC (trailing Z)
• Requests can be sent with a timezone (auto-converted to UTC)

Representing amounts

• Amounts are integers in the smallest currency unit (e.g. for JPY, 1 = 1 yen; for USD, 1 = 1 cent)
• No decimal points or comma separators
• The currency is stated in the currency field (ISO 4217)

ID format

Every resource ID has a prefix. You can tell the type at a glance.

Idempotency key (Idempotency-Key)

Specifying the same Idempotency-Key on a POST/PUT lets ReceiptRoller detect the duplicate and return the first result. This prevents duplicate creation on network retries.

• Use a unique value such as a UUID or ULID
• The key is retained for 24 hours
• It is not shared across different endpoints

Related guides

• Endpoints and versioning
• Representative API examples
• Error codes and retry guidance
• Back to the developer help index