JavaScript SDK reference

function initializeDefaultContext ( ) : SDK

Initialize the SDK for use in a Javascript environment without DOM

initializeDefaultContext doesn't take any arguments

Returns

initializeDefaultContext returns a SDK

interface SnipcartBrowserContextOptions

Inititialization options for `initializeBrowserContext`

Properties

exportGlobal – boolean

When set to true, window.Snipcart gets assigned with the constructed SnipcartBrowserContext instance

function initializeBrowserContext ( apiKey? : string, doc? : HTMLDocument, options? : SnipcartBrowserContextOptions ) : Promise

Initialize the SDK for use in a Web browser

Arguments

apiKey – an optional string

Snipcart Public API Key
doc – an optional HTMLDocument

Custom document node instead of `window.document`
options – an optional SnipcartBrowserContextOptions

Initialization options

Returns

initializeBrowserContext returns a Promise

interface BrowserAPI

The browser API, responsible for all browser related operations

Methods

insertPaymentForm ( parentNode: HTMLElement, options: PaymentFormOptions ) : Promise

Inserts a payment form iframe served and secured by Snipcart's payment service.
Arguments
1. parentNode – HTMLElement
  
  The HTML node that the payment form iframe will be appended to.
2. options – PaymentFormOptions
  
  An configuration object passed to the payment form window once it is ready to receive cross-window messages // tslint:disable-next-line:max-line-length
Returns

insertPaymentForm returns a Promise
insertPaymentAuthenticationWindow ( parentNode: HTMLElement ) : PaymentAuthenticationWindowAPI

Inserts a payment authentication window iframe when SCA challenge is requested.
Arguments
1. parentNode – HTMLElement
  
  The HTML node that the payment authentication window iframe will be appended to. // tslint:disable-next-line:max-line-length
Returns

insertPaymentAuthenticationWindow returns a PaymentAuthenticationWindowAPI

interface PaymentAuthenticationWindowAPI

Methods

authenticate ( ) : Promise

Starts the payment authentication challenge process.

authenticate doesn't take any arguments

Returns

authenticate returns a Promise
destroy ( ) : void

Removes the iframe and cancel all listeners.

destroy doesn't take any arguments and return nothing

interface PaymentFormAPI

Interface that exposes the actions available on a payment form instance.

Methods

destroy ( ) : void

Removes the payment form iframe element from the DOM.

destroy doesn't take any arguments and return nothing
authorizePayment ( ) : Promise

Triggers the authorization of the payment using the information provided in the form.

authorizePayment doesn't take any arguments

Returns

authorizePayment returns a Promise

interface SDKWithinBrowser

This is a specialization of the SDK interface, providing additional browser specific members

Properties

browser – BrowserAPI

enum SnipcartBrowserContextEvents : string

Members

CHECKOUT_CLICKED = "summary.checkout_clicked"
CUSTOMER_SIGNIN_CLICKED = "customer.signin_clicked"
CUSTOMER_REGISTER_CLICKED = "customer.register_clicked"

interface EventEmitter

Subscribe Only event emitter

Methods

on ( eventName: string, callback: (payload: T) => void ) : Unsubscribe
Arguments
1. eventName – string
2. callback – (payload: T) => void
Returns

on returns a Unsubscribe

interface ReadOnlyStore

ReadOnly Redux store

Methods

getState ( ) : S

Get the current state

getState doesn't take any arguments

Returns

getState returns a S
subscribe ( listener: () => void ) : Unsubscribe

Subscribe to state changes
Arguments
1. listener – () => void
  
  A callback to be invoked on every state change.
Returns

subscribe returns a Unsubscribe

interface SDK

This is the SDK

Properties

api – API

Cart API entry point
store – ReadOnlyStore

Returns the current store object backing Snipcart's current state
version – string

Returns the current Snipcart version
events – EventEmitter

Returns the event bus used to subscribe to events
ready – Promise

Returns a promise that gets resolved when the SDK is ready.

interface Unsubscribe

Function to remove listener added by `ReadOnlyStore.subscribe()`.

Methods

( ) : void

Signature of the `Unsubscribe` type itself

It doesn't take any arguments and return nothing

interface SDKInitilizationOptions

These are the SDK initialization options

Properties

apiKey – an optional string

Snipcart's Public API Key
cartToken – an optional string

The UID token of the cart to load at session start
customerToken – an optional string

The session token of a signed in customer
paymentSessionId – an optional string

In case of a redirect flow payment authorization, the UID of the payment session
language – an optional string

Current language of the session

enum CartItemsErrorCodes : string

Members

ItemNotFound = "snipcart_error_item_not_found"

