FoxCommerce API reference

FoxApi

Utils

FoxApi namespaces

FoxApi

Javascript Library for interacting with FoxCommerce API

Usage example

const api = new FoxApi({api_url: 'http://api.foxcommerce', stripe_key: 'abcdef1234567890'});
api.products.search({state: 'cart'});

Options

Option Type Default Description
api_url String Required option. Should point to phoenix backend.
stripe_key String Required option. Should contain Stripe.js publishable key. https://stripe.com/docs/stripe.js#setting-publishable-key

Methods

Method Returns Description
addAuth(<String> jwt) FoxApi Set jwt authorization header for next requests
removeAuth() FoxApi Removes jwt authorization header
getCustomerId() Number|null Returns customer id from parsed jwt string You can define jwt string via addAuth method, if there is no jwt strings method returns null.
setHeaders(<Object> headers) FoxApi Set http headers for next requests
addHeaders(<Object> headers) FoxApi Add new http headers for next requests
uri(<String> uri) String Prepares and returns final url which will be used in request.
request(<String> method, <String> uri, <Object> data?, <Object> options?) Promise Makes http request, possible options:
  • headers: headers to sent
get(<String> uri, <Object> data?, <Object> options?) Promise Makes GET http request
post(<String> uri, <Object> data?, <Object> options?) Promise Makes POST http request
patch(<String> uri, <Object> data?, <Object> options?) Promise Makes PATCH http request
delete(<String> uri, <Object> data?, <Object> options?) Promise Makes DELETE http request

Properties

Property Type Description
addresses Addresses Addresses instance
auth Auth Auth instance
creditCards CreditCards CreditCards instance
storeCredits StoreCredits StoreCredits instance
cart Cart Cart instance
account Account Account instance
orders Orders Orders instance
reviews Reviews Reviews instance
analytics Analytics Analytics instance
crossSell CrossSell CrossSell instance

Region

Field Type Required Example Description
id Number
1 Unique identifier.
countryId Number
2794 Country unique identifier.
name String
Washington Region name.

ShippingState

Field Type Required Example Description
shippingState String
Cart Shipping state. Available values:

StoreAdminResponse

Field Type Required Example Description
id Number
1 Unique identifier.
name String
John Smith Admin name.
email String
john@smith.com E-mail.

CustomerBase

Field Type Required Example Description
id Number
1 Unique identifier.
name String John Smith Full name.
email String
john@smith.com E-mail.
phoneNumber String 123-444-4388 Phone number.
location String San Francisco, CA Location.
modality String Desktop[PC] Client.
createdAt String
2020-01-01T12:00:00Z Creation date.
disabled Boolean
false Defines whether account is disabled.
isGuest Boolean
false Defines whether account is guest.
isBlacklisted Boolean
false Defines whether account is added to blacklisted.

CustomerResponse

Field Type Required Example Description
billingRegion Region Billing region name.
shippingRegion Region Shipping region name.
rank Number 1 Customer ranking.
numOrders Number 1 Total number of orders.
totalSales Number 100 Customers sales stats.
Field Type Required Example Description
id Number
1 Unique identifier.
name String
John Smith Full name.
email String
john@smith.com E-mail.
phoneNumber String
123-444-4388 Phone number.
location String
San Francisco, CA Location.
modality String
Desktop[PC] Client.
createdAt String
2020-01-01T12:00:00Z Creation date.
disabled Boolean
false Defines whether account is disabled.
isGuest Boolean
false Defines whether account is guest.
isBlacklisted Boolean
false Defines whether account is added to blacklisted.

GiftCardOriginType

Field Type Required Example Description
originType String
csrAppeasement GC origin type. Available values:

GiftCardState

Field Type Required Example Description
state String
OnHold GC state. Available values:

GiftCardBase

Field Type Required Example Description
id Number
1 Unique identifier.
createdAt String
2020-01-01T12:00:00Z Creation date.
code String
ABC-123 Public unique identifier.
subTypeId Number 1 Optional subtype.
originalBalance Number
50 Opening balance for GC (amount it was issued for).
currentBalance Number
50 Opening balance minus "captured" debits.
availableBalance Number
50 Opening balance minus "auth" debits.
Field Type Required Example Description
originType String
csrAppeasement GC origin type. Available values:
Field Type Required Example Description
state String
OnHold GC state. Available values:

