Skip to content
Docs
Open Backstage
Reference

BackstageClient.giftCards

BackstageClient.giftCards in @ticketlayer/backstage.

@ticketlayer/backstage

@ticketlayer/backstage / BackstageClient / giftCards

giftCards: {
  createProduct: (request: {
     accountId?: string | null;
     currency: string;
     deliveryMethods?: ("email" | "box_office_print" | "post")[];
     description?: string | null;
     eventId?: string | null;
     fixedAmounts?: number[] | null;
     maxAmount?: number | null;
     minAmount?: number | null;
     name: string;
   }, requestOptions?: RequestOptions) => Promise<{
     accountId: string | null;
     currency: string;
     deliveryMethods: ("email" | "box_office_print" | "post")[];
     description: string | null;
     eventId: string | null;
     fixedAmounts: number[] | null;
     id: string;
     maxAmount: number | null;
     minAmount: number | null;
     name: string;
     status: "active" | "archived";
  }>;
  issueCode: (storedValueAccountId: string, requestOptions?: RequestOptions) => Promise<{
     account: {
        accountId: string | null;
        balance: number;
        book: "live" | "test";
        codeIssuedAt: string | null;
        codeLast4: string | null;
        createdAt: string;
        currency: string;
        customerId: string | null;
        eventId: string | null;
        expiresAt: string | null;
        expiryPolicy: {
           dormancyFee:   | {
              afterInactiveMonths: number;
              amount: number;
            }
              | null;
           jurisdiction: string | null;
           minimumMonths: number | null;
           months: number | null;
           source: "organisation" | "jurisdiction_default";
        };
        faceValue: number | null;
        id: string;
        instrument: "account_credit" | "gift_card" | "pass_balance";
        lastActivityAt: string;
        ownerType: "customer" | "bearer" | "pass";
        recipient:   | {
           email?: string | null;
           message?: string | null;
           name?: string | null;
         }
           | null;
        sourceOrderId: string | null;
        sourceOrderLineItemId: string | null;
        status: "expired" | "active" | "void" | "pending" | "frozen";
        updatedAt: string;
     };
     code: string;
  }>;
  listProducts: (options?: {
     status?: "active" | "archived";
   }, requestOptions?: RequestOptions) => Promise<{
     accountId: string | null;
     currency: string;
     deliveryMethods: ("email" | "box_office_print" | "post")[];
     description: string | null;
     eventId: string | null;
     fixedAmounts: number[] | null;
     id: string;
     maxAmount: number | null;
     minAmount: number | null;
     name: string;
     status: "active" | "archived";
  }[]>;
  lookup: (request: {
     code: string;
   }, requestOptions?: RequestOptions) => Promise<{
     accountId: string | null;
     balance: number;
     book: "live" | "test";
     codeIssuedAt: string | null;
     codeLast4: string | null;
     createdAt: string;
     currency: string;
     customerId: string | null;
     eventId: string | null;
     expiresAt: string | null;
     expiryPolicy: {
        dormancyFee:   | {
           afterInactiveMonths: number;
           amount: number;
         }
           | null;
        jurisdiction: string | null;
        minimumMonths: number | null;
        months: number | null;
        source: "organisation" | "jurisdiction_default";
     };
     faceValue: number | null;
     id: string;
     instrument: "account_credit" | "gift_card" | "pass_balance";
     lastActivityAt: string;
     ownerType: "customer" | "bearer" | "pass";
     recipient:   | {
        email?: string | null;
        message?: string | null;
        name?: string | null;
      }
        | null;
     sourceOrderId: string | null;
     sourceOrderLineItemId: string | null;
     status: "expired" | "active" | "void" | "pending" | "frozen";
     updatedAt: string;
  }>;
  updateProduct: (productId: string, request: {
     accountId?: string | null;
     deliveryMethods?: ("email" | "box_office_print" | "post")[];
     description?: string | null;
     eventId?: string | null;
     fixedAmounts?: number[] | null;
     maxAmount?: number | null;
     minAmount?: number | null;
     name?: string;
     status?: "active" | "archived";
   }, requestOptions?: RequestOptions) => Promise<{
     accountId: string | null;
     currency: string;
     deliveryMethods: ("email" | "box_office_print" | "post")[];
     description: string | null;
     eventId: string | null;
     fixedAmounts: number[] | null;
     id: string;
     maxAmount: number | null;
     minAmount: number | null;
     name: string;
     status: "active" | "archived";
  }>;
};

Defined in: client.ts:7441

Gift cards methods

createProduct()#

createProduct: (request: {
  accountId?: string | null;
  currency: string;
  deliveryMethods?: ("email" | "box_office_print" | "post")[];
  description?: string | null;
  eventId?: string | null;
  fixedAmounts?: number[] | null;
  maxAmount?: number | null;
  minAmount?: number | null;
  name: string;
}, requestOptions?: RequestOptions) => Promise<{
  accountId: string | null;
  currency: string;
  deliveryMethods: ("email" | "box_office_print" | "post")[];
  description: string | null;
  eventId: string | null;
  fixedAmounts: number[] | null;
  id: string;
  maxAmount: number | null;
  minAmount: number | null;
  name: string;
  status: "active" | "archived";
}>;

