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	all	Template style for the receipt. Options: `"default"`
`output`	String	all	Output format for the receipt. Options: `"png"`, `"jpg"`, `"pdf"`, `"html"`
`content`	Object	all	Contains all content that will appear on the receipt
`style`	Object	all	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	all	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
`surveyCode`	String	default	Code for external survey completion
`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	all	Barcode and QR code details
`thankYou`	String	default	A short thank you message
`info`	Array	all	List of free-text lines to display
`preFooter`	Array	all	List of free-text lines to display above the footer
`footer`	Array	all	List of free-text lines to display at the bottom of the receipt

Store

Parameter	Type	Templates	Description
`name`	String	all	Store name
`image`	Object	all	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	all	URL for the store image
`alt`	String	all	Alternative text if the image fails to load from the URL provided
`grayscale`	Boolean	all	Render in black/white or color
`width`	Number	all	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	all	Barcode number string to be converted into a barcode
`showCode`	Boolean	all	Show the barcode number below the barcode
`barcodeHeight`	Number	all	Height of the barcode in pixels (e.g., 50)
`qrCode`	String	all	URL address to be converted into a QR code
`qrCodeWidth`	Number	all	Width of the barcode as a percentage of the receipt width (e.g., 40)

Parameter	Type	Description
`facebook`	String	Facebook account
`instagram`	String	Instagram account
`linkedin`	String	LinkedIn account
`reddit`	String	Reddit account
`twitter`	String	Twitter/X handle
`x`	String	Twitter/X handle
`bluesky`	String	BlueSky handle

Style

The style object holds any optional custom styling.

Parameter	Type	Templates	Description
`borderRadius`	Number	all	Border radius size in pixels (e.g., 2)
`fontFamily`	String	all	Font name, must be installed on the viewers device (monospace fonts recommended)
`fontSize`	Number	all	Font size (e.g., 14)
`footerFontSize`	Number	all	Font size of text in the footer (e.g., 12)
`barcodeFontSize`	Number	all	Font size of text below the barcode (e.g., 11)
`lineSpacing`	Number	all	Spacing between lines of text (e.g., 1.4)
`backgroundColor`	String	all	Color of receipt background (e.g., white, #f9f9f9)
`color`	String	all	Color of receipt text (e.g., #484848, black)
`barcodeColor`	String	all	Color of receipt barcode (e.g., #484848, black)
`qrCodeColor`	String	all	Color of receipt QR code (e.g., #484848, black)
`width`	Number	all	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

When making a request to fetch a receipt, you must provide your unique and secret and unique API key by storing it against X-AUTH-TOKEN in the request headers. To avoid leaking your API key to the client, it’s important to make this request on a secure server that you control. On your application’s server-side, you could set up an API endpoint that fetches the receipt, providing relevant data related to the order, and returns the HTML to your client-side.

// 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 security fetch the receipt providing your secret API key, which your client-side can then 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}")