enum CartErrorCodes : string

Members

DiscountNotFound = "snipcart_error_discount_not_found"
PaymentSessionNotInitialized = "snipcart_error_payment_session_not_initialized"
PaymentSessionMissingRequiredData = "snipcart_error_payment_session_missing_required_data"
PaymentSessionIncorrectState = "payment_session_incorrect_state"
PaymentAuthorizationFailed = "snipcart.errors.payment_authorization.{stateDescriptorCode}"

enum CommonErrorCodes : string

Members

OperationFailed = "snipcart_error_operation_failed"
InvalidRequest = "snipcart_error_invalid_request"
ValidationFailed = "snipcart_error_validation_failed"

enum CommonErrorFields : string

Members

Root = "globalForm"

interface Locales

interface LocalesRoot

Properties

payment – PaymentLocales

interface SessionSetLanguagePayload

Properties

lang – string
overrides – an optional LocalesRoot

interface API

This is the main API entrypoint to interact with Snipcart remote API. All APIs used to interact with the current cart are available through this.

Properties

cart – CartAPI

API to manage cart
orders – OrdersAPI
customer – CustomerAPI
localization – LocalizationAPI
session – SessionAPI

interface CartAPI

The cart API

Properties

items – ItemsAPI

Cart items API entry point

Methods

update ( payload: UpdateCartPayload ) : Promise

Updates a cart in progress
Arguments
1. payload – UpdateCartPayload
  
  Data to update
Returns

update returns a Promise
applyDiscount ( discountCode: string ) : Promise
Arguments
1. discountCode – string
  
  The discount code to apply
Returns

applyDiscount returns a Promise
removeDiscount ( discountCode: string ) : Promise
Arguments
1. discountCode – string
  
  The discount code to apply
Returns

removeDiscount returns a Promise
setShippingInformation ( information: ShippingInformation ) : Promise

Provide shipping information for the current cart
Arguments
1. information – ShippingInformation
  
  Billing address
Returns

setShippingInformation returns a Promise
setPaymentDetails ( details: PaymentDetails ) : Promise

Provide selected payment method and associated details for the current cart
Arguments
1. details – PaymentDetails
  
  Payment method details
Returns

setPaymentDetails returns a Promise
fetchShippingRates ( ) : Promise

Fetch shipping rates for the cart.

fetchShippingRates doesn't take any arguments

Returns

fetchShippingRates returns a Promise
initializePaymentSession ( paymentAuthorizationRedirectUrl? : string ) : Promise

Initializes the payment session.
Arguments
1. paymentAuthorizationRedirectUrl – an optional string
  
  When the payment authorization flow is Redirect, this is the URL to redirect once authorized.
Returns

initializePaymentSession returns a Promise
selectPaymentMethod ( paymentMethodId: string ) : Promise

Select the payment method to be used
Arguments
1. paymentMethodId – string
Returns

selectPaymentMethod returns a Promise
confirm ( ) : Promise

Confirm the order and process the payment

confirm doesn't take any arguments

Returns

confirm returns a Promise

interface ItemsAPI

The cart items API

Methods

add ( items: ) : Promise

Adds an item or multiple items to the cart.
Arguments
1. items –
  
  Items that will be added to the cart. Can be an arry of items or a single one.
Returns

add returns a Promise
remove ( item: ) : Promise

Removes an item from the cart.
Arguments
1. item –
  
  Item unique ID.
Returns

remove returns a Promise
update ( item: CartItem ) : Promise

Update an item in the cart
Arguments
1. item – CartItem
  
  Item to update with new values
Returns

update returns a Promise

interface CustomerAPI

The customer API

Methods

signin ( email: string, password: string ) : Promise

Logs in a customer.
Arguments
1. email – string
  
  Customer's email.
2. password – string
  
  Customer's password.
Returns

signin returns a Promise
signout ( ) : Promise

Logs out the current customer.

signout doesn't take any arguments

Returns

signout returns a Promise
register ( email: string, password: string, passwordConfirm: string ) : Promise

Creates a new customer.
Arguments
1. email – string
  
  Customer's desired email.
2. password – string
  
  Customer's password.
3. passwordConfirm – string
  
  Confirmation password.
Returns

register returns a Promise
fetchOrders ( limit: number, offset: number ) : Promise

Fetches customer orders sorted by completion date.
Arguments
1. limit – number
  
  the amount of orders to fetch.
2. offset – number
  
  the starting point of the result set.
Returns

fetchOrders returns a Promise

interface LocalizationAPI

The localization API

Methods

fetchSuggestedAddresses ( query: LocalizationQuery ) : Promise