Create a gift card product A gift card to sell: fixed amounts (2500, 5000, 10000) or a range (minAmount to maxAmount), in one currency; delivered by email (the default), post or printed at the box office; optionally narrowed to an account or event. A card bought from it is spendable only within this organisation, always. Needs storedvalue.manage on every account.

Parameters#

ParameterTypeDescription
request{ accountId?: string | null; currency: string; deliveryMethods?: ("email" | "box_office_print" | "post")[]; description?: string | null; eventId?: string | null; fixedAmounts?: number[] | null; maxAmount?: number | null; minAmount?: number | null; name: string; }-
request.accountId?string | nullDescription Cards spendable only on this account's orders
request.currency?stringExample GBP
request.deliveryMethods?("email" | "box_office_print" | "post")[]Description Email only when left out
request.description?string | null-
request.eventId?string | nullDescription Cards spendable only on this event
request.fixedAmounts?number[] | nullDescription Amounts on sale, minor units
request.maxAmount?number | nullDescription ...to this, minor units
request.minAmount?number | nullDescription A chosen amount from this...
request.name?string-
requestOptions?RequestOptions-

Returns#

Promise<{ accountId: string | null; currency: string; deliveryMethods: ("email" | "box_office_print" | "post")[]; description: string | null; eventId: string | null; fixedAmounts: number[] | null; id: string; maxAmount: number | null; minAmount: number | null; name: string; status: "active" | "archived"; }>

Operation Id#

createGiftCardProduct

issueCode()#

issueCode: (storedValueAccountId: string, requestOptions?: RequestOptions) => Promise<{
  account: {
     accountId: string | null;
     balance: number;
     book: "live" | "test";
     codeIssuedAt: string | null;
     codeLast4: string | null;
     createdAt: string;
     currency: string;
     customerId: string | null;
     eventId: string | null;
     expiresAt: string | null;
     expiryPolicy: {
        dormancyFee:   | {
           afterInactiveMonths: number;
           amount: number;
         }
           | null;
        jurisdiction: string | null;
        minimumMonths: number | null;
        months: number | null;
        source: "organisation" | "jurisdiction_default";
     };
     faceValue: number | null;
     id: string;
     instrument: "account_credit" | "gift_card" | "pass_balance";
     lastActivityAt: string;
     ownerType: "customer" | "bearer" | "pass";
     recipient:   | {
        email?: string | null;
        message?: string | null;
        name?: string | null;
      }
        | null;
     sourceOrderId: string | null;
     sourceOrderLineItemId: string | null;
     status: "expired" | "active" | "void" | "pending" | "frozen";
     updatedAt: string;
  };
  code: string;
}>;

Issue a gift card's code Mints the card's code and returns it this once: the counter that sold the card prints it, the post station prints it into the envelope - with the card's id (sva_...) as its packing label, which is scanned or typed into the parcel (never the code). Only its hash is kept. The card becomes active, its expiry starting now, and its fulfilment item is done (a posted card's when its parcel is dispatched). An emailed card has its code issued by the email queue instead. A card is issued only once its order is paid (STORED_VALUE_NOT_ACTIVE before). Issuing again REPLACES the code (a lost card: the old one stops working) and needs storedvalue.adjust; the first issue needs orders.update on the order's account.

Parameters#

ParameterType
storedValueAccountIdstring
requestOptions?RequestOptions

Returns#

Promise<{ account: { accountId: string | null; balance: number; book: "live" | "test"; codeIssuedAt: string | null; codeLast4: string | null; createdAt: string; currency: string; customerId: string | null; eventId: string | null; expiresAt: string | null; expiryPolicy: { dormancyFee: | { afterInactiveMonths: number; amount: number; } | null; jurisdiction: string | null; minimumMonths: number | null; months: number | null; source: "organisation" | "jurisdiction_default"; }; faceValue: number | null; id: string; instrument: "account_credit" | "gift_card" | "pass_balance"; lastActivityAt: string; ownerType: "customer" | "bearer" | "pass"; recipient: | { email?: string | null; message?: string | null; name?: string | null; } | null; sourceOrderId: string | null; sourceOrderLineItemId: string | null; status: "expired" | "active" | "void" | "pending" | "frozen"; updatedAt: string; }; code: string; }>

Operation Id#

issueGiftCardCode

listProducts()#

listProducts: (options?: {
  status?: "active" | "archived";
}, requestOptions?: RequestOptions) => Promise<{
  accountId: string | null;
  currency: string;
  deliveryMethods: ("email" | "box_office_print" | "post")[];
  description: string | null;
  eventId: string | null;
  fixedAmounts: number[] | null;
  id: string;
  maxAmount: number | null;
  minAmount: number | null;
  name: string;
  status: "active" | "archived";
}[]>;

List gift card products What the organisation sells as a gift card: fixed amounts or a range the buyer chooses within, in one currency, how each may be delivered, and what the cards it makes are narrowed to. Needs storedvalue.read.

Parameters#

ParameterType
options?{ status?: "active" | "archived"; }
options.status?"active" | "archived"
requestOptions?RequestOptions