GiftCard

Field Type Required Example Description
customer CustomerResponse If customer have purchased GiftCard, returns his info.
storeAdmin StoreAdminResponse If CSR created GiftCard, return his info.
Field Type Required Example Description
id Number
1 Unique identifier.
createdAt String
2020-01-01T12:00:00Z Creation date.
code String
ABC-123 Public unique identifier.
subTypeId Number
1 Optional subtype.
originalBalance Number
50 Opening balance for GC (amount it was issued for).
currentBalance Number
50 Opening balance minus "captured" debits.
availableBalance Number
50 Opening balance minus "auth" debits.
Field Type Required Example Description
originType String
csrAppeasement GC origin type. Available values:
Field Type Required Example Description
state String
OnHold GC state. Available values:

Query options

Option Type Default Description
size Number Page size.
from Number Start element (counting from 0) or # of elements to skip.
sortBy String Field to sort by (-fieldName for descending order).

Utils

Methods

Method Returns Description
parseError(<ResponseOrError> err) Array<string> Retrieves errors from api-js rejected promise. In case if err is Error itself returns array of single element - that error as a string.

Account

Methods

Method Returns Description
get() Promise<LoginResponse>
update(<UpdateCustomerPayload> payload) Promise<LoginResponse> Updates account.
changePassword(<string> oldPassword, <string> newPassword) Promise Changes password for account.

Addresses

Accessible via addresses property of FoxApi instance.

Methods

Method Returns Description
list(<Query options> options) Promise<AddressesResponse> Choices for options.sortBy parameter:
one(<Number> addressId) Promise<Address>
add(<CreateAddressPayload> address) Promise<Address> Adds new address.
update(<Number> addressId, <UpdateAddressPayload> address) Promise<Address> Updates selected address.
setAsDefault(<Number> addressId) Promise<Address> Sets selected address as default.
removeDefault() Promise Removes default address.
delete(<Number> addressId) Promise Deletes address.

Address

Field Type Required Example Description
id Number
1 Unique identifier.
region Region
Region/state if the country.
name String
John Smith Recipient name.
address1 String
555 E Lake Union St. Address line 1.
address2 String Suite 200 Address line 2.
city String
Seattle City.
zip String
98124 zip/postal code.
phoneNumber String 732-757-2923 Contact phone number.
isDefault Boolean false Default or not in address book.

AddressesResponse

Field Type Required Example Description
results Array<Address>
Addresses list.

CreateAddressPayload

Field Type Required Example Description
name String
John Smith Recipient name.
regionId Number
Region unique ID.
address1 String
555 E Lake Union St. Address line 1.
address2 String Suite 200 Address line 2.
city String
Seattle City.
zip String
98124 zip/postal code.
isDefault Boolean false Default or not in address book.
phoneNumber String 555-555-555 Contact phone number.

UpdateAddressPayload

Field Type Required Example Description
name String John Smith Recipient name.
regionId Number Region unique ID.
address1 String 555 E Lake Union St. Address line 1.
address2 String Suite 200 Address line 2.
city String Seattle City.
zip String 98124 zip/postal code.
isDefault Boolean false Default or not in address book.
phoneNumber String 555-555-555 Contact phone number.

Analytics

Accessible via analytics property of FoxApi instance.

Methods

Method Returns Description
trackEvent(<Object<SphexTracker>> tracker, <Function> saltFunction?) Promise Enables the tracking of UI specific events. The optional salt function must be a random number generator.

SphexTracker

Field Type Required Example Description
channel Number
Unique Channel ID number
subject Number
Unique Subject ID number
obj String
Name of the object type you are tracking the event for
verb String
A single word that describes the event
objId Number
Unique number that can trace the object being tracked
count Number

Auth

Accessible via auth property of FoxApi instance.

Methods