Returns addresses matching the specified query string.
Arguments
1. query – LocalizationQuery
  
  Query string
Returns

fetchSuggestedAddresses returns a Promise

interface OrdersAPI

Methods

fetch ( token: string ) : Promise

Retrieves an order by its unique token.
Arguments
1. token – string
  
  Order unique token.
Returns

fetch returns a Promise

interface SessionAPI

The session API

Methods

setLanguage ( lang: string, overrides? : Locales ) : void
Arguments
1. lang – string
2. overrides – an optional Locales
setLanguage doesn't return anything

enum PublicEvents : string

Members

ITEM_ADDING = "item.adding"
ITEM_ADDED = "item.added"
ITEM_UPDATED = "item.updated"
CART_CREATED = "cart.created"
CART_CONFIRMED = "cart.confirmed"
CUSTOMER_REGISTERED = "customer.registered"
CUSTOMER_SIGNEDIN = "customer.signedin"
CUSTOMER_SIGNEDOUT = "customer.signedout"
LANGUAGE_UPDATED = "language.updated"
SNIPCART_INITIALIZED = "snipcart.initialized"
SNIPCART_INITIALIZATION_FAILED = "snipcart.initialization.failed"

interface Address

Properties

name – string
company – an optional string
address1 – string
address2 – an optional string
city – string
country – string
postalCode – string
province – an optional string
phone – an optional string
vatNumber – an optional string
errors – an optional ValidationError

interface CartItem

Properties

uniqueId – an optional string
id – string
name – string
basePrice –
url – string
unitPrice – an optional
description – an optional string
image – an optional string
categories –
metadata – an optional {}
fileGuid – an optional string
quantity – number
minQuantity – number
maxQuantity – number
quantityStep – number
dimensions – Dimensions
customFields –
stackable – StackingOptions
hasTaxesIncluded – boolean
taxable – boolean
taxes – an optional
shippable – boolean

interface CartSummary

Properties

subtotal – number
total – number
taxes –
discountInducedTaxesVariation – number

interface CustomField

Properties

name – string
value –
type – string
options – an optional

interface CustomFieldOption

Properties

name – string
priceModifier – an optional number

interface Dimensions

Properties

weight – an optional number
width – an optional number
length – an optional number
height – an optional number

interface Discount

Properties

amountSaved – number
appliesOnAllRecurringOrders – boolean
code – string
id – string
name – string
trigger – string
type – string
value – number

interface DiscountError

Properties

cartSummary – CartSummary
result – { errors: ApiErrors; message: string; }

enum DiscountTrigger : string

Members

Code = "Code"

enum DiscountType : string

Members

FixedAmount = "FixedAmount"

interface EntityState

Properties

committing – Boolean

interface EntityWithState

Properties

state – an optional EntityState

interface BaseError

Properties

kind – TKind

enum ErrorKind : string

Members

System = "system"
Validation = "validation"

interface SystemError

Properties

code – string
message – string
technicalReason – an optional string
data – an optional any

interface ValidationError

Properties

form –
fields – { [key: string]: ValidationErrorItem[]; }

interface ValidationErrorItem

Properties

validation – string
message – string
attemptedValue – an optional any

interface LazyCollection

Properties

loading – boolean
status – LazyCollectionStatus
items –
errors – an optional SystemError

enum LazyCollectionStatus : string

Members

Loading = "Loading"
Loaded = "Loaded"
Stale = "Stale"

interface LocalizationQuery

Properties

query – string
context – string

enum PaymentAuthorizationFlow : string

Members

Form = "Form"
Redirect = "Redirect"
None = "None"

enum PaymentAuthorizationStates : string

Members

Unknown = "Unknown"
Unsuccessful = "Unsuccessful"
Pending = "Pending"
Successful = "Successful"

enum PaymentConfirmationSynchronicity : string

Members

Synchronous = "Synchronous"
Asynchronous = "Asynchronous"

interface PaymentDetails

Properties

method – string
details – T

enum AuthenticationChallengeState : number

Members

Ready = 0
Loading = 1

interface CreditCard

Properties

owner – string
last4 – string
brand – string

interface Invoice

Properties

targetId – string
email – string
amount – number
currency – string
billingAddress – InvoiceAddress
shippingAddress – an optional InvoiceAddress
items –

interface InvoiceAddress

Properties

name – string
surname – an optional string
streetAndNumber – string
city – string
postalCode – string
country – string

interface InvoiceItem

Properties

name – string
quantity – number
unitPrice – number
type – InvoiceItemType
rateOfTaxIncludedInPrice – an optional number

enum InvoiceItemType : string

Members

Physical = "physical"
Digital = "digital"
Tax = "tax"
Shipping = "shipping"
Discount = "discount"