Returns#

Promise<{ accountId: string | null; currency: string; deliveryMethods: ("email" | "box_office_print" | "post")[]; description: string | null; eventId: string | null; fixedAmounts: number[] | null; id: string; maxAmount: number | null; minAmount: number | null; name: string; status: "active" | "archived"; }[]>

Operation Id#

listGiftCardProducts

lookup()#

lookup: (request: {
  code: string;
}, requestOptions?: RequestOptions) => Promise<{
  accountId: string | null;
  balance: number;
  book: "live" | "test";
  codeIssuedAt: string | null;
  codeLast4: string | null;
  createdAt: string;
  currency: string;
  customerId: string | null;
  eventId: string | null;
  expiresAt: string | null;
  expiryPolicy: {
     dormancyFee:   | {
        afterInactiveMonths: number;
        amount: number;
      }
        | null;
     jurisdiction: string | null;
     minimumMonths: number | null;
     months: number | null;
     source: "organisation" | "jurisdiction_default";
  };
  faceValue: number | null;
  id: string;
  instrument: "account_credit" | "gift_card" | "pass_balance";
  lastActivityAt: string;
  ownerType: "customer" | "bearer" | "pass";
  recipient:   | {
     email?: string | null;
     message?: string | null;
     name?: string | null;
   }
     | null;
  sourceOrderId: string | null;
  sourceOrderLineItemId: string | null;
  status: "expired" | "active" | "void" | "pending" | "frozen";
  updatedAt: string;
}>;

Look up a gift card by its code The gift card a code names, with its balance: what the box office reads before taking it as payment. The code is sent in the body, never the URL, because it is a bearer secret; only its hash is stored, so this finds the card by hashing what is typed. STORED_VALUE_CODE_NOT_FOUND when it names none. Needs storedvalue.read.

Parameters#

ParameterTypeDescription
request{ code: string; }-
request.codestringExample 7KQ2-MZ9X-LP3R-TV8W
requestOptions?RequestOptions-

Returns#

Promise<{ accountId: string | null; balance: number; book: "live" | "test"; codeIssuedAt: string | null; codeLast4: string | null; createdAt: string; currency: string; customerId: string | null; eventId: string | null; expiresAt: string | null; expiryPolicy: { dormancyFee: | { afterInactiveMonths: number; amount: number; } | null; jurisdiction: string | null; minimumMonths: number | null; months: number | null; source: "organisation" | "jurisdiction_default"; }; faceValue: number | null; id: string; instrument: "account_credit" | "gift_card" | "pass_balance"; lastActivityAt: string; ownerType: "customer" | "bearer" | "pass"; recipient: | { email?: string | null; message?: string | null; name?: string | null; } | null; sourceOrderId: string | null; sourceOrderLineItemId: string | null; status: "expired" | "active" | "void" | "pending" | "frozen"; updatedAt: string; }>

Operation Id#

lookUpGiftCard

updateProduct()#

updateProduct: (productId: string, request: {
  accountId?: string | null;
  deliveryMethods?: ("email" | "box_office_print" | "post")[];
  description?: string | null;
  eventId?: string | null;
  fixedAmounts?: number[] | null;
  maxAmount?: number | null;
  minAmount?: number | null;
  name?: string;
  status?: "active" | "archived";
}, requestOptions?: RequestOptions) => Promise<{
  accountId: string | null;
  currency: string;
  deliveryMethods: ("email" | "box_office_print" | "post")[];
  description: string | null;
  eventId: string | null;
  fixedAmounts: number[] | null;
  id: string;
  maxAmount: number | null;
  minAmount: number | null;
  name: string;
  status: "active" | "archived";
}>;

Update a gift card product Change what a gift card sells for, how it is delivered, or archive it (status: archived) to stop selling it. Cards already sold are untouched. Needs storedvalue.manage on every account.

Parameters#

ParameterTypeDescription
productIdstring-
request{ accountId?: string | null; deliveryMethods?: ("email" | "box_office_print" | "post")[]; description?: string | null; eventId?: string | null; fixedAmounts?: number[] | null; maxAmount?: number | null; minAmount?: number | null; name?: string; status?: "active" | "archived"; }-
request.accountId?string | nullDescription Cards spendable only on this account's orders
request.deliveryMethods?("email" | "box_office_print" | "post")[]Description Email only when left out
request.description?string | null-
request.eventId?string | nullDescription Cards spendable only on this event
request.fixedAmounts?number[] | nullDescription Amounts on sale, minor units
request.maxAmount?number | nullDescription ...to this, minor units
request.minAmount?number | nullDescription A chosen amount from this...
request.name?string-
request.status?"active" | "archived"Description archived stops it being sold; cards already sold are untouched
requestOptions?RequestOptions-

Returns#

Promise<{ accountId: string | null; currency: string; deliveryMethods: ("email" | "box_office_print" | "post")[]; description: string | null; eventId: string | null; fixedAmounts: number[] | null; id: string; maxAmount: number | null; minAmount: number | null; name: string; status: "active" | "archived"; }>

Operation Id#

updateGiftCardProduct