gift_cards.go

// This file was auto-generated by Fern from our API Definition.

package square

import (
	json "encoding/json"
	fmt "fmt"
	internal "github.com/square/square-go-sdk/internal"
)

type LinkCustomerToGiftCardRequest struct {
	// The ID of the gift card to be linked.
	GiftCardID string `json:"-" url:"-"`
	// The ID of the customer to link to the gift card.
	CustomerID string `json:"customer_id" url:"-"`
}

type UnlinkCustomerFromGiftCardRequest struct {
	// The ID of the gift card to be unlinked.
	GiftCardID string `json:"-" url:"-"`
	// The ID of the customer to unlink from the gift card.
	CustomerID string `json:"customer_id" url:"-"`
}

type CreateGiftCardRequest struct {
	// A unique identifier for this request, used to ensure idempotency. For more information,
	// see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
	IdempotencyKey string `json:"idempotency_key" url:"-"`
	// The ID of the [location](entity:Location) where the gift card should be registered for
	// reporting purposes. Gift cards can be redeemed at any of the seller's locations.
	LocationID string `json:"location_id" url:"-"`
	// The gift card to create. The `type` field is required for this request. The `gan_source`
	// and `gan` fields are included as follows:
	//
	// To direct Square to generate a 16-digit GAN, omit `gan_source` and `gan`.
	//
	// To provide a custom GAN, include `gan_source` and `gan`.
	// - For `gan_source`, specify `OTHER`.
	// - For `gan`, provide a custom GAN containing 8 to 20 alphanumeric characters. The GAN must be
	// unique for the seller and cannot start with the same bank identification number (BIN) as major
	// credit cards. Do not use GANs that are easy to guess (such as 12345678) because they greatly
	// increase the risk of fraud. It is the responsibility of the developer to ensure the security
	// of their custom GANs. For more information, see
	// [Custom GANs](https://developer.squareup.com/docs/gift-cards/using-gift-cards-api#custom-gans).
	//
	// To register an unused, physical gift card that the seller previously ordered from Square,
	// include `gan` and provide the GAN that is printed on the gift card.
	GiftCard *GiftCard `json:"gift_card,omitempty" url:"-"`
}

type GiftCardsGetRequest struct {
	// The ID of the gift card to retrieve.
	ID string `json:"-" url:"-"`
}

type GetGiftCardFromGanRequest struct {
	// The gift card account number (GAN) of the gift card to retrieve.
	// The maximum length of a GAN is 255 digits to account for third-party GANs that have been imported.
	// Square-issued gift cards have 16-digit GANs.
	Gan string `json:"gan" url:"-"`
}

type GetGiftCardFromNonceRequest struct {
	// The payment token of the gift card to retrieve. Payment tokens are generated by the
	// Web Payments SDK or In-App Payments SDK.
	Nonce string `json:"nonce" url:"-"`
}

type GiftCardsListRequest struct {
	// If a [type](entity:GiftCardType) is provided, the endpoint returns gift cards of the specified type.
	// Otherwise, the endpoint returns gift cards of all types.
	Type *string `json:"-" url:"type,omitempty"`
	// If a [state](entity:GiftCardStatus) is provided, the endpoint returns the gift cards in the specified state.
	// Otherwise, the endpoint returns the gift cards of all states.
	State *string `json:"-" url:"state,omitempty"`
	// 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](https://developer.squareup.com/docs/working-with-apis/pagination).
	Limit *int `json:"-" url:"limit,omitempty"`
	// 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](https://developer.squareup.com/docs/working-with-apis/pagination).
	Cursor *string `json:"-" url:"cursor,omitempty"`
	// If a customer ID is provided, the endpoint returns only the gift cards linked to the specified customer.
	CustomerID *string `json:"-" url:"customer_id,omitempty"`
}

// A response that contains a `GiftCard`. The response might contain a set of `Error` objects if the request
// resulted in errors.
type CreateGiftCardResponse struct {
	// Any errors that occurred during the request.
	Errors []*Error `json:"errors,omitempty" url:"errors,omitempty"`
	// The new gift card.
	GiftCard *GiftCard `json:"gift_card,omitempty" url:"gift_card,omitempty"`

	extraProperties map[string]interface{}
	rawJSON         json.RawMessage
}

func (c *CreateGiftCardResponse) GetErrors() []*Error {
	if c == nil {
		return nil
	}
	return c.Errors
}

func (c *CreateGiftCardResponse) GetGiftCard() *GiftCard {
	if c == nil {
		return nil
	}
	return c.GiftCard
}

