Reference

BackstageClient.storedValue

BackstageClient.storedValue in @ticketlayer/backstage.

@ticketlayer/backstage / BackstageClient / storedValue

storedValue: {
  activity: (storedValueAccountId: string, options?: {
     cursor?: string;
     limit?: number;
   }, 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;
     };
     movements: {
        amount: number;
        causeId: string;
        causeType: string;
        description: string | null;
        journalId: string;
        kind: string;
        occurredAt: string;
        orderId: string | null;
        paymentId: string | null;
        postingId: string;
        refundId: string | null;
     }[];
     nextCursor: string | null;
  }>;
  adjust: (storedValueAccountId: string, request: {
     amount: number;
     reason: 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;
     };
     journalId: string;
  }>;
  closedLoopReport: (options?: {
     eurRates?: string;
   }, requestOptions?: RequestOptions) => Promise<{
     closedLoop: true;
     currencies: {
        adjusted: number;
        creditGiven: number;
        currency: string;
        loaded: number;
        loadedEur: number | null;
        redeemed: number;
        refunded: number;
        sold: number;
     }[];
     currenciesWithoutRate: string[];
     exceedsThreshold: boolean | null;
     from: string;
     loadedEur: number | null;
     organisationId: string;
     thresholdEur: number;
     to: string;
  }>;
  get: (storedValueAccountId: 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;
  }>;
  getSettings: (requestOptions?: RequestOptions) => Promise<{
     closedLoop: true;
     jurisdiction: string | null;
     jurisdictionFrom: "stored_value_settings" | "fee_settings" | null;
     own: {
        accountCreditBreakageRate: number | null;
        accountCreditExpiryMonths: number | null;
        dormancyFeeAmount: number | null;
        giftCardBreakageRate: number | null;
        giftCardExpiryMonths: number | null;
        jurisdiction: string | null;
     };
     policies: {
        account_credit: {
           dormancyFee:   | {
              afterInactiveMonths: number;
              amount: number;
            }
              | null;
           jurisdiction: string | null;
           minimumMonths: number | null;
           months: number | null;
           source: "organisation" | "jurisdiction_default";
        };
        gift_card: {
           dormancyFee:   | {
              afterInactiveMonths: number;
              amount: number;
            }
              | null;
           jurisdiction: string | null;
           minimumMonths: number | null;
           months: number | null;
           source: "organisation" | "jurisdiction_default";
        };
     };
     rule: {
        defaultMonths: number | null;
        dormancyAfterMonths: number | null;
        dormancyFeesAllowed: boolean;
        known: boolean;
        minimumMonths: number | null;
     };
  }>;
  giveCredit: (request: {
     accountId?: string;
     amount: number;
     currency: string;
     customerId: string;
     eventId?: string;
     reason: 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;
     };
     journalId: string;
  }>;
  list: (options?: {
     cursor?: string;
     customerId?: string;
     instrument?: "account_credit" | "gift_card" | "pass_balance";
     limit?: number;
     status?: "expired" | "active" | "void" | "pending" | "frozen";
   }, requestOptions?: RequestOptions) => Promise<{
     accounts: {
        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;
     }[];
     nextCursor: string | null;
  }>;
  setStatus: (storedValueAccountId: string, request: {
     reason: string;
     status: "active" | "void" | "frozen";
   }, 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;
  }>;
  updateSettings: (request: {
     accountCreditBreakageRate?: number | null;
     accountCreditExpiryMonths?: number | null;
     dormancyFeeAmount?: number | null;
     giftCardBreakageRate?: number | null;
     giftCardExpiryMonths?: number | null;
     jurisdiction?: string | null;
   }, requestOptions?: RequestOptions) => Promise<{
     closedLoop: true;
     jurisdiction: string | null;
     jurisdictionFrom: "stored_value_settings" | "fee_settings" | null;
     own: {
        accountCreditBreakageRate: number | null;
        accountCreditExpiryMonths: number | null;
        dormancyFeeAmount: number | null;
        giftCardBreakageRate: number | null;
        giftCardExpiryMonths: number | null;
        jurisdiction: string | null;
     };
     policies: {
        account_credit: {
           dormancyFee:   | {
              afterInactiveMonths: number;
              amount: number;
            }
              | null;
           jurisdiction: string | null;
           minimumMonths: number | null;
           months: number | null;
           source: "organisation" | "jurisdiction_default";
        };
        gift_card: {
           dormancyFee:   | {
              afterInactiveMonths: number;
              amount: number;
            }
              | null;
           jurisdiction: string | null;
           minimumMonths: number | null;
           months: number | null;
           source: "organisation" | "jurisdiction_default";
        };
     };
     rule: {
        defaultMonths: number | null;
        dormancyAfterMonths: number | null;
        dormancyFeesAllowed: boolean;
        known: boolean;
        minimumMonths: number | null;
     };
  }>;
};