Method Returns Description
signup(<String> email, <String> name, <String> password) Promise Register new user
login(<String> email, <String> password, <String> org) Promise<LoginResponse> Authenticate user by username and password. org is the name of the organization you want to log in under
googleSignin() Promise<GoogleSigninResponse>
logout() Promse Removes JWT cookie.
restorePassword(<String> email) Promise requests email instructions to reset password creates new password

LoginResponse

Field Type Required Example Description
jwt String
JWT token.
user.name String
User name.
user.email String
User email

GoogleSigninResponse

Field Type Required Example Description
url String
Url for redirection.

Cart

Accessible via cart property of FoxApi instance.

Methods

Method Returns Description
getShippingMethods() Promise<ShippingMethod[]> Returns available shipping methods.
chooseShippingMethod(<Number> shippingMethodId) Promise<FullOrder> Chooses shipping method for the cart.
removeShippingMethod() Promise Removes the shipping method from the cart.
setShippingAddress(<CreateAddressPayload> shippingAddress) Promise<FullOrder> Creates shipping address for the cart by a given address payload.
setShippingAddressById(<Number> shippingAddressId) Promise<FullOrder> Creates shipping address for the cart by a given address id.
updateShippingAddress(<UpdateAddressPayload> shippingAddress) Promise<FullOrder> Updates shipping address for the cart.
removeShippingAddress() Promise<void> Removes a shipping address from the cart.
get() Promise<FullOrder> Returns or creates new cart.
checkout() Promise<FullOrder> Place order from cart.
updateItems(<ItemsUpdatePayload> itemsUpdatePayload) Promise<FullOrder>
updateQty(<String> sku, <Number> quantity, <ItemAttributes> attributes?) Promise<FullOrder> Updates quantity and optionally attributes for selected item in the cart
addSku(<String> sku, <Number> quantity, <ItemAttributes> attributes?) Promise<FullOrder> Adds sku by defined quantity in the cart.
removeSku(<String> sku) Promise<FullOrder> Removes selected sku from the cart.
addCreditCard(<Number> creditCardId) Promise<FullOrder> Adds a credit card as payment method for the cart.
removeCreditCards() Promise<FullOrder> Removes all credit cards payment methods of the cart.
addGiftCard(<GiftCardPaymentPayload> giftCardPayload) Promise<FullOrder> Adds a gift card as payment method for the cart.
removeGiftCard(<string> giftCardCode) Promise<FullOrder> Removes gift card with provided code payment method from the cart.
addStoreCredit(<Number> amount) Promise<FullOrder> Adds store credit of specified amount to the cart.
removeStoreCredits() Promise<FullOrder> Removes all store credits payment methods of the cart.
addCoupon(<Number> code) Promise<FullOrder> Adds coupon code to the cart.
removeCoupon() Promise<FullOrder> Removes coupon code of the cart.

LineItemState

Field Type Required Example Description
state String
Cart Line item state. Available values:

OrderState

Field Type Required Example Description
orderState String
Cart Order State. Available values:

PaymentState

Field Type Required Example Description
paymentState String Cart Credit Card payment state. Available values:

FullOrder

Field Type Required Example Description
id Number
1 Unique identifier.
referenceNumber String
ABC-123 Order reference number.
lineItems LineItems
Line items with different types.
adjustments Array<Adjustment>
Order adjustments.
fraudScore Number
0 Fraud score.
customer CustomerResponse Associated customer.
totals OrderTotals
Order totals.
shippingMethod ShippingMethod Shipping method.
shippingAddress OrderShippingAddress Shipping address.
remorsePeriodEnd String 2020-01-01T12:00:00Z Remorse period end.
paymentMethods Array<DisplayPayment> Order payment.
warnings Array<String> List of validation errors and warnings Warnings.
Field Type Required Example Description
orderState String
Cart Order State. Available values:
Field Type Required Example Description
shippingState String
Cart Shipping state. Available values:
Field Type Required Example Description
paymentState String
Cart Credit Card payment state. Available values:

OrderShippingAddress

