{"id":13880139,"url":"https://github.com/excid3/receipts","last_synced_at":"2025-10-08T18:06:47.358Z","repository":{"id":26062191,"uuid":"29505782","full_name":"excid3/receipts","owner":"excid3","description":"Easy receipts and invoices for your Ruby on Rails applications","archived":false,"fork":false,"pushed_at":"2025-03-12T17:45:54.000Z","size":444,"stargazers_count":633,"open_issues_count":0,"forks_count":81,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-14T05:15:44.371Z","etag":null,"topics":["pdf","pdf-receipt","rails-application","receipt","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/excid3.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"github":["excid3"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2015-01-20T01:33:12.000Z","updated_at":"2025-03-24T00:23:23.000Z","dependencies_parsed_at":"2024-04-05T15:29:44.504Z","dependency_job_id":null,"html_url":"https://github.com/excid3/receipts","commit_stats":{"total_commits":54,"total_committers":10,"mean_commits":5.4,"dds":"0.20370370370370372","last_synced_commit":"f6f7f85192f1e569ca7c003d64829e2f50388eec"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/excid3%2Freceipts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/excid3%2Freceipts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/excid3%2Freceipts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/excid3%2Freceipts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/excid3","download_url":"https://codeload.github.com/excid3/receipts/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248824693,"owners_count":21167345,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["pdf","pdf-receipt","rails-application","receipt","ruby"],"created_at":"2024-08-06T08:02:48.720Z","updated_at":"2025-10-08T18:06:42.312Z","avatar_url":"https://github.com/excid3.png","language":"Ruby","funding_links":["https://github.com/sponsors/excid3"],"categories":["Ruby"],"sub_categories":[],"readme":"[![Tests](https://github.com/excid3/receipts/actions/workflows/ci.yml/badge.svg)](https://github.com/excid3/receipts/actions/workflows/ci.yml)\n\n# Receipts Gem\n\nReceipts, Invoices, and Statements for your Rails application that works with any payment provider. Receipts uses Prawn to generate the PDFs.\n\nCheck out the [example PDFs](https://github.com/excid3/receipts/blob/master/examples/).\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'receipts'\n```\n\nAnd then execute:\n\n```sh\n$ bundle\n```\n\nOr install it yourself as:\n\n```sh\n$ gem install receipts\n```\n\n## Usage\n\nTo generate a Receipt, Invoice, or Statement, create an instance and provide content to render:\n\n```ruby\nr = Receipts::Receipt.new(\n  # title: \"Receipt\",\n  details: [\n    [\"Receipt Number\", \"123\"],\n    [\"Date paid\", Date.today],\n    [\"Payment method\", \"ACH super long super long super long super long super long\"]\n  ],\n  company: {\n    name: \"Example, LLC\",\n    address: \"123 Fake Street\\nNew York City, NY 10012\",\n    email: \"support@example.com\",\n    logo: File.expand_path(\"./examples/images/logo.png\")\n  },\n  recipient: [\n    \"Customer\",\n    \"Their Address\",\n    \"City, State Zipcode\",\n    nil,\n    \"customer@example.org\"\n  ],\n  line_items: [\n    [\"\u003cb\u003eItem\u003c/b\u003e\", \"\u003cb\u003eUnit Cost\u003c/b\u003e\", \"\u003cb\u003eQuantity\u003c/b\u003e\", \"\u003cb\u003eAmount\u003c/b\u003e\"],\n    [\"Subscription\", \"$19.00\", \"1\", \"$19.00\"],\n    [nil, nil, \"Subtotal\", \"$19.00\"],\n    [nil, nil, \"Tax\", \"$1.12\"],\n    [nil, nil, \"Total\", \"$20.12\"],\n    [nil, nil, \"\u003cb\u003eAmount paid\u003c/b\u003e\", \"$20.12\"],\n    [nil, nil, \"Refunded on #{Date.today}\", \"$5.00\"]\n  ],\n  footer: \"Thanks for your business. Please contact us if you have any questions.\"\n)\n\n# Returns a string of the raw PDF\nr.render\n\n# Writes the PDF to disk\nr.render_file \"examples/receipt.pdf\"\n```\n\n### Configuration\n\nYou can specify the default font for all PDFs by defining the following in an initializer:\n\n```ruby\nReceipts.default_font = {\n  bold: Rails.root.join('app/assets/fonts/tradegothic/TradeGothic-Bold.ttf'),\n  normal: Rails.root.join('app/assets/fonts/tradegothic/TradeGothic.ttf'),\n}\n```\n\n### Options\n\nYou can pass the following options to generate a PDF:\n\n* `recipient` - Array of customer details to include. Typically, this is name, address, email, VAT ID, etc.\n\n* `company` - Hash of your company details\n\n  * `name` - Company name\n\n  * `address` - Company address\n\n  * `email` - Company support email address\n\n  * `phone` - Company phone number - _Optional_\n\n  * `logo` - Logo to be displayed on the receipt - _Optional_\n    This can be either a Path, File, StringIO, or URL. Here are a few examples:\n\n    ```ruby\n    logo: Rails.root.join(\"app/assets/images/logo.png\")\n    logo: File.expand_path(\"./logo.png\")\n    logo: File.open(\"app/assets/images/logo.png\", \"rb\")\n    logo: \"https://www.ruby-lang.org/images/header-ruby-logo@2x.png\" # Downloaded with OpenURI\n    ```\n\n  * `display: []` - Customize the company details rendered. By default, renders `[:address, :phone, :email]` under the company name. Items in the array should be Symbols matching keys in the `company` hash to be displayed.\n\n* `details` - Array of details about the Receipt, Invoice, Statement. Typically, this is receipt numbers, issue date, due date, status, etc.\n\n* `line_items` - Array of line items to be displayed in table format.\n\n* `footer` - String for a message at the bottom of the PDF.\n\n* `font` - Hash of paths to font files - _Optional_\n\n  ```ruby\n  font: {\n    bold: Rails.root.join('app/assets/fonts/tradegothic/TradeGothic-Bold.ttf'),\n    normal: Rails.root.join('app/assets/fonts/tradegothic/TradeGothic.ttf'),\n  }\n  ```\n\n* `logo_height` - An integer value of how tall the logo should be. Defaults to `16`\n\nHere's an example of where each option is displayed.\n\n![options](examples/images/options.jpg)\n\n#### Line Items Table - Column Widths\n\nYou may set an option to configure the line items table's columns width in order to accommodate shortcomings of Prawn's width guessing ability to render header and content reasonably sized.\nThe configuration depends on your line item column count and follows the prawn/table configuration as documented [here](https://prawnpdf.org/prawn-table-manual.pdf):\n\nThis will size the second column to 400 and the fourth column to 50.\n\n```ruby\ncolumn_widths: {1 =\u003e 400,3 =\u003e 50 }\n```\n\nThis will set all column widths, considering your table has 4 columns.\n\n```ruby\ncolumn_widths: [100, 200, 240]\n```\n\nIf not set, it will fall back to Prawn's default behavior.\n\n### Formatting\n\n`details` and `line_items` allow inline formatting with Prawn. This allows you to use HTML tags to format text: `\u003cb\u003e` `\u003ci\u003e` `\u003cu\u003e` `\u003cstrikethrough\u003e` `\u003csub\u003e` `\u003csup\u003e` `\u003cfont\u003e` `\u003ccolor\u003e` `\u003clink\u003e`\n\nSee [the Prawn docs](https://prawnpdf.org/) for more information.\n\n#### Page Size\n\nYou can specify a different page size by passing in the `page_size` keyword argument:\n\n```ruby\nreceipt = Receipts::Receipt.new page_size: \"A4\"\n```\n\n### Internationalization (I18n)\n\nYou can use `I18n.t` when rendering your receipts to internationalize them.\n\n```ruby\nline_items: [\n  [I18n.t(\"receipts.date\"),           created_at.to_s],\n  [I18n.t(\"receipts.product\"), \"GoRails\"],\n  [I18n.t(\"receipts.transaction\"), uuid]\n]\n```\n\n### Custom PDF Content\n\nYou can change the entire PDF content by instantiating an Receipts object without any options.\n\n```ruby\nreceipt = Receipts::Receipt.new # creates an empty PDF\n```\n\nEach Receipts object inherits from Prawn::Document. This allows you to choose what is rendered and include any custom Prawn content you like.\n\n```ruby\nreceipt.text(\"hello world\")\n```\n\nYou can also use the Receipts helpers in your custom PDFs at the current cursor position.\n\n```ruby\nreceipt.text(\"Custom header\")\nreceipt.render_line_items(line_items: [\n  [\"my line items\"]\n])\nreceipt.render_footer(\"This is a custom footer using the Receipts helper\")\n```\n\n### Rendering PDFs\n\nTo render a PDF in memory, use `render`. This is recommended for serving PDFs in your Rails controllers.\n\n```ruby\nreceipt.render\n```\n\nTo render a PDF to disk, use `render_file`:\n\n```ruby\nreceipt.render_file \"receipt.pdf\"\n```\n\n## Rendering PDFs in Rails controller actions\n\nHere's an example Rails controller action you can use for serving PDFs. We'll first look up the database record for the `Charge` we want to render a receipt for.\n\nThe `Charge` model has a `receipt` method that returns a `Receipts::Receipt` instance with all the receipt data filled out.\n\nThen we can `render` to generate the PDF in memory. This produces a String with the raw PDF data in it.\n\nUsing `send_data` from Rails, we can send the PDF contents and provide the browser with a recommended filename, content type and disposition.\n\n```ruby\nclass ChargesController \u003c ApplicationController\n  before_action :authenticate_user!\n  before_action :set_charge\n\n  def show\n    respond_to do |format|\n      format.pdf { send_pdf }\n    end\n  end\n\n  private\n\n    def set_charge\n      @charge = current_user.charges.find(params[:id])\n    end\n\n    def send_pdf\n      # Render the PDF in memory and send as the response\n      send_data @charge.receipt.render,\n        filename: \"#{@charge.created_at.strftime(\"%Y-%m-%d\")}-gorails-receipt.pdf\",\n        type: \"application/pdf\",\n        disposition: :inline # or :attachment to download\n    end\nend\n```\n\nThen, just `link_to` to your charge with the format of `pdf`. For example:\n\n```ruby\n# config/routes.rb\nresources :charges\n```\n\n```erb\n\u003c%= link_to \"View Receipt\", charge_path(@charge, format: :pdf) %\u003e\n```\n\n## Invoices\n\nInvoices follow the exact same set of steps as above. You'll simply want to modify the `details` to include other information for the Invoice such as the Issue Date, Due Date, etc.\n\n```ruby\nReceipts::Invoice.new(\n  # title: \"Invoice\",\n  details: [\n    [\"Invoice Number\", \"123\"],\n    [\"Issue Date\", Date.today.strftime(\"%B %d, %Y\")],\n    [\"Due Date\", Date.today.strftime(\"%B %d, %Y\")],\n    [\"Status\", \"\u003cb\u003e\u003ccolor rgb='#5eba7d'\u003ePAID\u003c/color\u003e\u003c/b\u003e\"]\n  ],\n  recipient: [\n    \"\u003cb\u003eBill To\u003c/b\u003e\",\n    \"Customer\",\n    \"Address\",\n    \"City, State Zipcode\",\n    \"customer@example.org\"\n  ],\n  company: {\n    name: \"Example, LLC\",\n    address: \"123 Fake Street\\nNew York City, NY 10012\",\n    phone: \"(555) 867-5309\",\n    email: \"support@example.com\",\n    logo: File.expand_path(\"./examples/images/logo.png\")\n  },\n  line_items: [\n    [\"\u003cb\u003eItem\u003c/b\u003e\", \"\u003cb\u003eUnit Cost\u003c/b\u003e\", \"\u003cb\u003eQuantity\u003c/b\u003e\", \"\u003cb\u003eAmount\u003c/b\u003e\"],\n    [\"Subscription\", \"$19.00\", \"1\", \"$19.00\"],\n    [nil, nil, \"Subtotal\", \"$19.00\"],\n    [nil, nil, \"Tax Rate\", \"0%\"],\n    [nil, nil, \"Amount Due\", \"$19.00\"]\n  ]\n)\n```\n\n## Statements\n\nStatements follow the exact same set of steps as above. You'll simply want to modify the `details` to include other information for the Invoice such as the Issue Date, Start and End Dates, etc.\n\n```ruby\nReceipts::Statement.new(\n  # title: \"Statement\",\n  details: [\n    [\"Statement Number\", \"123\"],\n    [\"Issue Date\", Date.today.strftime(\"%B %d, %Y\")],\n    [\"Period\", \"#{(Date.today - 30).strftime(\"%B %d, %Y\")} - #{Date.today.strftime(\"%B %d, %Y\")}\"]\n  ],\n  recipient: [\n    \"\u003cb\u003eBill To\u003c/b\u003e\",\n    \"Customer\",\n    \"Address\",\n    \"City, State Zipcode\",\n    \"customer@example.org\"\n  ],\n  company: {\n    name: \"Example, LLC\",\n    address: \"123 Fake Street\\nNew York City, NY 10012\",\n    email: \"support@example.com\",\n    phone: \"(555) 867-5309\",\n    logo: File.expand_path(\"./examples/images/logo.png\")\n  },\n  line_items: [\n    [\"\u003cb\u003eItem\u003c/b\u003e\", \"\u003cb\u003eUnit Cost\u003c/b\u003e\", \"\u003cb\u003eQuantity\u003c/b\u003e\", \"\u003cb\u003eAmount\u003c/b\u003e\"],\n    [\"Subscription\", \"$19.00\", \"1\", \"$19.00\"],\n    [nil, nil, \"Subtotal\", \"$19.00\"],\n    [nil, nil, \"Tax Rate\", \"0%\"],\n    [nil, nil, \"Total\", \"$19.00\"]\n  ]\n)\n```\n\n## Contributing\n\n1. Fork it [https://github.com/excid3/receipts/fork](https://github.com/excid3/receipts/fork)\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create a new Pull Request\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexcid3%2Freceipts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexcid3%2Freceipts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexcid3%2Freceipts/lists"}