func (c *CreateGiftCardResponse) GetExtraProperties() map[string]interface{} {
	return c.extraProperties
}

func (c *CreateGiftCardResponse) UnmarshalJSON(data []byte) error {
	type unmarshaler CreateGiftCardResponse
	var value unmarshaler
	if err := json.Unmarshal(data, &value); err != nil {
		return err
	}
	*c = CreateGiftCardResponse(value)
	extraProperties, err := internal.ExtractExtraProperties(data, *c)
	if err != nil {
		return err
	}
	c.extraProperties = extraProperties
	c.rawJSON = json.RawMessage(data)
	return nil
}

func (c *CreateGiftCardResponse) String() string {
	if len(c.rawJSON) > 0 {
		if value, err := internal.StringifyJSON(c.rawJSON); err == nil {
			return value
		}
	}
	if value, err := internal.StringifyJSON(c); err == nil {
		return value
	}
	return fmt.Sprintf("%#v", c)
}

// A response that contains a `GiftCard`. This response might contain a set of `Error` objects
// if the request resulted in errors.
type GetGiftCardFromGanResponse struct {
	// Any errors that occurred during the request.
	Errors []*Error `json:"errors,omitempty" url:"errors,omitempty"`
	// A gift card that was fetched, if present. It returns empty if an error occurred.
	GiftCard *GiftCard `json:"gift_card,omitempty" url:"gift_card,omitempty"`

	extraProperties map[string]interface{}
	rawJSON         json.RawMessage
}

func (g *GetGiftCardFromGanResponse) GetErrors() []*Error {
	if g == nil {
		return nil
	}
	return g.Errors
}

func (g *GetGiftCardFromGanResponse) GetGiftCard() *GiftCard {
	if g == nil {
		return nil
	}
	return g.GiftCard
}

func (g *GetGiftCardFromGanResponse) GetExtraProperties() map[string]interface{} {
	return g.extraProperties
}

func (g *GetGiftCardFromGanResponse) UnmarshalJSON(data []byte) error {
	type unmarshaler GetGiftCardFromGanResponse
	var value unmarshaler
	if err := json.Unmarshal(data, &value); err != nil {
		return err
	}
	*g = GetGiftCardFromGanResponse(value)
	extraProperties, err := internal.ExtractExtraProperties(data, *g)
	if err != nil {
		return err
	}
	g.extraProperties = extraProperties
	g.rawJSON = json.RawMessage(data)
	return nil
}

func (g *GetGiftCardFromGanResponse) String() string {
	if len(g.rawJSON) > 0 {
		if value, err := internal.StringifyJSON(g.rawJSON); err == nil {
			return value
		}
	}
	if value, err := internal.StringifyJSON(g); err == nil {
		return value
	}
	return fmt.Sprintf("%#v", g)
}

// A response that contains a `GiftCard` object. If the request resulted in errors,
// the response contains a set of `Error` objects.
type GetGiftCardFromNonceResponse struct {
	// Any errors that occurred during the request.
	Errors []*Error `json:"errors,omitempty" url:"errors,omitempty"`
	// The retrieved gift card.
	GiftCard *GiftCard `json:"gift_card,omitempty" url:"gift_card,omitempty"`

	extraProperties map[string]interface{}
	rawJSON         json.RawMessage
}

func (g *GetGiftCardFromNonceResponse) GetErrors() []*Error {
	if g == nil {
		return nil
	}
	return g.Errors
}

func (g *GetGiftCardFromNonceResponse) GetGiftCard() *GiftCard {
	if g == nil {
		return nil
	}
	return g.GiftCard
}

func (g *GetGiftCardFromNonceResponse) GetExtraProperties() map[string]interface{} {
	return g.extraProperties
}

func (g *GetGiftCardFromNonceResponse) UnmarshalJSON(data []byte) error {
	type unmarshaler GetGiftCardFromNonceResponse
	var value unmarshaler
	if err := json.Unmarshal(data, &value); err != nil {
		return err
	}
	*g = GetGiftCardFromNonceResponse(value)
	extraProperties, err := internal.ExtractExtraProperties(data, *g)
	if err != nil {
		return err
	}
	g.extraProperties = extraProperties
	g.rawJSON = json.RawMessage(data)
	return nil
}

func (g *GetGiftCardFromNonceResponse) String() string {
	if len(g.rawJSON) > 0 {
		if value, err := internal.StringifyJSON(g.rawJSON); err == nil {
			return value
		}
	}
	if value, err := internal.StringifyJSON(g); err == nil {
		return value
	}
	return fmt.Sprintf("%#v", g)
}