Field Type Required Example Description
id Number
1 Unique ID.
region Region
Associated region.
name String
Home Address record name.
address1 String
38 Baker Street Actual address.
address2 String 39 Baker Street Additional address line.
city String
Donkeyville City.
zip String
55555 Zip code.
isDefault Boolean
false Defines whether shipping address is default.

ShippingMethod

Field Type Required Example Description
id Number
1 Unique ID.
name String UPS Ground Display name in Admin panel.
price Number
10 Price of shipping.
isEnabled Boolean
true Defines whether shipping method is enabled in store.

DisplayPayment

Field Type Required Example Description
type String
Payment method type. Available values:

OrderTotals

Field Type Required Example Description
subTotal Number
100 Subtotal.
taxes Number
50 Taxes total.
shipping Number
5 Taxes total.
adjustments Number
50 Adjustments total.
total Number
100 Total.

LineItems

Field Type Required Example Description
skus Array<SkuLineItem>
SKU's as line items.
giftCard Array<GiftCard>
Gift cards as line items.

SkuLineItem

Field Type Required Example Description
imagePath String
http://lorempixel.com/75/75/fashion Image URL.
referenceNumber String
ABC-123 Unique line item UUID.
name String
donkey product Product name.
sku String
SKU-YAX SKU.
price Number
33 SKU price.
quantity Number
1 Quantity.
totalPrice Number
33 Price per item multiplied by quantity.
Field Type Required Example Description
state String
Cart Line item state. Available values:

Adjustment

Field Type Required Example Description
id Number
1 Unique identifier.
amount Number
10 Amount.
sourceId Number
1 Adjustment source ID.
sourceType String
order Adjustment source type.
reason String
Lorem ipsum Adjustment reason.

UpdateLineItemsPayload

Field Type Required Example Description
sku String
SKU-YAX SKU.
quantity Number
5 Quantity.

GiftCardPaymentPayload

Field Type Required Example Description
code String
ABC-123 Gift card code.
amount Number 10 Amount to pay.

ItemGiftCard

Field Type Required Example Description
senderName String
name of the person that is sending the giftcard
recipientName String
name of the person that is receiving the giftcard
recipientEmail String
recipient email address
message String optional message to deliver to the recipient

ItemAttributes

Field Type Required Example Description
giftcard ItemGiftCard giftcard to send attached to a lineItem

ItemUpdatePayload

Field Type Required Example Description
quantity Number
New quantity for sku
attributes ItemAttributes New attributes for sku

ItemsUpdatePayload

Key Value type Example Description
[sku] ItemUpdatePayload {'sku-bread': {quantity: 2}} Update payload for sku

CreditCards

Accessible via creditCards property of FoxApi instance.

Methods

Method Returns Description
list() Promise<CreditCardsResponse> Returns list of all credit cards.
one(<Number> creditCardId) Promise<CreditCard> Returns credit card by id.
create(<CreditCardCreatePayload> creditCard, <BillingAddressCreatePayload> billingAddress, <Boolean> addressIsNew) Promise<CreditCard> Adds new credit card.
update(<Number> creditCardId, <CreditCardUpdatePayload> creditCard) Promise<CreditCard> Updates selected credit card.
setAsDefault(<Number> creditCardId) Promise<CreditCard> Sets selected credit card as default.
delete(<Number> creditCardId) Promise Deletes selected credit card.
cardType(<String> number) String Detects credit card type
validateCardNumber(<String> number) Boolean Check if credit card'c number is valid
validateCVC(<String|Number> cvc) Boolean Check if credit card's cvc is valid
validateExpiry(<String|Number> month, <String|Number> year) Boolean Check if credit card's valid thru date is valid

CreditCard

Field Type Required Example Description
id Number
1 Unique identifier.
customerId Number
1 Customer ID.
holderName String
John Smith Cardholder name.
lastFour String
8752 Last four digits.
expMonth Number
4 Expiration month.
expYear Number
2020 Expiration year.
isDefault Boolean
false Defines whether credit card is default.
inWallet Boolean
false Defines whether credit card is in wallet.
brand String
Visa Brand name.
address Address
Billing address.

CreditCardCreatePayload

