Invoicing / Integrate / Process Invoices

Process Invoices


After you create and send invoices, you can update invoices, issue refunds against online payments, and mark invoices as paid or refunded.

1. Update invoice

To fully update an invoice, include the invoice ID in the URI and a complete invoice object in the JSON request body.

Note: The update invoice call does not support partial updates.

Updating the invoice emails a notification to both you and your customer.

You can suppress the email notifications that PayPal automatically sends:

  • To suppress email notifications to yourself, set the notify_merchant query parameter to false. This updates the invoice without sending the email notification to yourself.
  • To suppress email notifications to your customer, set the notify_customer query parameter to false. This updates the invoice without sending the email notification to the customer.

To share the invoice link in your own email, text, or chat message, call show invoice details to get the invoice URL in the HATEOAS links.

This sample request updates an invoice:

curl - X PUT \
  https: //api-m.sandbox.paypal.com/v1/invoicing/invoices/<invoice_id> \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <Access-Token>" \
  -d '{
  "merchant_info": {
    "logo_url": "https://pics.paypal.com/00/s/MjA2WDE4NzRYUE5H/p/ZDBlYzMxOTctZDE0Ni00ZmQ0LThkZTgtNGU5YzYyNjg3OTRh/image_109.PNG",
    "email": "dlarusso@example.com",
    "first_name": "David",
    "last_name": "Larusso",
    "business_name": "Mitchell & Murray",
    "phone": {
      "country_code": "001",
      "national_number": "4085551234"
    },
    "address": {
      "line1": "1234 First Street",
      "city": "Anytown",
      "state": "CA",
      "postal_code": "98765",
      "country_code": "US"
    }
  },
  "billing_info": [{
    "email": "stmeyers@example.com",
    "first_name": "Stephanie",
    "last_name": "Meyers"
  }],
  "items": [{
    "name": "Zoom System wireless headphones",
    "quantity": 2,
    "unit_price": {
      "currency": "USD",
      "value": "120.00"
    },
    "tax": {
      "name": "Tax",
      "percent": 8
    }
  }, {
    "name": "Bluetooth speaker",
    "quantity": 1,
    "unit_price": {
      "currency": "USD",
      "value": "145.00"
    },
    "tax": {
      "name": "Tax",
      "percent": 8
    }
  }],
  "payment_term": {
    "term_type": "NET_45"
  },
  "shipping_info": {
    "first_name": "Stephanie",
    "last_name": "Meyers",
    "address": {
      "line1": "1234 Main Street",
      "city": "Anytown",
      "state": "CA",
      "postal_code": "98765",
      "country_code": "US"
    }
  }
}'

A successful request returns the HTTP 200 OK status code and a JSON response body that displays the invoice with the recent updates:

{
  "id": "INV2-RF6D-L66T-D7H2-CRU7",
  "number": "0014",
  "status": "DRAFT",
  "merchant_info": {
    "email": "dlarusso@example.com",
    "first_name": "David",
    "last_name": "Larusso",
    "business_name": "Mitchell & Murray",
    "phone": {
      "country_code": "001",
      "national_number": "4085551234"
    },
    "address": {
      "line1": "1234 First Street",
      "city": "Anytown",
      "state": "CA",
      "postal_code": "98765",
      "country_code": "US"
    }
  },
  "billing_info": [
    {
      "email": "stmeyers@example.com",
      "first_name": "Stephanie",
      "last_name": "Meyers"
    }
  ],
  "shipping_info": {
    "first_name": "Stephanie",
    "last_name": "Meyers",
    "address": {
      "line1": "1234 Main Street",
      "city": "Anytown",
      "state": "CA",
      "postal_code": "98765",
      "country_code": "US"
    }
  },
  "items": [
    {
      "name": "Zoom System wireless headphones",
      "quantity": 2,
      "unit_price": {
        "currency": "USD",
        "value": "120.00"
      },
      "tax": {
        "name": "Tax",
        "percent": 8
      }
    },
    {
      "name": "Bluetooth speaker",
      "quantity": 1,
      "unit_price": {
        "currency": "USD",
        "value": "145.00"
      },
      "tax": {
        "name": "Tax",
        "percent": 8
      }
    }
  ],
  "invoice_date": "2017-03-24 PDT",
  "payment_term": {
    "term_type": "NET_45",
    "due_date": "2017-07-08 PDT"
  },
  "tax_calculated_after_discount": false,
  "tax_inclusive": false,
  "note": "Thank you for your business.",
  "total_amount": {
    "currency": "USD",
    "value": "500.00"
  }
}

2. Mark invoice as paid

You can mark an invoice, by ID, as paid.

Include these parameters in the JSON request body:

Parameter Type Description
date string Optional. The date when the invoice was paid, in Internet date and time format.
method enum Required. The payment mode or method. Value is BANK_TRANSFER, CASH, CHECK, CREDIT_CARD, DEBIT_CARD, PAYPAL, WIRE_TRANSFER, or OTHER.
note string Optional. A note associated with the payment.
amount object

Optional. The payment amount to record against the invoice.

If you omit this parameter, the total invoice amount is marked as paid. This amount cannot exceed the amount due.

Note: If the invoice is paid through the online invoice payment experience, PayPal automatically records the invoice as paid. Mark an invoice as paid only when you must record a non-PayPal payment, such as check or cash payment.

This sample request marks an invoice as paid:

curl -v -X POST \
  https://api-m.sandbox.paypal.com/v1/invoicing/invoices/<invoice_id>/record-payment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <Access-Token>" \
  -d '{
  "method": "CASH",
  "date": "2017-11-06 03:30:00 PST",
  "note": "I got the payment by cash!",
  "amount":
  {
    "currency": "USD",
    "value": "20.00"
  }
}'

A successful request returns the HTTP 200 OK status code with no JSON response body.

3. Process refund

To process a refund, call refund sale. In the request URI, include the ID of the sale transaction to refund. In the JSON request body, include the invoice number.

To get these values, call show invoice details.

To process a full refund including your fee to PayPal, omit the amount object.

To process a partial refund, include the amount object with a value of less than the full amount of the invoice.

After you process a refund and you show invoice details, the invoice status of a full refund is REFUNDED and the status of a partial refund is PARTIALLY_REFUNDED.

4. Mark invoice as refunded

You can mark an invoice, by ID, as refunded.

Include these parameters in the JSON request body:

Parameter Type Description
date string Optional. The date when the invoice was refunded, in Internet date and time format. For example, 2014-02-27 PST.
note string Optional. A note associated with the refund.
amount object

Optional. The currency and amount to record as refunded.

If you omit the amount, the total invoice paid amount is recorded as refunded.

To record a partial refund, enter an amount that is less than the amount that has been manually recorded as paid.

The refund amount cannot exceed the total amount that was marked as paid against this invoice.

You cannot mark an invoice as refunded if it was originally paid online through PayPal.

This sample request marks an invoice as refunded:

curl -v -X POST \
  https://api-m.sandbox.paypal.com/v1/invoicing/invoices/<invoice_id>/record-refund \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <Access-Token>" \
  -d '{
  "date": "2017-11-10 14:00:00 PST",
  "note": "Refunded by cash!",
  "amount":
  {
    "currency": "USD",
    "value": "20.00"
  }
}'

A successful request returns the HTTP 200 OK status code with no JSON response body.

Next

Continue to View Invoice Information.