// A response that contains a `GiftCard`. The response might contain a set of `Error` objects
// if the request resulted in errors.
type GetGiftCardResponse struct {
	// Any errors that occurred during the request.
	Errors []*Error `json:"errors,omitempty" url:"errors,omitempty"`
	// The gift card retrieved.
	GiftCard *GiftCard `json:"gift_card,omitempty" url:"gift_card,omitempty"`

	extraProperties map[string]interface{}
	rawJSON         json.RawMessage
}

func (g *GetGiftCardResponse) GetErrors() []*Error {
	if g == nil {
		return nil
	}
	return g.Errors
}

func (g *GetGiftCardResponse) GetGiftCard() *GiftCard {
	if g == nil {
		return nil
	}
	return g.GiftCard
}

func (g *GetGiftCardResponse) GetExtraProperties() map[string]interface{} {
	return g.extraProperties
}

func (g *GetGiftCardResponse) UnmarshalJSON(data []byte) error {
	type unmarshaler GetGiftCardResponse
	var value unmarshaler
	if err := json.Unmarshal(data, &value); err != nil {
		return err
	}
	*g = GetGiftCardResponse(value)
	extraProperties, err := internal.ExtractExtraProperties(data, *g)
	if err != nil {
		return err
	}
	g.extraProperties = extraProperties
	g.rawJSON = json.RawMessage(data)
	return nil
}

func (g *GetGiftCardResponse) String() string {
	if len(g.rawJSON) > 0 {
		if value, err := internal.StringifyJSON(g.rawJSON); err == nil {
			return value
		}
	}
	if value, err := internal.StringifyJSON(g); err == nil {
		return value
	}
	return fmt.Sprintf("%#v", g)
}

// Represents a Square gift card.
type GiftCard struct {
	// The Square-assigned ID of the gift card.
	ID *string `json:"id,omitempty" url:"id,omitempty"`
	// The gift card type.
	// See [Type](#type-type) for possible values
	Type GiftCardType `json:"type" url:"type"`
	// The source that generated the gift card account number (GAN). The default value is `SQUARE`.
	// See [GANSource](#type-gansource) for possible values
	GanSource *GiftCardGanSource `json:"gan_source,omitempty" url:"gan_source,omitempty"`
	// The current gift card state.
	// See [Status](#type-status) for possible values
	State *GiftCardStatus `json:"state,omitempty" url:"state,omitempty"`
	// The current gift card balance. This balance is always greater than or equal to zero.
	BalanceMoney *Money `json:"balance_money,omitempty" url:"balance_money,omitempty"`
	// The gift card account number (GAN). Buyers can use the GAN to make purchases or check
	// the gift card balance.
	Gan *string `json:"gan,omitempty" url:"gan,omitempty"`
	// The timestamp when the gift card was created, in RFC 3339 format.
	// In the case of a digital gift card, it is the time when you create a card
	// (using the Square Point of Sale application, Seller Dashboard, or Gift Cards API).
	// In the case of a plastic gift card, it is the time when Square associates the card with the
	// seller at the time of activation.
	CreatedAt *string `json:"created_at,omitempty" url:"created_at,omitempty"`
	// The IDs of the [customer profiles](entity:Customer) to whom this gift card is linked.
	CustomerIDs []string `json:"customer_ids,omitempty" url:"customer_ids,omitempty"`

	extraProperties map[string]interface{}
	rawJSON         json.RawMessage
}

func (g *GiftCard) GetID() *string {
	if g == nil {
		return nil
	}
	return g.ID
}

func (g *GiftCard) GetType() GiftCardType {
	if g == nil {
		return ""
	}
	return g.Type
}

func (g *GiftCard) GetGanSource() *GiftCardGanSource {
	if g == nil {
		return nil
	}
	return g.GanSource
}

func (g *GiftCard) GetState() *GiftCardStatus {
	if g == nil {
		return nil
	}
	return g.State
}

func (g *GiftCard) GetBalanceMoney() *Money {
	if g == nil {
		return nil
	}
	return g.BalanceMoney
}

func (g *GiftCard) GetGan() *string {
	if g == nil {
		return nil
	}
	return g.Gan
}

func (g *GiftCard) GetCreatedAt() *string {
	if g == nil {
		return nil
	}
	return g.CreatedAt
}

func (g *GiftCard) GetCustomerIDs() []string {
	if g == nil {
		return nil
	}
	return g.CustomerIDs
}

func (g *GiftCard) GetExtraProperties() map[string]interface{} {
	return g.extraProperties
}

