Broadleaf Microservices
  • v1.0.0-latest-prod

Core Types

ApiError

Response object that represents some error state from the API.

Property Type Description

cancelled?

boolean

Whether the error was from the request being cancelled.

exception?

string

Optional exception class name.

globalErrors?

Array<GlobalApiError>

Optionally gives additional information to the client about what was wrong with their request.

status

string

The HTTP status type such as NOT_FOUND.

statusCode

number

The HTTP status code such as 404.

timestamp

string

When the error occurred as an ISO formatted date string.

title

string

A human-readable representation of the type of error being returned.

type

string

A machine-readable representation of the type of error being returned.

ApiValidationError

extends ApiError

Type of ApiError for entity validation failures.

Property Type Description

fieldErrors

Record<string, Array<FieldValidationError>>

Map of FieldValidationErrors where the key is the FieldValidationError#path.

Client

Represents a web request client for making HTTP requests against Broadleaf REST APIs. By default, this client is built on top of the axios library and provides additional functionality such as request and response interceptors and configuration options.

  • getAgent(): AxiosInstance: Returns the AxiosInstance used by the client.

  • call<T>(config, [options]) ⇒ Promise<AxiosResponse<T>>: Executes an HTTP request using the axios client.

    • Parameters:

      • T defines the response type. Defaults to unknown.

      • config is the AxiosRequestConfig object. Required.

      • options: ClientCallOptions to further configure the call.

  • requestInterceptor([onFulfilled], [onRejected]) ⇒ () ⇒ void: Adds a request interceptor to the axios client.

    • Parameters:

      • onFulfilled: Function that executes before the request executes. Optional.

        • Type: (AxiosRequestConfig) ⇒ AxiosRequestConfig | Promise<AxiosRequestConfig>

      • onRejected: Function to be called when the request is rejected. Optional.

        • Type: (error: unknown) ⇒ unknown

  • responseInterceptor([onFulfilled], [onRejected]) ⇒ () ⇒ void: Adds a response interceptor to the axios client.

    • Parameters:

      • onFulfilled: Function that executes after a successful response. Optional.

        • Type: (AxiosResponse) ⇒ AxiosResponse | Promise<AxiosResponse>

      • onRejected: Function that executes after a failure response. Optional.

        • Type: (error: unknown) ⇒ unknown

ClientCallOptions

Options passed to the HTTP request call to customize the request configuration.

Property Type Description

applicationToken?

string

Application token to be used for this specific operation. This will take precedence over the client’s applicationToken.

accessToken?

string

Bearer token to be used to authorize this request for a particular user. This will include an Authorization header with the value Bearer ${accessToken}.

cancelToken?

CancelToken

Axios CancelToken to be used for request cancellation. This will be included on the request configuration passed to the request agent.

config?

AxiosRequestConfig

Overrides of the HTTP request configuration for an operation. These overrides will be merged into the default request configuration for the operation.

await client.getOperation({
  config: {
    headers: {
      'X-My-Header': 'My Header Value'
    }
  }
});

configCustomizer?

(config: AxiosRequestConfig) ⇒ Promise<void> | void

Function used to customize the HTTP request configuration for an operation. This function can be async and return a Promise.

await client.doOperation({
  configCustomizer: config => {
    config.headers['X-My-Header'] = 'My Header Value';
  }
});

headers?

{ [name: string]: string }

Overrides for the HTTP request headers for an operation. These headers will be merged into the default request headers for the operation.

locale?

string

The current locale for the operation. This value will be added as an Accept-Language header on the requst.

params?

{ [name: string]: unknown }

Overrides for the HTTP request parameters for an operation. These parameters will be merged into the default request parameters for the operation.

preview?

PreviewOptions

Options that allow for the access of sandboxed preview data

ClientOptions

Property Type Description

agent?

AxiosInstance

applicationToken?

string

Application token to be used for this specific operation.

baseURL?

string

Base URL for the axios client.

baseHost?

string

Concatenated with the basePath to create the default baseURL. Ignored if baseURL is provided.

basePath?

string

Concatenated with the baseHost to create the default baseURL. Ignored if baseURL is provided.

locale?

string

The current locale for the operation. This value will be added as an Accept-Language header on the requst.

preview?

PreviewOptions

