Integrate invoicing

CURRENTDOCS

Last updated: Apr 6th, 1:30pm

PayPal Invoicing API helps you create, update, send, and manage invoices programmatically from your backend systems. This quick start is for developers who want a minimal, end-to-end example in a sandbox account and need to see the core create-and-send flow with as little setup as possible. You’ll use the PayPal Invoicing REST API to create a draft invoice in your sandbox account, send it to a test customer, and verify that the invoice appears in your sandbox business account.

Prerequisites

PayPal business account with Invoicing enabled.

Obtain your sandbox credentials and access token. Refer to Get Started with PayPal REST APIs for more information.

(Optional) Use a test email you can access, not your PayPal business email. For the complete API reference, including full schema definitions and interactive examples, see the Invoicing API Reference.

What you’ll build

After completing this quick start, you will have:

Created a draft invoice in your sandbox account

Sent the invoice to a sandbox customer email address

Confirmed the invoice status has changed to UNPAID

Flow summary

Your server sends a POST request to create a draft invoice.

PayPal creates the invoice resource and returns an invoice ID.

Your server sends a POST request to send the invoice.

PayPal delivers the invoice to the recipient and updates the status.

You verify the invoice appears as UNPAID in your sandbox account.

Quick start

Get your token

Open the dashboard, then create or select an app. Copy the Client ID and Secret. Use these credentials to generate an access token, and include that token in the Authorization header for every request.

Note: Replace CLIENT_ID and CLIENT_SECRET with your sandbox app credentials from the dashboard.

1curl -X POST https://api-m.sandbox.paypal.com/v1/oauth2/token \
2  -H "Accept: application/json" \
3  -H "Accept-Language: en_US" \
4  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
5  -d "grant_type=client_credentials"

Expected result

        A successful token request returns the status 200 OK.
    
    Copy the access_token value from the response body. You'll use this value in Steps 2 and 3.

Create a draft invoice

Create a draft invoice in a single API call. The invoice is not visible to your customer yet. This step generates the invoice with all required details, such as customer, items, and amount, before sending to the customer. The invoice workflow is: Draft → Sent → Viewed → Paid (or Cancelled/Overdue). This example creates a draft invoice. Save the returned `id`, then call the send invoice endpoint when you're ready to request payment.

Note: Replace ACCESS_TOKEN with your token from Step 1, and replace customer@example.com with your sandbox personal account email.

1curl -X POST https://api-m.sandbox.paypal.com/v2/invoicing/invoices \
2  -H "Authorization: Bearer <ACCESS_TOKEN>" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "detail": {
6      "currency_code": "USD",
7      "note": "Thanks for your business"
8    },
9    "invoicer": {
10      "name": {
11        "given_name": "Jane",
12        "surname": "Doe"
13      }
14    },
15    "primary_recipients": [
16      {
17        "billing_info": {
18          "email_address": "customer@example.com"
19        }
20      }
21    ],
22    "items": [
23      {
24        "name": "Website design",
25        "quantity": "1",
26        "unit_amount": {
27          "currency_code": "USD",
28          "value": "500.00"
29        }
30      }
31    ]
32  }'

Expected result

        A successful request returns the status 201 Created.
    
    The response body contains an href link with your invoice ID (INV2-XXXX-XXXX-XXXX-XXXX).
    
    The invoice appears in your sandbox account with Draft status.

    The invoice is not yet visible to the customer.

Send the invoice

In your sandbox account, send the draft invoice you created in the previous step. This moves the invoice from DRAFT to SENT status, and PayPal sends a secure payment link in the email to your customer. Use the id from step 2 and pass it as the invoice_id path parameter. To change details in the sent invoice, update the specific details using the PUT method, and send_to_recipient: true to notify the customer.

Note: After you send an invoice, you can’t delete it. You can only cancel it to mark it as no longer active.

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/invoices/{invoice_id}/send \
2  -H 'Authorization: Bearer ACCESS-TOKEN' \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "send_to_recipient": true,
6    "send_to_invoicer": true
7  }'

Expected result

        A successful request returns the status 200 OK.
    
    The invoice status changes to UNPAID in your sandbox account. 

    PayPal sends the invoice to the customer email address provided in Step 2.
    
    The customer receives a payment link to pay through PayPal's hosted payment page.
    
Verify it works

You should see:

    Invoice appears in your sandbox PayPal business account under Invoicing.
    
    Invoice status shows as UNPAID.
    
    The customer email address you provided has received a payment notification.

    The invoice ID returned in Step 2 matches the invoice visible in the dashboard.

Next steps

Optional
Customize your integration

Learn more about customizing your invoicing integration

Integrate invoicing

Prerequisites

What you’ll build

Flow summary

Quick start

Get your token

Expected result

Create a draft invoice

Expected result

Send the invoice

Expected result

Verify it works

Next steps

We currently use cookies to improve and customize your experience on our site. If you accept, we’ll also use marketing cookies to show you personalized ads. Manage your cookies and learn more.