Invoicing

Create invoices to provide your buyers with an itemized list of goods and services, such as cost, quantity, taxes, discounts, and other fields.

On this page

Know before you code

  • Complete Onboarding before you begin this integration.
    • In the POST /v2/customer/partner-referrals API:
      • Pass the INVOICE_READ_WRITE and ACCESS_MERCHANT_INFORMATION permissions in the features object.
      • Pass products as EXPRESS_CHECKOUT
    • Get the email address returned in the primary_email field of the GET /v2/customer/partners/{partner_id}/merchant-integrations/{merchant_id} API response. You'll use this in the Invoicing APIs.
  • The instructions in Get started will help you get your access token.
  • You'll need your build notation (BN) code. If you don't have it, contact your PayPal sales manager.
  • This integration uses the Invoicing REST API.

Step 1: Create a draft invoice

To draft an invoice, copy the following code and modify it.

Sample request

API endpoint used: Create draft invoice

curl -v -X POST https://api.sandbox.paypal.com/v2/invoicing/invoices \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-H "PayPal-Partner-Attribution-Id: BN-Code" \
-d '{
  "detail": {
    "invoice_number": "123",
    "reference": "deal-ref",
    "invoice_date": "2020-11-12",
    "currency_code": "USD",
    "note": "Thank you for your business.",
    "term": "No refunds after 30 days.",
    "memo": "This is a long contract",
    "payment_term": {
      "term_type": "NET_10",
      "due_date": "2020-11-22"
    }
  },
  "invoicer": {
    "name": {
      "given_name": "David",
      "surname": "Larusso"
    },
    "address": {
      "address_line_1": "1234 First Street",
      "address_line_2": "337673 Hillside Court",
      "admin_area_2": "Anytown",
      "admin_area_1": "CA",
      "postal_code": "98765",
      "country_code": "US"
    },
    "email_address": " merchant@example.com",
    "phones": [
      {
        "country_code": "001",
        "national_number": "4085551234",
        "phone_type": "MOBILE"
      }
    ],
    "website": "www.test.com",
    "tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy- Jb5SeuGj185MNNw6g",
    "logo_url": "https://example.com/logo.PNG",
    "additional_notes": "2-4"
  },
  "primary_recipients": [
    {
      "billing_info": {
        "name": {
          "given_name": "Stephanie",
          "surname": "Meyers"
        },
        "address": {
          "address_line_1": "1234 Main Street",
          "admin_area_2": "Anytown",
          "admin_area_1": "CA",
          "postal_code": "98765",
          "country_code": "US"
        },
        "email_address": " bill-me@example.com",
        "phones": [
          {
            "country_code": "001",
            "national_number": "4884551234",
            "phone_type": "HOME"
          }
        ],
        "additional_info_value": "add-info"
      },
      "shipping_info": {
        "name": {
          "given_name": "Stephanie",
          "surname": "Meyers"
        },
        "address": {
          "address_line_1": "1234 Main Street",
          "admin_area_2": "Anytown",
          "admin_area_1": "CA",
          "postal_code": "98765",
          "country_code": "US"
        }
      }
    }
  ],
  "items": [
    {
      "name": "Yoga Mat",
      "description": "Elastic mat to practice yoga.",
      "quantity": "1",
      "unit_amount": {
        "currency_code": "USD",
        "value": "50.00"
      },
      "tax": {
        "name": "Sales Tax",
        "percent": "7.25"
      },
      "discount": {
        "percent": "5"
      },
      "unit_of_measure": "QUANTITY"
    },
    {
      "name": "Yoga t-shirt",
      "quantity": "1",
      "unit_amount": {
        "currency_code": "USD",
        "value": "10.00"
      },
      "tax": {
        "name": "Sales Tax",
        "percent": "7.25"
      },
      "discount": {
        "amount": {
          "currency_code": "USD",
          "value": "5.00"
        }
      },
      "unit_of_measure": "QUANTITY"
    }
  ],
  "configuration": {
    "partial_payment": {
      "allow_partial_payment": true,
      "minimum_amount_due": {
        "currency_code": "USD",
        "value": "20.00"
      }
    },
    "allow_tip": true,
    "tax_calculated_after_discount": true,
    "tax_inclusive": false,
    "template_id": ""
  },
  "amount": {
    "breakdown": {
      "custom": {
        "label": "Packing Charges",
        "amount": {
          "currency_code": "USD",
          "value": "10.00"
        }
      },
      "shipping": {
        "amount": {
          "currency_code": "USD",
          "value": "10.00"
        },
        "tax": {
          "name": "Sales Tax",
          "percent": "7.25"
        }
      },
      "discount": {
        "invoice_discount": {
          "percent": "5"
        }
      }
    }
  }
}'

Modify the code

After you copy the code in the sample request, modify the following:

  • Change Access-Token to your access token.
  • Change BN-Code to your build notation code.
  • Change <merchant@example.com> in invoicer: email_address to the primary_email of the Merchant received in GET /v1/customer/partners/{partner_id}/merchant-integrations/{merchant_id} API.
  • Change invoice_date and due_date to reflect the current or a future date.
  • Optional: Use the details from your order to set other invoice request parameters to populate the details of the invoice.

Step result

A successful request returns the following:

  • An invoice in your sandbox business account in Draft status. See this status by logging into your sandbox business account.
  • A return status code of HTTP 201 Created.
  • A JSON response body that has an ID of the invoice. In the sample response, the ID is INV2-W44B-KRGF-JM6R-26VU.

Use this ID to complete other REST API actions, such as editing or deleting the invoice and sending payment reminders.

Sample response

{
    "rel": "self",
    "href": "https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-W44B-KRGF-JM6R-26VU",
    "method": "GET"
}

Step 2: Send the invoice

To send the invoice, copy the following code and modify it.

Sample request

API endpoint used: Send invoice

curl -v -X POST https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-W44B-KRGF-JM6R-26VU /send \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "send_to_invoicer": true
}'

Modify the code

After you copy the code in the sample request, modify the following:

  • Change Access-Token to your access token.
  • Change the sample invoice ID, INV2-W44B-KRGF-JM6R-26VU, to the invoice ID that was returned when you created the invoice.
  • Optional: If you don't want PayPal to email the invoice notification to your buyer when you create it, because you want to send a QR code, set send_to_recipient to false. This parameter updates the invoice status to UNPAID and does not send the email notification.

Step result

A successful request returns the following:

  • A return status code of HTTP 200 OK.
  • A JSON response body with information about the invoice.
  • The invoice status in the merchant’s PayPal account moves to Unpaid (Sent).
  • If you set email notifications in the request body, the emails are sent.

Tip: PayPal automatically records payments made in the invoice using the Pay Now button. If you accept payments offline, such as a check or a wire transfer, manually record the payment.

Sample response

{
    "rel": "self",
    "href": "https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-W44B-KRGF-JM6R-26VU",
    "method": "GET"
}

Next steps

Test and go live

See also

  • Create QR codes so your buyers can easily view their invoice and pay online
  • Use other Invoicing REST API endpoints to manage your invoices, such as record invoice payments, send invoice reminders, and refunds on invoices.
Popular Search Queries
PayPal Help
FAQ's

FAQ's
Forum

Tech Support Community
PayPal Community