Pass line-item details

CurrentDocs

Last updated: Jan 14th, 4:24pm

You can pass the details of the items a buyer purchases, to PayPal, through the Create order request. When a buyer checks out their purchase, PayPal displays these invoice-line-item details, such as the item name, quantity, detailed description, price, for buyer verification.

Buyer experience

The details you pass to PayPal are presented to the buyer:

On the paysheet during the Pay with PayPal flow.

In the post-purchase email sent to the buyer about their payment transaction.

In the buyer’s PayPal account Activity > Transactions > All transactions section.

Displaying the purchase details:

Enhances buyer experience.

Provides greater transparency and increases conversion.

Minimizes disputes as buyers can verify the specifics of their purchase.

The following image shows a paysheet with the line-item details.

Paysheet,with,line-item,details

How it works

Pass the buyer's purchase details to PayPal. PayPal displays these details on the paysheet for buyer verification.

[Optional] Confirm whether the paysheet details match the details in your system.

Handle buyer updates to the shipping addresses or options that modify line-items.

Handle buyer updates to the purchases before you capture the order and complete payment processing.

Create an order and pass line-item details

In your app code, when you Create an Order, as part of the request body,

Send the line-item details in the purchase_units[].items[] array. If multiple line items exist, send multiple item objects in the array. Use the following attributes:
- name (Required): Name of the purchased item.
- quantity (Required): Quantity of the item, specified as a whole number.
- unit_amount (Required): Price or rate for a single unit of item, specified as an object with two keys - currency_code and value.
  Note: Ensure to enter a valid value for purchase_units[].amount.breakdown.item_total.
- description: Detailed item description.
- sku: Stock keeping unit (SKU) for the item.
- url: URL to the purchased item. Visible to buyer and used in buyer experiences.
- category: Item category type. Possible values: DIGITAL_GOODS, PHYSICAL_GOODS, DONATION
- image_url: URL of the item's image. File type and size restrictions apply. An image that violates these restrictions will not be honored.
- tax: The item tax for each unit, specified as an object.
  Note: If tax is specified, ensure to enter a valid value for purchase_units[].amount.breakdown.tax_total.

Send additional details, such as the total amount breakdown in purchase_units[].amount.breakdown.

After a successful processing of the Create order request and subsequent buyer log-in, PayPal displays the line-item details on a paysheet for buyer verification.

Sample request

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
2-H 'Content-Type: application/json' \
3-H 'PayPal-Request-Id: REQUEST-ID' \
4-H 'Authorization: Bearer ACCESS-TOKEN' \
5-d '{
6  "intent": "CAPTURE",
7  "purchase_units": [
8    {
9      "invoice_id": "90210",
10      "items": [
11        {
12          "name": "T-Shirt",
13          "description": "Super Fresh Shirt",
14          "unit_amount": {
15            "currency_code": "USD",
16            "value": "20.00"
17          },
18          "quantity": "1",
19          "category": "PHYSICAL_GOODS",
20          "sku": "sku01",
21          "image_url": "https://example.com/static/images/items/1/tshirt_green.jpg",
22          "url": "https://example.com/url-to-the-item-being-purchased-1",
23          "upc": {
24            "type": "UPC-A",
25            "code": "123456789012"
26          }
27        },
28        {
29          "name": "Shoes",
30          "description": "Running, Size 10.5",
31          "sku": "sku02",
32          "unit_amount": {
33            "currency_code": "USD",
34            "value": "100.00"
35          },
36          "quantity": "2",
37          "category": "PHYSICAL_GOODS",
38          "image_url": "https://example.com/static/images/items/1/shoes_running.jpg",
39          "url": "https://example.com/url-to-the-item-being-purchased-2",
40          "upc": {
41            "type": "UPC-A",
42            "code": "987654321012"
43          }
44        }
45      ],
46      "amount": {
47              "currency_code": "USD",
48              "value": "230.00",
49              "breakdown": {
50                "item_total": {
51                  "currency_code": "USD",
52                  "value": "220.00"
53                },
54                "shipping": {
55                  "currency_code": "USD",
56                  "value": "10.00"
57                }
58              }
59            }
60        }
61     ]
62  }'

[Optional] Retrieve line-item details

To confirm whether the line-item(s) details with PayPal match the details in your system, you can use the Show order details API request to retrieve the details in an order and verify them.

Note: In the request, ensure to specify the order ID of the order (whose details you want to retrieve), as the path parameter.

Sample request
Sample response

1curl -v -X GET https://api-m.sandbox.paypal.com/v2/checkout/orders/ORDER-ID \
2-H 'Authorization: Bearer ACCESS-TOKEN'

Handle shipping updates that modify line-items

Note: This step is valid only if you implement Shipping callback.

During the Pay with PayPal flow, if the buyer modifies the shipping address or shipping options and if these changes impact the items that can be delivered to the buyer, use the Shipping callback update to update the line items in the order.

Handle buyer updates to line-items

After payment approval from the buyer, the line-items may require modification, due to:

Purchase changes that the buyer makes after verifying the paysheet.

Changes on your website before capturing the order.

To update the line-item details, in your app code, use the Update order details API request.

In the request, be sure to:

Specify the order ID of the order (whose details you want to update), as the path parameter.

Pass the following attribute values:

op: Operation to be performed on the line item. Possible values: add, remove, replace.

value: Value of the item to be added or replaced. Required if op is add or replace.

Sample request

1curl -v -X PATCH https://api-m.sandbox.paypal.com/v2/checkout/orders/ORDER-ID \
2-H 'Content-Type: application/json' \
3-H 'Authorization: Bearer ACCESS-TOKEN' \
4-d '[
5  {
6    "op": "replace",
7    "path": "/purchase_units/@reference_id=='default'/items/quantity ",
8    "value": 2
9  }
10]'