interface PaymentAuthorization

Properties

url – string
confirmationSynchronicity – PaymentConfirmationSynchronicity
flow – PaymentAuthorizationFlow
state – PaymentAuthorizationStates
card – CreditCard
stateDescriptorCode – string
formLoadingState – PaymentFormLoadingState
error – an optional SystemError

enum PaymentFormLoadingState : number

Members

None = 0
Loading = 1
Loaded = 2

interface PaymentMethod

Properties

id – PaymentMethodIds
flow – PaymentAuthorizationFlow
name – an optional string
iconUrl – an optional string

enum PaymentMethodIds : string

Members

NoPayment = "no_payment"
Card = "card"
AchCredit = "ach_credit"
Alipay = "alipay"
Bancontact = "bancontact"
Eps = "eps"
Giropay = "giropay"
Ideal = "ideal"
Multibanco = "multibanco"
P24 = "p24"
SepaDebit = "sepa_debit"
Sofort = "sofort"
Wechat = "wechat"
ApplePay = "apple_pay"
BankTransfer = "bank_transfer"
Belfius = "belfius"
Kbc = "kbc"
KlarnaPayLater = "klarna_pay_later"
KlarnaSliceIt = "klarna_slice_it"
GiftCard = "gift_card"
IngHomePay = "ing_home_pay"
Paysafecard = "paysafecard"
PayPalExpressCheckout = "paypal"

interface PaymentSession

Properties

id – string
state – PaymentSessionStates
paymentMethod – string
availablePaymentMethods –
authorization – PaymentAuthorization
paymentAuthorizedRedirectUrl – string
invoice – Invoice
authenticationChallenge – { state: AuthenticationChallengeState; url: string; }

enum PaymentSessionStates : string

Members

RequiresPaymentMethod = "RequiresPaymentMethod"
Authorizing = "Authorizing"
RequiresAuthorization = "RequiresAuthorization"
Authorized = "Authorized"
Completed = "Completed"

interface ProductDefinition

Properties

id – string
name – string
price –
url – string
description – an optional string
image – an optional string
categories – an optional
metadata – an optional {}
fileGuid – an optional string
quantity – an optional number
minQuantity – an optional number
maxQuantity – an optional number
quantityStep – an optional number
dimensions – an optional Dimensions
customFields – an optional
stackable – an optional StackingOptions
shippable – boolean
hasTaxesIncluded – an optional boolean
taxable – boolean
taxes – an optional

function productDefinitionToCartItem ( definition: ProductDefinition, updatedItem? : CartItem ) : CartItem

Create a new or updated CartItem from provided ProductDefinition

Arguments

definition – ProductDefinition

product definition from JS API or html
updatedItem – an optional CartItem

serve as default data when updating an existing item

Returns

productDefinitionToCartItem returns a CartItem

interface ShippingInformation

Properties

method – string
cost – number

interface ShippingRate

Properties

description – string
cost – number
slug – string

interface Tax

Properties

name – string
amount – number
rate – number
appliesOnShipping – boolean
includedInPrice – boolean

interface UpdateCartPayload

Properties

billingAddress – an optional Address
shippingAddress – an optional Address
shipToBillingAddress – an optional boolean
email – an optional string
customFields – an optional

interface CartCreatedResponse

Properties

token – string
email – string
shippingAddress – Address
billingAddress – Address

interface CartResponse

Properties

token – string
lang – string
email – string
status – string
paymentStatus – string
billingAddress – Address
shippingAddress – Address
shippingInformation – ShippingInformationResponse
shipToBillingAddress – boolean
items –
discounts –
customFields –
taxes –
currency – string
summary – CartSummary
invoiceNumber – an optional string
card – an optional { last4Digits: string; type: string; }
paymentMethod – an optional string

interface CartUpdatedResponse

interface ShippingInformationResponse

Properties

fees – number
method – string

interface CartConfirmResponse

Properties

requiresRedirect – boolean
authenticationUrl – string
redirectUrl – string
cart – CartResponse
paymentSession – an optional PaymentSessionResponse

interface CartMutationResponse

Properties

result – T

interface CartMutationResponseBase

Properties

cartSummary – CartMutationSummary
billingAddress – Address
shippingAddress – Address
email – string

interface CartMutationSummary

Properties

subtotal – number
total – number
taxes –
discountInducedTaxesVariation – number
shippingFees – number
shippingMethod – string

interface CustomerAuthenticationResponse

Properties

sessionToken – string
customer – CustomerResponse
cartMutation – an optional CartMutationResponseBase

interface CustomerOrderItemResponse

Properties