Defined in: client.ts:7286

Stored value methods

activity()#

activity: (storedValueAccountId: string, options?: {
  cursor?: string;
  limit?: number;
}, 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;
  };
  movements: {
     amount: number;
     causeId: string;
     causeType: string;
     description: string | null;
     journalId: string;
     kind: string;
     occurredAt: string;
     orderId: string | null;
     paymentId: string | null;
     postingId: string;
     refundId: string | null;
  }[];
  nextCursor: string | null;
}>;

Get a stored-value account's activity Every movement on the balance, newest first: loads, credit given, refunds into it, spending, adjustments, expiry and dormancy fees. Each is a journal of the ledger, so this is the ledger's own history of the account. Needs storedvalue.read.

Parameters#

Parameter	Type
`storedValueAccountId`	`string`
`options?`	{ `cursor?`: `string`; `limit?`: `number`; }
`options.cursor?`	`string`
`options.limit?`	`number`
`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; }; movements: { amount: number; causeId: string; causeType: string; description: string | null; journalId: string; kind: string; occurredAt: string; orderId: string | null; paymentId: string | null; postingId: string; refundId: string | null; }[]; nextCursor: string | null; }>

Operation Id#

getStoredValueActivity

adjust()#

adjust: (storedValueAccountId: string, request: {
  amount: number;
  reason: 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;
  };
  journalId: string;
}>;

Adjust a stored-value balance Corrects a balance either way, with a reason, against the organisation's GoodwillCredit: a positive amount raises it, a negative one lowers it, never below nothing (STORED_VALUE_INSUFFICIENT). Posts one journal. Needs storedvalue.adjust.

Parameters#

Parameter	Type	Description
`storedValueAccountId`	`string`	-
`request`	{ `amount`: `number`; `reason`: `string`; }	-
`request.amount`	`number`	Description Signed minor units: positive raises the balance, negative lowers it (never below nothing) Example `500`
`request.reason?`	`string`	Example `Card machine double charge put right`
`requestOptions?`	`RequestOptions`	-

Returns#

Operation Id#

adjustStoredValue

closedLoopReport()#

closedLoopReport: (options?: {
  eurRates?: string;
}, requestOptions?: RequestOptions) => Promise<{
  closedLoop: true;
  currencies: {
     adjusted: number;
     creditGiven: number;
     currency: string;
     loaded: number;
     loadedEur: number | null;
     redeemed: number;
     refunded: number;
     sold: number;
  }[];
  currenciesWithoutRate: string[];
  exceedsThreshold: boolean | null;
  from: string;
  loadedEur: number | null;
  organisationId: string;
  thresholdEur: number;
  to: string;
}>;

Get the closed-loop value report Stored value this organisation loaded in the last 12 months (live book), per currency and by what loaded it (sold, credit given, refunded into it, adjusted), and what was redeemed, against the FCA notification threshold of 1 million euro for the limited network exclusion. The platform holds no exchange rates: pass eurRates for currencies other than EUR. Needs storedvalue.read on every account.

Parameters#

Parameter	Type
`options?`	{ `eurRates?`: `string`; }
`options.eurRates?`	`string`
`requestOptions?`	`RequestOptions`

Returns#

Promise<{ closedLoop: true; currencies: { adjusted: number; creditGiven: number; currency: string; loaded: number; loadedEur: number | null; redeemed: number; refunded: number; sold: number; }[]; currenciesWithoutRate: string[]; exceedsThreshold: boolean | null; from: string; loadedEur: number | null; organisationId: string; thresholdEur: number; to: string; }>

Operation Id#

getStoredValueClosedLoopReport

get()#

get: (storedValueAccountId: 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;
}>;

Get a stored-value account One gift card or credit balance: what it is, whose, its status and expiry policy, and its balance, which is the ledger's (Org:{org}:StoredValue:{instrument}, the lines naming this account). A gift card's code is never returned: it is shown once, when issued. Needs storedvalue.read.

Parameters#

Parameter	Type
`storedValueAccountId`	`string`
`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#

getStoredValueAccount

getSettings()#

