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 tofalse
. This updates the invoice without sending the email notification to yourself. - To suppress email notifications to your customer, set the
notify_customer
query parameter tofalse
. 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.