Skip to content

Latest commit

 

History

History
318 lines (220 loc) · 10.6 KB

gift-cards.md

File metadata and controls

318 lines (220 loc) · 10.6 KB

Gift Cards

$giftCardsApi = $client->getGiftCardsApi();

Class Name

GiftCardsApi

Methods

List Gift Cards

Lists all gift cards. You can specify optional filters to retrieve a subset of the gift cards. Results are sorted by created_at in ascending order.

function listGiftCards(
    ?string $type = null,
    ?string $state = null,
    ?int $limit = null,
    ?string $cursor = null,
    ?string $customerId = null
): ApiResponse

Parameters

Parameter Type Tags Description
type ?string Query, Optional If a type is provided, the endpoint returns gift cards of the specified type.
Otherwise, the endpoint returns gift cards of all types.
state ?string Query, Optional If a state is provided, the endpoint returns the gift cards in the specified state.
Otherwise, the endpoint returns the gift cards of all states.
limit ?int Query, Optional If a limit is provided, the endpoint returns only the specified number of results per page.
The maximum value is 200. The default value is 30.
For more information, see Pagination.
cursor ?string Query, Optional A pagination cursor returned by a previous call to this endpoint.
Provide this cursor to retrieve the next set of results for the original query.
If a cursor is not provided, the endpoint returns the first page of the results.
For more information, see Pagination.
customerId ?string Query, Optional If a customer ID is provided, the endpoint returns only the gift cards linked to the specified customer.

Response Type

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type ListGiftCardsResponse.

Example Usage

$apiResponse = $giftCardsApi->listGiftCards();

if ($apiResponse->isSuccess()) {
    $listGiftCardsResponse = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Getting more response information
var_dump($apiResponse->getStatusCode());
var_dump($apiResponse->getHeaders());

Create Gift Card

Creates a digital gift card or registers a physical (plastic) gift card. The resulting gift card has a PENDING state. To activate a gift card so that it can be redeemed for purchases, call CreateGiftCardActivity and create an ACTIVATE activity with the initial balance. Alternatively, you can use RefundPayment to refund a payment to the new gift card.

function createGiftCard(CreateGiftCardRequest $body): ApiResponse

Parameters

Parameter Type Tags Description
body CreateGiftCardRequest Body, Required An object containing the fields to POST for the request.

See the corresponding object definition for field details.

Response Type

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type CreateGiftCardResponse.

Example Usage

$body = CreateGiftCardRequestBuilder::init(
    'NC9Tm69EjbjtConu',
    '81FN9BNFZTKS4',
    GiftCardBuilder::init(
        GiftCardType::DIGITAL
    )->build()
)->build();

$apiResponse = $giftCardsApi->createGiftCard($body);

if ($apiResponse->isSuccess()) {
    $createGiftCardResponse = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Getting more response information
var_dump($apiResponse->getStatusCode());
var_dump($apiResponse->getHeaders());

Retrieve Gift Card From GAN

Retrieves a gift card using the gift card account number (GAN).

function retrieveGiftCardFromGAN(RetrieveGiftCardFromGANRequest $body): ApiResponse

Parameters

Parameter Type Tags Description
body RetrieveGiftCardFromGANRequest Body, Required An object containing the fields to POST for the request.

See the corresponding object definition for field details.

Response Type

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type RetrieveGiftCardFromGANResponse.

Example Usage

$body = RetrieveGiftCardFromGANRequestBuilder::init(
    '7783320001001635'
)->build();

$apiResponse = $giftCardsApi->retrieveGiftCardFromGAN($body);

if ($apiResponse->isSuccess()) {
    $retrieveGiftCardFromGANResponse = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Getting more response information
var_dump($apiResponse->getStatusCode());
var_dump($apiResponse->getHeaders());

Retrieve Gift Card From Nonce

Retrieves a gift card using a secure payment token that represents the gift card.

function retrieveGiftCardFromNonce(RetrieveGiftCardFromNonceRequest $body): ApiResponse

Parameters

Parameter Type Tags Description
body RetrieveGiftCardFromNonceRequest Body, Required An object containing the fields to POST for the request.

See the corresponding object definition for field details.

Response Type

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type RetrieveGiftCardFromNonceResponse.

Example Usage

$body = RetrieveGiftCardFromNonceRequestBuilder::init(
    'cnon:7783322135245171'
)->build();

$apiResponse = $giftCardsApi->retrieveGiftCardFromNonce($body);

if ($apiResponse->isSuccess()) {
    $retrieveGiftCardFromNonceResponse = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Getting more response information
var_dump($apiResponse->getStatusCode());
var_dump($apiResponse->getHeaders());

Link Customer to Gift Card

Links a customer to a gift card, which is also referred to as adding a card on file.

function linkCustomerToGiftCard(string $giftCardId, LinkCustomerToGiftCardRequest $body): ApiResponse

Parameters

Parameter Type Tags Description
giftCardId string Template, Required The ID of the gift card to be linked.
body LinkCustomerToGiftCardRequest Body, Required An object containing the fields to POST for the request.

See the corresponding object definition for field details.

Response Type

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type LinkCustomerToGiftCardResponse.

Example Usage

$giftCardId = 'gift_card_id8';

$body = LinkCustomerToGiftCardRequestBuilder::init(
    'GKY0FZ3V717AH8Q2D821PNT2ZW'
)->build();

$apiResponse = $giftCardsApi->linkCustomerToGiftCard(
    $giftCardId,
    $body
);

if ($apiResponse->isSuccess()) {
    $linkCustomerToGiftCardResponse = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Getting more response information
var_dump($apiResponse->getStatusCode());
var_dump($apiResponse->getHeaders());

Unlink Customer From Gift Card

Unlinks a customer from a gift card, which is also referred to as removing a card on file.

function unlinkCustomerFromGiftCard(string $giftCardId, UnlinkCustomerFromGiftCardRequest $body): ApiResponse

Parameters

Parameter Type Tags Description
giftCardId string Template, Required The ID of the gift card to be unlinked.
body UnlinkCustomerFromGiftCardRequest Body, Required An object containing the fields to POST for the request.

See the corresponding object definition for field details.

Response Type

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type UnlinkCustomerFromGiftCardResponse.

Example Usage

$giftCardId = 'gift_card_id8';

$body = UnlinkCustomerFromGiftCardRequestBuilder::init(
    'GKY0FZ3V717AH8Q2D821PNT2ZW'
)->build();

$apiResponse = $giftCardsApi->unlinkCustomerFromGiftCard(
    $giftCardId,
    $body
);

if ($apiResponse->isSuccess()) {
    $unlinkCustomerFromGiftCardResponse = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Getting more response information
var_dump($apiResponse->getStatusCode());
var_dump($apiResponse->getHeaders());

Retrieve Gift Card

Retrieves a gift card using the gift card ID.

function retrieveGiftCard(string $id): ApiResponse

Parameters

Parameter Type Tags Description
id string Template, Required The ID of the gift card to retrieve.

Response Type

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type RetrieveGiftCardResponse.

Example Usage

$id = 'id0';

$apiResponse = $giftCardsApi->retrieveGiftCard($id);

if ($apiResponse->isSuccess()) {
    $retrieveGiftCardResponse = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Getting more response information
var_dump($apiResponse->getStatusCode());
var_dump($apiResponse->getHeaders());