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

  1. apiKey – an optional string

    Snipcart Public API Key

  2. doc – an optional HTMLDocument

    Custom document node instead of `window.document`

  3. 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

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

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 LocalesRoot

Properties

  • payment PaymentLocales

interface SessionSetLanguagePayload

Properties

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

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

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

interface CartItem

Properties

interface CartSummary

Properties

interface CustomField

Properties

  • name string

  • value

  • type string

  • options – an optional

interface CustomFieldOption

Properties

interface Dimensions

Properties

interface Discount

Properties

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

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

enum LazyCollectionStatus : string

Members

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

interface LocalizationQuery

Properties

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

interface Invoice

Properties

interface InvoiceAddress

Properties

interface InvoiceItem

Properties

enum InvoiceItemType : string

Members

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

interface PaymentAuthorization

Properties

enum PaymentFormLoadingState : number

Members

  • None = 0
  • Loading = 1
  • Loaded = 2

interface PaymentMethod

Properties

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

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

  1. definition ProductDefinition

    product definition from JS API or html

  2. updatedItem – an optional CartItem

    serve as default data when updating an existing item

Returns

productDefinitionToCartItem returns a CartItem

interface ShippingInformation

Properties

interface ShippingRate

Properties

interface Tax

Properties

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

interface CartResponse

Properties

interface ShippingInformationResponse

Properties

interface CartConfirmResponse

Properties

interface CartMutationResponse

Properties

  • result T

interface CartMutationResponseBase

Properties

interface CartMutationSummary

Properties

interface CustomerAuthenticationResponse

Properties

interface CustomerOrderItemResponse

Properties

interface CustomerOrderResponse

Properties

interface CustomerResponse

Properties

interface ErrorResponse

Properties

  • message string

  • reason – an optional string

  • content – an optional any

  • errors { [property: string]: string[]; }

interface PagedResponse

Properties

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

  1. lang – an optional string

Returns

createInitialCartState returns a CartState

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

Arguments

  1. cart CartResponse

  2. latestState – an optional CartState

Returns

mapCartResponseToCartState returns a CartState

interface BaseCustomerState

Properties

  • status Status

interface SignedInCustomerState

Properties

interface SignedOutCustomerState

Properties

  • register { errors?: ValidationError; }

  • signin { errors?: ValidationError; }

interface Loadable

Properties

interface LocalizationState

Properties

  • suggestedAddressesQueries

interface SuggestedAddressesQuery

Properties

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

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

enum SavingStatus : number

Members

  • Unset = 0
  • Saving = 1
  • Saved = 2

enum StackingOptions : string

Members

  • Always = "always"
  • Auto = "auto"
  • Never = "never"