Skip to main content
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.
Note: You can view the complete protocol reference for the Cart API and the Complete Checkout API.

​
Advanced use cases

Beyond basic cart operations, the API supports sophisticated scenarios like gift cards and location-based services. These examples demonstrate advanced integration capabilities.

​
Gift cards

Create a cart containing a gift card with recipient details and scheduled delivery. 
POST /api/paypal/v1/merchant-cart
Content-Type: application/json
Authorization: Bearer <paypal-jwt-token>

{
  "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 vs. coordinate data
  • Graceful degradation when coordinates aren’t supported
Here’s how to structure address and coordinate data separately: 
{
  "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

FieldDescriptionExample
latitude & longitudePrecise WGS84 coordinates in decimal degreeslatitude: "37.3349", longitude: "-122.0090"
subdivisionAdministrative division (state, province, region) using ISO 3166-2 formatsubdivision: "CA" (California)
country_codeISO 3166-1 alpha-2 country code for the coordinate locationcountry_code: "US"