The Gift Cards API allows you to create, manage, and track gift cards that customers can use as payment methods. Gift cards store monetary value that can be redeemed during checkout, support email delivery to recipients, and provide comprehensive transaction tracking.
With the Gift Cards API, you can:
- Create gift cards with auto-generated or custom redemption codes.
- Send personalized gift card emails to recipients with custom messaging and scheduling.
- Query and search gift cards with advanced filtering and sorting options.
- Manage gift card status including disabling and expiration handling.
- Find gift cards by sender or recipient email addresses.
It's important to note the following points before starting to code:
- To use the Gift Cards API, the site must have the Wix Gift Card app installed.
- Email delivery features require a premium site plan.
- Gift card codes are obfuscated in all API responses except the initial creation response.
- All monetary amounts must include 2 decimal places maximum precision.
- Currency codes must follow ISO-4217 alphabetic format (for example:
"USD", "EUR").
- Gift card codes can be custom-provided or automatically generated.
A typical gift card follows this lifecycle:
- Creation: Create a gift card with a custom code, initial value, and currency.
- Email delivery (optional): Send the gift card to a recipient via email with personalized messaging.
- Redemption: Customers use the gift card code during checkout to apply the balance.
The API supports two recipient notification patterns:
- Immediate sending: Create a gift card with recipient information and send the email immediately by including notification info during creation.
- Deferred sending: Create a gift card first, then send it later with recipient details using Send Gift Card Email.
Gift card emails support extensive customization:
- Personalized messages: Up to 500 characters of custom text.
- Sender/recipient information: Display names and email addresses.
- Custom images: Add branded visuals to the email.
- Scheduled delivery: Send emails at specific future dates.
When integrating with the Gift Cards API, consider these error handling best practices:
- Implement retry logic for transient errors with exponential backoff.
- Validate input data before making API calls to prevent common validation errors.
- Check gift card status before performing operations that depend on the gift card being active.
- Handle premium site requirements by checking site plan before using email features.
- Use idempotency keys for gift card creation to prevent duplicate creation on retry.
- Log error details including request IDs for troubleshooting with Wix support.
- Gift card: A prepaid payment method that stores monetary value for future purchases. Created with custom codes and can include recipient notification settings.
- Balance: The current available amount remaining on a gift card that can be used for purchases. Automatically updated as transactions occur.
- Redemption: The process of using a gift card's balance to pay for purchases, which creates a
REDEEM transaction.
- Code obfuscation: Security feature that masks most characters of gift card codes in API responses, showing only the last 4 characters.
- Source: Indicates how a gift card was created - either through an eCommerce
ORDER or MANUAL creation via API.
- Notification info: Email delivery settings including recipient, sender, personalized message, and delivery scheduling options.
- Initial value: The original monetary amount assigned to a gift card when first created, which never changes.
- Code suffix: The last 4 characters of a gift card code, used for search and identification purposes while maintaining security.