Using the Products API

Purpose of this guide

This guide covers how to create, retrieve, update, and delete the product master under a business account using ReceiptRoller's Products API. It is the entry point for working with product data from a mobile app or server integration.

Prerequisites

• You have obtained an access token via the OAuth 2.0 authorization code flow
• Your app's scopes include store.products.read (read) and/or store.products.write (create, update, delete)
• You know the business account ID (UUID) (Listing business accounts, stores, and POS terminals)
• Base URL: https://receiptroller.io

Endpoint list

1. Retrieve the product list

GET /api/v1/products?organizationId={organizationId}
Authorization: Bearer {access_token}

Query parameters (optional)

• search — partial-match search on product name, SKU, or JAN code
• category — filter by category (exact match)
• brand — filter by brand (exact match)

Example response

{
  "organizationId": "a04507de-043a-4b47-b0a3-6204562f6e20",
  "products": [
    {
      "id": "prd-001",
      "productName": "ブレンドコーヒー M",
      "sku": "CFE-BLD-M",
      "janCode": "4912345000017",
      "category": "ドリンク",
      "brand": "オリジナル",
      "pricing": {
        "basePrice": 480,
        "baseCostPrice": 120,
        "taxRate": 0.10,
        "storePrices": []
      },
      "images": {
        "cover": "https://...",
        "gallery": ["https://..."]
      },
      "status": "Active",
      "variants": { "hasVariants": false, "options": [], "items": [] },
      "integrations": {
        "squareCatalogObjectId": "",
        "smaregiProductId": "SMG-12345"
      },
      "createdAt": "2026-04-01T09:00:00Z",
      "updatedAt": "2026-05-30T12:34:56Z"
    }
  ],
  "totalCount": 1
}

2. Retrieve details of a single product

GET /api/v1/products/{productId}?organizationId={organizationId}
Authorization: Bearer {access_token}

The response includes variants (such as size and color differences). If the product does not belong to the specified business account, it returns 404.

3. Create a new product

POST /api/v1/products?organizationId={organizationId}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "productName": "新商品 アイスティー",
  "sku": "TEA-ICE-001",
  "janCode": "4912345000024",
  "category": "ドリンク",
  "brand": "オリジナル",
  "description": "夏季限定の冷茶。",
  "basePrice": 380,
  "baseCostPrice": 95,
  "taxRate": 0.10,
  "status": "Active",
  "imageUrl": "https://..."
}

Notes

• Only productName is required. Everything else can be omitted
• Even if you include organizationId in the request body, it is ignored. The business account resolved from the token/query is always used (this prevents accidental writes to another tenant)
• The response is the complete product object, including the newly assigned id (productId)

4. Update a product

PUT /api/v1/products/{productId}?organizationId={organizationId}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "productName": "新商品 アイスティー（無糖）",
  "basePrice": 400,
  "status": "Active"
}

The fields you send overwrite the product record (this is a full replacement, not a partial update). Resend the existing values together for any field you want to preserve.

5. Delete a product (soft delete)

DELETE /api/v1/products/{productId}?organizationId={organizationId}
Authorization: Bearer {access_token}

Notes

• The response is 204 No Content
• Because this is a soft delete, the product ID can still be resolved from past POS receipt line items
• Deleted products are not included in list or search results

Handling POS integration IDs

ReceiptRoller's product master is integrated with external POS systems. The integrations block may contain the following IDs.

• squareCatalogObjectId / squareVariationId — the link to Square Catalog
• smaregiProductId — the link to Smaregi's product ID

For products synced from an external POS as the source of truth, these IDs are set automatically. You can write them directly from the API, but it is usually safer to leave them to POS sync and not touch them.

Variants (size and color differences)

When a single product has multiple variants, variants.hasVariants = true and both variants.options (option definitions) and variants.items (the actual variant entries) are populated. The common design is to register only the minimal parent product on creation and add variants later through a separate UI/API.

A typical flow (mobile app)

1. Obtain an access token via OAuth → include store.products.read and store.products.write in the scopes
2. Select a business account with GET /api/v1/me/organizations
3. Show GET /api/v1/products with pagination on the product list screen
4. Use POST /api/v1/products on the new product screen
5. On the edit screen, GET /api/v1/products/{id} → PUT /api/v1/products/{id}
6. After a delete confirmation, DELETE /api/v1/products/{id}

Error responses

Related articles

• Listing business accounts, stores, and POS terminals
• Using the Sales API
• For native mobile apps: multi-business-account access and the OAuth flow
• OAuth scope list and availability