> 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 # GetBalance # Package: giftCards # Namespace: GiftCardProvider # Method link: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/gift-cards/gift-cards-service-plugin/get-balance.md ## Introduction This method retrieves gift card data from your app. Wix calls this method when a customer applies a gift card as a payment method at checkout. --- ## REST API ### Schema ``` Method: getBalance Description: This method retrieves gift card data from your app. Wix calls this method when a customer applies a gift card as a payment method at checkout. URL: null Method: POST Method parameters: 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: extendedFields | type: ExtendedFields - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). param name: locationId | type: locationId | description: The physical location GUID. Can be based on the Locations API or an external provider. param name: pin | type: pin | description: Gift card PIN. Return type: GetBalanceResponse - name: balance | type: number | description: Current balance. - name: currencyCode | type: string | description: Currency code. - name: externalId | type: string | description: External GUID in the gift card provider's system. Used for integration and tracking across different platforms. Possible Errors: HTTP Code: 404 | Status Code: NOT_FOUND | Application Code: GIFT_CARD_NOT_FOUND | Description: Couldn't find the gift card. 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 ### Get Balance 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/balance' \ -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", }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.giftCards.GiftCardProvider.getBalance(request, metadata) Description: This method retrieves gift card data from your app. Wix calls this method when a customer applies 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: GetBalanceRequest - name: code | type: string | description: Gift card code. - name: locationId | type: string | description: The physical location GUID. Can be based on the Locations API or an external provider. - name: pin | type: string | description: Gift card PIN. - name: extendedFields | type: ExtendedFields | description: [Extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). Return type: PROMISE - name: balance | type: number | description: Current balance. - name: currencyCode | type: string | description: Currency code. - name: externalId | type: string | description: External GUID in the gift card provider's system. Used for integration and tracking across different platforms. Possible Errors: HTTP Code: 404 | Status Code: NOT_FOUND | Application Code: GIFT_CARD_NOT_FOUND | Description: Couldn't find the gift card. 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 ### getBalance ```javascript import { giftVouchersProvider } from '@wix/ecom/service-plugins'; async function getBalance(request,metadata) { const response = await giftVouchersProvider.getBalance(request,metadata); }; ``` ### getBalance (with elevated permissions) ```javascript import { giftVouchersProvider } from '@wix/ecom/service-plugins'; import { auth } from '@wix/essentials'; async function myGetBalanceMethod(request,metadata) { const elevatedGetBalance = auth.elevate(giftVouchersProvider.getBalance); const response = await elevatedGetBalance(request,metadata); } ``` ### getBalance (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 getBalance(request,metadata) { const response = await myWixClient.giftVouchersProvider.getBalance(request,metadata); }; ``` ---