# Integrate invoicing (/platforms/invoicing/integrate) ## Know before you code [#know-before-you-code] * This integration is available to select partners only. * Complete [Onboarding](/platforms/seller-onboarding/before-payment/) before you begin this integration. * In the `POST /v2/customer/partner-referrals` API: * Pass the `INVOICE_READ_WRITE` and `ACCESS_MERCHANT_INFORMATION` permissions in the `features` object. * Pass products as `EXPRESS_CHECKOUT` * Get the email address returned in the `primary_email` field of the `GET /v2/customer/partners/{partner_id}/merchant-integrations/{merchant_id}` API response. You'll use this in the Invoicing APIs. * Complete the steps in [Get started](/platforms/get-started/) to get your credentials. * Use your sandbox business email address as the address for the `Invoicer` API object. * This integration uses the [Invoicing REST API](/api/invoicing/v2/). * You can [make test calls to the Invoicing API with the PayPal API Executor](https://www.paypal.com/apex/product-profile/invoicing_v2/). * Use Postman to explore and test PayPal APIs. ## 1. Create draft invoice [#1-create-draft-invoice] To draft an invoice, copy the following code and modify it as needed. API endpoint used: [Create draft invoice](/api/invoicing/v2/invoices-create) #### Sample request ```text lineNumbers curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/invoices \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ACCESS-TOKEN' \ -H 'PayPal-Partner-Attribution-Id: BN-CODE' \ -H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \ -d '{ "detail": { "invoice_number": "123", "reference": "deal-ref", "invoice_date": "2028-11-22", "currency_code": "USD", "note": "Thank you for your business.", "term": "No refunds after 30 days.", "memo": "This is a long contract", "payment_term": { "term_type": "DUE_ON_DATE_SPECIFIED", "due_date": "2028-11-22" } }, "invoicer": { "name": { "given_name": "David", "surname": "Larusso" }, "address": { "address_line_1": "1234 First Street", "address_line_2": "337673 Hillside Court", "admin_area_2": "Anytown", "admin_area_1": "CA", "postal_code": "98765", "country_code": "US" }, "email_address": "merchant@example.com", "phones": [ { "country_code": "001", "national_number": "4085551234", "phone_type": "MOBILE" } ], "website": "https://example.com", "tax_id": "XX-XXXXXXX", "logo_url": "https://example.com/logo.PNG", "additional_notes": "example note" }, "primary_recipients": [ { "billing_info": { "name": { "given_name": "Stephanie", "surname": "Meyers" }, "address": { "address_line_1": "1234 Main Street", "admin_area_2": "Anytown", "admin_area_1": "CA", "postal_code": "98765", "country_code": "US" }, "email_address": "payer@example.com", "phones": [ { "country_code": "001", "national_number": "4884551234", "phone_type": "HOME" } ], "additional_info_value": "add-info" }, "shipping_info": { "name": { "given_name": "Stephanie", "surname": "Meyers" }, "address": { "address_line_1": "1234 Main Street", "admin_area_2": "Anytown", "admin_area_1": "CA", "postal_code": "98765", "country_code": "US" } } } ], "items": [ { "name": "Yoga mat", "description": "Elastic mat to practice yoga.", "quantity": "1", "unit_amount": { "currency_code": "USD", "value": "50.00" }, "tax": { "name": "Sales Tax", "percent": "7.25" }, "discount": { "percent": "5" }, "unit_of_measure": "QUANTITY" }, { "name": "Yoga t-shirt", "quantity": "1", "unit_amount": { "currency_code": "USD", "value": "10.00" }, "tax": { "name": "Sales Tax", "percent": "7.25" }, "discount": { "amount": { "currency_code": "USD", "value": "5.00" } }, "unit_of_measure": "QUANTITY" } ], "configuration": { "partial_payment": { "allow_partial_payment": true, "minimum_amount_due": { "currency_code": "USD", "value": "20.00" } }, "allow_tip": true, "tax_calculated_after_discount": true, "tax_inclusive": false, "template_id": "" }, "amount": { "breakdown": { "custom": { "label": "Packing Charges", "amount": { "currency_code": "USD", "value": "10.00" } }, "shipping": { "amount": { "currency_code": "USD", "value": "10.00" }, "tax": { "name": "Sales Tax", "percent": "7.25" } }, "discount": { "invoice_discount": { "percent": "5" } } } } }' ``` #### Sample response ```text lineNumbers { "rel": "self", "href": "https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-W44B-KRGF-JM6R-26VU", "method": "GET" } ``` This sample request demonstrates how to create an invoice: 1. **From**: Sender David Larusso, including their address, email address, and phone number. 2. **To**: Recipient Stephanie Meyers, including their address, email address, and phone number. 3. **Items**: * One yoga mat priced at $50, including sales tax. * One t-shirt priced at $10, including sales tax. 4. **Partial Payments**: Enabled with a $20 minimum. 5. **Optional Tip**: Allowed. 6. **Additional Charges**: * $10 packing charges, including sales tax. * $10 shipping charges, including sales tax. 7. **Discount**: A 5% invoice discount applied. ### Modify the code [#modify-the-code] After you copy the code in the sample request, modify the following: * Replace `ACCESS-TOKEN` with your [access token](/platforms/get-started/#exchange-your-api-credentials-for-an-access-token). * Replace `BN-CODE` with your [PayPal Attribution ID](/api/rest/requests/#paypal-partner-attribution-id) to receive revenue attribution. To find your BN code, see [Code and Credential Reference](/platforms/create-account/#link-bncode). * Replace `AUTH-ASSERTION-JWT` with your [PayPal-Auth-Assertion](/api/rest/requests/#paypal-auth-assertion) token. * Replace `merchant@example.com` in `invoicer: email_address` to the `primary_email` of the merchant retrieved from `GET /v1/customer/partners/{partner_id}/merchant-integrations/{merchant_id}` API. * Update `invoice_date` and `due_date` to reflect the current or a future date in the format `YYYY-MM-DD`. If you set a [`term_type`](/api/invoicing/v2#definition-invoice_payment_term), ensure the `due_date` falls within the specified term. * **Optional:** Customize your invoice with additional [invoice parameters](/api/invoicing/v2/invoices-create) as needed. ### Step result [#step-result] A successful request returns the following: * An invoice in your sandbox business account with the status set to `Draft`. You can view this status by logging into your sandbox business account. * A return status code of HTTP `201 Created`. * A JSON response body that includes the ID of the invoice. In the sample response, the ID is `INV2-W44B-KRGF-JM6R-26VU`. You can use this ID to perform other REST API actions, such as editing or deleting the invoice or sending payment reminders. ## 2. Send [#2-send] To send the invoice, copy the following code and modify it as needed. API endpoint used: [Send invoice](/api/invoicing/v2/invoices-send) #### Sample request ```text lineNumbers curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/invoices/{INVOICE-ID}/send \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ACCESS-TOKEN' \ -H 'PayPal-Partner-Attribution-Id: BN-CODE' \ -H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \ -d '{ "send_to_invoicer": true }' ``` #### Sample response ```text lineNumbers { "rel": "self", "href": "https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-W44B-KRGF-JM6R-26VU", "method": "GET" } ``` ### Modify the code [#modify-the-code-1] After you copy the code in the sample request, modify the following: * Replace `ACCESS-TOKEN` with your [access token](/platforms/get-started/#exchange-your-api-credentials-for-an-access-token). * Replace `BN-CODE` with your [PayPal Attribution ID](/api/rest/requests/#paypal-partner-attribution-id) to receive revenue attribution. To find your BN code, see [Code and Credential Reference](/platforms/create-account/#link-bncode). * Replace `AUTH-ASSERTION-JWT` with your [PayPal-Auth-Assertion](/api/rest/requests/#paypal-auth-assertion) token. * Replace `INVOICE-ID` to the invoice ID returned when you created the invoice. ### Step result [#step-result-1] A successful request returns the following: * A return status code of HTTP `200 OK`. * A JSON response body containing information about the invoice. * The invoice status in the merchant's PayPal account changes to `Unpaid (Sent)`. * An email is sent, if you set email notifications in the [request body](/api/invoicing/v2#invoices-send-request-body). > **Note:** **Tip:** PayPal automatically records payments made through the invoice's **Pay Now** button. If you accept payments offline, such as by check or wire transfer, you will need to manually record the payment. ## Next steps [#next-steps] [Customize your Invoicing integration](/platforms/invoicing/customize/)