Options passed to the HTTP request call to customize the request for previews. These will be treated as the default values when constructing the relevant request headers.

defaults?

AxiosRequestConfig

Default request configuration.

CurrencyUnit

Property Type Description

currencyCode

string

The unique currency code, the effective code depends on the currency.

numericCode?

string

The numeric currency code. within the ISO-4217 name space.

DefaultPaymentStrategy (Enum)

Defines the default payment strategies possible for PriceData.

Tip
 Added to Core SDK in 1.8.0.
Name Value Description

ONE_TIME

'ONE_TIME'

Indicates the payment is made once, usually at time of checkout

PREPAID

'PREPAID'

Indicates the payment is made at the beginning of the billing period

POSTPAID

'POSTPAID'

Indicates the payment is made at the end of the billing period

DefaultPriceListPriceSources (Enum)

Represents where a price is coming from within a price list.

Tip
 Added to Core SDK in 1.8.0.
Name Value Description

BLC_PRICE_LIST_PRICE_DATA

'BLC_PRICE_LIST_PRICE_DATA'

Represents that this price comes from the Price Data that is explicitly added to the Price List.

BLC_PRICE_LIST_FORMULA

'BLC_PRICE_LIST_FORMULA'

Represents that this price comes from the Price List’s formula, e.g. multiplier, percentage, addition, etc.

EXTERNAL

'EXTERNAL'

Represents that this price comes from an external source.

DefaultRecurringPeriodType (Enum)

Defines the default period types possible for recurring prices.

Tip
 Added to Core SDK in 1.8.0.
Name Value Description

MONTHLY

'MONTHLY'

QUARTERLY

'QUARTERLY'

ANNUALLY

'ANNUALLY'

DefaultRequestHeaderType (Enum)

Defines the names of frequently used request headers.

Name Value Description

ACCEPT_LANGUAGE

'Accept-Language'

AUTHORIZATION

'Authorization'

APPLICATION_TOKEN

'X-Application-Token'

PREVIEW_SANDBOX

'X-Preview-Sandbox'

PREVIEW_TOKEN

'X-Preview-Token'

PREVIEW_DATE

'X-Preview-Date'

DefaultTermDurationType (Enum)

Defines the default term duration types possible for recurring prices.

Tip
 Added to Core SDK in 1.8.0.
Name Value Description

DAYS

'DAYS'

WEEKS

'WEEKS'

MONTHS

'MONTHS'

YEARS

'YEARS'

EntityAsset

Represents a digital asset related to some entity like a product.

Property Type Description

applicationId?

string

The application id that this asset is associated with, used for asset resolving

tenantId?

string

The tenant id that this asset is associated with, used for asset resolving

type

string

Describes the general type of the asset.

provider

string

The name of the provider that is hosting the asset.

url?

string

The location used to resolve this asset.

contentUrl

string

Fully quailified URL for the asset. Includes all tenant and context information.

embedCode?

string

If and only if the type is 'EMBED', this field holds the HTML to embed.

altText?

string

Text that corresponds to the HTML alt attribute that should be used when this asset is rendered in a browser.

title?

string

Text that corresponds to the HTML title attribute that should be used when this asset is rendered in a browser.

tags?

Array<string>

Descriptive or identifying labels.

attributes

Record<string, unknown>

Additional attributes of the asset.

[key: string]

unknown

ExchangeRateDetail

Represents the details of the exchange rate used to convert a MonetaryAmount from one currency to another.

Tip
 Core SDK 1.7.2
Property Type Description

baseCurrencyCode

string

The original currency.

convertedCurrencyCode

string

The currency converted into.

rate

number

The conversion factor used to convert baseCurrencyCode to the convertedCurrencyCode.

attributes

Record<string, unknown>

Miscellaneous attributes that can be set to this ExchangeRateDetail.

FieldValidationError

extends GlobalApiError

Type of GlobalApiError for information about a field that failed validation.

Property Type Description

path

string

Path on the validated entity to the field that failed validation: cartItems[0].quantity.

rejectedValue?

unknown

Value that was rejected if applicable.

GlobalApiError

Represents an individual global error that came back from the API.

Property Type Description

code

string

Can be either machine-readable or human-readable representation of the error.

reason

string

Human-readable representation of the error

MonetaryAmount

Property Type Description

