# Quick start using Invoicing API (/api/invoicing)

PayPal Invoicing API lets you create, update, send, and manage invoices programmatically from your backend systems.



## Prerequisites [#prerequisites]

* [PayPal business account](https://www.paypal.com/business/open-business-account?_ga=2.49411041.673139926.1760916697-1259758161.1760473483) with Invoicing enabled.
* Obtain your sandbox credentials and access token. Refer to [Get Started with PayPal REST APIs](/api) for more information.
* (Optional) Use a test email you can access, not your PayPal business email.

> ### What you'll build [#what-youll-build]
>
> After completing this quickstart 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 [#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 [#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 [#step-1-get-your-token]

Open the [PayPal Developer Dashboard](https://developer.paypal.com/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.

> **Tip:** Replace `YOUR_CLIENT_ID` and `YOUR_CLIENT_SECRET` with your sandbox app
> credentials from the dashboard.

```bash
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 [#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 [#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.

> **Tip:** * Replace `ACCESS-TOKEN` with your token from Step 1. - Replace
>   `customer@example.com` with your sandbox personal account email.

```bash
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": "customer@example.com"
        }
      }
    ],
    "items": [
      {
        "name": "Website design",
        "quantity": "1",
        "unit_amount": {
          "currency_code": "USD",
          "value": "500.00"
        }
      }
    ]
  }'
```

#### Expected result [#expected-result-1]

* 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 [#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.

```bash
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 [#expected-result-2]

* 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 [#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](/invoicing/troubleshooting).

## See also [#see-also]

* [Invoicing API reference](/api/invoicing/v2/invoices-send/) for full operation and schema reference.