Receiptable API

Base Structure

{
  "template": "default",
  "output": "png",
  "content": {
    // Receipt content goes here
  },
  "style": {
    // Receipt styling options go here
  }
}

Parameter	Type	Templates	Description
`template`	String	default	Template style for the receipt. Options: `"default"`
`output`	String	default	Output format for the receipt. Options: `"png"`, `"jpg"`, `"pdf"`, `"html"`
`content`	Object	default	Contains all content that will appear on the receipt
`style`	Object	default	Contains optional styling

Content

The data object holds the content the content that will appear in the receipt. All content fields are optional; any absent will excluded them from the receipt.

Parameter	Type	Templates	Description
`store`	Object	default, barcode	Name of the store or business
`orderNumber`	String	default	Unique identifier for the order/transaction
`date`	String	default	Formatted date of the transaction
`time`	String	default	Formatted time of the transaction
`cashier`	String	default	Name or ID of the cashier/employee who processed the transaction
`socialMedia`	Object	default	Social media details
`customer`	Object	default	Contains customer information
`currency`	string	default	Currency code of the currency (e.g., usd, gpb, aud, cad)
`items`	Array	default	List of items objects
`tax`	Object	default	Tax details
`tip`	Number	default	Tip amount if applicable
`paymentMethod`	String	default	Method of payment (e.g., “Credit Card”, “Cash”)
`paymentDetails`	Object	default	Additional payment details
`barcode`	Object	default, barcode	Barcode and QR code details
`thankYou`	String	default	A short thank you message
`info`	Array	default, barcode	List of free-text lines to display
`preFooter`	Array	default, barcode	List of free-text lines to display above the footer
`footer`	Array	default, barcode	List of free-text lines to display at the bottom of the receipt

Store

Parameter	Type	Templates	Description
`name`	String	default, barcode	Store name
`image`	Object	default, barcode	Details related to the store’s image
`address`	String	default	Store address
`phone`	String	default	Store phone number
`website`	String	default	Store website

Image

Parameter	Type	Templates	Description
`url`	String	default, barcode	URL for the store image
`alt`	String	default, barcode	Alternative text if the image fails to load from the URL provided
`grayscale`	Boolean	default, barcode	Render in black/white or color
`width`	Number	default, barcode	Width of the image as a percentage of the receipt (0 - 100)

Customer

Parameter	Type	Templates	Description
`name`	String	default	Customer’s name
`email`	String	default	Customer’s email address
`phone`	String	default	Customer’s phone number
`address`	String	default	Customer’s address

Items

Parameter	Type	Templates	Description
`name`	String	default	Name of the product or service
`quantity`	Number	default	Number of items purchased
`price`	Number	default	Price per unit
`discount`	Number	default	Discount amount applied to this item

Tax

Parameter	Type	Templates	Description
`rate`	Number	default	Tax rate as a percentage (e.g., 8.5 for 8.5%)
`amount`	Number	default	Tax amount to override the calculation using the provided rate

Payment Details

Parameter	Type	Templates	Description
`cardType`	String	default	Type of card used (e.g., “Visa”, “Mastercard”)
`lastFour`	String	default	Last four digits of the card number

Barcode

Parameter	Type	Templates	Description
`barcode`	String	default, barcode	Barcode number string to be converted into a barcode
`showCode`	Boolean	default, barcode	Show the barcode number below the barcode
`barcodeHeight`	Number	default, barcode	Height of the barcode in pixels (e.g., 50)
`qrCode`	String	default, barcode	URL address to be converted into a QR code
`qrCodeWidth`	Number	default, barcode	Width of the barcode as a percentage of the receipt width (e.g., 40)

Parameter	Type	Templates	Description
`facebook`	String	default	Facebook account
`instagram`	String	default	Instagram account
`linkedin`	String	default	LinkedIn account
`reddit`	String	default	Reddit account
`twitter`	String	default	Twitter handle
`bluesky`	String	default	BlueSky handle

Style

The style object holds any optional custom styling.