amount

number

The monetary amount.

currency

string

The currency.

NarrowedPageable

extends UnnumberedPageable

Pageable that is suitable for denoting page boundaries for a narrowed fetch. Narrowed fetch results generally go through a NarrowExecutor and as a result, can provide a narrowed result set from what is physically represented in the database. For this reason, it is important to keep track of a silent underlyingPageSize when determining next page offset values. For example, next page offset is generally calculated as the current offset plus the underlyingPageSize.

Property Type Description

forward

boolean

Whether the pagination results represent a forward progression or backwards progression.

underlyingPageSize

number

The number of physical database records processed. This can be different than the narrowed records returned in a page.

NarrowedPageRequest

Params to include in API requests to indicate pagination options for denoting page boundaries for a narrowed fetch.

Property Type Description

forward

boolean

Whether to request a forward progression of results or a backward one.

offset

number

The offset to start the progression of the results, e.g., start at the 10th element.

sort?

string

How the results should be sorted.

Page<T, P>

Represents a "page" of data.

Property Type Description

content

Array<T>

The content in this page.

empty

boolean

Whether the page had no results.

first

boolean

Whether the page is the first.

last

boolean

Whether the page is the last.

number?

number

The page number.

numberOfElements

number

The number of elements in this page.

pageable

P

The pagination info.

size

number

The size of the page.

sort

Sort

The sort details for the page.

totalElements?

number

The total of all elements including those that extend beyond this page.

totalPages?

number

The total number of pages that can be returned based on the size and total elements.

Pageable

Defines the pagination for a result set.

Property Type Description

paged

boolean

Whether it contains paged information.

offset

number

The offset to be taken according to the underlying page and page size.

pageNumber?

number

The page number.

pageSize

number

The number of items to be returned.

sort?

Sort

The sort params for the pageable

unpaged

boolean

Whether it does NOT contain paged information.

PageRequestParams

Params to include in API requests to indicate pagination options for default paging.

Property Type Description

page?

number

The number of the page desired.

size?

number

The size of the page desired.

sort?

string

How the results should be sorted.

PreviewOptions

Options passed to the HTTP request call to customize the request for previews. This if the token is valid and and the sandbox is with in the same context as the token with a valid date

Property Type Description

token

string

Preview token to authorize that a request has access to preview data for a given sandbox

sandbox

string

The Sandbox ID.

date?

string

The date in which to preview data.

PriceableTargetRef

This represents a slimmed-down version of PriceableTarget that contains only that information which can be used to uniquely identify a target.

Tip
 Added to Core SDK in 1.8.0.
Property Type Description

targetId

string

The unique identifier for the priceable target

targetType?

string

The type of the priceable target (i.e. "SKU")

priceableFields?

Record<string, MonetaryAmount | number>

The fields to price

attributes?

Record<string, unknown>

Any additional attributes

termDurationLength?

number

The length of the terms, e.g., if this is 36 and termDurationType is MONTHS, then the price should be charged for 36 months.

termDurationType?

DefaultTermDurationType | string

The type of term duration, whether days, weeks, months, etc.

see DefaultTermDurationType

characteristics?

Record<string, string>

Gets the characteristics of the target, e.g., capacity:128GB. This indicates that the caller wants a specific price targeting these characteristics not just a base or default price for the target item. This is useful when the target is a flattened Product with no variations but still has configurable options that could drive pricing.

paymentStrategy?

DefaultPaymentStrategy | string

Only relevant for price that came from a specific PriceData. Represents the payment strategy, specifically when payment is billed for a recurring price.

see DefaultPaymentStrategy

recurringPeriodFrequency?

number

The frequency with which the recurring price should be charged.

recurringPeriodType?

DefaultRecurringPeriodType | string

The type of period, whether monthly, quarterly, annually, etc.

see DefaultRecurringPeriodType

PriceInfo

Represents pricing information for a priceable entity like a Product or Variant. This includes the type of price (sale, standard, contract), the source price list, recurring and usage prices, and details for other candidate prices that were not used.

Tip
 Added to Core SDK in 1.8.0.
Property Type Description

target

PriceableTargetRef

The target that the price is for.

price

MonetaryAmount

Determined best price for a target.

priceType

string

The type of whether salePrice, standardPrice, contractPrice, etc.

