Creating Invoices

An invoice is created by sending an HTTP POST message to with the details of the invoice passed in the body of the request.

The body of the message must be JSON encoded and the content-type should be set to application/json. On successful creation, the invoice details will be provided in a JSON encoded response.

If there is an error, you will receive a JSON encoded error response. All error responses will have an error field that is an object with two fields called type and message. A merchant is restricted to creating no more than 100 invoices per hour (there are also per second and per minute limits). The fields in the request are described below.

Required POST Fields


This is the amount that is required to be collected from the buyer. Note, if this is specified in a currency other than BTC, the price will be converted into BTC at market exchange rates to determine the amount collected from the buyer.


This is the currency code set for the price setting. Supported pricing currencies include USD, EUR, BTC, and all currencies listed on our Bitcoin Exchange Rates page.

Optional Payment Notification (IPN) Fields

The BitPay invoice service can be configured to send JSON-encoded POST callbacks to a merchant-provided URL endpoint. Settings for this capability are described below.


A passthru variable provided by the merchant and designed to be used by the merchant to correlate the invoice with an order or other object in their system. Maximum string length is 100 characters. This passthru variable can be a JSON-encoded string, e.g.:

posData: '{ "ref" : 711454, "affiliate" : "spring112" }'


A URL to send status update messages to your server (this must be an https URL, unencrypted http URLs or any other type of URL is not supported).

BitPay will send an IPN callback to this URL when the invoice status changes.



An invoice is considered to be confirmed immediately upon receipt of payment.


An invoice is considered to be confirmed after 1 block confirmation (~10 minutes).


An invoice is considered to be confirmed after 6 block confirmations (~1 hour).

If not set on the invoice, transactionSpeed will default to your account-level Order Settings. Note: orders are always posted to your BitPay Account Summary for settlement after 6 block confirmations (regardless of this setting).



Notifications will be sent on every status change.


Notifications are only sent when an invoice is confirmed (according to the transactionSpeed setting).


BitPay will send an email to this email address when the invoice status changes.

Optional Order Handling Fields


This is the URL for a return link that is displayed on the receipt, to return the shopper back to your website after a successful purchase. This could be a page specific to the order, or to their account.

Optional Display Information


Used to display your public order number to the buyer on the BitPay invoice. In the merchant Account Summary page, this value is used to identify the ledger entry. Maximum string length is 100 characters.


Used to display an item description to the buyer. Maximum string length is 100 characters.


Used to display an item SKU code or part number to the buyer. Maximum string length is 100 characters.


Defaults to false.


Indicates a physical item will be shipped (or picked up).


Indicates that nothing is to be shipped for this order.

Buyer Fields

These fields are used for display purposes only and will be shown on the invoice if provided. Maximum string length of each field is 100 characters.

  • buyerName
  • buyerAddress1
  • buyerAddress2
  • buyerCity
  • buyerState
  • buyerZip
  • buyerCountry
  • buyerEmail
  • buyerPhone

BitPay Server Response

  "url": "",
  "posData": "{ \"ref\" : 711454, \"affiliate\" : \"spring112\" }",
  "status": "new",
  "btcPrice": "0.069032",
  "btcDue": "0.069032",
  "price": 20,
  "currency": "USD",
  "exRates": {
    "USD": 289.71999999999997
  "itemDesc": "Lawncare, March",
  "invoiceTime": 1426574968897,
  "expirationTime": 1426575868897,
  "currentTime": 1426574968952,
  "guid": "177005a3-2867-4c65-add8-7ab088e3c414",
  "id": "7MxRGVuBC1XvV138b3AqAR",
  "btcPaid": "0.000000",
  "rate": 289.72,
  "exceptionStatus": false,
  "paymentUrls": {
    "BIP21": "bitcoin:mjBQNNE16a6gWKkkMxc2QiLzrZVViyruUe?amount=0.069032",
    "BIP72": "bitcoin:mjBQNNE16a6gWKkkMxc2QiLzrZVViyruUe?amount=0.069032&r=",
    "BIP72b": "bitcoin:?r=",
    "BIP73": ""
  "token": "Hncf45uBVPNoiXbycHDh2cC37auMxhrxm5ijNCsTKGKfX4Y1vbjWCZvoSdciMNw5G"

The response to a create invoice request, the response to a get invoice request, and the content of a status update notification are all identical JSON representations of the invoice object. The fields are described below.


The unique id of the invoice.


An https URL where the invoice can be viewed.


The passthrough variable provided by the merchant on the original invoice creation.


The current invoice base status. See Invoice States for more info. Possible states: new, paid, confirmed, complete, expired, invalid.


The current invoice extended status. See Invoice States for more info. Possible states: false, paidPartial, paidOver, paidLate.


The amount of bitcoin paid to the invoice.


The numeric exchange rate (based on invoice currency) associated with the invoice at the time of the original purchase.


The price set by the merchant (in terms of the provided currency).


The 3 letter currency code in which the invoice was priced.


The amount of bitcoins being requested for payment of this invoice (same as the price if the merchant set the price in BTC).


The time the invoice was created in milliseconds since midnight January 1, 1970. Time format is .


The time at which the invoice expires and no further payment will be accepted (in milliseconds since midnight January 1, 1970). Currently, all invoices are valid for 15 minutes. Time format is .


The current time on the system (by subtracting the current time from the expiration time, the amount of time remaining for payment can be determined). Time format is .

Displaying Invoices