Parameter	Type	Templates	Description
`borderRadius`	Number	default	Border radius size in pixels (e.g., 2)
`fontFamily`	String	default	Font name, must be installed on the viewers device (monospace fonts recommended)
`fontSize`	Number	default	Font size (e.g., 14)
`footerFontSize`	Number	default	Font size of text in the footer (e.g., 12)
`lineSpacing`	Number	default	Spacing between lines of text (e.g., 1.4)
`backgroundColor`	String	default	Color of receipt background (e.g., white, #f9f9f9)
`color`	String	default	Color of receipt text (e.g., #484848, black)
`barcodeColor`	String	default	Color of receipt barcode (e.g., #484848, black)
`qrCodeColor`	String	default	Color of receipt QR code (e.g., #484848, black)
`width`	Number	default	Width of receipt by character-length (e.g., 43)

Templates

Templates are pre-built curated layouts that also determine the fields that are shown on the receipt.

Examples for each template are available by sending a GET request to https://receiptable.dev/api/v1/receipt with the template name provided as a URL parameter.

Examples

JSON Payload

{
  "template": "default",
  "output": "html",
  "content": {
    "storeName": "COFFEE & BAKERY CO.",
    "storeAddress": "123 Main Street, Anytown, CA 94105",
    "storePhone": "(555) 123-4567",
    "storeWebsite": "www.coffeebakery.com",
    "orderNumber": "ORD-2025-04567",
    "date": "April 24, 2025",
    "time": "10:35 AM",
    "cashier": "Emma S.",
    "customer": {
      "name": "John Doe",
      "email": "john@example.com"
    },
    "items": [
      {
        "name": "Cappuccino (Large)",
        "quantity": 2,
        "price": 4.95
      },
      {
        "name": "Avocado Toast",
        "quantity": 1,
        "price": 8.75,
        "discount": 1.5
      }
    ],
    "tax": {
      "rate": 8.5
    },
    "tip": 4.0,
    "paymentMethod": "Credit Card",
    "paymentDetails": {
      "cardType": "Visa",
      "lastFour": "4321"
    },
    "barcode": {
      "barcode": "22437452",
      "qrCode": "https://www.receiptable.dev"
    },
    "thankYou": "Thank you for your purchase!",
    "footer": [
      "Rewards Points Earned: 25",
      "Visit our website for monthly specials!",
      "Receipt ID: TXN-25698-042425"
    ]
  }
}

To generate the receipt, send a HTTP POST request to the Receipt API endpoint. The request body should hold the JSON payload holding your custom receipt data. The request header must contain your unique API key as demonstrated below.

Node.js

const receiptData = {
  template: "default",
  output: "html",
  content: {},
};

fetch("https://receiptable.dev/api/v1/receipt", {
  method: "POST",
  headers: {
    "X-AUTH-TOKEN": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(receiptData),
})
  .then((response) => response.text())
  .then((html) => {
    console.log(html);
  })
  .catch((error) => console.error(error));

Python

import requests

receipt_data = {
    'template': 'default',
    'output': 'html',
    'content': {}
}

response = requests.post(
    'https://receiptable.dev/api/v1/receipt',
    headers={
        'X-AUTH-TOKEN': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json=receipt_data
)

if response.status_code == 200:
    print(response.text())
else:
    print('Error:', response.text)

C#

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var client = new HttpClient();

        var receiptData = new
        {
            template = "default",
            output = "html",
            content = new { }
        };

        var json = System.Text.Json.JsonSerializer.Serialize(receiptData);
        var content = new StringContent(json, Encoding.UTF8, "application/json");

        client.DefaultRequestHeaders.Add("X-AUTH-TOKEN", "YOUR_API_KEY");

        var response = await client.PostAsync("https://receiptable.dev/api/v1/receipt", content);
        var responseBody = await response.Content.ReadAsStringAsync();

        Console.WriteLine(responseBody);
    }
}

cURL

curl -X POST "https://receiptable.dev/api/v1/receipt" \
    -H "X-AUTH-TOKEN: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
            "template": "default",
            "format": "png",
            "content": {}
        }'

Embedding

Express

Since your request need to include your secret API key, it’s important to fetch your receipt on the server-side only. On your server-side, you could set up an endpoint that fetches the receipt (providing details about the order) and returns the HTML to your website.

// server.js
const express = require("express");
const axios = require("axios");
const app = express();

app.get("/receipt", async (req, res) => {
  const receiptData = {
    template: "default",
    output: "html",
    content: {},
  };

  try {
    const response = await axios.post(
      "https://receiptable.dev/api/v1/receipt",
      receiptData,
      {
        headers: {
          "X-AUTH-TOKEN": "YOUR_API_KEY", // Replace with your actual API key
          "Content-Type": "application/json",
        },
      }
    );

    // Send the raw HTML directly
    res.send(response.data.html);
  } catch (error) {
    console.error("API call failed:", error.message);
    res.status(500).send("Failed to load receipt");
  }
});

app.listen(3000, () => console.log("Server running on http://localhost:3000"));

In your website, you can use an <iframe> to load the HTML from your server.

<iframe
  src="https://yourdomain.com/receipt"
  width="100%"
  height="300"
  frameborder="0"
></iframe>

Or you can use JavaScript to fetch and load the HTML into an <iframe> (recommended).

<iframe id="receipt-iframe" style="width:100%; border:none;"></iframe>
<script>
  fetch("https://yourdomain.com/receipt")
    .then((res) => res.text())
    .then((html) => {
      const iframe = document.getElementById("receipt-iframe");
      const iframeDoc = iframe.contentDocument || iframe.contentWindow.document;
      iframeDoc.open();
      iframeDoc.write(html);
      iframeDoc.close();

      // Remove any default margin
      iframeDoc.contentWindow.document.body.style.margin = "0";

      // Adjust iframe height to match content (optional)
      iframe.onload = function () {
        iframe.style.height = iframeDoc.body.scrollHeight + "px";
      };
    })
    .catch((err) => {
      const iframe = document.getElementById("receipt-iframe");
      const iframeDoc = iframe.contentDocument || iframe.contentWindow.document;
      iframeDoc.open();
      iframeDoc.write("Error loading receipt.");
      iframeDoc.close();
    });
</script>

Or inject directly into a standard <div>. Whenever injecting raw HTML, it’s recommended to using sanitisation tools like DOMPurify.

<div id="receipt-container">Loading...</div>
<script>
  fetch("https://yourdomain.com/receipt")
    .then((res) => res.text())
    .then((html) => {
      document.getElementById("receipt-container").innerHTML = html;
    })
    .catch((err) => {
      document.getElementById("receipt-container").innerText =
        "Error loading receipt.";
    });
</script>

Next.js

Similarly to Express, you can set up an server-side endpoint to fetch the receipt which your client-side can consume.

// app/api/receipt/route.js
export async function GET() {
  const receiptData = {
    template: "default",
    output: "html",
    content: {},
  };

  try {
    const res = await fetch("https://receiptable.dev/api/v1/receipt", {
      method: "POST",
      headers: {
        "X-AUTH-TOKEN": process.env.RECEIPT_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(receiptData),
    });

    if (!res.ok) {
      throw new Error(`External API error: ${res.status}`);
    }

    const result = await res.text();

    return new Response(result.html, {
      status: 200,
      headers: { "Content-Type": "text/html" },
    });
  } catch (error) {
    console.error("Receipt API error:", error.message);
    return new Response("Failed to load receipt", { status: 500 });
  }
}

On the client-side, you can fetch from your server and render the receipt.

// app/receipt/page.jsx
"use client";

import { useEffect, useState } from "react";

export default function ReceiptPage() {
  const [html, setHtml] = useState("<p>Loading receipt...</p>");

  useEffect(() => {
    fetch("/api/receipt")
      .then((res) => res.text())
      .then(setHtml)
      .catch(() => setHtml("<p>Error loading receipt.</p>"));
  }, []);

  return (
    <div>
      <h1 className="text-xl font-bold mb-4">Receipt Viewer</h1>
      <div dangerouslySetInnerHTML={{ __html: html }} />
    </div>
  );
}

SendGrid

For email services like SendGrid, configure your server to fetch the receipt and embed it into the email body.

import os
import requests
from sendgrid import SendGridAPIClient
from sendgrid.helpers.mail import Mail

# Load API keys
RECEIPT_API_KEY = os.getenv('RECEIPT_API_KEY')
SENDGRID_API_KEY = os.getenv('SENDGRID_API_KEY')

receipt_payload = {
    "template": "default",
    "output": "html",
    "content": {}
}

# Generate receipt with Receipt API
receipt_response = requests.post(
    'https://receiptable.dev/api/v1/receipt',
    headers={
        'X-AUTH-TOKEN': RECEIPT_API_KEY,
        'Content-Type': 'application/json'
    },
    json=receipt_payload
)

if receipt_response.status_code != 200:
    raise Exception("Failed to generate receipt")

receipt_html = receipt_response.json().get('html')

# Send email with SendGrid
message = Mail(
    from_email='your@email.com',
    to_emails='recipient@example.com',
    subject='Your Receipt from Awesome Store',
    html_content=receipt_html
)

try:
    sg = SendGridAPIClient(SENDGRID_API_KEY)
    response = sg.send(message)
    print(f"Email sent: {response.status_code}")
except Exception as e:
    print(f"Error sending email: {e}")