func (g *GiftCard) UnmarshalJSON(data []byte) error {
	type unmarshaler GiftCard
	var value unmarshaler
	if err := json.Unmarshal(data, &value); err != nil {
		return err
	}
	*g = GiftCard(value)
	extraProperties, err := internal.ExtractExtraProperties(data, *g)
	if err != nil {
		return err
	}
	g.extraProperties = extraProperties
	g.rawJSON = json.RawMessage(data)
	return nil
}

func (g *GiftCard) String() string {
	if len(g.rawJSON) > 0 {
		if value, err := internal.StringifyJSON(g.rawJSON); err == nil {
			return value
		}
	}
	if value, err := internal.StringifyJSON(g); err == nil {
		return value
	}
	return fmt.Sprintf("%#v", g)
}

// Indicates the source that generated the gift card
// account number (GAN).
type GiftCardGanSource string

const (
	GiftCardGanSourceSquare GiftCardGanSource = "SQUARE"
	GiftCardGanSourceOther  GiftCardGanSource = "OTHER"
)

func NewGiftCardGanSourceFromString(s string) (GiftCardGanSource, error) {
	switch s {
	case "SQUARE":
		return GiftCardGanSourceSquare, nil
	case "OTHER":
		return GiftCardGanSourceOther, nil
	}
	var t GiftCardGanSource
	return "", fmt.Errorf("%s is not a valid %T", s, t)
}

func (g GiftCardGanSource) Ptr() *GiftCardGanSource {
	return &g
}

// Indicates the gift card state.
type GiftCardStatus string

const (
	GiftCardStatusActive      GiftCardStatus = "ACTIVE"
	GiftCardStatusDeactivated GiftCardStatus = "DEACTIVATED"
	GiftCardStatusBlocked     GiftCardStatus = "BLOCKED"
	GiftCardStatusPending     GiftCardStatus = "PENDING"
)

func NewGiftCardStatusFromString(s string) (GiftCardStatus, error) {
	switch s {
	case "ACTIVE":
		return GiftCardStatusActive, nil
	case "DEACTIVATED":
		return GiftCardStatusDeactivated, nil
	case "BLOCKED":
		return GiftCardStatusBlocked, nil
	case "PENDING":
		return GiftCardStatusPending, nil
	}
	var t GiftCardStatus
	return "", fmt.Errorf("%s is not a valid %T", s, t)
}

func (g GiftCardStatus) Ptr() *GiftCardStatus {
	return &g
}

// Indicates the gift card type.
type GiftCardType string

const (
	GiftCardTypePhysical GiftCardType = "PHYSICAL"
	GiftCardTypeDigital  GiftCardType = "DIGITAL"
)

func NewGiftCardTypeFromString(s string) (GiftCardType, error) {
	switch s {
	case "PHYSICAL":
		return GiftCardTypePhysical, nil
	case "DIGITAL":
		return GiftCardTypeDigital, nil
	}
	var t GiftCardType
	return "", fmt.Errorf("%s is not a valid %T", s, t)
}

func (g GiftCardType) Ptr() *GiftCardType {
	return &g
}

// A response that contains the linked `GiftCard` object. If the request resulted in errors,
// the response contains a set of `Error` objects.
type LinkCustomerToGiftCardResponse struct {
	// Any errors that occurred during the request.
	Errors []*Error `json:"errors,omitempty" url:"errors,omitempty"`
	// The gift card with the ID of the linked customer listed in the `customer_ids` field.
	GiftCard *GiftCard `json:"gift_card,omitempty" url:"gift_card,omitempty"`

	extraProperties map[string]interface{}
	rawJSON         json.RawMessage
}

func (l *LinkCustomerToGiftCardResponse) GetErrors() []*Error {
	if l == nil {
		return nil
	}
	return l.Errors
}

func (l *LinkCustomerToGiftCardResponse) GetGiftCard() *GiftCard {
	if l == nil {
		return nil
	}
	return l.GiftCard
}

func (l *LinkCustomerToGiftCardResponse) GetExtraProperties() map[string]interface{} {
	return l.extraProperties
}

func (l *LinkCustomerToGiftCardResponse) UnmarshalJSON(data []byte) error {
	type unmarshaler LinkCustomerToGiftCardResponse
	var value unmarshaler
	if err := json.Unmarshal(data, &value); err != nil {
		return err
	}
	*l = LinkCustomerToGiftCardResponse(value)
	extraProperties, err := internal.ExtractExtraProperties(data, *l)
	if err != nil {
		return err
	}
	l.extraProperties = extraProperties
	l.rawJSON = json.RawMessage(data)
	return nil
}

