> ## Documentation Index > Fetch the complete documentation index at: https://docs.paypal.ai/llms.txt > Use this file to discover all available pages before exploring further. # Advanced use cases To extend your API beyond basic product sales, you can enable specialized shopping experiences. This guide shows you how to: * Handle gift cards with recipient information and delivery scheduling. * Use geographic coordinates for location-aware services, such as local-inventory checking and delivery-radius validation. * Support multi-item carts with create, update, and per-item error handling. > **Note:** You can view the complete protocol reference for the [Cart API](/reference/api/rest/cart-operations/create-cart/) and the [Complete Checkout API](/reference/api/rest/checkout/complete-checkout/). ## Gift cards Create a cart containing a gift card with recipient details and scheduled delivery. ```bash lines expandable theme={null} POST /api/paypal/v1/merchant-cart Content-Type: application/json Authorization: Bearer { "items": [ { "variant_id": "GIFTCARD-100", "quantity": 1, "gift_options": { "is_gift": true, "recipient": { "name": "Mary Johnson", "email": "mary@example.com" }, "delivery_date": "2024-12-25T09:00:00Z", "sender_name": "John Smith", "gift_message": "Merry Christmas! Enjoy your shopping." } } ], "payment_method": { "type": "paypal" } } ``` ## Geographic coordinates Some merchants offer location-based services that require precise geographic positioning beyond standard postal addresses. The Cart API supports optional latitude/longitude coordinates to enable features like local inventory checking, distance-based pricing, delivery radius validation, and enhanced shipping calculations. This geographic data operates independently from shipping addresses, allowing you to provide location-aware commerce experiences while maintaining clean separation between postal and coordinate data. ### Latitude and longitude support strategy Geographic coordinates are optional. This feature is for merchants who can provide enhanced location services. Geographic coordinates are provided in a separate `geo_coordinates` field, distinct from the `shipping_address` object. This clean separation allows: * Postal addresses to remain focused on standard shipping data * Geographic coordinates to provide precise location enhancement * Independent handling of address and coordinate data * Graceful degradation when coordinates aren't supported Here's how to structure address and coordinate data separately: ```json lines expandable theme={null} { "shipping_address": { "address_line_1": "123 Main Street", "admin_area_2": "San Jose", "admin_area_1": "CA", "postal_code": "95131", "country_code": "US" }, "geo_coordinates": { "latitude": "37.3349", "longitude": "-122.0090", "subdivision": "CA", "country_code": "US" } } ``` ### Geographic fields The `geo_coordinates` object contains precise location data that enhances address information for location-aware services. | Field | Description | Example | | -------------------------- | ------------------------------------------------------------------------- | --------------------------------------------- | | `latitude` and `longitude` | Precise WGS84 coordinates in decimal degrees | `latitude: "37.3349", longitude: "-122.0090"` | | `subdivision` | Administrative division (state, province, region) using ISO 3166-2 format | `subdivision: "CA"` (California) | | `country_code` | ISO 3166-1 alpha-2 country code for the coordinate location | `country_code: "US"` | ## Multi-item carts The Cart API supports carts with multiple items. You can create a cart with several products in a single request, update the cart by replacing the full items list, and receive per-item error reporting when issues occur. ### Create a cart with multiple items Include multiple items in the `items` array, each with its own `variant_id`, `quantity`, and pricing. ```json lines expandable theme={null} { "items": [ { "variant_id": "SHIRT-BLUE-M", "quantity": 2, "name": "Blue T-Shirt", "description": "Cotton crew neck, Size M", "price": { "currency_code": "USD", "value": "29.99" } }, { "variant_id": "JEANS-SLIM-32", "quantity": 1, "name": "Slim Fit Jeans", "description": "Classic slim fit, Size 32", "price": { "currency_code": "USD", "value": "79.99" } }, { "variant_id": "SNEAKERS-WHITE-10", "quantity": 1, "name": "White Sneakers", "description": "Classic white, Size 10", "price": { "currency_code": "USD", "value": "89.99" } } ], "totals": { "subtotal": { "currency_code": "USD", "value": "229.96" }, "shipping": { "currency_code": "USD", "value": "9.99" }, "tax": { "currency_code": "USD", "value": "20.70" }, "total": { "currency_code": "USD", "value": "260.65" } } } ``` ### Update cart items To update a cart, send the complete items list in the request. The merchant compares this list to the existing cart and applies the differences. A single update can add new items, remove existing items, and change quantities. ```json lines expandable theme={null} { "items": [ { "variant_id": "SHIRT-BLUE-M", "quantity": 3, "name": "Blue T-Shirt", "description": "Cotton crew neck, Size M", "price": { "currency_code": "USD", "value": "29.99" } }, { "variant_id": "SNEAKERS-WHITE-10", "quantity": 1, "name": "White Sneakers", "description": "Classic white, Size 10", "price": { "currency_code": "USD", "value": "89.99" } }, { "variant_id": "HAT-BLACK-OS", "quantity": 1, "name": "Black Cap", "description": "One Size", "price": { "currency_code": "USD", "value": "24.99" } } ] } ``` In this example, compared to the original cart: `SHIRT-BLUE-M` quantity increased from 2 to 3, `JEANS-SLIM-32` was removed, and `HAT-BLACK-OS` was added. ### Error handling for multiple items Return a separate validation issue for each item that fails, and include the `variant_id` so the AI agent can identify the affected item. Errors can be reported in two ways: * **`200/201` with `INCOMPLETE` status** — the cart was created or updated, but some items have issues. Report them in the `validation_issues` array. * **`422 Unprocessable Entity`** — the cart could not be created or the update could not be applied. Report per-item errors in `details[].business_context`. The following example shows an `INCOMPLETE` response where 2 out of 3 items have inventory issues: ```json lines expandable theme={null} { "id": "CART-MULTI-001", "status": "INCOMPLETE", "validation_status": "INVALID", "items": [ { "variant_id": "SHIRT-BLUE-M", "quantity": 2, "name": "Blue T-Shirt", "price": { "currency_code": "USD", "value": "29.99" } }, { "variant_id": "JEANS-SLIM-32", "quantity": 2, "name": "Slim Fit Jeans", "price": { "currency_code": "USD", "value": "79.99" } }, { "variant_id": "SNEAKERS-WHITE-10", "quantity": 1, "name": "White Sneakers", "price": { "currency_code": "USD", "value": "89.99" } } ], "validation_issues": [ { "code": "INVENTORY_ISSUE", "type": "BUSINESS_RULE", "message": "Product is currently out of stock", "user_message": "Blue T-Shirt (Size M) is out of stock. Would you like a different color?", "variant_id": "SHIRT-BLUE-M", "context": { "specific_issue": "ITEM_OUT_OF_STOCK", "available_quantity": 0, "requested_quantity": 2 }, "resolution_options": [ { "action": "REMOVE_ITEM", "label": "Remove from cart" }, { "action": "SUGGEST_ALTERNATIVE", "label": "View other colors" } ] }, { "code": "INVENTORY_ISSUE", "type": "INVALID_DATA", "message": "Requested quantity exceeds available stock", "user_message": "Only 1 unit of Slim Fit Jeans is available. You requested 2.", "variant_id": "JEANS-SLIM-32", "context": { "specific_issue": "INSUFFICIENT_INVENTORY", "available_quantity": 1, "requested_quantity": 2 }, "resolution_options": [ { "action": "MODIFY_CART", "label": "Update to available quantity" } ] } ], "totals": { "subtotal": { "currency_code": "USD", "value": "89.99" }, "shipping": { "currency_code": "USD", "value": "9.99" }, "total": { "currency_code": "USD", "value": "99.98" } } } ```