uniqueId – string
name – string
quantity – number
price – number
image – string

interface CustomerOrderResponse

Properties

token – string
status – string
orderedOn – string
total – number
currency – string
invoiceNumber – string
items –

interface CustomerResponse

Properties

email – string

interface ApiErrors

interface ErrorResponse

Properties

message – string
reason – an optional string
content – an optional any
errors – { [property: string]: string[]; }

interface PagedResponse

Properties

items –
totalItems – number
offset – number
limit – number

interface PaymentSessionResponse

Properties

data – PaymentSession

interface CartState

Properties

token – string
email – string
lang – string
status – CartStatus
shipToBillingAddress – boolean
billingAddress – Address
shippingAddress – Address
shippingRates – LazyCollection
shippingDetails –
items –
taxes – LazyCollection
discounts – { errors?: SDKError; items: Discount[]; }
customFields –
paymentDetails –
subtotal – number
total – number
currency – string
paymentSession – an optional PaymentSession
invoiceNumber – an optional string
discountInducedTaxesVariation – number
card – an optional { last4: string; brand: string; }
errors – { payment?: SDKError; }

function createInitialCartState ( lang? : string ) : CartState

Arguments

lang – an optional string

Returns

createInitialCartState returns a CartState

function mapCartResponseToCartState ( cart: CartResponse, latestState? : CartState ) : CartState

Arguments

cart – CartResponse
latestState – an optional CartState

Returns

mapCartResponseToCartState returns a CartState

interface BaseCustomerState

Properties

status – Status

interface SignedInCustomerState

Properties

email – string
sessionToken – string

interface SignedOutCustomerState

Properties

register – { errors?: ValidationError; }
signin – { errors?: ValidationError; }

interface Loadable

Properties

loading – boolean

interface LocalizationState

Properties

suggestedAddressesQueries –

interface SuggestedAddressesQuery

Properties

query – string
context – string
loading – boolean
results –

function createInitialLocalizationState ( ) : LocalizationState

createInitialLocalizationState doesn't take any arguments

Returns

createInitialLocalizationState returns a LocalizationState

interface SessionState

Properties

id – string
lang – string
settings – { countries: []; currency: string; shippingEnabled: boolean; domain?: string; }
loading – boolean
features –

interface SnipcartState

Properties

cart – CartState
session – SessionState
customer –
localization – LocalizationState

interface StatusObject

Properties

status – T

enum CartStatus : number

Members

Uninitialized = 0
Creating = 1
Ready = 2
Completed = 3

enum Features : string

Members

CustomerDashboard = "CustomerDashboard"

enum PaymentStatus : number

Members

Unset = 0
Saving = 1
Saved = 2
Processing = 3
WaitingForUser = 4
Paid = 5
Refunded = 6
Pending = 7

JavaScript SDK reference

Returns

Properties

function initializeBrowserContext ( apiKey? : string, doc? : HTMLDocument, options? : SnipcartBrowserContextOptions ) : Promise

Arguments

Returns

Methods

insertPaymentForm ( parentNode: HTMLElement, options: PaymentFormOptions ) : Promise

Arguments

Returns

insertPaymentAuthenticationWindow ( parentNode: HTMLElement ) : PaymentAuthenticationWindowAPI

Arguments

Returns

Methods

authenticate ( ) : Promise

Returns

destroy ( ) : void

Methods

destroy ( ) : void

authorizePayment ( ) : Promise

Returns

Properties

Members

Methods

on ( eventName: string, callback: (payload: T) => void ) : Unsubscribe

Arguments

Returns

Methods

getState ( ) : S

Returns

subscribe ( listener: () => void ) : Unsubscribe

Arguments

Returns

Properties

Methods

( ) : void

Properties

Members

Members

Members

Members

Properties

Properties

Properties

Properties

Methods

update ( payload: UpdateCartPayload ) : Promise

Arguments

Returns

applyDiscount ( discountCode: string ) : Promise

Arguments

Returns

removeDiscount ( discountCode: string ) : Promise

Arguments

Returns

setShippingInformation ( information: ShippingInformation ) : Promise

Arguments

Returns

setPaymentDetails ( details: PaymentDetails ) : Promise

Arguments

Returns

fetchShippingRates ( ) : Promise

Returns

initializePaymentSession ( paymentAuthorizationRedirectUrl? : string ) : Promise

Arguments

Returns

selectPaymentMethod ( paymentMethodId: string ) : Promise

Arguments

Returns

confirm ( ) : Promise

Returns

Methods

add ( items: ) : Promise

Arguments

Returns

remove ( item: ) : Promise

Arguments

Returns

update ( item: CartItem ) : Promise

Arguments