Advanced features and use cases for Store Sync

This guide is for developers who have completed the core Store Sync integration and want to extend their API to support specialized shopping experiences. No additional prerequisites or configuration are required beyond the base integration in Integrate Store Sync with your API. 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.

Gift cards

To create a cart containing a gift card with recipient details and scheduled delivery, follow these steps:

1. Add the gift card as an item in your cart request using its variant_id.
2. Include a gift_options object on the item with the recipient's name, email, delivery date, sender name, and optional gift message.
3. Submit the cart request to POST /merchant-cart.

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"
  }
}

Results: PayPal returns a cart response with status of CREATED and validation_status of VALID. The gift card is scheduled for delivery to the recipient on the specified delivery_date.

Geographic coordinates

Some merchants offer location-based services that require precise geographic positioning beyond standard postal addresses. The Cart API supports optional latitude and longitude coordinates to enable features like local inventory checking, distance-based pricing, delivery radius validation, and enhanced shipping calculations.

Geographic coordinate data operates independently from shipping addresses, which allows you to provide location-aware commerce experiences while maintaining a clean separation between postal and coordinate data.

Latitude and longitude support strategy

Geographic coordinates are optional and intended for merchants who can provide enhanced location services. Coordinates are provided in a separate geo_coordinates field, distinct from the shipping_address object. This 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 are not supported.

The following example shows 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"
  }
}

Results: PayPal uses the geo_coordinates values to enhance location-aware services such as inventory lookups and delivery radius checks. The shipping_address is used for fulfillment as normal. If your implementation does not support geographic coordinates, the field is ignored and the request proceeds using the shipping address only.

Geographic fields

The geo_coordinates object contains precise location data that enhances address information for location-aware services.

Troubleshoot common issues

Next steps

To see how these features can be used in real-world scenarios, review some Store Sync integration use cases that demonstrate error handling patterns and best practices for implementing intelligent, agentic shopping experiences. For complete protocol details, refer to the Cart API reference and the Complete Checkout API reference.