Field Type Required Example Description
token String
tok_absj22123mjssm stripe.js credit card token.
lastFour String
1234 Last four digits of card number.
expYear Number
2020 Expiration year.
expMonth Number
4 Expiration month.
brand String
Visa Credit card brand.
holderName String
John Smith Cardholder name.
billingAddress CreateAddressPayload
Billing address.
addressIsNew Boolean
false If the billing address was just created.

CreditCardUpdatePayload

Field Type Required Example Description
holderName String John Smith Cardholder name.
expMonth Number 4 Expiration month.
expYear Number 2020 Expiration year.
address CreateAddressPayload Billing address.
addressId Number Billing address ID.

CrossSell

Accessible via cross-sell property of FoxApi instance.

Methods

Method Returns Description
crossSellTrain(<PurchaseEventObject> purchaseEvent) Promise Sends a purchase event object to populate a sparse matrix for cross-sell analytics and related product tracking. The POST body is an object with a customer ID, channel ID, and a list of product ID's purchased by the customer. This method is intended for Admin use only.
crossSellRelated(<Number> productId, <Number> channelId) Promise Returns JSON of what products are similar to the productId in the query params. { "products": [ RelatedProduct ] } Score == 1 means these products were purchased by the exact same set of customers. Score == 0 means no customer has purchased both of these
crossSellRelatedFull(<Number> productId, <Number> channelId, <Number> size) Promise Returns JSON of what products are similar to the productId in the query params. { "products": [ RelatedProductFull ] } Score == 1 means these products were purchased by the exact same set of customers. Score == 0 means no customer has purchased both of these
crossSellCustomerRelated(<Number> customerId, <Number> channelId) Promise Returns JSON of what products are similar to the products purchased by the customer in the query params. { "products": [ RelatedProduct ] } Score == 1 means these products were purchased by the exact same set of customers. Score == 0 means no customer has purchased both of these
crossSellCustomerRelatedFull(<Number> customerId, <Number> channelId, <Number> size) Promise Returns JSON of what products are similar to the products purchased by the customer in the query params. { "products": [ RelatedProductFull ] } Score == 1 means these products were purchased by the exact same set of customers. Score == 0 means no customer has purchased both of these

PurchaseEventObject

Field Type Required Example Description
cust_id Number
CustomerID number
prod_ids Array<Number>
ProductID numbers
channel_id Number
Unique Channel ID number

Orders

Methods

Method Returns Description
list() Promise
get(<string> referenceNumber) Promise

Reviews

Accessible via reviews property of FoxApi instance.

Methods

Method Returns Description
add(<ReviewPayload> review) Promise<Review> Adds a new product review.
update(<Number> reviewId, <ReviewPayload> review) Promise<Review> Updates the selected product review.
delete(<Number> reviewId) Promise Deletes the selected product review.

StoreCredits

Accessible via storeCredits property of FoxApi instance.

Methods

Method Returns Description
list() Promise<StoreCreditsResponse> Returns list of all store credits.
one(<Number> storeCreditId) Promise<StoreCredit> Returns store credit by id.
totals() Promise<StoreCreditTotals>

StoreCreditOriginType

Field Type Required Example Description
originType String
CsrAppeasement SC origin type. Available values:

StoreCreditState

Field Type Required Example Description
state String
OnHold SC state. Available values:

StoreCredit

Field Type Required Example Description
id Number
1 Unique identifier.
createdAt String
2020-01-01T12:00:00Z Creation date.
currency String
USD SC currency.
subTypeId Number 1 Optional subtype.
originalBalance Number
50 Opening balance for SC (amount it was issued for).
currentBalance Number
50 Opening balance minus "captured" debits.
availableBalance Number
50 Opening balance minus "auth" debits.
Field Type Required Example Description
originType String
CsrAppeasement SC origin type. Available values:
Field Type Required Example Description
state String
OnHold SC state. Available values:

StoreCreditTotals

Field Type Required Example Description
currentBalance Number
50 Total current balance for customer.
availableBalance Number
50 Total available balance for customer.

StoreCreditsResponse

Field Type Required Example Description
result Array<StoreCredit>