Session lifecycle
Reuse one session across the journey
Open a session once, then carry itssessionId through the catalogue, the cart, and the confirmation. Do not open a new session per call: the cart lives in the session, and a new session starts from an empty cart.
Recover from an expired session
When a call returns404 for a session you created earlier, treat the session as gone. Create a fresh one and rebuild the cart from the selection you keep on your side. Build this recovery path in from the start rather than assuming sessions last forever.
One exception: on Get the gift shop configuration, a 404 can also mean no configuration exists for the session’s owner. If a fresh session hits the same 404 on that call, check the owner identifiers rather than recreating sessions in a loop.
A paid session locks its cart
The session carries astatus: Pending while the guest shops, Paid once the payment is confirmed. After payment the cart no longer accepts changes: adding, updating, or removing items stops working. Read Get session partial data when you need to know which side of that line a session is on, and start a new session for a new purchase.
Set the culture at creation
Pass the guest’sculture when you create the session: product names, descriptions, and the localised country list all follow it. To switch language mid-journey, update the session rather than recreating it, so the cart survives the change.
Catalogue
Cache what rarely changes
The configuration, categories, and localisation lists are stable for a given shop. Cache them on your side and refresh them periodically rather than on every page view. Do not cache the cart: read it from the API whenever you display it.Respect the price type
A product’s price is eitherFixed or a Range. For a range, let the guest choose an amount between minAmount and maxAmount and send it when adding the item to the cart. For a fixed price, send the product’s own amount unchanged: the amount field is required in both cases, and the API rejects a missing or different amount with a 400.
Respect the quantity limits
Each product carries amin and max quantity. Validate the guest’s input against them before calling Add a cart item, and surface the limits in the interface rather than letting the call fail.
Tell the guest where a voucher is used
Every product carries ausage field. Direct is a value voucher, spent on the hotel’s or group’s online D-EDGE booking engine; its price always appears on the voucher document. Indirect is a service redeemed with the shop owner, at the hotel or within the group, which marks the voucher as used when the guest presents the code; its price can be hidden with hidePrice. Read the field and adapt your product page and confirmation message, so a spa voucher is never presented as spendable online, and a price-hiding option is never shown on a product that always prints its value.
Cart and gift options
Capture the gift intent
Each cart item can go to the shopper or to a beneficiary (sendTo). When the guest offers the voucher to someone else, collect the beneficiary’s name and email, and the optional personal message (comment) and sender name (sentFrom): they travel with the voucher.
Use the cart as the source of truth
Amounts, taxes, and totals are computed by the API. Display the cart from the Get the active cart response rather than recomputing prices on your side, and re-read it right before confirmation so the guest pays what they saw.Confirmation and order
Redirect promptly after confirmation
Confirm the cart returns aredirectUrl to the payment page, hosted and handled by D-EDGE. Send the guest there straight away: the URL reflects the cart at confirmation time. Pass a confirmationUrl so the guest comes back to your site after payment.
Treat the order as sensitive
The order carries the voucher codes, the shopper’s personal data, and a payment summary. A voucher code is worth money: store and display it with the same care as a credential, and never store the payment card details returned with the order.Resilience
Retry transient errors with care
Retry transient failures (network blips, timeouts, and occasional5xx) on GET calls with exponential backoff. Add a cart item is not idempotent (see Requests): before retrying it, read the cart with Get the active cart so you do not add the same voucher twice.
Plan for slow or unreachable calls
Decide upfront how long your interface waits for a response and what it shows past that point. Make the choice deliberately rather than letting the network decide.Log the problem details
When a call fails, capture thetitle field and, on validation errors, the errors map and the traceId from the problem details body in your logs. The traceId lets the partnership team pinpoint the exact failing call when you report it; keep detail and instance too when they are present.