getSettings: (requestOptions?: RequestOptions) => Promise<{
  closedLoop: true;
  jurisdiction: string | null;
  jurisdictionFrom: "stored_value_settings" | "fee_settings" | null;
  own: {
     accountCreditBreakageRate: number | null;
     accountCreditExpiryMonths: number | null;
     dormancyFeeAmount: number | null;
     giftCardBreakageRate: number | null;
     giftCardExpiryMonths: number | null;
     jurisdiction: string | null;
  };
  policies: {
     account_credit: {
        dormancyFee:   | {
           afterInactiveMonths: number;
           amount: number;
         }
           | null;
        jurisdiction: string | null;
        minimumMonths: number | null;
        months: number | null;
        source: "organisation" | "jurisdiction_default";
     };
     gift_card: {
        dormancyFee:   | {
           afterInactiveMonths: number;
           amount: number;
         }
           | null;
        jurisdiction: string | null;
        minimumMonths: number | null;
        months: number | null;
        source: "organisation" | "jurisdiction_default";
     };
  };
  rule: {
     defaultMonths: number | null;
     dormancyAfterMonths: number | null;
     dormancyFeesAllowed: boolean;
     known: boolean;
     minimumMonths: number | null;
  };
}>;

Get the organisation's stored-value settings The jurisdiction stored value is issued under (the organisation's own setting, else its fee settings' jurisdiction), that jurisdiction's rules (UK: no expiry by default and no minimum; Ireland: 5 years; US: 5 years, dormancy fees only after 12 months without activity), the expiry policy a new gift card and new credit would get, and the expected breakage rates. closedLoop is always true: a balance is spent only within this organisation, a rule rather than a setting. Needs storedvalue.read on every account.

Parameters#

Parameter	Type
`requestOptions?`	`RequestOptions`

Returns#

Promise<{ closedLoop: true; jurisdiction: string | null; jurisdictionFrom: "stored_value_settings" | "fee_settings" | null; own: { accountCreditBreakageRate: number | null; accountCreditExpiryMonths: number | null; dormancyFeeAmount: number | null; giftCardBreakageRate: number | null; giftCardExpiryMonths: number | null; jurisdiction: string | null; }; policies: { account_credit: { dormancyFee: | { afterInactiveMonths: number; amount: number; } | null; jurisdiction: string | null; minimumMonths: number | null; months: number | null; source: "organisation" | "jurisdiction_default"; }; gift_card: { dormancyFee: | { afterInactiveMonths: number; amount: number; } | null; jurisdiction: string | null; minimumMonths: number | null; months: number | null; source: "organisation" | "jurisdiction_default"; }; }; rule: { defaultMonths: number | null; dormancyAfterMonths: number | null; dormancyFeesAllowed: boolean; known: boolean; minimumMonths: number | null; }; }>

Operation Id#

getStoredValueSettings

giveCredit()#

giveCredit: (request: {
  accountId?: string;
  amount: number;
  currency: string;
  customerId: string;
  eventId?: string;
  reason: 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;
  };
  journalId: string;
}>;

Give a customer account credit Credit the organisation gives a customer as goodwill, with a reason, into the customer's credit balance in that currency (created on first use; narrowed to an account or event when asked). Posts DR GoodwillCredit, CR the liability. The customer spends it at checkout signed in, or at the box office. Needs storedvalue.issue (on the account it is narrowed to, else on every account).

Parameters#

Parameter	Type	Description
`request`	{ `accountId?`: `string`; `amount`: `number`; `currency`: `string`; `customerId`: `string`; `eventId?`: `string`; `reason`: `string`; }	-
`request.accountId?`	`string`	Description Narrow the credit to one account's orders
`request.amount?`	`number`	Description Minor units Example `1500`
`request.currency?`	`string`	Example `GBP`
`request.customerId?`	`string`	Example `cus_7Kq2mZ9xLp3RtV8wYb1c`
`request.eventId?`	`string`	Description Narrow the credit to one event
`request.reason?`	`string`	Example `Sorry about the long queue`
`requestOptions?`	`RequestOptions`	-

Returns#

Operation Id#

giveStoredValueCredit

list()#

list: (options?: {
  cursor?: string;
  customerId?: string;
  instrument?: "account_credit" | "gift_card" | "pass_balance";
  limit?: number;
  status?: "expired" | "active" | "void" | "pending" | "frozen";
}, requestOptions?: RequestOptions) => Promise<{
  accounts: {
     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;
  }[];
  nextCursor: string | null;
}>;

List stored-value accounts Gift cards and account credit, newest first, filtered by instrument, status and customer, each with its balance from the ledger. A balance narrowed to an account is listed to those holding storedvalue.list on it; one of the whole organisation to those holding it on every account.

Parameters#

Parameter	Type
`options?`	{ `cursor?`: `string`; `customerId?`: `string`; `instrument?`: `"account_credit"` \| `"gift_card"` \| `"pass_balance"`; `limit?`: `number`; `status?`: `"expired"` \| `"active"` \| `"void"` \| `"pending"` \| `"frozen"`; }
`options.cursor?`	`string`
`options.customerId?`	`string`
`options.instrument?`	`"account_credit"` \| `"gift_card"` \| `"pass_balance"`
`options.limit?`	`number`
`options.status?`	`"expired"` \| `"active"` \| `"void"` \| `"pending"` \| `"frozen"`
`requestOptions?`	`RequestOptions`