priceTypeDetails

Record<string, PriceTypeDetail>

Map of each type of price to each corresponding PriceTypeDetail, which contains the best overall price for that type.

recurringPrice?

RecurringPriceDetail

The recurring price for the target, if applicable.

Tip
 Browse SDK 1.7.0

usagePrice?

UsagePriceDetail

The usage price for the target, if applicable.

Tip
 Browse SDK 1.7.0

priceListId?

string

The ID of the source price list.

priceListPriceSource?

DefaultPriceListPriceSources | string

If this price is from a price list, this field indicates the source of the price within the price list, e.g. price list formula, price list price data, etc.

paymentStrategy

DefaultPaymentStrategy | string

Only relevant for price that came from a specific PriceData. Represents the payment strategy, specifically when payment is billed for a recurring price.

See DefaultPaymentStrategy

Tip
 Browse SDK 1.7.2

convertedPriceTypeDetails?

Record<string, PriceTypeDetail>

Map containing the entries of priceTypeDetails but converted to the requested currency.

The requested currency is obtained from the PriceContext.

Tip
 Browse SDK 1.7.2

[key: string]

unknown

PriceTypeDetail

Aggregation of price details for a specific priceable field provided by a priceable target, e.g., the best prices for each of a Product’s cost, standard price, and sale price. This is useful when wanting to show strikethrough pricing.

Tip
 Added to Core SDK in 1.8.0.
Property Type Description

bestPrice

MonetaryAmount

The determined best price value for this type of price from amongst all the candidates.

type

string

The corresponding type of the price: salePrice, standardPrice, contractPrice, etc.

bestRecurringPriceDetail?

RecurringPriceDetail

The recurring price for the target, if applicable.

Tip
 Core SDK 1.7.0

bestUsagePriceDetail?

UsagePriceDetail

The usage price for the target, if applicable.

Tip
 Core SDK 1.7.0

priceListId?

string

The ID of the source price list.

hasCurrencyConversion?

boolean

Whether this detail has a corresponding record in PriceInfo#convertedPriceTypeDetails where the price has been converted to a different currency.

Tip
 Core SDK 1.7.2

exchangeRateDetail?

ExchangeRateDetail

Details recording the exchange rate used to convert the price to a different currency. This is only present on converted detail not on the original detail, e.g., this won’t be present on the same detail where hasCurrencyConversion is true.

Tip
 Core SDK 1.7.2

[key: string]

unknown

Any additional custom attributes included on this object.

RecurringPriceDetail

Represents details for a recurring price, e.g., a subscription price, including information about the billing period and any terms.

Tip
 Added to Core SDK in 1.8.0.
Property Type Description

price

MonetaryAmount

Determined best price for a target.

periodFrequency

number

The frequency with which the recurring price should be charged.

periodType

DefaultRecurringPeriodType | string

The type of period, whether monthly, quarterly, annually, etc.

see DefaultRecurringPeriodType

periodLimit?

number

The number of periods that the price should be charged.

termDurationLength?

number

The length of the terms, e.g., if this is 36 and termDurationType is MONTHS, then the price should be charged for 36 months.

termDurationType?

DefaultTermDurationType | string

The type of term duration, whether days, weeks, months, etc.

see DefaultTermDurationType

Sort

Defines the sort details for a result set.

Property Type Description

empty

boolean

Whether it is empty.

orders?

Array<SortOrder>

Ordering to apply.

sorted

boolean

Whether it is sorted.

unsorted

boolean

Whether it is NOT sorted.

SortOrder

Describes the sort details for a specific property.

Property Type Description

direction

'ASC' | 'DESC'

The sort direction.

ignoreCase

boolean

Whether to ignore case when sorting on the property.

property

string

The property to sort by.

nullHandling

'NATIVE' | 'NULLS_FIRST' | 'NULLS_LAST'

How to handle null values when sorting.

UsagePriceDetail

Represents details for a usage price, e.g., price per minute, including the unit of measure.

Tip
 Added to Core SDK in 1.8.0.
Property Type Description

price

MonetaryAmount

The price to charge for usage.

amount

number

The amount of units to charge for, e.g., charge $2 for every 1 GB used.

units

string

The units (e.g., minutes, texts, GB) defining what is getting used against which to charge the amount.