> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # Redeem # Package: giftCards # Namespace: GiftCardProvider # Method link: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/gift-cards/gift-cards-service-plugin/redeem.md ## Introduction This method requests that a transaction be created by your app. Wix calls this method when a customer completes a purchase that includes a gift card as a payment method at checkout. --- ## REST API ### Schema ``` Method: redeem Description: This method requests that a transaction be created by your app. Wix calls this method when a customer completes a purchase that includes a gift card as a payment method at checkout. URL: null Method: POST Method parameters: param name: amount | type: amount | description: Amount to redeem from the gift card. param name: appInstanceId | type: appInstanceId | description: App GUID of the Gift Card provider. Deprecated. param name: code | type: code | description: Gift card code. param name: currencyCode | type: currencyCode | description: Currency code. param name: locationId | type: locationId | description: Physical location GUID. Can be based on the Locations API or an external provider. param name: orderId | type: orderId | description: Order GUID the gift card transaction is applied to. Order details can be collected from eCommerce Search Orders. param name: pin | type: pin | description: Gift card PIN. Return type: RedeemResponse - name: remainingBalance | type: number | description: Remaining balance on the Gift Card after the redemption. - name: currencyCode | type: string | description: Currency code. - name: transactionId | type: string | description: Transaction GUID. Possible Errors: HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: CURRENCY_NOT_SUPPORTED | Description: Currency code isn't supported. HTTP Code: 404 | Status Code: NOT_FOUND | Application Code: GIFT_CARD_NOT_FOUND | Description: Couldn't find the gift card. HTTP Code: 409 | Status Code: ALREADY_EXISTS | Application Code: ALREADY_REDEEMED | Description: Gift card was already redeemed for this order. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: INSUFFICIENT_FUNDS | Description: Gift card doesn't have enough funds. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: GIFT_CARD_EXPIRED | Description: Gift card has expired. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: GIFT_CARD_DISABLED | Description: Gift card is disabled. ``` ### Examples ### Redeem Gift Card The data payload will include the following object as an encoded JWT. For the purposes of this example, we show the request and response objects decoded. ```curl curl -X POST \ 'http://provider.example.com/v1/redeem' \ -H 'user-agent: Wix' \ -H 'accept-encoding: gzip, deflate' \ -H 'content-type: text/plain; charset=utf-8' \ -d '{ "code": "GIFT-CARD-CODE-123", "appInstanceId":"044667f4-c13f-46c2-8506-de9e42293896", "amount": 20.00, "currencyCode": "USD", "orderId": "00000000-0000-0000-0000-000000000001" }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.giftCards.GiftCardProvider.redeem(request, metadata) Description: This method requests that a transaction be created by your app. Wix calls this method when a customer completes a purchase that includes a gift card as a payment method at checkout. Method parameters: param name: metadata | type: Context | description: this message is not directly used by any service, it exists to describe the expected parameters that SHOULD be provided to invoked Velo methods as part of open-platform. e.g. SPIs, event-handlers, etc.. NOTE: this context object MUST be provided as the last argument in each Velo method signature. Example: ```typescript export function wixStores_onOrderCanceled({ event, metadata }: OrderCanceledEvent) { ... } ``` - name: requestId | type: string | description: A unique identifier of the request. You may print this GUID to your logs to help with future debugging and easier correlation with Wix's logs. - name: currency | type: string | description: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-letter currency code. - name: identity | type: IdentificationData | description: An object that describes the identity that triggered this request. - ONE-OF: - name: anonymousVisitorId | type: string | description: GUID of a site visitor that has not logged in to the site. - name: memberId | type: string | description: GUID of a site visitor that has logged in to the site. - name: wixUserId | type: string | description: GUID of a Wix user (site owner, contributor, etc.). - name: appId | type: string | description: GUID of an app. - name: languages | type: array | description: A string representing a language and region in the format of `"xx-XX"`. First 2 letters represent the language code according to ISO 639-1. This is followed by a dash "-", and then a by 2 capital letters representing the region according to ISO 3166-2. For example, `"en-US"`. - name: instanceId | type: string | description: The service provider app's instance GUID. param name: request | type: RedeemRequest - name: code | type: string | description: Gift card code. - name: amount | type: number | description: Amount to redeem from the gift card. - name: orderId | type: string | description: Order GUID the gift card transaction is applied to. Order details can be collected from eCommerce Search Orders. - name: currencyCode | type: string | description: Currency code. - name: locationId | type: string | description: Physical location GUID. Can be based on the Locations API or an external provider. - name: pin | type: string | description: Gift card PIN. Return type: PROMISE - name: remainingBalance | type: number | description: Remaining balance on the Gift Card after the redemption. - name: currencyCode | type: string | description: Currency code. - name: transactionId | type: string | description: Transaction GUID. Possible Errors: HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: CURRENCY_NOT_SUPPORTED | Description: Currency code isn't supported. HTTP Code: 404 | Status Code: NOT_FOUND | Application Code: GIFT_CARD_NOT_FOUND | Description: Couldn't find the gift card. HTTP Code: 409 | Status Code: ALREADY_EXISTS | Application Code: ALREADY_REDEEMED | Description: Gift card was already redeemed for this order. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: INSUFFICIENT_FUNDS | Description: Gift card doesn't have enough funds. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: GIFT_CARD_EXPIRED | Description: Gift card has expired. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: GIFT_CARD_DISABLED | Description: Gift card is disabled. ``` ### Examples ### redeem ```javascript import { giftVouchersProvider } from '@wix/ecom/service-plugins'; async function redeem(request,metadata) { const response = await giftVouchersProvider.redeem(request,metadata); }; ``` ### redeem (with elevated permissions) ```javascript import { giftVouchersProvider } from '@wix/ecom/service-plugins'; import { auth } from '@wix/essentials'; async function myRedeemMethod(request,metadata) { const elevatedRedeem = auth.elevate(giftVouchersProvider.redeem); const response = await elevatedRedeem(request,metadata); } ``` ### redeem (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { giftVouchersProvider } from '@wix/ecom/service-plugins'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { giftVouchersProvider }, // Include the auth strategy and host as relevant }); async function redeem(request,metadata) { const response = await myWixClient.giftVouchersProvider.redeem(request,metadata); }; ``` ---