Returns#

Promise<{ accounts: { 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; }[]; nextCursor: string | null; }>

Operation Id#

listStoredValueAccounts

setStatus()#

setStatus: (storedValueAccountId: string, request: {
  reason: string;
  status: "active" | "void" | "frozen";
}, 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;
}>;

Freeze, unfreeze or void a stored-value account frozen keeps the balance and stops it being spent (a card reported lost, a dispute); active unfreezes it; void closes an account that holds nothing (STORED_VALUE_NOT_EMPTY otherwise). The change and its reason are kept on the account. Needs storedvalue.adjust.

Parameters#

Parameter	Type	Description
`storedValueAccountId`	`string`	-
`request`	{ `reason`: `string`; `status`: `"active"` \| `"void"` \| `"frozen"`; }	-
`request.reason`	`string`	Example `Card reported lost`
`request.status?`	`"active"` \| `"void"` \| `"frozen"`	Description `frozen` keeps the balance and stops it being spent; `active` unfreezes; `void` closes an account that holds nothing
`requestOptions?`	`RequestOptions`	-

Returns#

Operation Id#

setStoredValueStatus

updateSettings()#

updateSettings: (request: {
  accountCreditBreakageRate?: number | null;
  accountCreditExpiryMonths?: number | null;
  dormancyFeeAmount?: number | null;
  giftCardBreakageRate?: number | null;
  giftCardExpiryMonths?: number | null;
  jurisdiction?: string | null;
}, requestOptions?: RequestOptions) => Promise<{
  closedLoop: true;
  jurisdiction: string | null;
  jurisdictionFrom: "stored_value_settings" | "fee_settings" | null;
  own: {
     accountCreditBreakageRate: number | null;
     accountCreditExpiryMonths: number | null;
     dormancyFeeAmount: number | null;
     giftCardBreakageRate: number | null;
     giftCardExpiryMonths: number | null;
     jurisdiction: string | null;
  };
  policies: {
     account_credit: {
        dormancyFee:   | {
           afterInactiveMonths: number;
           amount: number;
         }
           | null;
        jurisdiction: string | null;
        minimumMonths: number | null;
        months: number | null;
        source: "organisation" | "jurisdiction_default";
     };
     gift_card: {
        dormancyFee:   | {
           afterInactiveMonths: number;
           amount: number;
         }
           | null;
        jurisdiction: string | null;
        minimumMonths: number | null;
        months: number | null;
        source: "organisation" | "jurisdiction_default";
     };
  };
  rule: {
     defaultMonths: number | null;
     dormancyAfterMonths: number | null;
     dormancyFeesAllowed: boolean;
     known: boolean;
     minimumMonths: number | null;
  };
}>;

Set the organisation's stored-value settings A field left out keeps its value; null goes back to the jurisdiction's default. An expiry shorter than the statutory minimum is refused (STORED_VALUE_EXPIRY_TOO_SHORT), as is a dormancy fee where none is allowed (STORED_VALUE_DORMANCY_FEE_NOT_ALLOWED). Balances already issued keep the policy they were issued under. A breakage rate recognises expected breakage in proportion to redemptions (IFRS 15); without one, breakage is recognised at expiry. Needs storedvalue.manage on every account.

Parameters#

Parameter	Type	Description
`request`	{ `accountCreditBreakageRate?`: `number` \| `null`; `accountCreditExpiryMonths?`: `number` \| `null`; `dormancyFeeAmount?`: `number` \| `null`; `giftCardBreakageRate?`: `number` \| `null`; `giftCardExpiryMonths?`: `number` \| `null`; `jurisdiction?`: `string` \| `null`; }	-
`request.accountCreditBreakageRate?`	`number` \| `null`	Description As giftCardBreakageRate, for account credit
`request.accountCreditExpiryMonths?`	`number` \| `null`	Description As giftCardExpiryMonths, for account credit
`request.dormancyFeeAmount?`	`number` \| `null`	Description A monthly fee after 12 months without activity, where the jurisdiction allows one (the US); null for none
`request.giftCardBreakageRate?`	`number` \| `null`	Description The share of gift card value expected never to be redeemed (0 to under 1), recognised in proportion to redemptions; null recognises breakage only at expiry Example `0.08`
`request.giftCardExpiryMonths?`	`number` \| `null`	Description Null: the jurisdiction's default. 0: never. Never shorter than the statutory minimum.
`request.jurisdiction?`	`string` \| `null`	Description The jurisdiction stored value is issued under (GB, IE, US-NY); null follows the organisation's fee settings Example `IE`
`requestOptions?`	`RequestOptions`	-

Returns#

Operation Id#

updateStoredValueSettings