Marketplaces and Platforms / Accept Payments / Invoicing

Invoicing

APICurrent


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

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.

1. Create 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-m.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-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-W44B-KRGF-JM6R-26VU",
    "method": "GET"
}

2. Send 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-m.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-m.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.