func (l *LinkCustomerToGiftCardResponse) String() string {
	if len(l.rawJSON) > 0 {
		if value, err := internal.StringifyJSON(l.rawJSON); err == nil {
			return value
		}
	}
	if value, err := internal.StringifyJSON(l); err == nil {
		return value
	}
	return fmt.Sprintf("%#v", l)
}

// A response that contains a list of `GiftCard` objects. If the request resulted in errors,
// the response contains a set of `Error` objects.
type ListGiftCardsResponse struct {
	// Any errors that occurred during the request.
	Errors []*Error `json:"errors,omitempty" url:"errors,omitempty"`
	// The requested gift cards or an empty object if none are found.
	GiftCards []*GiftCard `json:"gift_cards,omitempty" url:"gift_cards,omitempty"`
	// When a response is truncated, it includes a cursor that you can use in a
	// subsequent request to retrieve the next set of gift cards. If a cursor is not present, this is
	// the final response.
	// For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
	Cursor *string `json:"cursor,omitempty" url:"cursor,omitempty"`

	extraProperties map[string]interface{}
	rawJSON         json.RawMessage
}

func (l *ListGiftCardsResponse) GetErrors() []*Error {
	if l == nil {
		return nil
	}
	return l.Errors
}

func (l *ListGiftCardsResponse) GetGiftCards() []*GiftCard {
	if l == nil {
		return nil
	}
	return l.GiftCards
}

func (l *ListGiftCardsResponse) GetCursor() *string {
	if l == nil {
		return nil
	}
	return l.Cursor
}

func (l *ListGiftCardsResponse) GetExtraProperties() map[string]interface{} {
	return l.extraProperties
}

func (l *ListGiftCardsResponse) UnmarshalJSON(data []byte) error {
	type unmarshaler ListGiftCardsResponse
	var value unmarshaler
	if err := json.Unmarshal(data, &value); err != nil {
		return err
	}
	*l = ListGiftCardsResponse(value)
	extraProperties, err := internal.ExtractExtraProperties(data, *l)
	if err != nil {
		return err
	}
	l.extraProperties = extraProperties
	l.rawJSON = json.RawMessage(data)
	return nil
}

func (l *ListGiftCardsResponse) String() string {
	if len(l.rawJSON) > 0 {
		if value, err := internal.StringifyJSON(l.rawJSON); err == nil {
			return value
		}
	}
	if value, err := internal.StringifyJSON(l); err == nil {
		return value
	}
	return fmt.Sprintf("%#v", l)
}

// A response that contains the unlinked `GiftCard` object. If the request resulted in errors,
// the response contains a set of `Error` objects.
type UnlinkCustomerFromGiftCardResponse struct {
	// Any errors that occurred during the request.
	Errors []*Error `json:"errors,omitempty" url:"errors,omitempty"`
	// The gift card with the ID of the unlinked customer removed from the `customer_ids` field.
	// If no other customers are linked, the `customer_ids` field is also removed.
	GiftCard *GiftCard `json:"gift_card,omitempty" url:"gift_card,omitempty"`

	extraProperties map[string]interface{}
	rawJSON         json.RawMessage
}

func (u *UnlinkCustomerFromGiftCardResponse) GetErrors() []*Error {
	if u == nil {
		return nil
	}
	return u.Errors
}

func (u *UnlinkCustomerFromGiftCardResponse) GetGiftCard() *GiftCard {
	if u == nil {
		return nil
	}
	return u.GiftCard
}

func (u *UnlinkCustomerFromGiftCardResponse) GetExtraProperties() map[string]interface{} {
	return u.extraProperties
}

func (u *UnlinkCustomerFromGiftCardResponse) UnmarshalJSON(data []byte) error {
	type unmarshaler UnlinkCustomerFromGiftCardResponse
	var value unmarshaler
	if err := json.Unmarshal(data, &value); err != nil {
		return err
	}
	*u = UnlinkCustomerFromGiftCardResponse(value)
	extraProperties, err := internal.ExtractExtraProperties(data, *u)
	if err != nil {
		return err
	}
	u.extraProperties = extraProperties
	u.rawJSON = json.RawMessage(data)
	return nil
}

func (u *UnlinkCustomerFromGiftCardResponse) String() string {
	if len(u.rawJSON) > 0 {
		if value, err := internal.StringifyJSON(u.rawJSON); err == nil {
			return value
		}
	}
	if value, err := internal.StringifyJSON(u); err == nil {
		return value
	}
	return fmt.Sprintf("%#v", u)
}