Voucher for a friend

Most gift shop purchases are for someone else. The cart carries that intent natively: each item says who receives the voucher, with a personal message, the sender’s name, and, on Indirect products, the option to hide the price on the voucher itself.

Gift options

Every cart item accepts five gift fields:

Field	Role
`sendTo`	`Beneficiary` sends the voucher to someone else; `Shopper` sends it to the buyer
`beneficiary`	The recipient’s first name, last name, and email
`comment`	A personal message, printed on the voucher
`sentFrom`	The sender’s name, as signed on the voucher
`hidePrice`	Hides the amount on the voucher document. Works on `Indirect` products only: a `Direct` voucher always shows its value, and the API ignores the flag

After payment, D-EDGE emails the voucher to the beneficiary and the purchase confirmation to the shopper. Nothing to build on your side beyond the form.

Add a gift to the cart

The examples send the X-API-KEY header introduced in the Quick start. Replace {sessionId} with your session, and the productId and amount with a product from your catalogue. The example adds an Indirect product (a spa session), where hidePrice takes effect; the amount is required and must equal the product’s Fixed price.

curl --request POST \
  --url 'https://{apiBaseUrl}/v1/{sessionId}/cart/item' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "productId": 80002,
    "quantity": 1,
    "amount": { "amount": 150.0, "currency": "EUR" },
    "hidePrice": true,
    "comment": "Happy birthday, enjoy!",
    "sendTo": "Beneficiary",
    "beneficiary": {
      "firstName": "Alex",
      "lastName": "Example",
      "email": "beneficiary@example.com"
    },
    "sentFrom": "Guest"
  }'

const response = await fetch("https://{apiBaseUrl}/v1/{sessionId}/cart/item", {
  method: "POST",
  headers: {
    "X-API-KEY": process.env.DEDGE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    productId: 80002,
    quantity: 1,
    amount: { amount: 150.0, currency: "EUR" },
    hidePrice: true,
    comment: "Happy birthday, enjoy!",
    sendTo: "Beneficiary",
    beneficiary: {
      firstName: "Alex",
      lastName: "Example",
      email: "beneficiary@example.com",
    },
    sentFrom: "Guest",
  }),
});

const { cartItemIds } = await response.json();

import os
import requests

response = requests.post(
    "https://{apiBaseUrl}/v1/{sessionId}/cart/item",
    headers={"X-API-KEY": os.environ["DEDGE_API_KEY"]},
    json={
        "productId": 80002,
        "quantity": 1,
        "amount": {"amount": 150.0, "currency": "EUR"},
        "hidePrice": True,
        "comment": "Happy birthday, enjoy!",
        "sendTo": "Beneficiary",
        "beneficiary": {
            "firstName": "Alex",
            "lastName": "Example",
            "email": "beneficiary@example.com",
        },
        "sentFrom": "Guest",
    },
)

cart_item_ids = response.json()["cartItemIds"]

$response = $client->post('v1/{sessionId}/cart/item', [
    'headers' => ['X-API-KEY' => getenv('DEDGE_API_KEY')],
    'json'    => [
        'productId'   => 80002,
        'quantity'    => 1,
        'amount'      => ['amount' => 150.0, 'currency' => 'EUR'],
        'hidePrice'   => true,
        'comment'     => 'Happy birthday, enjoy!',
        'sendTo'      => 'Beneficiary',
        'beneficiary' => [
            'firstName' => 'Alex',
            'lastName'  => 'Example',
            'email'     => 'beneficiary@example.com',
        ],
        'sentFrom'    => 'Guest',
    ],
]);

$cartItemIds = json_decode($response->getBody(), true)['cartItemIds'];

var response = await client.PostAsJsonAsync("/v1/{sessionId}/cart/item", new
{
    productId = 80002,
    quantity = 1,
    amount = new { amount = 150.0, currency = "EUR" },
    hidePrice = true,
    comment = "Happy birthday, enjoy!",
    sendTo = "Beneficiary",
    beneficiary = new
    {
        firstName = "Alex",
        lastName = "Example",
        email = "beneficiary@example.com"
    },
    sentFrom = "Guest"
});

var cartItemIds = JsonDocument.Parse(
    await response.Content.ReadAsStringAsync()).RootElement.GetProperty("cartItemIds");

String body = """
    {
      "productId": 80002,
      "quantity": 1,
      "amount": { "amount": 150.0, "currency": "EUR" },
      "hidePrice": true,
      "comment": "Happy birthday, enjoy!",
      "sendTo": "Beneficiary",
      "beneficiary": {
        "firstName": "Alex",
        "lastName": "Example",
        "email": "beneficiary@example.com"
      },
      "sentFrom": "Guest"
    }
    """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://{apiBaseUrl}/v1/{sessionId}/cart/item"))
    .header("X-API-KEY", System.getenv("DEDGE_API_KEY"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
JsonNode cartItemIds = mapper.readTree(response.body()).path("cartItemIds");

A 201 returns the created item identifiers:

{
  "cartItemIds": ["b2000002-0002-0003-0004-200000000002"]
}

One cart item is created per unit: quantity: 3 returns three identifiers, and each item carries its own message, recipient, and price visibility, edited separately with Update a cart item.

Shopper form

The confirmation step needs the shopper’s own details, including a country, and can carry a phone code. Two localisation endpoints feed that form: Get country names, translated into the session’s culture, and Get phone codes.

curl --request GET \
  --url 'https://{apiBaseUrl}/v1/{sessionId}/Localization/Countries' \
  --header 'X-API-KEY: YOUR_API_KEY'

{
  "FR": "France",
  "GB": "United Kingdom",
  "US": "United States"
}

Get phone codes returns one entry per country too, but with lowercase keys, English names whatever the session culture, and a value that combines the country name with the dialling prefix. Parse it before rendering a prefix select:

{
  "fr": "France - +33",
  "gb": "United Kingdom - +44",
  "us": "United States - +1"
}

Tips

Validate the beneficiary’s email twice. It is where the voucher lands; a typo is a lost gift and a support ticket. An email confirmation field is worth the friction here.
Offer hidePrice on Indirect gifts only. When sendTo is Beneficiary, most buyers expect the amount of a service to stay private. On a Direct product the flag has no effect: the API accepts it, then keeps the price visible, so a toggle there would silently do nothing.
Cap the message length in your form. The comment is printed on the voucher document; a short, well-displayed message beats a truncated one.
Keep Shopper one click away. Some buyers want to print the voucher and hand it over themselves; sendTo: "Shopper" covers them with the same cart.

Add a cart item

Full schema for the cart item and its gift options.

Confirm the cart

The shopper’s details and the payment hand-off.

Get started

Build

Resources

Gift options

Add a gift to the cart

Shopper form

Tips

Add a cart item

Confirm the cart

​Gift options

​Add a gift to the cart

​Shopper form

​Tips

​Related

Add a cart item

Confirm the cart

Gift options

Add a gift to the cart

Shopper form

Tips

Related