@spree/storefront-api-v2-sdk
Advanced tools
Node module to easily integrate your JavaScript or TypeScript application with Spree API V2. You can create an entirely custom Storefront in JS/TS with this package including one page checkout, Single Page Apps, PWAs and so on
Node module to easily integrate your JavaScript or TypeScript application with Spree API V2. You can create an entirely custom Storefront in JS/TS with this package including one page checkout, Single Page Apps, PWAs and so on.
Developed and maintained by:
Сontents:
Install the NPM package:
npm install @spree/storefront-api-v2-sdk --save
Create a client:
import { makeClient } from '@spree/storefront-api-v2-sdk'
// When using the SDK in a <script> tag or as part of a Webpack bundle
// targeted for the browser, instead use:
// import { makeClient } from '@spree/storefront-api-v2-sdk/dist/client'
const client = makeClient({
host: 'http://localhost:3000'
})
TypeScript definitions are included in the module and should be automatically used by any editor that supports them.
client allows calling Spree methods, ex.:
client.products.list({
include: 'default_variant',
page: 1
})
The SDK is also hosted by the UNPKG CDN. Follow this link to download version 4.5.1 and this link to download the newest version. Include the SDK on a website like so:
<script src="https://unpkg.com/@spree/storefront-api-v2-sdk@4.5.1/dist/client/index.js"></script>
<script>
const client = window.SpreeSDK.makeClient({
host: 'http://localhost:3000'
})
// ...
</script>
Client methods return a result object. When a request succeeds, the data received from Spree is retrievable using its success() method and provided in the JSON:API format. isSuccess() tells if a request succeeded.
The SDK avoids throwing JavaScript Errors. Instead, any error is included in a result object.
To determine whether a call was successful, use isSuccess() or isFail() methods on the result. Details of a failed call can be retrieved using fail(). The method returns a SpreeSDKError instance, which is the primary type for all errors returned by the SDK and extends the native JavaScript Error type.
Available SpreeSDKError subtypes:
| Class Name | Purpose |
|---|---|
MisconfigurationError | Signifies the SDK's Client was created with improper options. Make sure the values of host and other options (if any) provided to Client have the correct format. |
NoResponseError | Spree store could not be reached. Ensure it's running and available under the host address provided to the Client instance. |
SpreeError | Spree responded with an error. To debug the issue, check the error's serverResponse field. It contains details about the response from Spree, such as the HTTP status code and headers. |
BasicSpreeError | Extends SpreeError with a summary field provided by Spree and containing a summary of the issue. |
ExpandedSpreeError | Extends BasicSpreeError with a errors field. errors contains a detailed explanation of the issue, ex. all the validation errors when trying to add shipping details to a Spree order. The getErrors method can be used to retrieve a concrete value inside errors, ex. expSpreeError.getErrors(['bill_address', 'firstname']). |
The specific type of error returned by fail() can be determined using instanceof, ex. if(response.fail() instanceof BasicSpreeError){...}.
Most endpoints require a token for authentication. It can be an Order Token, Bearer Token or a Confirmation Token.
Identifies a guest user's cart and order.
const response = await client.cart.create()
const orderToken: string = response.success().data.attributes.token
Identifies a logged in user.
const response = await client.authentication.getToken({
username: 'spree@example.com',
password: 'spree123'
})
const bearerToken: string = response.success().access_token
Identifies a user for a single operation. For example, to reset their account's password. Confirmation Tokens are single-use and may have an expiration date.
By default, the Spree SDK uses Axios to communicate with Spree. Another built-in option is fetch. It can be set as follows:
createClient({ fetcherType: 'fetch', host: ... })
The 'fetch' option will look for global fetch and Request values and fallback to node-fetch during runtime.
A custom fetcher can be used like so:
createClient({ fetcherType: 'custom', createFetcher: ... })
To create a custom fetcher which uses a fetch-compatible interface, use the createCustomizedFetchFetcher function.
Spree Storefront API SDK contains each endpoint according to Spree Guides
getTokenCreates a Bearer token required to authorize OAuth API calls.
Parameters schema:
username: string
password: string
Success response schema:
access_token: string
token_type: string = 'Bearer'
expires_in: number
refresh_token: string
created_at: number
Failure response schema: Error schema
Example:
const token = await client.authentication.getToken({
username: 'spree@example.com',
password: 'spree123'
})
refreshTokenMethod refreshToken refreshes a Bearer token required to authorize OAuth API calls.
Parameters schema:
refresh_token: string
Success response schema:
access_token: string
token_type: string = 'Bearer'
expires_in: number
refresh_token: string
created_at: number
Failure response schema: Error schema
Example:
const token = await client.authentication.refreshToken({
refresh_token: 'aebe2886d7dbba6f769e20043e40cfa3447e23ad9d8e82c632f60ed63a2f0df1'
})
createCreates new account and returns its attributes.
Parameters schema:
user: {
email: string
password: string
password_confirmation: string
}
Success response schema: Success schema
Failure response schema: Error schema
Example:
const response = await client.account.create({
user: {
email: 'john@snow.org',
password: 'spree123',
password_confirmation: 'spree123'
}
})
confirmConfirms new account e-mail and returns account registration status.
Parameters schema:
confirmationToken: string
Success response schema:
data: {
state: string
}
Failure response schema: Error schema
Example:
const response = await client.account.confirm('2xssfC9Hzf8DJXyRZGmB')
forgotPasswordSends an account recovery link to the provided email address. The link allows resetting the password for the account.
Parameters schema:
user: {
email: string
}
Success response schema: Success schema
Failure response schema: Error schema
Example:
const response = await client.account.forgotPassword({
user: {
email: 'spree@example.com'
}
})
resetPasswordChanges the password associated with the account using an account recovery token.
Parameters schema:
user: {
password: string
password_confirmation: string
}
Required token: Confirmation token
Success response schema: Success schema
Failure response schema: Error schema
Example:
const response = await client.account.resetPassword('7381273269536713689562374856', {
user: {
password: '123!@#asdASD',
password_confirmation: '123!@#asdASD'
}
})
updateUpdates account and returns its attributes.
Parameters schema:
user: {
email: string
password: string
password_confirmation: string
}
Required token: Bearer token
Success response schema: Success schema
Failure response schema: Error schema
Example:
const response = await client.account.update(
{ bearerToken },
{
user: {
email: 'john@snow.org',
password: 'new_spree123',
password_confirmation: 'new_spree123'
}
}
)
accountInfoReturns current user information.
Required token: Bearer token
Success response schema: Success schema
Failure response schema: Error schema
Example:
const response = await client.account.accountInfo({ bearerToken })
creditCardsListReturns a list of Credit Cards for the signed in User.
Required token: Bearer token
Success response schema: Success schema
Failure response schema: Error schema
Example:
const response = await client.account.creditCardsList({ bearerToken })
defaultCreditCardReturn the User's default Credit Card.
Required token: Bearer token
Success response schema: Success schema
Failure response schema: Error schema
Example:
const response = await client.account.defaultCreditCard({ bearerToken })
completedOrdersListReturns Orders placed by the User. Only completed ones.
Required token: Bearer token
Success response schema: Success schema
Failure response schema: Error schema
Example:
const response = await client.account.completedOrdersList({ bearerToken })
completedOrderReturn the User's completed Order.
Required token: Bearer token
Parameters schema:
orderNumber: string
Success response schema: Success schema
Failure response schema: Error schema
Example:
const response = await client.account.completedOrder({ bearerToken }, 'R653163382')
addressesListReturns a list of Addresses for the signed in User
Required token: Bearer token
Success response schema: Success schema
Failure response schema: Error schema
Example:
const response = await client.account.addressesList({ bearerToken })
showAddressCreate a new Address for the signed in User.
Required token: Bearer token
Parameters schema:
addressId: string
Success response schema: Success schema
Failure response schema: Error schema
Example:
const response = await client.account.showAddress({ bearerToken }, '1')
createAddressCreate a new Address for the signed in User.
Required token: Bearer token
Parameters schema:
address: {
firstname: string
lastname: string
address1: string
address2?: string
city: string
phone?: string
zipcode: string
state_name: string // State Abbreviations
country_iso: string // Country ISO (2-chars) or ISO3 (3-chars)
company?: string
}
Success response schema: Success schema
Failure response schema: Error schema
Example:
const response = await client.account.createAddress(
{ bearerToken },
{
address: {
firstname: 'John',
lastname: 'Snow',
address1: '7735 Old Georgetown Road',
address2: '2nd Floor',
city: 'Bethesda',
phone: '3014445002',
zipcode: '20814',
state_name: 'MD',
country_iso: 'US',
company: 'Spark'
}
}
)
updateAddressUpdate selected Address for the signed in User.
Required token: Bearer token
Parameters schema:
address: {
firstname: string
lastname: string
address1: string
address2?: string
city: string
phone?: string
zipcode: string
state_name: string // State Abbreviations
country_iso: string // Country ISO (2-chars) or ISO3 (3-chars)
company?: string
}
Success response schema: Success schema
Failure response schema: Error schema
Example:
const response = await client.account.updateAddress({ bearerToken }, '1', {
address: {
firstname: 'John',
lastname: 'Snow',
address1: '7735 Old Georgetown Road',
address2: '2nd Floor',
city: 'Bethesda',
phone: '3014445002',
zipcode: '20814',
state_name: 'MD',
country_iso: 'US',
company: 'Spark'
}
})
removeAddressRemoves selected Address for the signed in User.
Required token: Bearer token
Parameters schema:
addressId: string
Success response schema: Success schema
Failure response schema: Error schema
Example:
const response = await client.account.removeAddress({ bearerToken }, '1')
statusReturns placed Order.
Required token: Order token
Parameters schema:
orderNumber: string
Success response schema: Success schema
Failure response schema: Error schema
Example:
const response = await client.order.status({ orderToken }, 'R653163382')
createCreates a new Cart and returns its attributes.
Required token: Bearer token if logged in user
Success response schema: Success schema
Failure response schema: Error schema
Example:
// Logged in user
const response = await client.cart.create({ bearerToken })
// or guest user
const response = await client.cart.create()
showReturns contents of the cart.
Required token: Bearer token or Order token
Success response schema: Success schema
Failure response schema: Error schema
Example:
// Logged in user
const response = await client.cart.show({ bearerToken })
// or guest user
const response = await client.cart.show({ orderToken })
addItemAdds a Product Variant to the Cart.
Required token: Bearer token or Order token
Parameters schema:
{
variant_id: string
quantity: number
options?: {
[key: string]: string
}
}
Success response schema: Success schema
Failure response schema: Error schema
Example:
// Logged in user
const response = await client.cart.addItem(
{ bearerToken },
{
variant_id: '1',
quantity: 1
}
)
// or guest user
const response = await client.cart.addItem(
{ orderToken },
{
variant_id: '1',
quantity: 1
}
)
setQuantitySets the quantity of a given line item. It has to be a positive integer greater than 0.
Required token: Bearer token or Order token
Parameters schema:
{
line_item_id: string
quantity: number
}
Success response schema: Success schema
Failure response schema: Error schema
Example:
// Logged in user
const response = await client.cart.setQuantity(
{ bearerToken },
{
line_item_id: '9',
quantity: 100
}
)
// or guest user
const response = await client.cart.setQuantity(
{ orderToken },
{
line_item_id: '9',
quantity: 100
}
)
removeItemRemoves Line Item from Cart.
Required token: Bearer token or Order token
Parameters schema:
line_item_id: string
Success response schema: Success schema
Failure response schema: Error schema
Example:
// Logged in user
const response = await client.cart.removeItem({ bearerToken }, '1')
// or guest user
const response = await client.cart.removeItem({ orderToken }, '1')
emptyCartEmpties the Cart.
Required token: Bearer token or Order token
Success response schema: Success schema
Failure response schema: Error schema
Example:
// Logged in user
const response = await client.cart.emptyCart({ bearerToken })
// or guest user
const response = await client.cart.emptyCart({ orderToken })
applyCouponCodeApplies a coupon code to the Cart.
Required token: Bearer token or Order token
Parameters schema:
{
coupon_code: string
}
Success response schema: Success schema
Failure response schema: Error schema
Example:
// Loged in user
const response = await client.cart.applyCouponCode(
{ bearerToken },
{
coupon_code: 'promo_test'
}
)
// or guest user
const response = await client.cart.applyCouponCode(
{ orderToken },
{
coupon_code: 'promo_test'
}
)
removeCouponCodeRemoves a coupon code from the Cart.
Required token: Bearer token or Order token
Parameters schema:
coupon_code?: string
Success response schema: Success schema
Filed response schema: Error schema
Example:
// Logged in user
const response = await client.cart.removeCouponCode({ bearerToken }, 'promo_test')
// or guest user
const response = await client.cart.removeCouponCode({ orderToken }, 'promo_test')
estimateShippingMethodsReturns a list of Estimated Shipping Rates for Cart.
Required token: Bearer token or Order token
Parameters schema:
country_iso: string
Success response schema: Success schema
Failure response schema: Error schema
Example:
// Logged in user
const response = await client.cart.estimateShippingMethods({ bearerToken }, 'USA')
// or guest user
const response = await client.cart.estimateShippingMethods({ orderToken }, 'USA')
orderUpdateUpdates the Checkout You can run multiple Checkout updates with different data types.
Required token: Bearer token or Order token
Parameters schema:
order: {
email: string
bill_address_attributes?: {
firstname: string
lastname: string
address1: string
city: string
phone: string
zipcode: string
state_name: string
country_iso: string
}
ship_address_attributes?: {
firstname: string
lastname: string
address1: string
city: string
phone: string
zipcode: string
state_name: string
country_iso: string
}
shipments_attributes?: [
{
selected_shipping_rate_id: number
id: number
}
]
payments_attributes?: [
{
payment_method_id: number
}
]
}
payment_source?: {
[payment_method_id: number]: {
number: string
month: string
year: string
verification_value: string
name: string
}
}
Success response schema: Success schema
Failure response schema: Error schema
Example:
// Logged in user
const response = await client.checkout.orderUpdate({ bearerToken }, { order: {...} })
// or guest user
const response = await client.checkout.orderUpdate({ orderToken }, { order: {...} })
orderNextGoes to the next Checkout step.
Required token: Bearer token or Order token
Success response schema: Success schema
Failure response schema: Error schema
Example:
// Logged in user
const response = await client.checkout.orderNext({ bearerToken })
// or guest user
const response = await client.checkout.orderNext({ orderToken })
advanceAdvances Checkout to the furthest Checkout step validation allows, until the Complete step.
Required token: Bearer token or Order token
Success response schema: Success schema
Failure response schema: Error schema
Example:
// Logged in user
const response = await client.checkout.advance({ bearerToken })
// or guest user
const response = await client.checkout.advance({ orderToken })
completeCompletes the Checkout.
Required token: Bearer token or Order token
Success response schema: Success schema
Failure response schema: Error schema
Example:
// Logged in user
const response = await client.checkout.complete({ bearerToken })
// or guest user
const response = await client.checkout.complete({ orderToken })
addStoreCreditsAdds Store Credit payments if a user has any.
Required token: Bearer token or Order token
Parameters schema:
{
amount: number
}
Success response schema: Success schema
Failure response schema: Error schema
Example:
// Logged in user
const response = await client.checkout.addStoreCredits({ bearerToken }, { amount: 100 })
// or guest user
const response = await client.checkout.addStoreCredits({ orderToken }, { amount: 100 })
removeStoreCreditsRemove Store Credit payments if any applied.
Required token: Bearer token or Order token
Success response schema: Success schema
Failure response schema: Error schema
Example:
// Logged in user
const response = await client.checkout.removeStoreCredits({ bearerToken })
// or guest user
const response = await client.checkout.removeStoreCredits({ orderToken })
paymentMethodsReturns a list of available Payment Methods.
Required token: Bearer token or Order token
Success response schema: Success schema
Failure response schema: Error schema
Example:
// Logged in user
const response = await client.checkout.paymentMethods({ bearerToken })
// or guest user
const response = await client.checkout.paymentMethods({ orderToken })
shippingMethodsReturns a list of available Shipping Rates for Checkout. Shipping Rates are grouped against Shipments. Each checkout cna have multiple Shipments eg. some products are available in stock and will be send out instantly and some needs to be backordered.
Required token: Bearer token or Order token
Parameters schema:
params?: {
include?: string
}
Success response schema: Success schema
Failure response schema: Error schema
Example:
// Logged in user
const response = await client.checkout.shippingMethods(
{ bearerToken },
{
include: 'shipping_rates,stock_location'
}
)
// or guest user
const response = await client.checkout.shippingMethods(
{ orderToken },
{
include: 'shipping_rates,stock_location'
}
)
Returns a list of Products.
listRequired token: Bearer token if logged in user
Parameters schema:
token?: IToken
params?: {
include?: string
fields?: {
[key: string]: string
}
filter?: {
[key: string]: number
}
sort?: string
page?: number
per_page?: number
}
Success response schema: Success schema
Failure response schema: Error schema
Example:
const response = await client.products.list()
showRequired token: Bearer token if logged in user
Parameters schema:
id: string
token?: IToken
params?: {
include: string
fields: {
[key: string]: string
}
}
Success response schema: Success schema
Failure response schema: Error schema
Example:
const response = = await client.products.show('123')
listReturns a list of Taxons.
Parameters schema:
params?: {
include?: string
fields?: {
[key: string]: string
}
filter?: {
[key: string]: number
}
page?: number
per_page?: number
}
Success response schema: Success schema
Failure response schema: Error schema
Example:
const response = await client.taxons.list()
showReturns a single Taxon.
Parameters schema:
id: string
params?: {
id: string
params?: {
include: string
fields: {
[key: string]: string
}
}
}
Success response schema: Success schema
Failure response schema: Error schema
Example:
const products = await client.taxons.show('1')
const cartCreateResponse = await client.cart.create()
const orderToken = cartCreateResponse.success().data.attributes.token
await client.cart.addItem({ orderToken }, { variant_id: '1' })
// Save a shipping address for shipping methods
await client.checkout.orderUpdate({ orderToken }, {
order: {
ship_address_attributes: {...}
}
})
const shipping = (await client.checkout.shippingMethods({ orderToken })).success()
const payment = (await client.checkout.paymentMethods({ orderToken })).success()
// Pick a shipping and payment method
await client.checkout.orderUpdate({ orderToken }, { order: {...} })
await client.checkout.complete({ orderToken })
const cartCreateResponse = await client.cart.create()
const orderToken = cartCreateResponse.success().data.attributes.token
await client.cart.addItem({ orderToken }, { variant_id: '1' })
// Step one - save email, billing and shipping addresses
await client.checkout.orderUpdate({ orderToken }, {
order: {
email,
bill_address_attributes: {...},
ship_address_attributes: {...}
}
})
await client.checkout.orderNext({ bearerToken })
// Step two - pick a shipping method
const shipping = (await client.checkout.shippingMethods({ orderToken })).success()
await client.checkout.orderUpdate({ orderToken }, {
order: {
shipments_attributes: [{
id: shipping.data[0].id,
selected_shipping_rate_id: shipping.data[0].relationships.shipping_rates.data[0].id
}]
}
})
await client.checkout.orderNext({ orderToken })
// Step three - pick a payment method
const payment = (await client.checkout.paymentMethods({ orderToken })).success()
await client.checkout.orderUpdate({ orderToken }, {
order: {
payments_attributes: [{
payment_method_id: payment.data[0].id
}]
},
payment_source: {
[payment.data[0].id]: {
number: '4111111111111111',
month: '1',
year: '2022',
verification_value: '123',
name: 'John Doe'
}
}
})
// Order complete
await client.checkout.orderNext({ orderToken })
await client.checkout.complete({ orderToken })
Spree is maintained by Spark Solutions Sp. z o.o..
We are passionate about open source software. We are available for hire.
FAQs
Node module to easily integrate your JavaScript or TypeScript application with Spree Storefront API V2. You can create an entirely custom Storefront in JS/TS with this package including one page checkout, Single Page Apps, PWAs and so on.
We found that @spree/storefront-api-v2-sdk demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.
Security News
vlt introduced its new package manager and a serverless registry this week, innovating in a space where npm has stagnated.
Security News
Research
The Socket Research Team uncovered a malicious Python package typosquatting the popular 'fabric' SSH library, silently exfiltrating AWS credentials from unsuspecting developers.