Quick start using Invoicing API

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.

Flow summary

1. Your server sends a POST request to create a draft invoice.
2. PayPal creates the invoice resource and returns an invoice ID.
3. Your server passes the invoice ID in a POST request to send the invoice.
4. PayPal delivers the invoice to the recipient and updates the status.
5. You verify the invoice appears as UNPAID in your sandbox account.

Quick start

Start building with the Invoicing API using this quick-start guide to create, send, and manage invoices programmatically.

Step 1: Get your token

Open the PayPal Developer 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.

curl -X POST https://api-m.sandbox.paypal.com/v1/oauth2/token \
  -H "Accept: application/json" \
  -H "Accept-Language: en_US" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -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.

Step 2: 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.

curl -X POST https://api-m.sandbox.paypal.com/v2/invoicing/invoices \
  -H "Authorization: Bearer ACCESS-TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "detail": {
      "currency_code": "USD",
      "note": "Thanks for your business"
    },
    "invoicer": {
      "name": {
        "given_name": "Jane",
        "surname": "Doe"
      }
    },
    "primary_recipients": [
      {
        "billing_info": {
          "email_address": "[email protected]"
        }
      }
    ],
    "items": [
      {
        "name": "Website design",
        "quantity": "1",
        "unit_amount": {
          "currency_code": "USD",
          "value": "500.00"
        }
      }
    ]
  }'

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.

Step 3: 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. After you send an invoice, it cannot be deleted and can only be canceled to mark it as no longer active.

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

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 appear 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.

If verification fails, see Troubleshooting.

See also

• Invoicing API reference for full operation and schema reference.