API Reference

The FoxCommerce API is organized around REST and is organized around predictable, resource-oriented URLs. All API endpoints are stateless, respond with JSON, and indicate errors using HTTP status codes with standard error messages.

To make this API easy to explore, this document contains test credentials that will allow you access the public demo site at demo.foxcommerce.com.

API Libraries

Official libraries are available to aid in the development of storefront and administrative JavaScript applications. For storefront applications: see API.js. For administrative applications: see AdminAPI.js.

API Endpoint

https://demo.foxcommerce.com

Authentication

Authenticate your account using your organization, username, and password to create a JSON Web Token (JWT) that can be passed to the API as a header or cookie. The standard JWT will give you access to the whole system full privileges to modify whatever you want - so be sure to keep the token safe!

The token that is created during login or signup is signed using public/private key encryption, to prevent the token from being tampered with or modified by any entity other than the Fox Platform.

The token itself contains information about the requestor’s account, permissions, and expiration time. Additionally, all requests made through the API that modify data are recorded in the Activity Log and associated with the user identified by the JWT.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. Most endpoints will require the JWT to be included with the request, or else they will fail with a 401 error. A few, however, are public and will succeed, and some may return a JWT used to indicate a guest session.

Obtaining a Token

Request a token by logging into with your organization, email, and password.

Traditional API tokens are coming soon!

For now, keep using JWT made through the login endpoint. You’ll experience no loss in functionality, but will need to recreate the token daily (as it will expire).

Example Request

$ curl -i \
    -H "Content-Type: application/json" \
    -X POST -d '{"org":<org>,"email":<email>,"password":<password>}' \
    https://demo.foxcommerce.com/api/v1/public/login

Replace the values <org>, <email>, and <password> with your organization, email, and password, respectively.

User Permissions

In addition to identifying the user, the token is also responsible for communicating permissions information, specifically:

  • Scope - the ID of the organization that the user belongs to;

  • Role - whether the user is a customer or administrator;

  • Claims - specific, fine-grained permissions for specific resources.

Scope

Scope is a data primitive that is used for permissioning across the platform while acting as a representation of organizational structure inside the Fox Platform. It is a hierarchical structure for organizing users, and their data, in ways that give tremendous flexibility in providing access to members of an organization.

To illustrate this concept, consider the following example. In this example, we have three scopes: 1, 2, and 3. 1 is the parent of 2 and 3, and they form the following tree:

┌───────┐
│   1   │
│  / \  │
│ 2   3 │
└───────┘

Scopes are written in the token as a ‘.’ delimited string. So, in the token, the scopes would appear as:

  • 1 = 1

  • 2 = 1.2

  • 3 = 1.3

Because of the parent-child nature of the relationship, scope 1 has access to all data under 1, 1.2, and 1.3, while 1.2, 1.3 only have access to their own data.

Role

Role describes a collection of permissions assigned to a user. There are currently two roles that a user may have:

  • admin

  • customer

Claim

Claims are fine-grained permissions on specific resources in the system. A claim is a combination of three pieces:

  • Fox Resource Name (FRN): A string that identifies a resource type, such as a product or order;

    • frn:pim:sku = FRN for a SKU
    • frn:oms:order = FRN for an order
  • Scope: A ‘.’ delimited scope, as shown above;

  • Actions: An array of strings, signifying the basic actions.

    • c = create
    • r = read
    • u = update
    • d = delete

A claim is written as: "<FRN>:<Scope>": [<actions>]

{
  "aud": "user",
  "id": 1,
  "email": "admin@admin.com",
  "ratchet": 0,
  "scope": "1",
  "roles": ["admin"],
  "name": "Frankly Admin",
  "claims": {
    "frn:usr:org:1": ["c", "r", "u", "d"],
    "frn:pim:sku:1": ["c", "r", "u", "d"],
    "frn:oms:cart:1": ["c", "r", "u", "d"],
    "frn:usr:user:1": ["c", "r", "u", "d"],
    "frn:oms:order:1": ["c", "r", "u", "d"],
    "frn:pim:album:1": ["c", "r", "u", "d"],
    "frn:pim:coupon:1": ["c", "r", "u", "d"],
    "frn:pim:product:1": ["c", "r", "u", "d"]
  },
  "exp": 1525895101,
  "iss": "FC"
}

Errors

The Fox Platform uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.), and codes in the 5xx range indicate an error with Fox’s platform.

Error Object

Field Description
errors An array of strings that provide information about the error that occurred

HTTP Status Code Summary

Code Meaning
200 - OK Everything worked as expected
201 - Created Entity was successfully created
400 - Bad Request The request was unacceptable, often due to missing required parameters
401 - Unauthorized JWT was missing or user didn’t have permission to perform API request
404 - Not Found The requested resource doesn’t exist
500 - Server Error Something with wrong with the Fox Platform

Authentication

Login

POST https://developer.foxcommerce.com/v1/public/login
Example Request
{
  "email": "example@example.com",
  "password": "password",
  "kind": "admin"
}
Example Response
{
  "id": 1,
  "email": "example@example.com",
  "scopes": [
    "admin"
  ],
  "exp": 1466079553,
  "admin": true
}

Login
POST/v1/public/login

Request Definition
attributes
email
string, optional
E-mail.
password
string, optional
Password.
kind
string, optional
Authorize either is admin or customer.
Response Definition
Status Code 200
attributes
id
number, optional
User ID.
email
string, optional
E-mail.
scopes
array, optional
User scopes.
exp
number, optional
Session expiration timestamp.
admin
boolean, optional
Whether user is an admin or not.

Logout

POST https://developer.foxcommerce.com/v1/public/logout
Example Request
Example Response

Logout
POST/v1/public/logout

Request Definition
Response Definition
Status Code 200

Registration

POST https://developer.foxcommerce.com/v1/public/registrations/new
Example Request
{
  "email": "user@example.org",
  "name": "John Smith",
  "password": "password",
  "isGuest": false
}
Example Response
{
  "id": 1,
  "name": "John Smith",
  "email": "john@smith.com",
  "isGuest": false,
  "disabled": false,
  "isBlacklisted": false,
  "createdAt": "2020-01-01T12:00:00Z",
  "groups": [
    {
      "id": 1,
      "name": "Super Awesome Group",
      "type": "dynamic"
    }
  ],
  "storeCreditTotals": {
    "currentBalance": 50,
    "availableBalance": 50
  },
  "totalSales": 100
}

Registration
POST/v1/public/registrations/new

Request Definition
attributes
email
string, optional
Customer email.
name
string, optional
Customer full name.
password
string, optional
Customer password.
isGuest
boolean, optional
create customer as guest if true.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
name
string, optional
The customer's full name.
email
string, optional
The customer's email - by default, this is a unique identifier for all non-guest customers.
isGuest
boolean, optional
Defines whether account is guest - these accounts do not contain account credentials and are therefore unable to login to the site.
disabled
boolean, optional
Defines whether account is disabled - if this is set, the customer will be unable to login.
isBlacklisted
boolean, optional
Defines whether account is added to blacklisted - blacklisted accounts are used for fraud and will allow customers to login but not purchase.
createdAt
string, optional
The date when the customer was created.
groups
array, optional
The list of groups that the customer is a part of - groups are used to manually or programatically cluster customers.
storeCreditTotals
object
Summary information about the store credit balance that the user possesses.
totalSales
number, optional
The amount of money, in cents, that the customer has spent on the site.

Customer Management

The Fox Platform provides a deep set of capabilities for managing, understanding, and engaging with your customers. This section contains the resources needed to understand and manage customer account, view their current cart, previous orders, purchased items, and group together for easy and powerful analytics.

Customer

This object is the base customer entity.

attributes
id
number, optional
Unique identifier.
name
string, optional
The customer's full name.
email
string, optional
The customer's email - by default, this is a unique identifier for all non-guest customers.
isGuest
boolean, optional
Defines whether account is guest - these accounts do not contain account credentials and are therefore unable to login to the site.
disabled
boolean, optional
Defines whether account is disabled - if this is set, the customer will be unable to login.
isBlacklisted
boolean, optional
Defines whether account is added to blacklisted - blacklisted accounts are used for fraud and will allow customers to login but not purchase.
createdAt
string, optional
The date when the customer was created.
groups
array, optional
The list of groups that the customer is a part of - groups are used to manually or programatically cluster customers.
storeCreditTotals
object
Summary information about the store credit balance that the user possesses.
totalSales
number, optional
The amount of money, in cents, that the customer has spent on the site.
GET https://developer.foxcommerce.com/v1/customers/1
Example Response
{
  "id": 1,
  "name": "John Smith",
  "email": "john@smith.com",
  "isGuest": false,
  "disabled": false,
  "isBlacklisted": false,
  "createdAt": "2020-01-01T12:00:00Z",
  "groups": [
    {
      "id": 1,
      "name": "Super Awesome Group",
      "type": "dynamic"
    }
  ],
  "storeCreditTotals": {
    "currentBalance": 50,
    "availableBalance": 50
  },
  "totalSales": 100
}

Retrieve Customer
GET/v1/customers/{id}

Allows an administrator to retrieve a customer record, which includes basic information about the customer profile, location, and transaction summary.

URI Parameters
HideShow
id
number (required) Example: 1

Customer ID.

Response Definition
attributes
id
number, optional
Unique identifier.
name
string, optional
The customer's full name.
email
string, optional
The customer's email - by default, this is a unique identifier for all non-guest customers.
isGuest
boolean, optional
Defines whether account is guest - these accounts do not contain account credentials and are therefore unable to login to the site.
disabled
boolean, optional
Defines whether account is disabled - if this is set, the customer will be unable to login.
isBlacklisted
boolean, optional
Defines whether account is added to blacklisted - blacklisted accounts are used for fraud and will allow customers to login but not purchase.
createdAt
string, optional
The date when the customer was created.
groups
array, optional
The list of groups that the customer is a part of - groups are used to manually or programatically cluster customers.
storeCreditTotals
object
Summary information about the store credit balance that the user possesses.
totalSales
number, optional
The amount of money, in cents, that the customer has spent on the site.

POST https://developer.foxcommerce.com/v1/customers
Example Request
{
  "email": "user@example.org",
  "name": "John Smith",
  "password": "password",
  "isGuest": false
}
Example Response
{
  "id": 1,
  "name": "John Smith",
  "email": "john@smith.com",
  "isGuest": false,
  "disabled": false,
  "isBlacklisted": false,
  "createdAt": "2020-01-01T12:00:00Z",
  "groups": [
    {
      "id": 1,
      "name": "Super Awesome Group",
      "type": "dynamic"
    }
  ],
  "storeCreditTotals": {
    "currentBalance": 50,
    "availableBalance": 50
  },
  "totalSales": 100
}

Create New Customer
POST/v1/customers

Allows an administrator to create a new customer record. The new customer may either be a guest or full customer and the creator is given the option of whether to supply a password.

New full customers must have a unique email address within their own scope.

Request Definition
attributes
email
string, optional
Customer email.
name
string, optional
Customer full name.
password
string, optional
Customer password.
isGuest
boolean, optional
create customer as guest if true.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
name
string, optional
The customer's full name.
email
string, optional
The customer's email - by default, this is a unique identifier for all non-guest customers.
isGuest
boolean, optional
Defines whether account is guest - these accounts do not contain account credentials and are therefore unable to login to the site.
disabled
boolean, optional
Defines whether account is disabled - if this is set, the customer will be unable to login.
isBlacklisted
boolean, optional
Defines whether account is added to blacklisted - blacklisted accounts are used for fraud and will allow customers to login but not purchase.
createdAt
string, optional
The date when the customer was created.
groups
array, optional
The list of groups that the customer is a part of - groups are used to manually or programatically cluster customers.
storeCreditTotals
object
Summary information about the store credit balance that the user possesses.
totalSales
number, optional
The amount of money, in cents, that the customer has spent on the site.

PATCH https://developer.foxcommerce.com/v1/customers/1
Example Request
{
  "email": "new@example.org",
  "name": "Jane Smith",
  "phoneNumber": "555 55 55"
}
Example Response
{
  "id": 1,
  "name": "John Smith",
  "email": "john@smith.com",
  "isGuest": false,
  "disabled": false,
  "isBlacklisted": false,
  "createdAt": "2020-01-01T12:00:00Z",
  "groups": [
    {
      "id": 1,
      "name": "Super Awesome Group",
      "type": "dynamic"
    }
  ],
  "storeCreditTotals": {
    "currentBalance": 50,
    "availableBalance": 50
  },
  "totalSales": 100
}

Update Existing Customer
PATCH/v1/customers/{id}

URI Parameters
HideShow
id
number (required) Example: 1

Customer ID.

Request Definition
attributes
email
string, optional
Customer email.
name
string, optional
Customer full name.
phoneNumber
string, optional
Phone number.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
name
string, optional
The customer's full name.
email
string, optional
The customer's email - by default, this is a unique identifier for all non-guest customers.
isGuest
boolean, optional
Defines whether account is guest - these accounts do not contain account credentials and are therefore unable to login to the site.
disabled
boolean, optional
Defines whether account is disabled - if this is set, the customer will be unable to login.
isBlacklisted
boolean, optional
Defines whether account is added to blacklisted - blacklisted accounts are used for fraud and will allow customers to login but not purchase.
createdAt
string, optional
The date when the customer was created.
groups
array, optional
The list of groups that the customer is a part of - groups are used to manually or programatically cluster customers.
storeCreditTotals
object
Summary information about the store credit balance that the user possesses.
totalSales
number, optional
The amount of money, in cents, that the customer has spent on the site.

GET https://developer.foxcommerce.com/v1/customers/cart
Example Response
{
  "id": 1,
  "referenceNumber": "ABC-123",
  "orderState": "Cart",
  "shippingState": "Cart",
  "paymentState": "Cart",
  "lineItems": {
    "skus": [
      {
        "imagePath": "http://lorempixel.com/75/75/fashion",
        "referenceNumber": "ABC-123",
        "name": "donkey product",
        "sku": "SKU-YAX",
        "price": 33,
        "quantity": 1,
        "state": "Cart",
        "totalPrice": 33
      }
    ],
    "giftCard": [
      {
        "id": 1,
        "createdAt": "2020-01-01T12:00:00Z",
        "code": "ABC-123",
        "originType": "csrAppeasement",
        "subTypeId": 1,
        "state": "onHold",
        "originalBalance": 50,
        "currentBalance": 50,
        "availableBalance": 50,
        "message": "Lorem ipsum",
        "customer": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com",
          "isGuest": false,
          "disabled": false,
          "isBlacklisted": false,
          "createdAt": "2020-01-01T12:00:00Z",
          "groups": [
            {
              "id": 1,
              "name": "Super Awesome Group",
              "type": "dynamic"
            }
          ],
          "storeCreditTotals": {
            "currentBalance": 50,
            "availableBalance": 50
          },
          "totalSales": 100
        },
        "storeAdmin": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com"
        }
      }
    ]
  },
  "adjustments": [
    {
      "id": 1,
      "amount": 10,
      "sourceId": 1,
      "sourceType": "order",
      "reason": "Lorem ipsum"
    }
  ],
  "fraudScore": 0,
  "customer": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com",
    "isGuest": false,
    "disabled": false,
    "isBlacklisted": false,
    "createdAt": "2020-01-01T12:00:00Z",
    "groups": [
      {
        "id": 1,
        "name": "Super Awesome Group",
        "type": "dynamic"
      }
    ],
    "storeCreditTotals": {
      "currentBalance": 50,
      "availableBalance": 50
    },
    "totalSales": 100
  },
  "totals": {
    "subTotal": 100,
    "taxes": 50,
    "shipping": 5,
    "adjustments": 50,
    "total": 100
  },
  "shippingMethod": {
    "id": 1,
    "name": "UPS Ground",
    "price": 10,
    "isEnabled": true
  },
  "shippingAddress": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555",
    "isDefault": false
  },
  "remorsePeriodEnd": "2020-01-01T12:00:00Z",
  "paymentMethods": [
    {
      "type": "CreditCard"
    }
  ],
  "warnings": [
    "List of validation errors and warnings"
  ]
}

View Cart
GET/v1/customers/cart

Response Definition
attributes
id
number, optional
Unique identifier.
referenceNumber
string, optional
Order reference number.
orderState
string, optional
Order State.
shippingState
string, optional
Shipping state.
paymentState
string, optional
Credit Card payment state.
lineItems
object
Line items with different types.
adjustments
array, optional
Order adjustments.
fraudScore
number, optional
Fraud score.
customer
object
Associated customer.
totals
object
Order totals.
shippingMethod
object
Shipping method.
shippingAddress
object
Shipping address.
remorsePeriodEnd
string, optional
Remorse period end.
paymentMethods
array, optional
Order payment.
warnings
array, optional
Warnings.

POST https://developer.foxcommerce.com/v1/customers/1/disable
Example Request
{
  "disabled": false
}
Example Response
{
  "id": 1,
  "name": "John Smith",
  "email": "john@smith.com",
  "isGuest": false,
  "disabled": false,
  "isBlacklisted": false,
  "createdAt": "2020-01-01T12:00:00Z",
  "groups": [
    {
      "id": 1,
      "name": "Super Awesome Group",
      "type": "dynamic"
    }
  ],
  "storeCreditTotals": {
    "currentBalance": 50,
    "availableBalance": 50
  },
  "totalSales": 100
}

Enable / Disable
POST/v1/customers/{id}/disable

URI Parameters
HideShow
id
number (required) Example: 1
Request Definition
attributes
disabled
boolean, optional
Defines whether account is disabled.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
name
string, optional
The customer's full name.
email
string, optional
The customer's email - by default, this is a unique identifier for all non-guest customers.
isGuest
boolean, optional
Defines whether account is guest - these accounts do not contain account credentials and are therefore unable to login to the site.
disabled
boolean, optional
Defines whether account is disabled - if this is set, the customer will be unable to login.
isBlacklisted
boolean, optional
Defines whether account is added to blacklisted - blacklisted accounts are used for fraud and will allow customers to login but not purchase.
createdAt
string, optional
The date when the customer was created.
groups
array, optional
The list of groups that the customer is a part of - groups are used to manually or programatically cluster customers.
storeCreditTotals
object
Summary information about the store credit balance that the user possesses.
totalSales
number, optional
The amount of money, in cents, that the customer has spent on the site.

POST https://developer.foxcommerce.com/v1/customers/1/blacklist
Example Request
{
  "blacklisted": true
}
Example Response
{
  "id": 1,
  "name": "John Smith",
  "email": "john@smith.com",
  "isGuest": false,
  "disabled": false,
  "isBlacklisted": false,
  "createdAt": "2020-01-01T12:00:00Z",
  "groups": [
    {
      "id": 1,
      "name": "Super Awesome Group",
      "type": "dynamic"
    }
  ],
  "storeCreditTotals": {
    "currentBalance": 50,
    "availableBalance": 50
  },
  "totalSales": 100
}

Add To / Remove From Blacklist
POST/v1/customers/{id}/blacklist

URI Parameters
HideShow
id
number (required) Example: 1
Request Definition
attributes
blacklisted
boolean, optional
Defines whether account is added to blacklisted.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
name
string, optional
The customer's full name.
email
string, optional
The customer's email - by default, this is a unique identifier for all non-guest customers.
isGuest
boolean, optional
Defines whether account is guest - these accounts do not contain account credentials and are therefore unable to login to the site.
disabled
boolean, optional
Defines whether account is disabled - if this is set, the customer will be unable to login.
isBlacklisted
boolean, optional
Defines whether account is added to blacklisted - blacklisted accounts are used for fraud and will allow customers to login but not purchase.
createdAt
string, optional
The date when the customer was created.
groups
array, optional
The list of groups that the customer is a part of - groups are used to manually or programatically cluster customers.
storeCreditTotals
object
Summary information about the store credit balance that the user possesses.
totalSales
number, optional
The amount of money, in cents, that the customer has spent on the site.

POST https://developer.foxcommerce.com/v1/customers/1/activate
Example Request
{
  "name": "John Smith"
}
Example Response
{
  "id": 1,
  "name": "John Smith",
  "email": "john@smith.com",
  "isGuest": false,
  "disabled": false,
  "isBlacklisted": false,
  "createdAt": "2020-01-01T12:00:00Z",
  "groups": [
    {
      "id": 1,
      "name": "Super Awesome Group",
      "type": "dynamic"
    }
  ],
  "storeCreditTotals": {
    "currentBalance": 50,
    "availableBalance": 50
  },
  "totalSales": 100
}

Activate Guest
POST/v1/customers/{id}/activate

URI Parameters
HideShow
id
number (required) Example: 1
Request Definition
attributes
name
string, optional
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
name
string, optional
The customer's full name.
email
string, optional
The customer's email - by default, this is a unique identifier for all non-guest customers.
isGuest
boolean, optional
Defines whether account is guest - these accounts do not contain account credentials and are therefore unable to login to the site.
disabled
boolean, optional
Defines whether account is disabled - if this is set, the customer will be unable to login.
isBlacklisted
boolean, optional
Defines whether account is added to blacklisted - blacklisted accounts are used for fraud and will allow customers to login but not purchase.
createdAt
string, optional
The date when the customer was created.
groups
array, optional
The list of groups that the customer is a part of - groups are used to manually or programatically cluster customers.
storeCreditTotals
object
Summary information about the store credit balance that the user possesses.
totalSales
number, optional
The amount of money, in cents, that the customer has spent on the site.

Address

GET https://developer.foxcommerce.com/v1/customers/1/addresses/1
Example Response
{
  "id": 1,
  "region": {
    "id": 1,
    "countryId": 2794,
    "name": "Washington"
  },
  "name": "John Smith",
  "address1": "555 E Lake Union St.",
  "address2": "Suite 200",
  "city": "Seattle",
  "zip": "98124",
  "phoneNumber": "732-757-2923",
  "isDefault": false
}

View
GET/v1/customers/{customerId}/addresses/{addressId}

URI Parameters
HideShow
customerId
number (required) Example: 1

Customer ID.

addressId
number (required) Example: 1

Address ID.

Response Definition
attributes
id
number, optional
Unique identifier.
region
object
Region/state if the country.
name
string, optional
Recipient name.
address1
string, optional
Address line 1.
address2
string, optional
Address line 2.
city
string, optional
City.
zip
string, optional
zip/postal code.
phoneNumber
string, optional
Contact phone number.
isDefault
boolean, optional
Default or not in address book.

POST https://developer.foxcommerce.com/v1/customers/1/addresses
Example Request
{
  "name": "John Smith",
  "regionId": 1,
  "address1": "555 E Lake Union St.",
  "address2": "Suite 200",
  "city": "Seattle",
  "zip": "98124",
  "isDefault": false,
  "phoneNumber": "555-555-555"
}
Example Response
{
  "id": 1,
  "region": {
    "id": 1,
    "countryId": 2794,
    "name": "Washington"
  },
  "name": "John Smith",
  "address1": "555 E Lake Union St.",
  "address2": "Suite 200",
  "city": "Seattle",
  "zip": "98124",
  "phoneNumber": "732-757-2923",
  "isDefault": false
}

Create
POST/v1/customers/{customerId}/addresses

URI Parameters
HideShow
customerId
number (required) Example: 1

Customer ID.

Request Definition
attributes
name
string, optional
Recipient name.
regionId
number, optional
Region unique ID.
address1
string, optional
Address line 1.
address2
string, optional
Address line 2.
city
string, optional
City.
zip
string, optional
zip/postal code.
isDefault
boolean, optional
Default or not in address book.
phoneNumber
string, optional
Contact phone number.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
region
object
Region/state if the country.
name
string, optional
Recipient name.
address1
string, optional
Address line 1.
address2
string, optional
Address line 2.
city
string, optional
City.
zip
string, optional
zip/postal code.
phoneNumber
string, optional
Contact phone number.
isDefault
boolean, optional
Default or not in address book.

PATCH https://developer.foxcommerce.com/v1/customers/1/addresses/1
Example Request
{
  "name": "John Smith",
  "regionId": 1,
  "address1": "555 E Lake Union St.",
  "address2": "Suite 200",
  "city": "Seattle",
  "zip": "98124",
  "isDefault": false,
  "phoneNumber": "555-555-555"
}
Example Response
{
  "id": 1,
  "region": {
    "id": 1,
    "countryId": 2794,
    "name": "Washington"
  },
  "name": "John Smith",
  "address1": "555 E Lake Union St.",
  "address2": "Suite 200",
  "city": "Seattle",
  "zip": "98124",
  "phoneNumber": "732-757-2923",
  "isDefault": false
}

Update
PATCH/v1/customers/{customerId}/addresses/{addressId}

URI Parameters
HideShow
customerId
number (required) Example: 1

Customer ID.

addressId
number (required) Example: 1

Address ID.

Request Definition
attributes
name
string, optional
Recipient name.
regionId
number, optional
Region unique ID.
address1
string, optional
Address line 1.
address2
string, optional
Address line 2.
city
string, optional
City.
zip
string, optional
zip/postal code.
isDefault
boolean, optional
Default or not in address book.
phoneNumber
string, optional
Contact phone number.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
region
object
Region/state if the country.
name
string, optional
Recipient name.
address1
string, optional
Address line 1.
address2
string, optional
Address line 2.
city
string, optional
City.
zip
string, optional
zip/postal code.
phoneNumber
string, optional
Contact phone number.
isDefault
boolean, optional
Default or not in address book.

POST https://developer.foxcommerce.com/v1/customers/1/addresses/1/default
Example Response
{
  "id": 1,
  "region": {
    "id": 1,
    "countryId": 2794,
    "name": "Washington"
  },
  "name": "John Smith",
  "address1": "555 E Lake Union St.",
  "address2": "Suite 200",
  "city": "Seattle",
  "zip": "98124",
  "phoneNumber": "732-757-2923",
  "isDefault": false
}

Set as Default
POST/v1/customers/{customerId}/addresses/{addressId}/default

URI Parameters
HideShow
customerId
number (required) Example: 1

Customer ID.

addressId
number (required) Example: 1

Address ID.

Response Definition
attributes
id
number, optional
Unique identifier.
region
object
Region/state if the country.
name
string, optional
Recipient name.
address1
string, optional
Address line 1.
address2
string, optional
Address line 2.
city
string, optional
City.
zip
string, optional
zip/postal code.
phoneNumber
string, optional
Contact phone number.
isDefault
boolean, optional
Default or not in address book.

DELETE https://developer.foxcommerce.com/v1/customers/1/addresses/default
Example Response

Remove Default Address
DELETE/v1/customers/{customerId}/addresses/default

This endpoint removes isDefault flag from any existing customer address.

URI Parameters
HideShow
customerId
number (required) Example: 1

Customer ID.

Response Definition

DELETE https://developer.foxcommerce.com/v1/customers/1/addresses/1
Example Response

Delete
DELETE/v1/customers/{customerId}/addresses/{addressId}

URI Parameters
HideShow
customerId
number (required) Example: 1

Customer ID.

addressId
number (required) Example: 1

Address ID.

Response Definition

Credit Card

GET https://developer.foxcommerce.com/v1/customers/1/payment-methods/credit-cards
Example Response
{
  "result": [
    {
      "id": 1,
      "customerId": 1,
      "holderName": "John Smith",
      "lastFour": "8752",
      "expMonth": 4,
      "expYear": 2020,
      "isDefault": false,
      "inWallet": false,
      "brand": "Visa",
      "address": {
        "id": 1,
        "region": {
          "id": 1,
          "countryId": 2794,
          "name": "Washington"
        },
        "name": "John Smith",
        "address1": "555 E Lake Union St.",
        "address2": "Suite 200",
        "city": "Seattle",
        "zip": "98124",
        "phoneNumber": "732-757-2923",
        "isDefault": false
      }
    }
  ]
}

List
GET/v1/customers/{customerId}/payment-methods/credit-cards

URI Parameters
HideShow
customerId
number (required) Example: 1

Customer unique ID.

Response Definition
attributes
result
array, optional

POST https://developer.foxcommerce.com/v1/customers/1/payment-methods/credit-cards
Example Request
{
  "token": "tok_absj22123mjssm",
  "lastFour": "1234",
  "expYear": 2020,
  "expMonth": 4,
  "brand": "Visa",
  "holderName": "John Smith",
  "billingAddress": {
    "name": "John Smith",
    "regionId": 1,
    "address1": "555 E Lake Union St.",
    "address2": "Suite 200",
    "city": "Seattle",
    "zip": "98124",
    "isDefault": false,
    "phoneNumber": "555-555-555"
  },
  "addressIsNew": false
}
Example Response
{
  "id": 1,
  "customerId": 1,
  "holderName": "John Smith",
  "lastFour": "8752",
  "expMonth": 4,
  "expYear": 2020,
  "isDefault": false,
  "inWallet": false,
  "brand": "Visa",
  "address": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "John Smith",
    "address1": "555 E Lake Union St.",
    "address2": "Suite 200",
    "city": "Seattle",
    "zip": "98124",
    "phoneNumber": "732-757-2923",
    "isDefault": false
  }
}

Create
POST/v1/customers/{customerId}/payment-methods/credit-cards

URI Parameters
HideShow
customerId
number (required) Example: 1

Customer ID.

Request Definition
attributes
token
string, optional
stripe.js credit card token.
lastFour
string, optional
Last four digits of card number.
expYear
number, optional
Expiration year.
expMonth
number, optional
Expiration month.
brand
string, optional
Credit card brand.
holderName
string, optional
Cardholder name.
billingAddress
object
Billing address.
addressIsNew
boolean, optional
If the billing address was just created.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
customerId
number, optional
Customer ID.
holderName
string, optional
Cardholder name.
lastFour
string, optional
Last four digits.
expMonth
number, optional
Expiration month.
expYear
number, optional
Expiration year.
isDefault
boolean, optional
Defines whether credit card is default.
inWallet
boolean, optional
Defines whether credit card is in wallet.
brand
string, optional
Brand name.
address
object
Billing address.

PATCH https://developer.foxcommerce.com/v1/customers/1/payment-methods/credit-cards/1
Example Request
{
  "holderName": "John Smith",
  "expMonth": 4,
  "expYear": 2020,
  "address": {
    "name": "John Smith",
    "regionId": 1,
    "address1": "555 E Lake Union St.",
    "address2": "Suite 200",
    "city": "Seattle",
    "zip": "98124",
    "isDefault": false,
    "phoneNumber": "555-555-555"
  },
  "addressId": 1
}
Example Response
{
  "id": 1,
  "customerId": 1,
  "holderName": "John Smith",
  "lastFour": "8752",
  "expMonth": 4,
  "expYear": 2020,
  "isDefault": false,
  "inWallet": false,
  "brand": "Visa",
  "address": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "John Smith",
    "address1": "555 E Lake Union St.",
    "address2": "Suite 200",
    "city": "Seattle",
    "zip": "98124",
    "phoneNumber": "732-757-2923",
    "isDefault": false
  }
}

Update
PATCH/v1/customers/{customerId}/payment-methods/credit-cards/{creditCardId}

URI Parameters
HideShow
customerId
number (required) Example: 1

Customer ID.

creditCardId
number (required) Example: 1

Credit card ID.

Request Definition
attributes
holderName
string, optional
Cardholder name.
expMonth
number, optional
Expiration month.
expYear
number, optional
Expiration year.
address
object
Billing address.
addressId
number, optional
Billing address ID.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
customerId
number, optional
Customer ID.
holderName
string, optional
Cardholder name.
lastFour
string, optional
Last four digits.
expMonth
number, optional
Expiration month.
expYear
number, optional
Expiration year.
isDefault
boolean, optional
Defines whether credit card is default.
inWallet
boolean, optional
Defines whether credit card is in wallet.
brand
string, optional
Brand name.
address
object
Billing address.

POST https://developer.foxcommerce.com/v1/customers/1/payment-methods/credit-cards/1/default
Example Request
{
  "isDefault": false
}
Example Response
{
  "id": 1,
  "customerId": 1,
  "holderName": "John Smith",
  "lastFour": "8752",
  "expMonth": 4,
  "expYear": 2020,
  "isDefault": false,
  "inWallet": false,
  "brand": "Visa",
  "address": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "John Smith",
    "address1": "555 E Lake Union St.",
    "address2": "Suite 200",
    "city": "Seattle",
    "zip": "98124",
    "phoneNumber": "732-757-2923",
    "isDefault": false
  }
}

Set as Default
POST/v1/customers/{customerId}/payment-methods/credit-cards/{creditCardId}/default

URI Parameters
HideShow
customerId
number (required) Example: 1

Customer ID.

creditCardId
number (required) Example: 1

Credit card ID.

Request Definition
attributes
isDefault
boolean, optional
Defines whether credit card is default.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
customerId
number, optional
Customer ID.
holderName
string, optional
Cardholder name.
lastFour
string, optional
Last four digits.
expMonth
number, optional
Expiration month.
expYear
number, optional
Expiration year.
isDefault
boolean, optional
Defines whether credit card is default.
inWallet
boolean, optional
Defines whether credit card is in wallet.
brand
string, optional
Brand name.
address
object
Billing address.

DELETE https://developer.foxcommerce.com/v1/customers/1/payment-methods/credit-cards/1
Example Response

Delete
DELETE/v1/customers/{customerId}/payment-methods/credit-cards/{creditCardId}

URI Parameters
HideShow
customerId
number (required) Example: 1

Customer ID.

creditCardId
number (required) Example: 1

Credit card ID.

Response Definition

Store Credit

POST https://developer.foxcommerce.com/v1/customer/payment-methods/store-credits
Example Request
{
  "amount": 10,
  "reasonId": 1,
  "subReasonId": 1,
  "currency": "USD"
}
Example Response
{
  "id": 1,
  "createdAt": "2020-01-01T12:00:00Z",
  "currency": "USD",
  "originType": "csrAppeasement",
  "subTypeId": 1,
  "state": "onHold",
  "originalBalance": 50,
  "currentBalance": 50,
  "availableBalance": 50,
  "canceledReason": "Lorem ipsum"
}

Create
POST/v1/customer/payment-methods/store-credits

Request Definition
attributes
amount
number, optional
Store credit amount.
reasonId
number, optional
Reason of creation.
subReasonId
number, optional
Subreason.
currency
string, optional
Store credit currency.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
createdAt
string, optional
Creation date.
currency
string, optional
SC currency.
originType
string, optional
SC origin type.
subTypeId
number, optional
Optional subtype.
state
string, optional
SC state.
originalBalance
number, optional
Opening balance for SC (amount it was issued for).
currentBalance
number, optional
Opening balance minus "captured" debits.
availableBalance
number, optional
Opening balance minus "auth" debits.
canceledReason
string, optional
Cancellation reason (present if SC canceled).

GET https://developer.foxcommerce.com/v1/customers/1/payment-methods/store-credit/totals
Example Response
{
  "currentBalance": 50,
  "availableBalance": 50
}

Total
GET/v1/customers/{customerId}/payment-methods/store-credit/totals

URI Parameters
HideShow
customerId
number (required) Example: 1

Unique Customer ID.

Response Definition
attributes
currentBalance
number, optional
Total current balance for customer.
availableBalance
number, optional
Total available balance for customer.

POST https://developer.foxcommerce.com/v1/customer/1/payment-methods/store-credits/1/convert
Example Response
{
  "id": 1,
  "createdAt": "2020-01-01T12:00:00Z",
  "code": "ABC-123",
  "originType": "csrAppeasement",
  "subTypeId": 1,
  "state": "onHold",
  "originalBalance": 50,
  "currentBalance": 50,
  "availableBalance": 50,
  "message": "Lorem ipsum",
  "customer": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com",
    "isGuest": false,
    "disabled": false,
    "isBlacklisted": false,
    "createdAt": "2020-01-01T12:00:00Z",
    "groups": [
      {
        "id": 1,
        "name": "Super Awesome Group",
        "type": "dynamic"
      }
    ],
    "storeCreditTotals": {
      "currentBalance": 50,
      "availableBalance": 50
    },
    "totalSales": 100
  },
  "storeAdmin": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com"
  }
}

Convert To Gift Card
POST/v1/customer/{customerId}/payment-methods/store-credits/{storeCreditId}/convert

URI Parameters
HideShow
customerId
number (required) Example: 1

Customer ID.

storeCreditId
number (required) Example: 1

Store Credit ID.

Response Definition
attributes
id
number, optional
Unique identifier.
createdAt
string, optional
Creation date.
code
string, optional
Public unique identifier.
originType
string, optional
GC origin type.
subTypeId
number, optional
Optional subtype.
state
string, optional
GC state.
originalBalance
number, optional
Opening balance for GC (amount it was issued for).
currentBalance
number, optional
Opening balance minus "captured" debits.
availableBalance
number, optional
Opening balance minus "auth" debits.
message
string, optional
Optional message entered by CSR or customer.
customer
object
If customer have purchased GiftCard, returns his info.
storeAdmin
object
If CSR created GiftCard, return his info.

Customer Group

Customer Group is an entity that aggregates similar customers for purposes of analytics or integration with third-party services. There are two types of groups: dynamic and manual. Manual groups are lists of individual customers compiled by a user, while dynamic are aggregations based on a criteria defined by a user. The membership to dynamic groups will continuously update as changes are made to the system.

attributes
id
number, optional
Unique identifier.
name
string, optional
Name of group.
state
string, optional
Line item state.
email
string, optional
E-mail.
clientState
string, optional
client json state,
elasticRequest
string, optional
client json state
customersCount
number, optional
Customers count in group
updatedAt
string, optional
Last update time
createdAt
string, optional
Creation time
GET https://developer.foxcommerce.com/v1/groups
Example Response
{
  "result": [
    {
      "id": 1,
      "name": "John Smith",
      "email": "john@smith.com",
      "isGuest": false,
      "disabled": false,
      "isBlacklisted": false,
      "createdAt": "2020-01-01T12:00:00Z",
      "groups": [
        {
          "id": 1,
          "name": "Super Awesome Group",
          "type": "dynamic"
        }
      ],
      "storeCreditTotals": {
        "currentBalance": 50,
        "availableBalance": 50
      },
      "totalSales": 100
    }
  ]
}

List
GET/v1/groups

Response Definition
attributes
result
array, optional

GET https://developer.foxcommerce.com/v1/groups/1
Example Response
{
  "id": 1,
  "name": "Super Awesome Group",
  "state": "Cart",
  "email": "john@smith.com",
  "clientState": "<json>",
  "elasticRequest": "`<json>",
  "customersCount": 15,
  "updatedAt": "2020-01-01T12:00:00Z",
  "createdAt": "2020-01-01T12:00:00Z"
}

View
GET/v1/groups/{id}

URI Parameters
HideShow
id
number (required) Example: 1

Group ID.

Response Definition
attributes
id
number, optional
Unique identifier.
name
string, optional
Name of group.
state
string, optional
Line item state.
email
string, optional
E-mail.
clientState
string, optional
client json state,
elasticRequest
string, optional
client json state
customersCount
number, optional
Customers count in group
updatedAt
string, optional
Last update time
createdAt
string, optional
Creation time

POST https://developer.foxcommerce.com/v1/groups
Example Request
{
  "name": "New group name",
  "clientState": "<json>",
  "elasticRequest": "`<json>",
  "customersCount": 15,
  "email": "new@example.org"
}
Example Response
{
  "id": 1,
  "name": "Super Awesome Group",
  "state": "Cart",
  "email": "john@smith.com",
  "clientState": "<json>",
  "elasticRequest": "`<json>",
  "customersCount": 15,
  "updatedAt": "2020-01-01T12:00:00Z",
  "createdAt": "2020-01-01T12:00:00Z"
}

Create
POST/v1/groups

Request Definition
attributes
name
string, optional
New name of group.
clientState
string, optional
client json state,
elasticRequest
string, optional
client json state
customersCount
number, optional
Customers count in group
email
string, optional
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
name
string, optional
Name of group.
state
string, optional
Line item state.
email
string, optional
E-mail.
clientState
string, optional
client json state,
elasticRequest
string, optional
client json state
customersCount
number, optional
Customers count in group
updatedAt
string, optional
Last update time
createdAt
string, optional
Creation time

PATCH https://developer.foxcommerce.com/v1/groups/1
Example Request
{
  "name": "New group name",
  "clientState": "<json>",
  "elasticRequest": "`<json>",
  "customersCount": 15,
  "email": "new@example.org"
}
Example Response
{
  "id": 1,
  "name": "Super Awesome Group",
  "state": "Cart",
  "email": "john@smith.com",
  "clientState": "<json>",
  "elasticRequest": "`<json>",
  "customersCount": 15,
  "updatedAt": "2020-01-01T12:00:00Z",
  "createdAt": "2020-01-01T12:00:00Z"
}

Update
PATCH/v1/groups/{id}

URI Parameters
HideShow
id
number (required) Example: 1

Group ID.

Request Definition
attributes
name
string, optional
New name of group.
clientState
string, optional
client json state,
elasticRequest
string, optional
client json state
customersCount
number, optional
Customers count in group
email
string, optional
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
name
string, optional
Name of group.
state
string, optional
Line item state.
email
string, optional
E-mail.
clientState
string, optional
client json state,
elasticRequest
string, optional
client json state
customersCount
number, optional
Customers count in group
updatedAt
string, optional
Last update time
createdAt
string, optional
Creation time

Product Management

Managing products, their attributes, and how they are sold is one of core aspects of the Fox Platform. The principle characteristic of products management inside Fox is flexiblity around the definition and implemenation of what a product should have. Aside from a few key fields, as an admin, you have the ability to make products fit your usecase like a glove.

All information is stored in a specific context and every change is automatically versioned.

In addition, each of the core objects (Products and SKUs) may be classified by tags and taxonomies.

Products

The product is the most basic merchandising unit in FoxCommerce. A product is the storefront representation of one or more SKUs. It can be categorized, searched on, and merchandised with custom content and images.

GET https://developer.foxcommerce.com/v1/products/default/1
Example Response
{
  "id": 1,
  "context": {
    "name": "default",
    "attributes": {
      "lang": "en",
      "modality": "desktop"
    }
  },
  "attributes": {
    "name": {
      "t": "string",
      "v": "Fox Socks"
    },
    "description": {
      "t": "string",
      "v": "The finest fox designed socks that money can buy."
    }
  },
  "albums": [
    {
      "name": "Desktop",
      "images": [
        {
          "alt": "Red and blue sock",
          "src": "http://some.cdn.com/products/1/red-blue-sock.jpg"
        }
      ]
    }
  ],
  "skus": [
    {
      "attributes": {
        "code": {
          "t": "string",
          "v": "FOX-RED"
        },
        "salePrice": {
          "t": "price",
          "v": {
            "currency": "USD",
            "value": 1899
          }
        }
      },
      "albums": [
        {
          "name": "Desktop",
          "images": [
            {
              "alt": "Red sock",
              "src": "http:/some.cdn.com/products/1/red-sock.jpg"
            }
          ]
        }
      ]
    },
    {
      "attributes": {
        "code": {
          "t": "string",
          "v": "FOX-BLUE"
        },
        "salePrice": {
          "t": "price",
          "v": {
            "currency": "USD",
            "value": 1899
          }
        }
      },
      "albums": [
        {
          "name": "Desktop",
          "images": [
            {
              "alt": "Blue sock",
              "src": "http:/some.cdn.com/products/1/blue-sock.jpg"
            }
          ]
        }
      ]
    }
  ],
  "variants": [
    {
      "attributes": {
        "name": {
          "t": "string",
          "v": "Color"
        }
      },
      "values": [
        {
          "id": 1,
          "name": "Red",
          "swatch": "FF0000",
          "skuCodes": [
            "FOX-RED"
          ]
        },
        {
          "id": 2,
          "name": "Blue",
          "swatch": "0000FF",
          "skuCodes": [
            "FOX-BLUE"
          ]
        }
      ]
    }
  ]
}

View
GET/v1/products/{context}/{id}

URI Parameters
HideShow
context
string (required) Example: default

The context in which a product is viewable.

id
number (required) Example: 1

Product ID.

Response Definition

POST https://developer.foxcommerce.com/v1/products/default
Example Request
{
  "attributes": {
    "name": {
      "t": "string",
      "v": "Fox Socks"
    },
    "description": {
      "t": "string",
      "v": "The finest fox designed socks that money can buy."
    }
  },
  "skus": [
    {
      "attributes": {
        "code": {
          "t": "string",
          "v": "FOX-RED"
        },
        "salePrice": {
          "t": "price",
          "v": {
            "currency": "USD",
            "value": 1899
          }
        }
      },
      "variantValues": [
        "Red"
      ]
    },
    {
      "attributes": {
        "code": {
          "t": "string",
          "v": "FOX-BLUE"
        },
        "salePrice": {
          "t": "price",
          "v": {
            "currency": "USD",
            "value": 1899
          }
        }
      },
      "variantValues": [
        "Blue"
      ]
    }
  ],
  "variants": [
    {
      "attributes": {
        "name": {
          "t": "string",
          "v": "Color"
        }
      },
      "values": [
        {
          "name": "Red",
          "swatch": "FF0000",
          "skuCodes": [
            "FOX-RED"
          ]
        },
        {
          "name": "Blue",
          "swatch": "0000FF",
          "skuCodes": [
            "FOX-BLUE"
          ]
        }
      ]
    }
  ]
}
Example Response
{
  "id": 1,
  "context": {
    "name": "default",
    "attributes": {
      "lang": "en",
      "modality": "desktop"
    }
  },
  "attributes": {
    "name": {
      "t": "string",
      "v": "Fox Socks"
    },
    "description": {
      "t": "string",
      "v": "The finest fox designed socks that money can buy."
    }
  },
  "albums": [
    {
      "name": "Desktop",
      "images": [
        {
          "alt": "Red and blue sock",
          "src": "http://some.cdn.com/products/1/red-blue-sock.jpg"
        }
      ]
    }
  ],
  "skus": [
    {
      "attributes": {
        "code": {
          "t": "string",
          "v": "FOX-RED"
        },
        "salePrice": {
          "t": "price",
          "v": {
            "currency": "USD",
            "value": 1899
          }
        }
      },
      "albums": [
        {
          "name": "Desktop",
          "images": [
            {
              "alt": "Red sock",
              "src": "http:/some.cdn.com/products/1/red-sock.jpg"
            }
          ]
        }
      ]
    },
    {
      "attributes": {
        "code": {
          "t": "string",
          "v": "FOX-BLUE"
        },
        "salePrice": {
          "t": "price",
          "v": {
            "currency": "USD",
            "value": 1899
          }
        }
      },
      "albums": [
        {
          "name": "Desktop",
          "images": [
            {
              "alt": "Blue sock",
              "src": "http:/some.cdn.com/products/1/blue-sock.jpg"
            }
          ]
        }
      ]
    }
  ],
  "variants": [
    {
      "attributes": {
        "name": {
          "t": "string",
          "v": "Color"
        }
      },
      "values": [
        {
          "id": 1,
          "name": "Red",
          "swatch": "FF0000",
          "skuCodes": [
            "FOX-RED"
          ]
        },
        {
          "id": 2,
          "name": "Blue",
          "swatch": "0000FF",
          "skuCodes": [
            "FOX-BLUE"
          ]
        }
      ]
    }
  ]
}

Create
POST/v1/products/{context}

URI Parameters
HideShow
context
string (required) Example: default

The context in which a product is viewable.

Request Definition
Response Definition
Status Code 200

PATCH https://developer.foxcommerce.com/v1/products/default/1
Example Request
{
  "attributes": {
    "name": {
      "t": "string",
      "v": "Fox Socks"
    },
    "description": {
      "t": "string",
      "v": "The finest fox designed socks that money can buy."
    }
  },
  "skus": [
    {
      "code": "FOX-RED",
      "attributes": {
        "salePrice": {
          "t": "price",
          "v": {
            "currency": "USD",
            "value": 1899
          }
        }
      },
      "variantValues": [
        "Red"
      ]
    },
    {
      "code": "FOX-BLUE",
      "attributes": {
        "salePrice": {
          "t": "price",
          "v": {
            "currency": "USD",
            "value": 1899
          }
        }
      },
      "variantValues": [
        "Blue"
      ]
    }
  ],
  "variants": [
    {
      "attributes": {
        "name": {
          "t": "string",
          "v": "Color"
        }
      },
      "values": [
        {
          "id": 1,
          "name": "Red",
          "swatch": "FF0000",
          "skuCodes": [
            "FOX-RED"
          ]
        },
        {
          "id": 2,
          "name": "Blue",
          "swatch": "0000FF",
          "skuCodes": [
            "FOX-BLUE"
          ]
        }
      ]
    }
  ]
}
Example Response
{
  "id": 1,
  "context": {
    "name": "default",
    "attributes": {
      "lang": "en",
      "modality": "desktop"
    }
  },
  "attributes": {
    "name": {
      "t": "string",
      "v": "Fox Socks"
    },
    "description": {
      "t": "string",
      "v": "The finest fox designed socks that money can buy."
    }
  },
  "albums": [
    {
      "name": "Desktop",
      "images": [
        {
          "alt": "Red and blue sock",
          "src": "http://some.cdn.com/products/1/red-blue-sock.jpg"
        }
      ]
    }
  ],
  "skus": [
    {
      "code": "FOX-RED",
      "attributes": {
        "salePrice": {
          "t": "price",
          "v": {
            "currency": "USD",
            "value": 1899
          }
        }
      },
      "albums": [
        {
          "name": "Desktop",
          "images": [
            {
              "alt": "Red sock",
              "src": "http:/some.cdn.com/products/1/red-sock.jpg"
            }
          ]
        }
      ]
    },
    {
      "code": "FOX-BLUE",
      "attributes": {
        "salePrice": {
          "t": "price",
          "v": {
            "currency": "USD",
            "value": 1899
          }
        }
      },
      "albums": [
        {
          "name": "Desktop",
          "images": [
            {
              "alt": "Blue sock",
              "src": "http:/some.cdn.com/products/1/blue-sock.jpg"
            }
          ]
        }
      ]
    }
  ],
  "variants": [
    {
      "attributes": {
        "name": {
          "t": "string",
          "v": "Color"
        }
      },
      "values": [
        {
          "id": 1,
          "name": "Red",
          "swatch": "FF0000",
          "skuCodes": [
            "FOX-RED"
          ]
        },
        {
          "id": 2,
          "name": "Blue",
          "swatch": "0000FF",
          "skuCodes": [
            "FOX-BLUE"
          ]
        }
      ]
    }
  ]
}

Update
PATCH/v1/products/{context}/{id}

URI Parameters
HideShow
context
string (required) Example: default

The context in which a product is viewable.

id
number (required) Example: 1

Product ID.

Request Definition
Response Definition
Status Code 200

DELETE https://developer.foxcommerce.com/v1/products/default/1
Example Response
{
  "id": 1,
  "context": {
    "name": "default",
    "attributes": {
      "lang": "en",
      "modality": "desktop"
    }
  },
  "attributes": {
    "name": {
      "t": "string",
      "v": "Fox Socks"
    },
    "description": {
      "t": "string",
      "v": "The finest fox designed socks that money can buy."
    }
  },
  "albums": [
    {
      "name": "Desktop",
      "images": [
        {
          "alt": "Red and blue sock",
          "src": "http://some.cdn.com/products/1/red-blue-sock.jpg"
        }
      ]
    }
  ],
  "skus": [
    {
      "attributes": {
        "code": {
          "t": "string",
          "v": "FOX-RED"
        },
        "salePrice": {
          "t": "price",
          "v": {
            "currency": "USD",
            "value": 1899
          }
        }
      },
      "albums": [
        {
          "name": "Desktop",
          "images": [
            {
              "alt": "Red sock",
              "src": "http:/some.cdn.com/products/1/red-sock.jpg"
            }
          ]
        }
      ]
    },
    {
      "attributes": {
        "code": {
          "t": "string",
          "v": "FOX-BLUE"
        },
        "salePrice": {
          "t": "price",
          "v": {
            "currency": "USD",
            "value": 1899
          }
        }
      },
      "albums": [
        {
          "name": "Desktop",
          "images": [
            {
              "alt": "Blue sock",
              "src": "http:/some.cdn.com/products/1/blue-sock.jpg"
            }
          ]
        }
      ]
    }
  ],
  "variants": [
    {
      "attributes": {
        "name": {
          "t": "string",
          "v": "Color"
        }
      },
      "values": [
        {
          "id": 1,
          "name": "Red",
          "swatch": "FF0000",
          "skuCodes": [
            "FOX-RED"
          ]
        },
        {
          "id": 2,
          "name": "Blue",
          "swatch": "0000FF",
          "skuCodes": [
            "FOX-BLUE"
          ]
        }
      ]
    }
  ],
  "archivedAt": "2020-01-01T12:00:00Z"
}

Archive
DELETE/v1/products/{context}/{id}

URI Parameters
HideShow
context
string (required) Example: default

The context in which a product is viewable.

id
number (required) Example: 1

Product ID.

Response Definition

Product Album

GET https://developer.foxcommerce.com/v1/products/default/1/albums/1
Example Response
{
  "id": 1,
  "name": "Desktop images",
  "images": [
    {
      "src": "http://lorempixel.com/test.png",
      "title": "test image",
      "alt": "some image text"
    }
  ],
  "createdAt": "2020-01-01T12:00:00Z",
  "updatedAt": "2020-01-01T12:00:00Z",
  "archivedAt": "2020-01-01T12:00:00Z"
}

View
GET/v1/products/{context}/{productId}/albums/{id}

URI Parameters
HideShow
context
string (required) Example: default

The context in which the album will be viewable.

productId
number (required) Example: 1

Product ID.

id
number (required) Example: 1

Product ID.

Response Definition
attributes
id
number, optional
Unique identifier.
name
string, optional
Name of the album.
images
array, optional
Images that are part of the album.
createdAt
string, optional
Creation date.
updatedAt
string, optional
Last update date.
archivedAt
string, optional
Archiving date.

POST https://developer.foxcommerce.com/v1/products/default/1/albums
Example Request
{
  "name": "Desktop images",
  "images": [
    {
      "src": "http://lorempixel.com/test.png",
      "title": "test image",
      "alt": "some image text"
    }
  ]
}
Example Response
{
  "id": 1,
  "name": "Desktop images",
  "images": [
    {
      "src": "http://lorempixel.com/test.png",
      "title": "test image",
      "alt": "some image text"
    }
  ],
  "createdAt": "2020-01-01T12:00:00Z",
  "updatedAt": "2020-01-01T12:00:00Z",
  "archivedAt": "2020-01-01T12:00:00Z"
}

Create
POST/v1/products/{context}/{id}/albums

Create a new album that is not associated with a product.

URI Parameters
HideShow
context
string (required) Example: default

The context in which the album will be viewable.

id
number (required) Example: 1

Product ID.

Request Definition
attributes
name
string, optional
Name of the album.
images
array, optional
Images that are part of the album.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
name
string, optional
Name of the album.
images
array, optional
Images that are part of the album.
createdAt
string, optional
Creation date.
updatedAt
string, optional
Last update date.
archivedAt
string, optional
Archiving date.

PATCH https://developer.foxcommerce.com/v1/products/default/1/albums/1
Example Request
{
  "name": "Desktop images",
  "images": [
    {
      "src": "http://lorempixel.com/test.png",
      "title": "test image",
      "alt": "some image text"
    }
  ]
}
Example Response
{
  "id": 1,
  "name": "Desktop images",
  "images": [
    {
      "src": "http://lorempixel.com/test.png",
      "title": "test image",
      "alt": "some image text"
    }
  ],
  "createdAt": "2020-01-01T12:00:00Z",
  "updatedAt": "2020-01-01T12:00:00Z",
  "archivedAt": "2020-01-01T12:00:00Z"
}

Update
PATCH/v1/products/{context}/{productId}/albums/{id}

Update the album or any of the images inside. Any manipulation of the album should be done from this method. This includes adding existing images by URL, reordering images, or deleting images.

Internally, all changes are versions, so earlier iterations can be retrieved at a later time.

URI Parameters
HideShow
context
string (required) Example: default

The context in which the album will be viewable.

productId
number (required) Example: 1

Product ID.

id
number (required) Example: 1

Album ID.

Request Definition
attributes
name
string, optional
Name of the album.
images
array, optional
Images that are part of the album.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
name
string, optional
Name of the album.
images
array, optional
Images that are part of the album.
createdAt
string, optional
Creation date.
updatedAt
string, optional
Last update date.
archivedAt
string, optional
Archiving date.

SKUs

GET https://developer.foxcommerce.com/v1/skus/default/SKU-TEST
Example Response
{
  "id": 1,
  "context": {
    "name": "default",
    "attributes": {
      "lang": "en",
      "modality": "desktop"
    }
  },
  "attributes": {
    "code": {
      "t": "string",
      "v": "TEST-SKU"
    },
    "salePrice": {
      "t": "price",
      "v": {
        "currency": "USD",
        "value": 1899
      }
    },
    "retailPrice": {
      "t": "price",
      "v": {
        "currency": "USD",
        "value": 1599
      }
    }
  },
  "albums": [
    {
      "name": "Desktop",
      "images": [
        {
          "alt": "Test SKU",
          "src": "http:/some.cdn.com/skus/1/test-sku.jpg"
        }
      ]
    }
  ],
  "variantValueIds": [
    1
  ]
}

View
GET/v1/skus/{context}/{code}

URI Parameters
HideShow
context
string (required) Example: default

The context in which a SKU is viewable.

code
string (required) Example: SKU-TEST

Unique code that identifies a SKU.

Response Definition

POST https://developer.foxcommerce.com/v1/skus/default
Example Request
{
  "attributes": {
    "code": {
      "t": "string",
      "v": "TEST-SKU"
    },
    "salePrice": {
      "t": "price",
      "v": {
        "currency": "USD",
        "value": 1899
      }
    },
    "retailPrice": {
      "t": "price",
      "v": {
        "currency": "USD",
        "value": 1599
      }
    }
  }
}
Example Response
{
  "id": 1,
  "context": {
    "name": "default",
    "attributes": {
      "lang": "en",
      "modality": "desktop"
    }
  },
  "attributes": {
    "code": {
      "t": "string",
      "v": "TEST-SKU"
    },
    "salePrice": {
      "t": "price",
      "v": {
        "currency": "USD",
        "value": 1899
      }
    },
    "retailPrice": {
      "t": "price",
      "v": {
        "currency": "USD",
        "value": 1599
      }
    }
  },
  "albums": [],
  "variantValueIds": []
}

Create
POST/v1/skus/{context}

URI Parameters
HideShow
context
string (required) Example: default

The context in which a SKU is viewable.

Request Definition
Response Definition
Status Code 200

PATCH https://developer.foxcommerce.com/v1/skus/default/SKU-TEST
Example Request
{
  "attributes": {
    "code": {
      "t": "string",
      "v": "TEST-SKU"
    },
    "salePrice": {
      "t": "price",
      "v": {
        "currency": "USD",
        "value": 1899
      }
    },
    "retailPrice": {
      "t": "price",
      "v": {
        "currency": "USD",
        "value": 1599
      }
    }
  }
}
Example Response
{
  "id": 1,
  "context": {
    "name": "default",
    "attributes": {
      "lang": "en",
      "modality": "desktop"
    }
  },
  "attributes": {
    "code": {
      "t": "string",
      "v": "TEST-SKU"
    },
    "salePrice": {
      "t": "price",
      "v": {
        "currency": "USD",
        "value": 1899
      }
    },
    "retailPrice": {
      "t": "price",
      "v": {
        "currency": "USD",
        "value": 1599
      }
    }
  },
  "albums": [
    {
      "name": "Desktop",
      "images": [
        {
          "alt": "Test SKU",
          "src": "http:/some.cdn.com/skus/1/test-sku.jpg"
        }
      ]
    }
  ],
  "variantValueIds": [
    1
  ]
}

Update
PATCH/v1/skus/{context}/{code}

URI Parameters
HideShow
context
string (required) Example: default

The context in which a SKU is viewable.

code
string (required) Example: SKU-TEST

Unique code that identifies a SKU.

Request Definition
Response Definition
Status Code 200

DELETE https://developer.foxcommerce.com/v1/skus/default/SKU-TEST
Example Response
{
  "id": 1,
  "context": {
    "name": "default",
    "attributes": {
      "lang": "en",
      "modality": "desktop"
    }
  },
  "attributes": {
    "code": {
      "t": "string",
      "v": "TEST-SKU"
    },
    "salePrice": {
      "t": "price",
      "v": {
        "currency": "USD",
        "value": 1899
      }
    },
    "retailPrice": {
      "t": "price",
      "v": {
        "currency": "USD",
        "value": 1599
      }
    }
  },
  "albums": [
    {
      "name": "Desktop",
      "images": [
        {
          "alt": "Test SKU",
          "src": "http:/some.cdn.com/skus/1/test-sku.jpg"
        }
      ]
    }
  ],
  "variantValueIds": [
    1
  ],
  "archivedAt": "2020-01-01T12:00:00Z"
}

Archive
DELETE/v1/skus/{context}/{code}

URI Parameters
HideShow
context
string (required) Example: default

The context in which a SKU is viewable.

code
string (required) Example: SKU-TEST

Unique code that identifies a SKU.

Response Definition

SKU Album

GET https://developer.foxcommerce.com/v1/skus/default/SKU-TEST/albums/1
Example Response
{
  "id": 1,
  "name": "Desktop images",
  "images": [
    {
      "src": "http://lorempixel.com/test.png",
      "title": "test image",
      "alt": "some image text"
    }
  ],
  "createdAt": "2020-01-01T12:00:00Z",
  "updatedAt": "2020-01-01T12:00:00Z",
  "archivedAt": "2020-01-01T12:00:00Z"
}

View
GET/v1/skus/{context}/{code}/albums/{id}

URI Parameters
HideShow
context
string (required) Example: default

The context in which the album will be viewable.

code
string (required) Example: SKU-TEST

Unique code that identifies a SKU.

id
number (required) Example: 1

Album ID.

Response Definition
attributes
id
number, optional
Unique identifier.
name
string, optional
Name of the album.
images
array, optional
Images that are part of the album.
createdAt
string, optional
Creation date.
updatedAt
string, optional
Last update date.
archivedAt
string, optional
Archiving date.

POST https://developer.foxcommerce.com/v1/skus/default/SKU-TEST/albums
Example Request
{
  "name": "Desktop images",
  "images": [
    {
      "src": "http://lorempixel.com/test.png",
      "title": "test image",
      "alt": "some image text"
    }
  ]
}
Example Response
{
  "id": 1,
  "name": "Desktop images",
  "images": [
    {
      "src": "http://lorempixel.com/test.png",
      "title": "test image",
      "alt": "some image text"
    }
  ],
  "createdAt": "2020-01-01T12:00:00Z",
  "updatedAt": "2020-01-01T12:00:00Z",
  "archivedAt": "2020-01-01T12:00:00Z"
}

Create
POST/v1/skus/{context}/{code}/albums

Create a new album that is not associated with a SKU.

URI Parameters
HideShow
context
string (required) Example: default

The context in which the album will be viewable.

code
string (required) Example: SKU-TEST

Unique code that identifies a SKU.

Request Definition
attributes
name
string, optional
Name of the album.
images
array, optional
Images that are part of the album.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
name
string, optional
Name of the album.
images
array, optional
Images that are part of the album.
createdAt
string, optional
Creation date.
updatedAt
string, optional
Last update date.
archivedAt
string, optional
Archiving date.

PATCH https://developer.foxcommerce.com/v1/skus/default/SKU-TEST/albums/1
Example Request
{
  "name": "Desktop images",
  "images": [
    {
      "src": "http://lorempixel.com/test.png",
      "title": "test image",
      "alt": "some image text"
    }
  ]
}
Example Response
{
  "id": 1,
  "name": "Desktop images",
  "images": [
    {
      "src": "http://lorempixel.com/test.png",
      "title": "test image",
      "alt": "some image text"
    }
  ],
  "createdAt": "2020-01-01T12:00:00Z",
  "updatedAt": "2020-01-01T12:00:00Z",
  "archivedAt": "2020-01-01T12:00:00Z"
}

Update
PATCH/v1/skus/{context}/{code}/albums/{id}

Update the album or any of the images inside. Any manipulation of the album should be done from this method. This includes adding existing images by URL, reordering images, or deleting images.

Internally, all changes are versions, so earlier iterations can be retrieved at a later time.

URI Parameters
HideShow
context
string (required) Example: default

The context in which the album will be viewable.

code
string (required) Example: SKU-TEST

Unique code that identifies a SKU.

id
number (required) Example: 1

Album ID.

Request Definition
attributes
name
string, optional
Name of the album.
images
array, optional
Images that are part of the album.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
name
string, optional
Name of the album.
images
array, optional
Images that are part of the album.
createdAt
string, optional
Creation date.
updatedAt
string, optional
Last update date.
archivedAt
string, optional
Archiving date.

Variants

GET https://developer.foxcommerce.com/v1/variants/default/1
Example Response
{
  "id": 1
}

View
GET/v1/variants/{context}/{id}

URI Parameters
HideShow
context
string (required) Example: default

The context in which a product is viewable.

id
number (required) Example: 1

Unique indentifier for a Variant.

Response Definition
attributes
id
number, optional
Unique identifier.

POST https://developer.foxcommerce.com/v1/variants/default
Example Request
{
  "id": 1,
  "values": [
    {
      "id": 1,
      "name": "Color",
      "swatch": "FF0000"
    }
  ]
}
Example Response
{
  "id": 1
}

Create
POST/v1/variants/{context}

URI Parameters
HideShow
context
string (required) Example: default

The context in which a product is viewable.

Request Definition
attributes
id
number, optional
Unique identifier.
attributes VariantValuePayload
object, optional
Custom attributes.
values
array, optional
Values to create with the variant.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.

PATCH https://developer.foxcommerce.com/v1/variants/default/1
Example Request
{
  "id": 1,
  "values": [
    {
      "id": 1,
      "name": "Color",
      "swatch": "FF0000"
    }
  ]
}
Example Response
{
  "id": 1
}

Update
PATCH/v1/variants/{context}/{id}

URI Parameters
HideShow
context
string (required) Example: default

The context in which a product is viewable.

id
number (required) Example: 1

Unique indentifier for a Variant.

Request Definition
attributes
id
number, optional
Unique identifier.
attributes VariantValuePayload
object, optional
Custom attributes.
values
array, optional
Values to create with the variant.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.

Product Reviews

GET https://developer.foxcommerce.com/v1/review/default/1
Example Response
{
  "id": 0,
  "sku": "",
  "userId": 0,
  "attributes": {}
}

View
GET/v1/review/{context}/{id}

URI Parameters
HideShow
context
string (required) Example: default

The context in which a review is viewable.

id
number (required) Example: 1

Unique identifier for a Review.

Response Definition
attributes
id
number, optional
Review id
sku
string, optional
Code of SKU to which the comment is related
userId
number, optional
Id of customer to which the comment belongs
attributes
object, optional
Review attributes. Should contain 'title' attribute.

POST https://developer.foxcommerce.com/v1/review/default
Example Request
{
  "attributes": {},
  "sku": ""
}
Example Response
{
  "id": 0,
  "sku": "",
  "userId": 0,
  "attributes": {}
}

Create
POST/v1/review/{context}

URI Parameters
HideShow
context
string (required) Example: default

The context in which a review is viewable.

Request Definition
attributes
userId
number, optional
Id of customer for which review should belong
attributes
object, optional
Custom attributes
sku
string, optional
Code of SKU to which the comment is related
scope
string, optional
override for scope override
Response Definition
Status Code 200
attributes
id
number, optional
Review id
sku
string, optional
Code of SKU to which the comment is related
userId
number, optional
Id of customer to which the comment belongs
attributes
object, optional
Review attributes. Should contain 'title' attribute.

PATCH https://developer.foxcommerce.com/v1/review/default/1
Example Request
{
  "attributes": {}
}
Example Response
{
  "id": 0,
  "sku": "",
  "userId": 0,
  "attributes": {}
}

Update
PATCH/v1/review/{context}/{id}

URI Parameters
HideShow
context
string (required) Example: default

The context in which a review is viewable.

id
number (required) Example: 1

Unique identifier for a Product Review.

Request Definition
attributes
attributes
object, optional
Custom attributes.
Response Definition
Status Code 200
attributes
id
number, optional
Review id
sku
string, optional
Code of SKU to which the comment is related
userId
number, optional
Id of customer to which the comment belongs
attributes
object, optional
Review attributes. Should contain 'title' attribute.

DELETE https://developer.foxcommerce.com/v1/review/default/1
Example Response

Delete
DELETE/v1/review/{context}/{id}

URI Parameters
HideShow
context
string (required) Example: default

The context in which a review is viewable.

id
number (required) Example: 1

Unique identifier for a Product Review.

Response Definition

Merchandising

The Fox Merchandising system gives users the ability to classify products and manage the content presented with them. Like Product Management, it is built on top of a very flexible model that allows content to be attached to every object and for the object to exist in multiple contexts.

Like Product Management, all information is automatically versioned.

Albums

POST https://developer.foxcommerce.com/v1/albums/default
Example Request
{
  "name": "Desktop images",
  "images": [
    {
      "src": "http://lorempixel.com/test.png",
      "title": "test image",
      "alt": "some image text"
    }
  ]
}
Example Response
{
  "id": 1,
  "name": "Desktop images",
  "images": [
    {
      "src": "http://lorempixel.com/test.png",
      "title": "test image",
      "alt": "some image text"
    }
  ],
  "createdAt": "2020-01-01T12:00:00Z",
  "updatedAt": "2020-01-01T12:00:00Z",
  "archivedAt": "2020-01-01T12:00:00Z"
}

Create
POST/v1/albums/{context}

Create a new album that is not associated with an entity in the system.

URI Parameters
HideShow
context
string (required) Example: default

The context in which the album will be viewable.

Request Definition
attributes
name
string, optional
Name of the album.
images
array, optional
Images that are part of the album.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
name
string, optional
Name of the album.
images
array, optional
Images that are part of the album.
createdAt
string, optional
Creation date.
updatedAt
string, optional
Last update date.
archivedAt
string, optional
Archiving date.

GET https://developer.foxcommerce.com/v1/albums/default/1
Example Response
{
  "id": 1,
  "name": "Desktop images",
  "images": [
    {
      "src": "http://lorempixel.com/test.png",
      "title": "test image",
      "alt": "some image text"
    }
  ],
  "createdAt": "2020-01-01T12:00:00Z",
  "updatedAt": "2020-01-01T12:00:00Z",
  "archivedAt": "2020-01-01T12:00:00Z"
}

View
GET/v1/albums/{context}/{id}

URI Parameters
HideShow
context
string (required) Example: default

The context in which the album is viewable.

id
number (required) Example: 1

Album ID.

Response Definition
attributes
id
number, optional
Unique identifier.
name
string, optional
Name of the album.
images
array, optional
Images that are part of the album.
createdAt
string, optional
Creation date.
updatedAt
string, optional
Last update date.
archivedAt
string, optional
Archiving date.

PATCH https://developer.foxcommerce.com/v1/albums/default/1
Example Request
{
  "name": "Desktop images",
  "images": [
    {
      "src": "http://lorempixel.com/test.png",
      "title": "test image",
      "alt": "some image text"
    }
  ]
}
Example Response
{
  "id": 1,
  "name": "Desktop images",
  "images": [
    {
      "src": "http://lorempixel.com/test.png",
      "title": "test image",
      "alt": "some image text"
    }
  ],
  "createdAt": "2020-01-01T12:00:00Z",
  "updatedAt": "2020-01-01T12:00:00Z",
  "archivedAt": "2020-01-01T12:00:00Z"
}

Update
PATCH/v1/albums/{context}/{id}

Update the album or any of the images inside. Any manipulation of the album should be done from this method. This includes adding existing images by URL, reordering images, or deleting images.

Internally, all changes are versions, so earlier iterations can be retrieved at a later time.

URI Parameters
HideShow
context
string (required) Example: default

The context in which the album is viewable.

id
number (required) Example: 1

Album ID.

Request Definition
attributes
name
string, optional
Name of the album.
images
array, optional
Images that are part of the album.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
name
string, optional
Name of the album.
images
array, optional
Images that are part of the album.
createdAt
string, optional
Creation date.
updatedAt
string, optional
Last update date.
archivedAt
string, optional
Archiving date.

DELETE https://developer.foxcommerce.com/v1/albums/default/1
Example Response
{
  "id": 1,
  "name": "Desktop images",
  "images": [
    {
      "src": "http://lorempixel.com/test.png",
      "title": "test image",
      "alt": "some image text"
    }
  ],
  "createdAt": "2020-01-01T12:00:00Z",
  "updatedAt": "2020-01-01T12:00:00Z",
  "archivedAt": "2020-01-01T12:00:00Z"
}

Archive
DELETE/v1/albums/{context}/{id}

URI Parameters
HideShow
context
string (required) Example: default

The context in which the album is viewable.

id
number (required) Example: 1

Album ID.

Response Definition
attributes
id
number, optional
Unique identifier.
name
string, optional
Name of the album.
images
array, optional
Images that are part of the album.
createdAt
string, optional
Creation date.
updatedAt
string, optional
Last update date.
archivedAt
string, optional
Archiving date.

POST https://developer.foxcommerce.com/v1/albums/default/1/images
Example Request
-----BOUNDARY
Content-Disposition: form-data; name="upload-filename"; filename="$filename"
Content-Type: $mimetype
Content-Transfer-Encoding: binarydata

$binarydata
  -----BOUNDARY
Example Response
{
  "id": 1,
  "name": "Desktop images",
  "images": [
    {
      "src": "http://lorempixel.com/test.png",
      "title": "test image",
      "alt": "some image text"
    }
  ],
  "createdAt": "2020-01-01T12:00:00Z",
  "updatedAt": "2020-01-01T12:00:00Z",
  "archivedAt": "2020-01-01T12:00:00Z"
}

Upload Image
POST/v1/albums/{context}/{id}/images

Uploads a raw image file to S3 storage and inserts it’s URL as a new image in the album. The filename that’s inserted as the $filename parameter will be the name of the file in S3.

URI Parameters
HideShow
context
string (required) Example: default

The context in which the album is viewable.

id
number (required) Example: 1

Album ID.

Request Definition
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
name
string, optional
Name of the album.
images
array, optional
Images that are part of the album.
createdAt
string, optional
Creation date.
updatedAt
string, optional
Last update date.
archivedAt
string, optional
Archiving date.

Taxonomies

GET https://developer.foxcommerce.com/v1/taxonomies/default/1
Example Response
{
  "id": 0,
  "hierarchical": false,
  "attributes": {},
  "taxons": [
    {
      "id": 0,
      "attributes": {},
      "children": [
        {}
      ]
    }
  ]
}

View
GET/v1/taxonomies/{context}/{id}

URI Parameters
HideShow
context
string (required) Example: default

The context in which a taxonomy is viewable.

id
number (required) Example: 1

Unique identifier for a Taxonomy.

Response Definition
attributes
id
number, optional
Taxonomy id
hierarchical
boolean, optional
Type of taxonomy (hierarchical or flat)
attributes
object, optional
Custom attributes
taxons
array, optional
Taxons of the taxonomy

POST https://developer.foxcommerce.com/v1/taxonomies/default
Example Request
{
  "attributes": {},
  "hierarchical": false
}
Example Response
{
  "id": 0,
  "hierarchical": false,
  "attributes": {},
  "taxons": [
    {
      "id": 0,
      "attributes": {},
      "children": [
        {}
      ]
    }
  ]
}

Create
POST/v1/taxonomies/{context}

URI Parameters
HideShow
context
string (required) Example: default

The context in which a taxonomy is viewable.

Request Definition
attributes
attributes
object, optional
Custom attributes.
hierarchical
boolean, optional
Defines whether taxonomy is hierarchical or flat.
Response Definition
Status Code 200
attributes
id
number, optional
Taxonomy id
hierarchical
boolean, optional
Type of taxonomy (hierarchical or flat)
attributes
object, optional
Custom attributes
taxons
array, optional
Taxons of the taxonomy

PATCH https://developer.foxcommerce.com/v1/taxonomies/default/1
Example Request
{
  "attributes": {}
}
Example Response
{
  "id": 0,
  "hierarchical": false,
  "attributes": {},
  "taxons": [
    {
      "id": 0,
      "attributes": {},
      "children": [
        {}
      ]
    }
  ]
}

Update
PATCH/v1/taxonomies/{context}/{id}

URI Parameters
HideShow
context
string (required) Example: default

The context in which a taxonomy is viewable.

id
number (required) Example: 1

Unique identifier for a Taxonomy.

Request Definition
attributes
attributes
object, optional
Custom attributes.
Response Definition
Status Code 200
attributes
id
number, optional
Taxonomy id
hierarchical
boolean, optional
Type of taxonomy (hierarchical or flat)
attributes
object, optional
Custom attributes
taxons
array, optional
Taxons of the taxonomy

DELETE https://developer.foxcommerce.com/v1/taxonomies/default/1
Example Response

Delete
DELETE/v1/taxonomies/{context}/{id}

URI Parameters
HideShow
context
string (required) Example: default

The context in which a taxonomy is viewable.

id
number (required) Example: 1

Unique identifier for a Taxonomy.

Response Definition

Taxons

GET https://developer.foxcommerce.com/v1/taxons/default/1
Example Response
{
  "id": 0,
  "attributes": {},
  "children": [
    {}
  ]
}

View
GET/v1/taxons/{context}/{id}

URI Parameters
HideShow
context
string (required) Example: default

The context in which a taxon is viewable.

id
number (required) Example: 1

Unique identifier for a Taxon.

Response Definition
attributes
id
number, optional
Taxon id
attributes
object, optional
Custom attributes
children
array, optional
Children taxons of the taxonomy (for hierarchical taxons only)

POST https://developer.foxcommerce.com/v1/taxonomy/default/1
Example Request
{
  "attributes": {},
  "location": {
    "position": 0
  }
}
Example Response
{
  "id": 0,
  "attributes": {},
  "children": [
    {}
  ]
}

Create
POST/v1/taxonomy/{context}/{taxonomy_id}

URI Parameters
HideShow
context
string (required) Example: default

The context in which a taxon is viewable.

taxonomy_id
number (required) Example: 1

Unique identifier for a Taxonomy.

Request Definition
attributes
attributes
object, optional
Custom attributes.
location
object
Defines location of taxon in taxonomy hierarchy (for hierarchical taxonomies only).
Response Definition
Status Code 200
attributes
id
number, optional
Taxon id
attributes
object, optional
Custom attributes
children
array, optional
Children taxons of the taxonomy (for hierarchical taxons only)

PATCH https://developer.foxcommerce.com/v1/taxons/default/1
Example Request
{
  "location": {
    "position": 0
  }
}
Example Response
{
  "id": 0,
  "attributes": {},
  "children": [
    {}
  ]
}

Update
PATCH/v1/taxons/{context}/{id}

URI Parameters
HideShow
context
string (required) Example: default

The context in which a taxon is viewable.

id
number (required) Example: 1

Unique identifier for a Taxon.

Request Definition
attributes
attributes
object, optional
Custom attributes.
location
object
Defines location of taxon in taxonomy hierarchy (for hierarchical taxonomies only).
Response Definition
Status Code 200
attributes
id
number, optional
Taxon id
attributes
object, optional
Custom attributes
children
array, optional
Children taxons of the taxonomy (for hierarchical taxons only)

DELETE https://developer.foxcommerce.com/v1/taxons/default/1
Example Response

Delete
DELETE/v1/taxons/{context}/{id}

URI Parameters
HideShow
context
string (required) Example: default

The context in which a taxonomy is viewable.

id
number (required) Example: 1

Unique identifier for a Taxon.

Response Definition

Inventory Management

This section covers all the endpoints that a site administrator could use to view and manage inventory and shipping information in FoxCommerce. Every endpoint in this section required authentication.

Stock Item Summaries

Stock Level Summaries allows a user to see levels of inventory available across various inventory types and stock locations.

Inventory Types

  • Sellable: the standard inventory type. Units in this state are considered to be in-stock and available in a stock location.

  • Non-sellable: inventory that is in a stock location but not allowed to sold. One example would be inventory that has been received in a warehouse from a manufacturer, but is not yet put in to bins.

  • Backorder: the amount of inventory that is either available for backorder or has already been backordered.

  • Preorder: the amount of inventory that is either available for preorder or has already been preordered.

Inventory Count Definitions

  • On Hand: refers to the number of units that are sitting within a given stock location. Depending on other states, these may or may not be available for sale.

  • Hold: units that have been purchased, but are in one of the hold order states (Manual Hold, Fraud Hold, Remorse Hold). If an outside WMS or 3PL is connected to FoxCommerce, these units will not show up as purchased in that system. Units that are in this state cannot be purchased by other customers.

  • Reserved: units that are in the process of being fulfilled.

  • AFS: the number of units that are available for sale. This is a calculated field (afs = on hand - hold - reserved).

GET https://developer.foxcommerce.com/v1/inventory/summary/TEST-SKU
Example Response
{
  "summary": [
    {
      "sku": "TEST-SKU",
      "stockItem": {
        "id": 1,
        "sku": "TEST-SKU",
        "stockLocationId": 1,
        "defaultUnitCost": 999
      },
      "stockLocation": {
        "id": 1,
        "name": "default",
        "type": "Warehouse"
      },
      "type": "Sellable",
      "onHand": 100,
      "onHold": 12,
      "reserved": 15,
      "afs": 73,
      "afsCost": 72927,
      "createdAt": "2016-10-03T06:10:20.464687Z"
    },
    {
      "sku": "TEST-SKU",
      "stockItem": {
        "id": 1,
        "sku": "TEST-SKU",
        "stockLocationId": 1,
        "defaultUnitCost": 999
      },
      "stockLocation": {
        "id": 1,
        "name": "default",
        "type": "Warehouse"
      },
      "type": "Non-sellable",
      "onHand": 0,
      "onHold": 0,
      "reserved": 0,
      "shipped": 0,
      "afs": 0,
      "afsCost": 0,
      "createdAt": "2016-10-03T06:10:20.469778Z"
    },
    {
      "sku": "TEST-SKU",
      "stockItem": {
        "id": 1,
        "sku": "TEST-SKU",
        "stockLocationId": 1,
        "defaultUnitCost": 999
      },
      "stockLocation": {
        "id": 1,
        "name": "default",
        "type": "Warehouse"
      },
      "type": "Backorder",
      "onHand": 100,
      "onHold": 0,
      "reserved": 0,
      "shipped": 0,
      "afs": 100,
      "afsCost": 99900,
      "createdAt": "2016-10-03T06:10:20.470854Z"
    },
    {
      "sku": "TEST-SKU",
      "stockItem": {
        "id": 1,
        "sku": "TEST-SKU",
        "stockLocationId": 1,
        "defaultUnitCost": 999
      },
      "stockLocation": {
        "id": 1,
        "name": "default",
        "type": "Warehouse"
      },
      "type": "Preorder",
      "onHand": 0,
      "onHold": 0,
      "reserved": 0,
      "shipped": 0,
      "afs": 0,
      "afsCost": 0,
      "createdAt": "2016-10-03T06:10:20.471925Z"
    }
  ]
}

View
GET/v1/inventory/summary/{code}

URI Parameters
HideShow
code
string (required) Example: TEST-SKU

The code representing the SKU who’s inventory should be viewed.

Response Definition

Stock Locations

Stock Locations are representations of any place that inventory may be stored. FoxCommerce Inventory is designed to be manage and track inventory over multiple stock locations for a given storefront, as well as over multiple types of stock location.

Stock Location Types

  • Warehouse (currently supported)

  • Retail Store (coming soon)

  • Pop-up Shop (coming soon)

GET https://developer.foxcommerce.com/v1/inventory/stock-locations/1
Example Response
{
  "id": 1,
  "name": "Memphis Warehouse",
  "type": "Warehouse",
  "address": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555"
  }
}

View
GET/v1/inventory/stock-locations/{id}

URI Parameters
HideShow
id
number (required) Example: 1

Stock Location ID.

Response Definition
attributes
id
number, optional
Unique ID.
name
string, optional
Name of the stock location.
type
string, optional
Stock location type.
address
object
Address of the stock location.

POST https://developer.foxcommerce.com/v1/inventory/stock-locations
Example Request
{
  "name": "Memphis Warehouse",
  "type": "Warehouse",
  "address": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555"
  }
}
Example Response
{
  "id": 1,
  "name": "Memphis Warehouse",
  "type": "Warehouse",
  "address": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555"
  }
}

Create
POST/v1/inventory/stock-locations

Request Definition
attributes
name
string, optional
Name of the stock location.
type
string, optional
Stock location type.
address
object
Address of the stock location.
Response Definition
Status Code 201
attributes
id
number, optional
Unique ID.
name
string, optional
Name of the stock location.
type
string, optional
Stock location type.
address
object
Address of the stock location.

PUT https://developer.foxcommerce.com/v1/inventory/stock-locations/1
Example Request
{
  "name": "Memphis Warehouse",
  "type": "Warehouse",
  "address": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555"
  }
}
Example Response
{
  "id": 1,
  "name": "Memphis Warehouse",
  "type": "Warehouse",
  "address": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555"
  }
}

Update
PUT/v1/inventory/stock-locations/{id}

URI Parameters
HideShow
id
number (required) Example: 1

Stock Location ID.

Request Definition
attributes
name
string, optional
Name of the stock location.
type
string, optional
Stock location type.
address
object
Address of the stock location.
Response Definition
Status Code 200
attributes
id
number, optional
Unique ID.
name
string, optional
Name of the stock location.
type
string, optional
Stock location type.
address
object
Address of the stock location.

DELETE https://developer.foxcommerce.com/v1/inventory/stock-locations/1
Example Response
This response has no content.

Delete
DELETE/v1/inventory/stock-locations/{id}

URI Parameters
HideShow
id
number (required) Example: 1

Stock Location ID.

Response Definition

Stock Items

Stock Items are the representation of a SKU within a specific Stock Location.

GET https://developer.foxcommerce.com/v1/inventory/stock-items/1
Example Response
{
  "id": 1,
  "sku": "TEST-SKU",
  "stockLocationId": 1,
  "defaultUnitCost": 0
}

View
GET/v1/inventory/stock-items/{id}

URI Parameters
HideShow
id
number (required) Example: 1

Stock Item ID.

Response Definition
attributes
id
number, optional
Unique ID.
sku
string, optional
Code representing the SKU with which to associate the Stock Item
stockLocationId
number, optional
ID of the Stock Location the Stock Item should be a part of.
defaultUnitCost
number, optional
A default unit cost to give all new units of a Stock Item

POST https://developer.foxcommerce.com/v1/inventory/stock-items
Example Request
{
  "sku": "TEST-SKU",
  "stockLocationId": 1,
  "defaultUnitCost": 0
}
Example Response
{
  "id": 1,
  "sku": "TEST-SKU",
  "stockLocationId": 1,
  "defaultUnitCost": 0
}

Create
POST/v1/inventory/stock-items

Request Definition
attributes
sku
string, optional
Code representing the SKU with which to associate the Stock Item
stockLocationId
number, optional
ID of the Stock Location the Stock Item should be a part of.
defaultUnitCost
number, optional
A default unit cost to give all new units of a Stock Item
Response Definition
Status Code 201
attributes
id
number, optional
Unique ID.
sku
string, optional
Code representing the SKU with which to associate the Stock Item
stockLocationId
number, optional
ID of the Stock Location the Stock Item should be a part of.
defaultUnitCost
number, optional
A default unit cost to give all new units of a Stock Item

PATCH https://developer.foxcommerce.com/v1/inventory/stock-items/1/increment
Example Request
{
  "qty": 1,
  "type": "sellable",
  "unitCost": 999
}
Example Response
This response has no content.

Increment
PATCH/v1/inventory/stock-items/{id}/increment

Increment the number of units available to a stock item in the on hand state. Units can be added to any type (sellable, nonsellable, preorder, or backorder).

URI Parameters
HideShow
id
number (required) Example: 1

Stock Item ID.

Request Definition
attributes
qty
number, optional
The number of units to increment
type
string, optional
Stock item type.
unitCost
number, optional
The unit cost to give new stock items. If none is supplied, the stock item's default unit cost is used.
Response Definition
Status Code 204

PATCH https://developer.foxcommerce.com/v1/inventory/stock-items/1/decrement
Example Request
{
  "qty": 1,
  "type": "sellable"
}
Example Response
This response has no content.

Decrement
PATCH/v1/inventory/stock-items/{id}/decrement

Decrement the number of units available to a stock item in the on hand state. Units can be removed from any type (sellable, nonsellable, preorder, or backorder).

URI Parameters
HideShow
id
number (required) Example: 1

Stock Item ID.

Request Definition
attributes
qty
number, optional
The number of units to decrement
type
string, optional
Stock item type.
Response Definition
Status Code 204

Shipments

Shipments track the status of items that have been purchased and are scheduled to be sent from a store to a 3rd party, such as a customer.

Shipment States

  • Pending: the initial state when a new shipment is created. It means that the shipment exists in the warehouse and is in the process of being readied for shipment.

  • Shipped: the shipment has left the warehouse and is in the process of being fulfilled.

  • Delivered: the recipient has received the shipment.

  • Cancelled: the shipment has been cancelled and inventory has been made available to other customers.

GET https://developer.foxcommerce.com/v1/inventory/shipments/BR10001
Example Response
[
  {
    "id": 1,
    "referenceNumber": "SR10001",
    "shippingMethod": {
      "id": 1,
      "name": "Ground Shipping",
      "carrier": {
        "id": 1,
        "name": "UPS",
        "trackingTemplate": "http://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=%s"
      },
      "code": "UPS-GROUND"
    },
    "orderRefNum": "BR10001",
    "state": "pending",
    "shipmentDate": "2020-01-01T12:00:00Z",
    "estimatedArrival": "2020-01-01T12:00:00Z",
    "deliveredDate": "2020-01-01T12:00:00Z",
    "address": {
      "id": 1,
      "region": {
        "id": 1,
        "countryId": 2794,
        "name": "Washington"
      },
      "name": "Home",
      "address1": "38 Baker Street",
      "address2": "39 Baker Street",
      "city": "Donkeyville",
      "zip": "55555"
    },
    "shipmentLineItems": [
      {
        "id": 1,
        "referenceNumber": "SR10001",
        "ShipmentLineItem": "Hello, world!"
      }
    ],
    "trackingNumber": "1Z9999999999999999",
    "shippingPrice": 399
  }
]

View By Order
GET/v1/inventory/shipments/{referenceNumber}

Gets all of the shipments associated with a single order.

URI Parameters
HideShow
referenceNumber
string (required) Example: BR10001

Order reference number.

Response Definition
attributes

POST https://developer.foxcommerce.com/v1/inventory/shipments
Example Request
{
  "referenceNumber": "SR10001",
  "shippingMethodCode": "GROUND-SHIPPING",
  "orderRefNum": "BR10001",
  "state": "pending",
  "shipmentDate": "2020-01-01T12:00:00Z",
  "estimatedArrival": "2020-01-01T12:00:00Z",
  "deliveredDate": "2020-01-01T12:00:00Z",
  "address": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555"
  },
  "shipmentLineItems": [
    {
      "sku": "test-sku",
      "name": "Brown Shoes",
      "price": 999,
      "imagePath": "http://testsku.png"
    }
  ],
  "trackingNumber": "1Z9999999999999999",
  "shippingPrice": 399
}
Example Response
{
  "id": 1,
  "referenceNumber": "SR10001",
  "shippingMethod": {
    "id": 1,
    "name": "Ground Shipping",
    "carrier": {
      "id": 1,
      "name": "UPS",
      "trackingTemplate": "http://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=%s"
    },
    "code": "UPS-GROUND"
  },
  "orderRefNum": "BR10001",
  "state": "pending",
  "shipmentDate": "2020-01-01T12:00:00Z",
  "estimatedArrival": "2020-01-01T12:00:00Z",
  "deliveredDate": "2020-01-01T12:00:00Z",
  "address": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555"
  },
  "shipmentLineItems": [
    {
      "id": 1,
      "referenceNumber": "SR10001",
      "ShipmentLineItem": "Hello, world!"
    }
  ],
  "trackingNumber": "1Z9999999999999999",
  "shippingPrice": 399
}

Create
POST/v1/inventory/shipments

This is the manual shipment creation endpoint. Use this if you want to have precise control over how the shipments are created and the logic for splitting them. In order for the shipment to be created successfully, the following conditions must be met:

  1. The items that you’re attempting to ship must have been reserved by the order that’s associated with the shipment. This step is automatically performed by the OMS API when checkout occurs.

    For more details on the reserved status, please see the StockItems API in this document.

  2. The items that you’re attempting to ship may not be a part of any other shipment.

  3. All items that you’re attempting to ship must exist in the same stock location. Since a shipment represents the bundle of items leaving a stock location, it’s necessary that all items must be able to be shipped from the same location.

Request Definition
attributes
referenceNumber
string, optional
Unique ID for the shipment.
shippingMethodCode
string, optional
Code to identify the shipment to use.
orderRefNum
string, optional
Order that the shipment is associated with.
state
string, optional
Shipment state.
shipmentDate
string, optional
Date that the shipment leaves the warehouse.
estimatedArrival
string, optional
Date that the shipment is expected to arrive to the customer.
deliveredDate
string, optional
Date that the shipment was delivered.
address
object
Destination address.
shipmentLineItems
array, optional
The items that should be part of the shipment.
trackingNumber
string, optional
An optional tracking number, if it's provided.
shippingPrice
number, optional
The price of the shipment.
Response Definition
Status Code 201
attributes
id
number, optional
Unique ID.
referenceNumber
string, optional
Unique ID for the shipment.
shippingMethod
object
orderRefNum
string, optional
Order that the shipment is associated with.
state
string, optional
Shipment state.
shipmentDate
string, optional
Date that the shipment leaves the warehouse.
estimatedArrival
string, optional
Date that the shipment is expected to arrive to the customer.
deliveredDate
string, optional
Date that the shipment was delivered.
address
object
Destination address.
shipmentLineItems
array, optional
The items that should be part of the shipment.
trackingNumber
string, optional
An optional tracking number, if it's provided.
shippingPrice
number, optional
The price of the shipment.

POST https://developer.foxcommerce.com/v1/inventory/shipments/from-order
Example Request
{
  "id": 1,
  "referenceNumber": "ABC-123",
  "orderState": "Cart",
  "shippingState": "Cart",
  "paymentState": "Cart",
  "lineItems": {
    "skus": [
      {
        "imagePath": "http://lorempixel.com/75/75/fashion",
        "referenceNumber": "ABC-123",
        "name": "donkey product",
        "sku": "SKU-YAX",
        "price": 33,
        "quantity": 1,
        "state": "Cart",
        "totalPrice": 33
      }
    ],
    "giftCard": [
      {
        "id": 1,
        "createdAt": "2020-01-01T12:00:00Z",
        "code": "ABC-123",
        "originType": "csrAppeasement",
        "subTypeId": 1,
        "state": "onHold",
        "originalBalance": 50,
        "currentBalance": 50,
        "availableBalance": 50,
        "message": "Lorem ipsum",
        "customer": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com",
          "isGuest": false,
          "disabled": false,
          "isBlacklisted": false,
          "createdAt": "2020-01-01T12:00:00Z",
          "groups": [
            {
              "id": 1,
              "name": "Super Awesome Group",
              "type": "dynamic"
            }
          ],
          "storeCreditTotals": {
            "currentBalance": 50,
            "availableBalance": 50
          },
          "totalSales": 100
        },
        "storeAdmin": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com"
        }
      }
    ]
  },
  "adjustments": [
    {
      "id": 1,
      "amount": 10,
      "sourceId": 1,
      "sourceType": "order",
      "reason": "Lorem ipsum"
    }
  ],
  "fraudScore": 0,
  "customer": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com",
    "isGuest": false,
    "disabled": false,
    "isBlacklisted": false,
    "createdAt": "2020-01-01T12:00:00Z",
    "groups": [
      {
        "id": 1,
        "name": "Super Awesome Group",
        "type": "dynamic"
      }
    ],
    "storeCreditTotals": {
      "currentBalance": 50,
      "availableBalance": 50
    },
    "totalSales": 100
  },
  "totals": {
    "subTotal": 100,
    "taxes": 50,
    "shipping": 5,
    "adjustments": 50,
    "total": 100
  },
  "shippingMethod": {
    "id": 1,
    "name": "UPS Ground",
    "price": 10,
    "isEnabled": true
  },
  "shippingAddress": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555",
    "isDefault": false
  },
  "remorsePeriodEnd": "2020-01-01T12:00:00Z",
  "paymentMethods": [
    {
      "type": "CreditCard"
    }
  ],
  "warnings": [
    "List of validation errors and warnings"
  ]
}
Example Response
[
  {
    "id": 1,
    "referenceNumber": "SR10001",
    "shippingMethod": {
      "id": 1,
      "name": "Ground Shipping",
      "carrier": {
        "id": 1,
        "name": "UPS",
        "trackingTemplate": "http://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=%s"
      },
      "code": "UPS-GROUND"
    },
    "orderRefNum": "BR10001",
    "state": "pending",
    "shipmentDate": "2020-01-01T12:00:00Z",
    "estimatedArrival": "2020-01-01T12:00:00Z",
    "deliveredDate": "2020-01-01T12:00:00Z",
    "address": {
      "id": 1,
      "region": {
        "id": 1,
        "countryId": 2794,
        "name": "Washington"
      },
      "name": "Home",
      "address1": "38 Baker Street",
      "address2": "39 Baker Street",
      "city": "Donkeyville",
      "zip": "55555"
    },
    "shipmentLineItems": [
      {
        "id": 1,
        "referenceNumber": "SR10001",
        "ShipmentLineItem": "Hello, world!"
      }
    ],
    "trackingNumber": "1Z9999999999999999",
    "shippingPrice": 399
  }
]

Create From Order
POST/v1/inventory/shipments/from-order

This is the automatic shipment creation endpoint provided about the WMS. It will create a set of shipments based on internal FoxCommerce WMS logic.

Note: At this time only single shipments are supported.

Request Definition
attributes
id
number, optional
Unique identifier.
referenceNumber
string, optional
Order reference number.
orderState
string, optional
Order State.
shippingState
string, optional
Shipping state.
paymentState
string, optional
Credit Card payment state.
lineItems
object
Line items with different types.
adjustments
array, optional
Order adjustments.
fraudScore
number, optional
Fraud score.
customer
object
Associated customer.
totals
object
Order totals.
shippingMethod
object
Shipping method.
shippingAddress
object
Shipping address.
remorsePeriodEnd
string, optional
Remorse period end.
paymentMethods
array, optional
Order payment.
warnings
array, optional
Warnings.
Response Definition
Status Code 201
attributes

PATCH https://developer.foxcommerce.com/v1/inventory/shipments/1
Example Request
{
  "referenceNumber": "SR10001",
  "shippingMethodCode": "GROUND-SHIPPING",
  "orderRefNum": "BR10001",
  "state": "pending",
  "shipmentDate": "2020-01-01T12:00:00Z",
  "estimatedArrival": "2020-01-01T12:00:00Z",
  "deliveredDate": "2020-01-01T12:00:00Z",
  "address": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555"
  },
  "shipmentLineItems": [
    {
      "sku": "test-sku",
      "name": "Brown Shoes",
      "price": 999,
      "imagePath": "http://testsku.png"
    }
  ],
  "trackingNumber": "1Z9999999999999999",
  "shippingPrice": 399
}
Example Response
[
  {
    "id": 1,
    "referenceNumber": "SR10001",
    "shippingMethod": {
      "id": 1,
      "name": "Ground Shipping",
      "carrier": {
        "id": 1,
        "name": "UPS",
        "trackingTemplate": "http://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=%s"
      },
      "code": "UPS-GROUND"
    },
    "orderRefNum": "BR10001",
    "state": "pending",
    "shipmentDate": "2020-01-01T12:00:00Z",
    "estimatedArrival": "2020-01-01T12:00:00Z",
    "deliveredDate": "2020-01-01T12:00:00Z",
    "address": {
      "id": 1,
      "region": {
        "id": 1,
        "countryId": 2794,
        "name": "Washington"
      },
      "name": "Home",
      "address1": "38 Baker Street",
      "address2": "39 Baker Street",
      "city": "Donkeyville",
      "zip": "55555"
    },
    "shipmentLineItems": [
      {
        "id": 1,
        "referenceNumber": "SR10001",
        "ShipmentLineItem": "Hello, world!"
      }
    ],
    "trackingNumber": "1Z9999999999999999",
    "shippingPrice": 399
  }
]

Update
PATCH/v1/inventory/shipments/{id}

This will update the state of a single shipment.

URI Parameters
HideShow
id
number (required) Example: 1

Unique ID.

Request Definition
attributes
referenceNumber
string, optional
Unique ID for the shipment.
shippingMethodCode
string, optional
Code to identify the shipment to use.
orderRefNum
string, optional
Order that the shipment is associated with.
state
string, optional
Shipment state.
shipmentDate
string, optional
Date that the shipment leaves the warehouse.
estimatedArrival
string, optional
Date that the shipment is expected to arrive to the customer.
deliveredDate
string, optional
Date that the shipment was delivered.
address
object
Destination address.
shipmentLineItems
array, optional
The items that should be part of the shipment.
trackingNumber
string, optional
An optional tracking number, if it's provided.
shippingPrice
number, optional
The price of the shipment.
Response Definition
Status Code 200
attributes

Order Management

The Fox Platform allows for robust handling of customer purchases, allowing administrators, customer service representatives, and others to work with carts, place orders, and manage payment methods.

Carts

This object represents a customer’s purchase before the customer has checked out. It contains the items that the customer wishes to purchase, where and however they should be shipped, what discounts are applied, and how they are paid.

All actions that manipulate the cart validate the state of the cart for things like available inventory, whether selected shipping options are valid, etc. This gives you confidence that you will understand the consequences of any changes to the cart.

attributes
id
number, optional
Unique identifier.
referenceNumber
string, optional
Order reference number.
orderState
string, optional
Order State.
shippingState
string, optional
Shipping state.
paymentState
string, optional
Credit Card payment state.
lineItems
object
Line items with different types.
adjustments
array, optional
Order adjustments.
fraudScore
number, optional
Fraud score.
customer
object
Associated customer.
totals
object
Order totals.
shippingMethod
object
Shipping method.
shippingAddress
object
Shipping address.
remorsePeriodEnd
string, optional
Remorse period end.
paymentMethods
array, optional
Order payment.
warnings
array, optional
Warnings.
GET https://developer.foxcommerce.com/v1/carts/ABC-123
Example Response
{
  "id": 1,
  "referenceNumber": "ABC-123",
  "orderState": "Cart",
  "shippingState": "Cart",
  "paymentState": "Cart",
  "lineItems": {
    "skus": [
      {
        "imagePath": "http://lorempixel.com/75/75/fashion",
        "referenceNumber": "ABC-123",
        "name": "donkey product",
        "sku": "SKU-YAX",
        "price": 33,
        "quantity": 1,
        "state": "Cart",
        "totalPrice": 33
      }
    ],
    "giftCard": [
      {
        "id": 1,
        "createdAt": "2020-01-01T12:00:00Z",
        "code": "ABC-123",
        "originType": "csrAppeasement",
        "subTypeId": 1,
        "state": "onHold",
        "originalBalance": 50,
        "currentBalance": 50,
        "availableBalance": 50,
        "message": "Lorem ipsum",
        "customer": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com",
          "isGuest": false,
          "disabled": false,
          "isBlacklisted": false,
          "createdAt": "2020-01-01T12:00:00Z",
          "groups": [
            {
              "id": 1,
              "name": "Super Awesome Group",
              "type": "dynamic"
            }
          ],
          "storeCreditTotals": {
            "currentBalance": 50,
            "availableBalance": 50
          },
          "totalSales": 100
        },
        "storeAdmin": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com"
        }
      }
    ]
  },
  "adjustments": [
    {
      "id": 1,
      "amount": 10,
      "sourceId": 1,
      "sourceType": "order",
      "reason": "Lorem ipsum"
    }
  ],
  "fraudScore": 0,
  "customer": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com",
    "isGuest": false,
    "disabled": false,
    "isBlacklisted": false,
    "createdAt": "2020-01-01T12:00:00Z",
    "groups": [
      {
        "id": 1,
        "name": "Super Awesome Group",
        "type": "dynamic"
      }
    ],
    "storeCreditTotals": {
      "currentBalance": 50,
      "availableBalance": 50
    },
    "totalSales": 100
  },
  "totals": {
    "subTotal": 100,
    "taxes": 50,
    "shipping": 5,
    "adjustments": 50,
    "total": 100
  },
  "shippingMethod": {
    "id": 1,
    "name": "UPS Ground",
    "price": 10,
    "isEnabled": true
  },
  "shippingAddress": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555",
    "isDefault": false
  },
  "remorsePeriodEnd": "2020-01-01T12:00:00Z",
  "paymentMethods": [
    {
      "type": "CreditCard"
    }
  ],
  "warnings": [
    "List of validation errors and warnings"
  ]
}

View
GET/v1/carts/{refNum}

URI Parameters
HideShow
refNum
string (required) Example: ABC-123

Cart referenceNumber.

Response Definition
attributes
id
number, optional
Unique identifier.
referenceNumber
string, optional
Order reference number.
orderState
string, optional
Order State.
shippingState
string, optional
Shipping state.
paymentState
string, optional
Credit Card payment state.
lineItems
object
Line items with different types.
adjustments
array, optional
Order adjustments.
fraudScore
number, optional
Fraud score.
customer
object
Associated customer.
totals
object
Order totals.
shippingMethod
object
Shipping method.
shippingAddress
object
Shipping address.
remorsePeriodEnd
string, optional
Remorse period end.
paymentMethods
array, optional
Order payment.
warnings
array, optional
Warnings.

POST https://developer.foxcommerce.com/v1/carts
Example Request
{
  "customerId": 1,
  "email": "john@smith.com"
}
Example Response
{
  "id": 1,
  "referenceNumber": "ABC-123",
  "orderState": "Cart",
  "shippingState": "Cart",
  "paymentState": "Cart",
  "lineItems": {
    "skus": [
      {
        "imagePath": "http://lorempixel.com/75/75/fashion",
        "referenceNumber": "ABC-123",
        "name": "donkey product",
        "sku": "SKU-YAX",
        "price": 33,
        "quantity": 1,
        "state": "Cart",
        "totalPrice": 33
      }
    ],
    "giftCard": [
      {
        "id": 1,
        "createdAt": "2020-01-01T12:00:00Z",
        "code": "ABC-123",
        "originType": "csrAppeasement",
        "subTypeId": 1,
        "state": "onHold",
        "originalBalance": 50,
        "currentBalance": 50,
        "availableBalance": 50,
        "message": "Lorem ipsum",
        "customer": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com",
          "isGuest": false,
          "disabled": false,
          "isBlacklisted": false,
          "createdAt": "2020-01-01T12:00:00Z",
          "groups": [
            {
              "id": 1,
              "name": "Super Awesome Group",
              "type": "dynamic"
            }
          ],
          "storeCreditTotals": {
            "currentBalance": 50,
            "availableBalance": 50
          },
          "totalSales": 100
        },
        "storeAdmin": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com"
        }
      }
    ]
  },
  "adjustments": [
    {
      "id": 1,
      "amount": 10,
      "sourceId": 1,
      "sourceType": "order",
      "reason": "Lorem ipsum"
    }
  ],
  "fraudScore": 0,
  "customer": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com",
    "isGuest": false,
    "disabled": false,
    "isBlacklisted": false,
    "createdAt": "2020-01-01T12:00:00Z",
    "groups": [
      {
        "id": 1,
        "name": "Super Awesome Group",
        "type": "dynamic"
      }
    ],
    "storeCreditTotals": {
      "currentBalance": 50,
      "availableBalance": 50
    },
    "totalSales": 100
  },
  "totals": {
    "subTotal": 100,
    "taxes": 50,
    "shipping": 5,
    "adjustments": 50,
    "total": 100
  },
  "shippingMethod": {
    "id": 1,
    "name": "UPS Ground",
    "price": 10,
    "isEnabled": true
  },
  "shippingAddress": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555",
    "isDefault": false
  },
  "remorsePeriodEnd": "2020-01-01T12:00:00Z",
  "paymentMethods": [
    {
      "type": "CreditCard"
    }
  ],
  "warnings": [
    "List of validation errors and warnings"
  ]
}

Create
POST/v1/carts

Creates a cart for an existing customer (or guest account) when customerId given or creates a cart along with a new guest account when email is given.

Request Definition
attributes
customerId
number, optional
Customer ID.
email
string, optional
Customer e-mail.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
referenceNumber
string, optional
Order reference number.
orderState
string, optional
Order State.
shippingState
string, optional
Shipping state.
paymentState
string, optional
Credit Card payment state.
lineItems
object
Line items with different types.
adjustments
array, optional
Order adjustments.
fraudScore
number, optional
Fraud score.
customer
object
Associated customer.
totals
object
Order totals.
shippingMethod
object
Shipping method.
shippingAddress
object
Shipping address.
remorsePeriodEnd
string, optional
Remorse period end.
paymentMethods
array, optional
Order payment.
warnings
array, optional
Warnings.

POST https://developer.foxcommerce.com/v1/carts/ABC-123/checkout
Example Response
{
  "id": 1,
  "referenceNumber": "ABC-123",
  "orderState": "Cart",
  "shippingState": "Cart",
  "paymentState": "Cart",
  "lineItems": {
    "skus": [
      {
        "imagePath": "http://lorempixel.com/75/75/fashion",
        "referenceNumber": "ABC-123",
        "name": "donkey product",
        "sku": "SKU-YAX",
        "price": 33,
        "quantity": 1,
        "state": "Cart",
        "totalPrice": 33
      }
    ],
    "giftCard": [
      {
        "id": 1,
        "createdAt": "2020-01-01T12:00:00Z",
        "code": "ABC-123",
        "originType": "csrAppeasement",
        "subTypeId": 1,
        "state": "onHold",
        "originalBalance": 50,
        "currentBalance": 50,
        "availableBalance": 50,
        "message": "Lorem ipsum",
        "customer": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com",
          "isGuest": false,
          "disabled": false,
          "isBlacklisted": false,
          "createdAt": "2020-01-01T12:00:00Z",
          "groups": [
            {
              "id": 1,
              "name": "Super Awesome Group",
              "type": "dynamic"
            }
          ],
          "storeCreditTotals": {
            "currentBalance": 50,
            "availableBalance": 50
          },
          "totalSales": 100
        },
        "storeAdmin": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com"
        }
      }
    ]
  },
  "adjustments": [
    {
      "id": 1,
      "amount": 10,
      "sourceId": 1,
      "sourceType": "order",
      "reason": "Lorem ipsum"
    }
  ],
  "fraudScore": 0,
  "customer": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com",
    "isGuest": false,
    "disabled": false,
    "isBlacklisted": false,
    "createdAt": "2020-01-01T12:00:00Z",
    "groups": [
      {
        "id": 1,
        "name": "Super Awesome Group",
        "type": "dynamic"
      }
    ],
    "storeCreditTotals": {
      "currentBalance": 50,
      "availableBalance": 50
    },
    "totalSales": 100
  },
  "totals": {
    "subTotal": 100,
    "taxes": 50,
    "shipping": 5,
    "adjustments": 50,
    "total": 100
  },
  "shippingMethod": {
    "id": 1,
    "name": "UPS Ground",
    "price": 10,
    "isEnabled": true
  },
  "shippingAddress": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555",
    "isDefault": false
  },
  "remorsePeriodEnd": "2020-01-01T12:00:00Z",
  "paymentMethods": [
    {
      "type": "CreditCard"
    }
  ],
  "warnings": [
    "List of validation errors and warnings"
  ]
}

Checkout
POST/v1/carts/{refNum}/checkout

Place order from cart with provided reference number.

URI Parameters
HideShow
refNum
string (required) Example: ABC-123

Cart reference number

Response Definition
attributes
id
number, optional
Unique identifier.
referenceNumber
string, optional
Order reference number.
orderState
string, optional
Order State.
shippingState
string, optional
Shipping state.
paymentState
string, optional
Credit Card payment state.
lineItems
object
Line items with different types.
adjustments
array, optional
Order adjustments.
fraudScore
number, optional
Fraud score.
customer
object
Associated customer.
totals
object
Order totals.
shippingMethod
object
Shipping method.
shippingAddress
object
Shipping address.
remorsePeriodEnd
string, optional
Remorse period end.
paymentMethods
array, optional
Order payment.
warnings
array, optional
Warnings.

SKU Line Items

POST https://developer.foxcommerce.com/v1/carts/ABC-123/line-items
Example Request
[
  {
    "sku": "SKU-YAX",
    "quantity": 5
  }
]
Example Response
{
  "id": 1,
  "referenceNumber": "ABC-123",
  "orderState": "Cart",
  "shippingState": "Cart",
  "paymentState": "Cart",
  "lineItems": {
    "skus": [
      {
        "imagePath": "http://lorempixel.com/75/75/fashion",
        "referenceNumber": "ABC-123",
        "name": "donkey product",
        "sku": "SKU-YAX",
        "price": 33,
        "quantity": 1,
        "state": "Cart",
        "totalPrice": 33
      }
    ],
    "giftCard": [
      {
        "id": 1,
        "createdAt": "2020-01-01T12:00:00Z",
        "code": "ABC-123",
        "originType": "csrAppeasement",
        "subTypeId": 1,
        "state": "onHold",
        "originalBalance": 50,
        "currentBalance": 50,
        "availableBalance": 50,
        "message": "Lorem ipsum",
        "customer": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com",
          "isGuest": false,
          "disabled": false,
          "isBlacklisted": false,
          "createdAt": "2020-01-01T12:00:00Z",
          "groups": [
            {
              "id": 1,
              "name": "Super Awesome Group",
              "type": "dynamic"
            }
          ],
          "storeCreditTotals": {
            "currentBalance": 50,
            "availableBalance": 50
          },
          "totalSales": 100
        },
        "storeAdmin": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com"
        }
      }
    ]
  },
  "adjustments": [
    {
      "id": 1,
      "amount": 10,
      "sourceId": 1,
      "sourceType": "order",
      "reason": "Lorem ipsum"
    }
  ],
  "fraudScore": 0,
  "customer": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com",
    "isGuest": false,
    "disabled": false,
    "isBlacklisted": false,
    "createdAt": "2020-01-01T12:00:00Z",
    "groups": [
      {
        "id": 1,
        "name": "Super Awesome Group",
        "type": "dynamic"
      }
    ],
    "storeCreditTotals": {
      "currentBalance": 50,
      "availableBalance": 50
    },
    "totalSales": 100
  },
  "totals": {
    "subTotal": 100,
    "taxes": 50,
    "shipping": 5,
    "adjustments": 50,
    "total": 100
  },
  "shippingMethod": {
    "id": 1,
    "name": "UPS Ground",
    "price": 10,
    "isEnabled": true
  },
  "shippingAddress": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555",
    "isDefault": false
  },
  "remorsePeriodEnd": "2020-01-01T12:00:00Z",
  "paymentMethods": [
    {
      "type": "CreditCard"
    }
  ],
  "warnings": [
    "List of validation errors and warnings"
  ]
}

Set SKU Line Items
POST/v1/carts/{refNum}/line-items

Set the number of line items. Upon completion, cart line items will match the quantities in this payload.

URI Parameters
HideShow
refNum
string (required) Example: ABC-123

Cart referenceNumber.

Request Definition
attributes
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
referenceNumber
string, optional
Order reference number.
orderState
string, optional
Order State.
shippingState
string, optional
Shipping state.
paymentState
string, optional
Credit Card payment state.
lineItems
object
Line items with different types.
adjustments
array, optional
Order adjustments.
fraudScore
number, optional
Fraud score.
customer
object
Associated customer.
totals
object
Order totals.
shippingMethod
object
Shipping method.
shippingAddress
object
Shipping address.
remorsePeriodEnd
string, optional
Remorse period end.
paymentMethods
array, optional
Order payment.
warnings
array, optional
Warnings.

PATCH https://developer.foxcommerce.com/v1/carts/ABC-123/line-items
Example Request
[
  {
    "sku": "SKU-YAX",
    "quantity": 5
  }
]
Example Response
{
  "id": 1,
  "referenceNumber": "ABC-123",
  "orderState": "Cart",
  "shippingState": "Cart",
  "paymentState": "Cart",
  "lineItems": {
    "skus": [
      {
        "imagePath": "http://lorempixel.com/75/75/fashion",
        "referenceNumber": "ABC-123",
        "name": "donkey product",
        "sku": "SKU-YAX",
        "price": 33,
        "quantity": 1,
        "state": "Cart",
        "totalPrice": 33
      }
    ],
    "giftCard": [
      {
        "id": 1,
        "createdAt": "2020-01-01T12:00:00Z",
        "code": "ABC-123",
        "originType": "csrAppeasement",
        "subTypeId": 1,
        "state": "onHold",
        "originalBalance": 50,
        "currentBalance": 50,
        "availableBalance": 50,
        "message": "Lorem ipsum",
        "customer": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com",
          "isGuest": false,
          "disabled": false,
          "isBlacklisted": false,
          "createdAt": "2020-01-01T12:00:00Z",
          "groups": [
            {
              "id": 1,
              "name": "Super Awesome Group",
              "type": "dynamic"
            }
          ],
          "storeCreditTotals": {
            "currentBalance": 50,
            "availableBalance": 50
          },
          "totalSales": 100
        },
        "storeAdmin": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com"
        }
      }
    ]
  },
  "adjustments": [
    {
      "id": 1,
      "amount": 10,
      "sourceId": 1,
      "sourceType": "order",
      "reason": "Lorem ipsum"
    }
  ],
  "fraudScore": 0,
  "customer": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com",
    "isGuest": false,
    "disabled": false,
    "isBlacklisted": false,
    "createdAt": "2020-01-01T12:00:00Z",
    "groups": [
      {
        "id": 1,
        "name": "Super Awesome Group",
        "type": "dynamic"
      }
    ],
    "storeCreditTotals": {
      "currentBalance": 50,
      "availableBalance": 50
    },
    "totalSales": 100
  },
  "totals": {
    "subTotal": 100,
    "taxes": 50,
    "shipping": 5,
    "adjustments": 50,
    "total": 100
  },
  "shippingMethod": {
    "id": 1,
    "name": "UPS Ground",
    "price": 10,
    "isEnabled": true
  },
  "shippingAddress": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555",
    "isDefault": false
  },
  "remorsePeriodEnd": "2020-01-01T12:00:00Z",
  "paymentMethods": [
    {
      "type": "CreditCard"
    }
  ],
  "warnings": [
    "List of validation errors and warnings"
  ]
}

Update SKU Line Items
PATCH/v1/carts/{refNum}/line-items

Add to or remove from the number of line items that are currently stored in your cart.

URI Parameters
HideShow
refNum
string (required) Example: ABC-123

Cart referenceNumber.

Request Definition
attributes
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
referenceNumber
string, optional
Order reference number.
orderState
string, optional
Order State.
shippingState
string, optional
Shipping state.
paymentState
string, optional
Credit Card payment state.
lineItems
object
Line items with different types.
adjustments
array, optional
Order adjustments.
fraudScore
number, optional
Fraud score.
customer
object
Associated customer.
totals
object
Order totals.
shippingMethod
object
Shipping method.
shippingAddress
object
Shipping address.
remorsePeriodEnd
string, optional
Remorse period end.
paymentMethods
array, optional
Order payment.
warnings
array, optional
Warnings.

Gift Card Line Items

POST https://developer.foxcommerce.com/v1/carts/ABC-123/gift-cards
Example Request
{
  "balance": 10,
  "reasonId": 1,
  "currency": "USD",
  "subTypeId": 1
}
Example Response
{
  "id": 1,
  "referenceNumber": "ABC-123",
  "orderState": "Cart",
  "shippingState": "Cart",
  "paymentState": "Cart",
  "lineItems": {
    "skus": [
      {
        "imagePath": "http://lorempixel.com/75/75/fashion",
        "referenceNumber": "ABC-123",
        "name": "donkey product",
        "sku": "SKU-YAX",
        "price": 33,
        "quantity": 1,
        "state": "Cart",
        "totalPrice": 33
      }
    ],
    "giftCard": [
      {
        "id": 1,
        "createdAt": "2020-01-01T12:00:00Z",
        "code": "ABC-123",
        "originType": "csrAppeasement",
        "subTypeId": 1,
        "state": "onHold",
        "originalBalance": 50,
        "currentBalance": 50,
        "availableBalance": 50,
        "message": "Lorem ipsum",
        "customer": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com",
          "isGuest": false,
          "disabled": false,
          "isBlacklisted": false,
          "createdAt": "2020-01-01T12:00:00Z",
          "groups": [
            {
              "id": 1,
              "name": "Super Awesome Group",
              "type": "dynamic"
            }
          ],
          "storeCreditTotals": {
            "currentBalance": 50,
            "availableBalance": 50
          },
          "totalSales": 100
        },
        "storeAdmin": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com"
        }
      }
    ]
  },
  "adjustments": [
    {
      "id": 1,
      "amount": 10,
      "sourceId": 1,
      "sourceType": "order",
      "reason": "Lorem ipsum"
    }
  ],
  "fraudScore": 0,
  "customer": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com",
    "isGuest": false,
    "disabled": false,
    "isBlacklisted": false,
    "createdAt": "2020-01-01T12:00:00Z",
    "groups": [
      {
        "id": 1,
        "name": "Super Awesome Group",
        "type": "dynamic"
      }
    ],
    "storeCreditTotals": {
      "currentBalance": 50,
      "availableBalance": 50
    },
    "totalSales": 100
  },
  "totals": {
    "subTotal": 100,
    "taxes": 50,
    "shipping": 5,
    "adjustments": 50,
    "total": 100
  },
  "shippingMethod": {
    "id": 1,
    "name": "UPS Ground",
    "price": 10,
    "isEnabled": true
  },
  "shippingAddress": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555",
    "isDefault": false
  },
  "remorsePeriodEnd": "2020-01-01T12:00:00Z",
  "paymentMethods": [
    {
      "type": "CreditCard"
    }
  ],
  "warnings": [
    "List of validation errors and warnings"
  ]
}

Add
POST/v1/carts/{refNum}/gift-cards

URI Parameters
HideShow
refNum
string (required) Example: ABC-123

Cart referenceNumber.

Request Definition
attributes
balance
number, optional
Gift card balance.
reasonId
number, optional
Reason ID for generation.
currency
string, optional
Gift card currency.
subTypeId
number, optional
Possible subtype ID.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
referenceNumber
string, optional
Order reference number.
orderState
string, optional
Order State.
shippingState
string, optional
Shipping state.
paymentState
string, optional
Credit Card payment state.
lineItems
object
Line items with different types.
adjustments
array, optional
Order adjustments.
fraudScore
number, optional
Fraud score.
customer
object
Associated customer.
totals
object
Order totals.
shippingMethod
object
Shipping method.
shippingAddress
object
Shipping address.
remorsePeriodEnd
string, optional
Remorse period end.
paymentMethods
array, optional
Order payment.
warnings
array, optional
Warnings.

PATCH https://developer.foxcommerce.com/v1/carts/ABC-123/gift-cards/ABC-123
Example Request
{
  "balance": 10,
  "reasonId": 1,
  "currency": "USD",
  "subTypeId": 1
}
Example Response
{
  "id": 1,
  "referenceNumber": "ABC-123",
  "orderState": "Cart",
  "shippingState": "Cart",
  "paymentState": "Cart",
  "lineItems": {
    "skus": [
      {
        "imagePath": "http://lorempixel.com/75/75/fashion",
        "referenceNumber": "ABC-123",
        "name": "donkey product",
        "sku": "SKU-YAX",
        "price": 33,
        "quantity": 1,
        "state": "Cart",
        "totalPrice": 33
      }
    ],
    "giftCard": [
      {
        "id": 1,
        "createdAt": "2020-01-01T12:00:00Z",
        "code": "ABC-123",
        "originType": "csrAppeasement",
        "subTypeId": 1,
        "state": "onHold",
        "originalBalance": 50,
        "currentBalance": 50,
        "availableBalance": 50,
        "message": "Lorem ipsum",
        "customer": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com",
          "isGuest": false,
          "disabled": false,
          "isBlacklisted": false,
          "createdAt": "2020-01-01T12:00:00Z",
          "groups": [
            {
              "id": 1,
              "name": "Super Awesome Group",
              "type": "dynamic"
            }
          ],
          "storeCreditTotals": {
            "currentBalance": 50,
            "availableBalance": 50
          },
          "totalSales": 100
        },
        "storeAdmin": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com"
        }
      }
    ]
  },
  "adjustments": [
    {
      "id": 1,
      "amount": 10,
      "sourceId": 1,
      "sourceType": "order",
      "reason": "Lorem ipsum"
    }
  ],
  "fraudScore": 0,
  "customer": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com",
    "isGuest": false,
    "disabled": false,
    "isBlacklisted": false,
    "createdAt": "2020-01-01T12:00:00Z",
    "groups": [
      {
        "id": 1,
        "name": "Super Awesome Group",
        "type": "dynamic"
      }
    ],
    "storeCreditTotals": {
      "currentBalance": 50,
      "availableBalance": 50
    },
    "totalSales": 100
  },
  "totals": {
    "subTotal": 100,
    "taxes": 50,
    "shipping": 5,
    "adjustments": 50,
    "total": 100
  },
  "shippingMethod": {
    "id": 1,
    "name": "UPS Ground",
    "price": 10,
    "isEnabled": true
  },
  "shippingAddress": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555",
    "isDefault": false
  },
  "remorsePeriodEnd": "2020-01-01T12:00:00Z",
  "paymentMethods": [
    {
      "type": "CreditCard"
    }
  ],
  "warnings": [
    "List of validation errors and warnings"
  ]
}

Edit
PATCH/v1/carts/{refNum}/gift-cards/{code}

URI Parameters
HideShow
refNum
string (required) Example: ABC-123

Cart referenceNumber.

code
string (required) Example: ABC-123

Gift Card code.

Request Definition
attributes
balance
number, optional
Gift card balance.
reasonId
number, optional
Reason ID for generation.
currency
string, optional
Gift card currency.
subTypeId
number, optional
Possible subtype ID.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
referenceNumber
string, optional
Order reference number.
orderState
string, optional
Order State.
shippingState
string, optional
Shipping state.
paymentState
string, optional
Credit Card payment state.
lineItems
object
Line items with different types.
adjustments
array, optional
Order adjustments.
fraudScore
number, optional
Fraud score.
customer
object
Associated customer.
totals
object
Order totals.
shippingMethod
object
Shipping method.
shippingAddress
object
Shipping address.
remorsePeriodEnd
string, optional
Remorse period end.
paymentMethods
array, optional
Order payment.
warnings
array, optional
Warnings.

DELETE https://developer.foxcommerce.com/v1/carts/ABC-123/gift-cards/ABC-123
Example Response
{
  "id": 1,
  "referenceNumber": "ABC-123",
  "orderState": "Cart",
  "shippingState": "Cart",
  "paymentState": "Cart",
  "lineItems": {
    "skus": [
      {
        "imagePath": "http://lorempixel.com/75/75/fashion",
        "referenceNumber": "ABC-123",
        "name": "donkey product",
        "sku": "SKU-YAX",
        "price": 33,
        "quantity": 1,
        "state": "Cart",
        "totalPrice": 33
      }
    ],
    "giftCard": [
      {
        "id": 1,
        "createdAt": "2020-01-01T12:00:00Z",
        "code": "ABC-123",
        "originType": "csrAppeasement",
        "subTypeId": 1,
        "state": "onHold",
        "originalBalance": 50,
        "currentBalance": 50,
        "availableBalance": 50,
        "message": "Lorem ipsum",
        "customer": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com",
          "isGuest": false,
          "disabled": false,
          "isBlacklisted": false,
          "createdAt": "2020-01-01T12:00:00Z",
          "groups": [
            {
              "id": 1,
              "name": "Super Awesome Group",
              "type": "dynamic"
            }
          ],
          "storeCreditTotals": {
            "currentBalance": 50,
            "availableBalance": 50
          },
          "totalSales": 100
        },
        "storeAdmin": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com"
        }
      }
    ]
  },
  "adjustments": [
    {
      "id": 1,
      "amount": 10,
      "sourceId": 1,
      "sourceType": "order",
      "reason": "Lorem ipsum"
    }
  ],
  "fraudScore": 0,
  "customer": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com",
    "isGuest": false,
    "disabled": false,
    "isBlacklisted": false,
    "createdAt": "2020-01-01T12:00:00Z",
    "groups": [
      {
        "id": 1,
        "name": "Super Awesome Group",
        "type": "dynamic"
      }
    ],
    "storeCreditTotals": {
      "currentBalance": 50,
      "availableBalance": 50
    },
    "totalSales": 100
  },
  "totals": {
    "subTotal": 100,
    "taxes": 50,
    "shipping": 5,
    "adjustments": 50,
    "total": 100
  },
  "shippingMethod": {
    "id": 1,
    "name": "UPS Ground",
    "price": 10,
    "isEnabled": true
  },
  "shippingAddress": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555",
    "isDefault": false
  },
  "remorsePeriodEnd": "2020-01-01T12:00:00Z",
  "paymentMethods": [
    {
      "type": "CreditCard"
    }
  ],
  "warnings": [
    "List of validation errors and warnings"
  ]
}

Delete
DELETE/v1/carts/{refNum}/gift-cards/{code}

URI Parameters
HideShow
refNum
string (required) Example: ABC-123

Cart referenceNumber.

code
string (required) Example: ABC-123

Gift Card code.

Response Definition
attributes
id
number, optional
Unique identifier.
referenceNumber
string, optional
Order reference number.
orderState
string, optional
Order State.
shippingState
string, optional
Shipping state.
paymentState
string, optional
Credit Card payment state.
lineItems
object
Line items with different types.
adjustments
array, optional
Order adjustments.
fraudScore
number, optional
Fraud score.
customer
object
Associated customer.
totals
object
Order totals.
shippingMethod
object
Shipping method.
shippingAddress
object
Shipping address.
remorsePeriodEnd
string, optional
Remorse period end.
paymentMethods
array, optional
Order payment.
warnings
array, optional
Warnings.

Credit Card Payments

POST https://developer.foxcommerce.com/v1/carts/ABC-123/payment-methods/credit-cards
Example Request
{
  "creditCardId": 1
}
Example Response
{
  "id": 1,
  "referenceNumber": "ABC-123",
  "orderState": "Cart",
  "shippingState": "Cart",
  "paymentState": "Cart",
  "lineItems": {
    "skus": [
      {
        "imagePath": "http://lorempixel.com/75/75/fashion",
        "referenceNumber": "ABC-123",
        "name": "donkey product",
        "sku": "SKU-YAX",
        "price": 33,
        "quantity": 1,
        "state": "Cart",
        "totalPrice": 33
      }
    ],
    "giftCard": [
      {
        "id": 1,
        "createdAt": "2020-01-01T12:00:00Z",
        "code": "ABC-123",
        "originType": "csrAppeasement",
        "subTypeId": 1,
        "state": "onHold",
        "originalBalance": 50,
        "currentBalance": 50,
        "availableBalance": 50,
        "message": "Lorem ipsum",
        "customer": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com",
          "isGuest": false,
          "disabled": false,
          "isBlacklisted": false,
          "createdAt": "2020-01-01T12:00:00Z",
          "groups": [
            {
              "id": 1,
              "name": "Super Awesome Group",
              "type": "dynamic"
            }
          ],
          "storeCreditTotals": {
            "currentBalance": 50,
            "availableBalance": 50
          },
          "totalSales": 100
        },
        "storeAdmin": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com"
        }
      }
    ]
  },
  "adjustments": [
    {
      "id": 1,
      "amount": 10,
      "sourceId": 1,
      "sourceType": "order",
      "reason": "Lorem ipsum"
    }
  ],
  "fraudScore": 0,
  "customer": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com",
    "isGuest": false,
    "disabled": false,
    "isBlacklisted": false,
    "createdAt": "2020-01-01T12:00:00Z",
    "groups": [
      {
        "id": 1,
        "name": "Super Awesome Group",
        "type": "dynamic"
      }
    ],
    "storeCreditTotals": {
      "currentBalance": 50,
      "availableBalance": 50
    },
    "totalSales": 100
  },
  "totals": {
    "subTotal": 100,
    "taxes": 50,
    "shipping": 5,
    "adjustments": 50,
    "total": 100
  },
  "shippingMethod": {
    "id": 1,
    "name": "UPS Ground",
    "price": 10,
    "isEnabled": true
  },
  "shippingAddress": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555",
    "isDefault": false
  },
  "remorsePeriodEnd": "2020-01-01T12:00:00Z",
  "paymentMethods": [
    {
      "type": "CreditCard"
    }
  ],
  "warnings": [
    "List of validation errors and warnings"
  ]
}

Add
POST/v1/carts/{refNum}/payment-methods/credit-cards

URI Parameters
HideShow
refNum
string (required) Example: ABC-123

Cart reference number

Request Definition
attributes
creditCardId
number, optional
Credit Card ID
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
referenceNumber
string, optional
Order reference number.
orderState
string, optional
Order State.
shippingState
string, optional
Shipping state.
paymentState
string, optional
Credit Card payment state.
lineItems
object
Line items with different types.
adjustments
array, optional
Order adjustments.
fraudScore
number, optional
Fraud score.
customer
object
Associated customer.
totals
object
Order totals.
shippingMethod
object
Shipping method.
shippingAddress
object
Shipping address.
remorsePeriodEnd
string, optional
Remorse period end.
paymentMethods
array, optional
Order payment.
warnings
array, optional
Warnings.

DELETE https://developer.foxcommerce.com/v1/carts/ABC-123/payment-methods/credit-cards
Example Response
{
  "id": 1,
  "referenceNumber": "ABC-123",
  "orderState": "Cart",
  "shippingState": "Cart",
  "paymentState": "Cart",
  "lineItems": {
    "skus": [
      {
        "imagePath": "http://lorempixel.com/75/75/fashion",
        "referenceNumber": "ABC-123",
        "name": "donkey product",
        "sku": "SKU-YAX",
        "price": 33,
        "quantity": 1,
        "state": "Cart",
        "totalPrice": 33
      }
    ],
    "giftCard": [
      {
        "id": 1,
        "createdAt": "2020-01-01T12:00:00Z",
        "code": "ABC-123",
        "originType": "csrAppeasement",
        "subTypeId": 1,
        "state": "onHold",
        "originalBalance": 50,
        "currentBalance": 50,
        "availableBalance": 50,
        "message": "Lorem ipsum",
        "customer": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com",
          "isGuest": false,
          "disabled": false,
          "isBlacklisted": false,
          "createdAt": "2020-01-01T12:00:00Z",
          "groups": [
            {
              "id": 1,
              "name": "Super Awesome Group",
              "type": "dynamic"
            }
          ],
          "storeCreditTotals": {
            "currentBalance": 50,
            "availableBalance": 50
          },
          "totalSales": 100
        },
        "storeAdmin": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com"
        }
      }
    ]
  },
  "adjustments": [
    {
      "id": 1,
      "amount": 10,
      "sourceId": 1,
      "sourceType": "order",
      "reason": "Lorem ipsum"
    }
  ],
  "fraudScore": 0,
  "customer": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com",
    "isGuest": false,
    "disabled": false,
    "isBlacklisted": false,
    "createdAt": "2020-01-01T12:00:00Z",
    "groups": [
      {
        "id": 1,
        "name": "Super Awesome Group",
        "type": "dynamic"
      }
    ],
    "storeCreditTotals": {
      "currentBalance": 50,
      "availableBalance": 50
    },
    "totalSales": 100
  },
  "totals": {
    "subTotal": 100,
    "taxes": 50,
    "shipping": 5,
    "adjustments": 50,
    "total": 100
  },
  "shippingMethod": {
    "id": 1,
    "name": "UPS Ground",
    "price": 10,
    "isEnabled": true
  },
  "shippingAddress": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555",
    "isDefault": false
  },
  "remorsePeriodEnd": "2020-01-01T12:00:00Z",
  "paymentMethods": [
    {
      "type": "CreditCard"
    }
  ],
  "warnings": [
    "List of validation errors and warnings"
  ]
}

Delete
DELETE/v1/carts/{refNum}/payment-methods/credit-cards

URI Parameters
HideShow
refNum
string (required) Example: ABC-123

Cart reference number

Response Definition
attributes
id
number, optional
Unique identifier.
referenceNumber
string, optional
Order reference number.
orderState
string, optional
Order State.
shippingState
string, optional
Shipping state.
paymentState
string, optional
Credit Card payment state.
lineItems
object
Line items with different types.
adjustments
array, optional
Order adjustments.
fraudScore
number, optional
Fraud score.
customer
object
Associated customer.
totals
object
Order totals.
shippingMethod
object
Shipping method.
shippingAddress
object
Shipping address.
remorsePeriodEnd
string, optional
Remorse period end.
paymentMethods
array, optional
Order payment.
warnings
array, optional
Warnings.

Gift Card Payments

POST https://developer.foxcommerce.com/v1/carts/ABC-123/payment-methods/gift-cards
Example Request
{
  "code": "ABC-123",
  "amount": 10
}
Example Response
{
  "id": 1,
  "referenceNumber": "ABC-123",
  "orderState": "Cart",
  "shippingState": "Cart",
  "paymentState": "Cart",
  "lineItems": {
    "skus": [
      {
        "imagePath": "http://lorempixel.com/75/75/fashion",
        "referenceNumber": "ABC-123",
        "name": "donkey product",
        "sku": "SKU-YAX",
        "price": 33,
        "quantity": 1,
        "state": "Cart",
        "totalPrice": 33
      }
    ],
    "giftCard": [
      {
        "id": 1,
        "createdAt": "2020-01-01T12:00:00Z",
        "code": "ABC-123",
        "originType": "csrAppeasement",
        "subTypeId": 1,
        "state": "onHold",
        "originalBalance": 50,
        "currentBalance": 50,
        "availableBalance": 50,
        "message": "Lorem ipsum",
        "customer": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com",
          "isGuest": false,
          "disabled": false,
          "isBlacklisted": false,
          "createdAt": "2020-01-01T12:00:00Z",
          "groups": [
            {
              "id": 1,
              "name": "Super Awesome Group",
              "type": "dynamic"
            }
          ],
          "storeCreditTotals": {
            "currentBalance": 50,
            "availableBalance": 50
          },
          "totalSales": 100
        },
        "storeAdmin": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com"
        }
      }
    ]
  },
  "adjustments": [
    {
      "id": 1,
      "amount": 10,
      "sourceId": 1,
      "sourceType": "order",
      "reason": "Lorem ipsum"
    }
  ],
  "fraudScore": 0,
  "customer": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com",
    "isGuest": false,
    "disabled": false,
    "isBlacklisted": false,
    "createdAt": "2020-01-01T12:00:00Z",
    "groups": [
      {
        "id": 1,
        "name": "Super Awesome Group",
        "type": "dynamic"
      }
    ],
    "storeCreditTotals": {
      "currentBalance": 50,
      "availableBalance": 50
    },
    "totalSales": 100
  },
  "totals": {
    "subTotal": 100,
    "taxes": 50,
    "shipping": 5,
    "adjustments": 50,
    "total": 100
  },
  "shippingMethod": {
    "id": 1,
    "name": "UPS Ground",
    "price": 10,
    "isEnabled": true
  },
  "shippingAddress": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555",
    "isDefault": false
  },
  "remorsePeriodEnd": "2020-01-01T12:00:00Z",
  "paymentMethods": [
    {
      "type": "CreditCard"
    }
  ],
  "warnings": [
    "List of validation errors and warnings"
  ]
}

Add
POST/v1/carts/{refNum}/payment-methods/gift-cards

URI Parameters
HideShow
refNum
string (required) Example: ABC-123

Cart reference number

Request Definition
attributes
code
string, optional
Gift card code.
amount
number, optional
Amount to pay.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
referenceNumber
string, optional
Order reference number.
orderState
string, optional
Order State.
shippingState
string, optional
Shipping state.
paymentState
string, optional
Credit Card payment state.
lineItems
object
Line items with different types.
adjustments
array, optional
Order adjustments.
fraudScore
number, optional
Fraud score.
customer
object
Associated customer.
totals
object
Order totals.
shippingMethod
object
Shipping method.
shippingAddress
object
Shipping address.
remorsePeriodEnd
string, optional
Remorse period end.
paymentMethods
array, optional
Order payment.
warnings
array, optional
Warnings.

PATCH https://developer.foxcommerce.com/v1/carts/ABC-123/payment-methods/gift-cards
Example Request
{
  "code": "ABC-123",
  "amount": 10
}
Example Response
{
  "id": 1,
  "referenceNumber": "ABC-123",
  "orderState": "Cart",
  "shippingState": "Cart",
  "paymentState": "Cart",
  "lineItems": {
    "skus": [
      {
        "imagePath": "http://lorempixel.com/75/75/fashion",
        "referenceNumber": "ABC-123",
        "name": "donkey product",
        "sku": "SKU-YAX",
        "price": 33,
        "quantity": 1,
        "state": "Cart",
        "totalPrice": 33
      }
    ],
    "giftCard": [
      {
        "id": 1,
        "createdAt": "2020-01-01T12:00:00Z",
        "code": "ABC-123",
        "originType": "csrAppeasement",
        "subTypeId": 1,
        "state": "onHold",
        "originalBalance": 50,
        "currentBalance": 50,
        "availableBalance": 50,
        "message": "Lorem ipsum",
        "customer": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com",
          "isGuest": false,
          "disabled": false,
          "isBlacklisted": false,
          "createdAt": "2020-01-01T12:00:00Z",
          "groups": [
            {
              "id": 1,
              "name": "Super Awesome Group",
              "type": "dynamic"
            }
          ],
          "storeCreditTotals": {
            "currentBalance": 50,
            "availableBalance": 50
          },
          "totalSales": 100
        },
        "storeAdmin": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com"
        }
      }
    ]
  },
  "adjustments": [
    {
      "id": 1,
      "amount": 10,
      "sourceId": 1,
      "sourceType": "order",
      "reason": "Lorem ipsum"
    }
  ],
  "fraudScore": 0,
  "customer": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com",
    "isGuest": false,
    "disabled": false,
    "isBlacklisted": false,
    "createdAt": "2020-01-01T12:00:00Z",
    "groups": [
      {
        "id": 1,
        "name": "Super Awesome Group",
        "type": "dynamic"
      }
    ],
    "storeCreditTotals": {
      "currentBalance": 50,
      "availableBalance": 50
    },
    "totalSales": 100
  },
  "totals": {
    "subTotal": 100,
    "taxes": 50,
    "shipping": 5,
    "adjustments": 50,
    "total": 100
  },
  "shippingMethod": {
    "id": 1,
    "name": "UPS Ground",
    "price": 10,
    "isEnabled": true
  },
  "shippingAddress": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555",
    "isDefault": false
  },
  "remorsePeriodEnd": "2020-01-01T12:00:00Z",
  "paymentMethods": [
    {
      "type": "CreditCard"
    }
  ],
  "warnings": [
    "List of validation errors and warnings"
  ]
}

Edit
PATCH/v1/carts/{refNum}/payment-methods/gift-cards

URI Parameters
HideShow
refNum
string (required) Example: ABC-123

Cart reference number

Request Definition
attributes
code
string, optional
Gift card code.
amount
number, optional
Amount to pay.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
referenceNumber
string, optional
Order reference number.
orderState
string, optional
Order State.
shippingState
string, optional
Shipping state.
paymentState
string, optional
Credit Card payment state.
lineItems
object
Line items with different types.
adjustments
array, optional
Order adjustments.
fraudScore
number, optional
Fraud score.
customer
object
Associated customer.
totals
object
Order totals.
shippingMethod
object
Shipping method.
shippingAddress
object
Shipping address.
remorsePeriodEnd
string, optional
Remorse period end.
paymentMethods
array, optional
Order payment.
warnings
array, optional
Warnings.

DELETE https://developer.foxcommerce.com/v1/carts/ABC-123/payment-methods/gift-cards/ABC-123
Example Response
{
  "id": 1,
  "referenceNumber": "ABC-123",
  "orderState": "Cart",
  "shippingState": "Cart",
  "paymentState": "Cart",
  "lineItems": {
    "skus": [
      {
        "imagePath": "http://lorempixel.com/75/75/fashion",
        "referenceNumber": "ABC-123",
        "name": "donkey product",
        "sku": "SKU-YAX",
        "price": 33,
        "quantity": 1,
        "state": "Cart",
        "totalPrice": 33
      }
    ],
    "giftCard": [
      {
        "id": 1,
        "createdAt": "2020-01-01T12:00:00Z",
        "code": "ABC-123",
        "originType": "csrAppeasement",
        "subTypeId": 1,
        "state": "onHold",
        "originalBalance": 50,
        "currentBalance": 50,
        "availableBalance": 50,
        "message": "Lorem ipsum",
        "customer": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com",
          "isGuest": false,
          "disabled": false,
          "isBlacklisted": false,
          "createdAt": "2020-01-01T12:00:00Z",
          "groups": [
            {
              "id": 1,
              "name": "Super Awesome Group",
              "type": "dynamic"
            }
          ],
          "storeCreditTotals": {
            "currentBalance": 50,
            "availableBalance": 50
          },
          "totalSales": 100
        },
        "storeAdmin": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com"
        }
      }
    ]
  },
  "adjustments": [
    {
      "id": 1,
      "amount": 10,
      "sourceId": 1,
      "sourceType": "order",
      "reason": "Lorem ipsum"
    }
  ],
  "fraudScore": 0,
  "customer": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com",
    "isGuest": false,
    "disabled": false,
    "isBlacklisted": false,
    "createdAt": "2020-01-01T12:00:00Z",
    "groups": [
      {
        "id": 1,
        "name": "Super Awesome Group",
        "type": "dynamic"
      }
    ],
    "storeCreditTotals": {
      "currentBalance": 50,
      "availableBalance": 50
    },
    "totalSales": 100
  },
  "totals": {
    "subTotal": 100,
    "taxes": 50,
    "shipping": 5,
    "adjustments": 50,
    "total": 100
  },
  "shippingMethod": {
    "id": 1,
    "name": "UPS Ground",
    "price": 10,
    "isEnabled": true
  },
  "shippingAddress": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555",
    "isDefault": false
  },
  "remorsePeriodEnd": "2020-01-01T12:00:00Z",
  "paymentMethods": [
    {
      "type": "CreditCard"
    }
  ],
  "warnings": [
    "List of validation errors and warnings"
  ]
}

Delete
DELETE/v1/carts/{refNum}/payment-methods/gift-cards/{code}

URI Parameters
HideShow
refNum
string (required) Example: ABC-123

Cart reference number

code
string (required) Example: ABC-123

Gift card code.

Response Definition
attributes
id
number, optional
Unique identifier.
referenceNumber
string, optional
Order reference number.
orderState
string, optional
Order State.
shippingState
string, optional
Shipping state.
paymentState
string, optional
Credit Card payment state.
lineItems
object
Line items with different types.
adjustments
array, optional
Order adjustments.
fraudScore
number, optional
Fraud score.
customer
object
Associated customer.
totals
object
Order totals.
shippingMethod
object
Shipping method.
shippingAddress
object
Shipping address.
remorsePeriodEnd
string, optional
Remorse period end.
paymentMethods
array, optional
Order payment.
warnings
array, optional
Warnings.

Store Credit Payments

POST https://developer.foxcommerce.com/v1/carts/ABC-123/payment-methods/store-credits
Example Request
{
  "amount": 10
}
Example Response
{
  "id": 1,
  "referenceNumber": "ABC-123",
  "orderState": "Cart",
  "shippingState": "Cart",
  "paymentState": "Cart",
  "lineItems": {
    "skus": [
      {
        "imagePath": "http://lorempixel.com/75/75/fashion",
        "referenceNumber": "ABC-123",
        "name": "donkey product",
        "sku": "SKU-YAX",
        "price": 33,
        "quantity": 1,
        "state": "Cart",
        "totalPrice": 33
      }
    ],
    "giftCard": [
      {
        "id": 1,
        "createdAt": "2020-01-01T12:00:00Z",
        "code": "ABC-123",
        "originType": "csrAppeasement",
        "subTypeId": 1,
        "state": "onHold",
        "originalBalance": 50,
        "currentBalance": 50,
        "availableBalance": 50,
        "message": "Lorem ipsum",
        "customer": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com",
          "isGuest": false,
          "disabled": false,
          "isBlacklisted": false,
          "createdAt": "2020-01-01T12:00:00Z",
          "groups": [
            {
              "id": 1,
              "name": "Super Awesome Group",
              "type": "dynamic"
            }
          ],
          "storeCreditTotals": {
            "currentBalance": 50,
            "availableBalance": 50
          },
          "totalSales": 100
        },
        "storeAdmin": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com"
        }
      }
    ]
  },
  "adjustments": [
    {
      "id": 1,
      "amount": 10,
      "sourceId": 1,
      "sourceType": "order",
      "reason": "Lorem ipsum"
    }
  ],
  "fraudScore": 0,
  "customer": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com",
    "isGuest": false,
    "disabled": false,
    "isBlacklisted": false,
    "createdAt": "2020-01-01T12:00:00Z",
    "groups": [
      {
        "id": 1,
        "name": "Super Awesome Group",
        "type": "dynamic"
      }
    ],
    "storeCreditTotals": {
      "currentBalance": 50,
      "availableBalance": 50
    },
    "totalSales": 100
  },
  "totals": {
    "subTotal": 100,
    "taxes": 50,
    "shipping": 5,
    "adjustments": 50,
    "total": 100
  },
  "shippingMethod": {
    "id": 1,
    "name": "UPS Ground",
    "price": 10,
    "isEnabled": true
  },
  "shippingAddress": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555",
    "isDefault": false
  },
  "remorsePeriodEnd": "2020-01-01T12:00:00Z",
  "paymentMethods": [
    {
      "type": "CreditCard"
    }
  ],
  "warnings": [
    "List of validation errors and warnings"
  ]
}

Add
POST/v1/carts/{refNum}/payment-methods/store-credits

URI Parameters
HideShow
refNum
string (required) Example: ABC-123

Cart reference number

Request Definition
attributes
amount
number, optional
Amount to pay.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
referenceNumber
string, optional
Order reference number.
orderState
string, optional
Order State.
shippingState
string, optional
Shipping state.
paymentState
string, optional
Credit Card payment state.
lineItems
object
Line items with different types.
adjustments
array, optional
Order adjustments.
fraudScore
number, optional
Fraud score.
customer
object
Associated customer.
totals
object
Order totals.
shippingMethod
object
Shipping method.
shippingAddress
object
Shipping address.
remorsePeriodEnd
string, optional
Remorse period end.
paymentMethods
array, optional
Order payment.
warnings
array, optional
Warnings.

DELETE https://developer.foxcommerce.com/v1/carts/ABC-123/payment-methods/store-credits
Example Response
{
  "id": 1,
  "referenceNumber": "ABC-123",
  "orderState": "Cart",
  "shippingState": "Cart",
  "paymentState": "Cart",
  "lineItems": {
    "skus": [
      {
        "imagePath": "http://lorempixel.com/75/75/fashion",
        "referenceNumber": "ABC-123",
        "name": "donkey product",
        "sku": "SKU-YAX",
        "price": 33,
        "quantity": 1,
        "state": "Cart",
        "totalPrice": 33
      }
    ],
    "giftCard": [
      {
        "id": 1,
        "createdAt": "2020-01-01T12:00:00Z",
        "code": "ABC-123",
        "originType": "csrAppeasement",
        "subTypeId": 1,
        "state": "onHold",
        "originalBalance": 50,
        "currentBalance": 50,
        "availableBalance": 50,
        "message": "Lorem ipsum",
        "customer": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com",
          "isGuest": false,
          "disabled": false,
          "isBlacklisted": false,
          "createdAt": "2020-01-01T12:00:00Z",
          "groups": [
            {
              "id": 1,
              "name": "Super Awesome Group",
              "type": "dynamic"
            }
          ],
          "storeCreditTotals": {
            "currentBalance": 50,
            "availableBalance": 50
          },
          "totalSales": 100
        },
        "storeAdmin": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com"
        }
      }
    ]
  },
  "adjustments": [
    {
      "id": 1,
      "amount": 10,
      "sourceId": 1,
      "sourceType": "order",
      "reason": "Lorem ipsum"
    }
  ],
  "fraudScore": 0,
  "customer": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com",
    "isGuest": false,
    "disabled": false,
    "isBlacklisted": false,
    "createdAt": "2020-01-01T12:00:00Z",
    "groups": [
      {
        "id": 1,
        "name": "Super Awesome Group",
        "type": "dynamic"
      }
    ],
    "storeCreditTotals": {
      "currentBalance": 50,
      "availableBalance": 50
    },
    "totalSales": 100
  },
  "totals": {
    "subTotal": 100,
    "taxes": 50,
    "shipping": 5,
    "adjustments": 50,
    "total": 100
  },
  "shippingMethod": {
    "id": 1,
    "name": "UPS Ground",
    "price": 10,
    "isEnabled": true
  },
  "shippingAddress": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555",
    "isDefault": false
  },
  "remorsePeriodEnd": "2020-01-01T12:00:00Z",
  "paymentMethods": [
    {
      "type": "CreditCard"
    }
  ],
  "warnings": [
    "List of validation errors and warnings"
  ]
}

Delete
DELETE/v1/carts/{refNum}/payment-methods/store-credits

URI Parameters
HideShow
refNum
string (required) Example: ABC-123

Cart reference number

Response Definition
attributes
id
number, optional
Unique identifier.
referenceNumber
string, optional
Order reference number.
orderState
string, optional
Order State.
shippingState
string, optional
Shipping state.
paymentState
string, optional
Credit Card payment state.
lineItems
object
Line items with different types.
adjustments
array, optional
Order adjustments.
fraudScore
number, optional
Fraud score.
customer
object
Associated customer.
totals
object
Order totals.
shippingMethod
object
Shipping method.
shippingAddress
object
Shipping address.
remorsePeriodEnd
string, optional
Remorse period end.
paymentMethods
array, optional
Order payment.
warnings
array, optional
Warnings.

Shipping Method

Shipping methods are used to describe the ways that the contents of a cart can transported to the customer. All actions that occur against this set of endpoints modify which shipping method is used by the cart.

PATCH https://developer.foxcommerce.com/v1/carts/1/shipping-methods
Example Request
{
  "shippingMethodId": 1
}
Example Response
{
  "id": 1,
  "referenceNumber": "ABC-123",
  "orderState": "Cart",
  "shippingState": "Cart",
  "paymentState": "Cart",
  "lineItems": {
    "skus": [
      {
        "imagePath": "http://lorempixel.com/75/75/fashion",
        "referenceNumber": "ABC-123",
        "name": "donkey product",
        "sku": "SKU-YAX",
        "price": 33,
        "quantity": 1,
        "state": "Cart",
        "totalPrice": 33
      }
    ],
    "giftCard": [
      {
        "id": 1,
        "createdAt": "2020-01-01T12:00:00Z",
        "code": "ABC-123",
        "originType": "csrAppeasement",
        "subTypeId": 1,
        "state": "onHold",
        "originalBalance": 50,
        "currentBalance": 50,
        "availableBalance": 50,
        "message": "Lorem ipsum",
        "customer": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com",
          "isGuest": false,
          "disabled": false,
          "isBlacklisted": false,
          "createdAt": "2020-01-01T12:00:00Z",
          "groups": [
            {
              "id": 1,
              "name": "Super Awesome Group",
              "type": "dynamic"
            }
          ],
          "storeCreditTotals": {
            "currentBalance": 50,
            "availableBalance": 50
          },
          "totalSales": 100
        },
        "storeAdmin": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com"
        }
      }
    ]
  },
  "adjustments": [
    {
      "id": 1,
      "amount": 10,
      "sourceId": 1,
      "sourceType": "order",
      "reason": "Lorem ipsum"
    }
  ],
  "fraudScore": 0,
  "customer": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com",
    "isGuest": false,
    "disabled": false,
    "isBlacklisted": false,
    "createdAt": "2020-01-01T12:00:00Z",
    "groups": [
      {
        "id": 1,
        "name": "Super Awesome Group",
        "type": "dynamic"
      }
    ],
    "storeCreditTotals": {
      "currentBalance": 50,
      "availableBalance": 50
    },
    "totalSales": 100
  },
  "totals": {
    "subTotal": 100,
    "taxes": 50,
    "shipping": 5,
    "adjustments": 50,
    "total": 100
  },
  "shippingMethod": {
    "id": 1,
    "name": "UPS Ground",
    "price": 10,
    "isEnabled": true
  },
  "shippingAddress": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555",
    "isDefault": false
  },
  "remorsePeriodEnd": "2020-01-01T12:00:00Z",
  "paymentMethods": [
    {
      "type": "CreditCard"
    }
  ],
  "warnings": [
    "List of validation errors and warnings"
  ]
}

Update
PATCH/v1/carts/{refNum}/shipping-methods

Changes the shipping method to a cart.

URI Parameters
HideShow
refNum
string (required) Example: 1

Cart referenceNumber

Request Definition
attributes
shippingMethodId
number, optional
Shipping method ID.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
referenceNumber
string, optional
Order reference number.
orderState
string, optional
Order State.
shippingState
string, optional
Shipping state.
paymentState
string, optional
Credit Card payment state.
lineItems
object
Line items with different types.
adjustments
array, optional
Order adjustments.
fraudScore
number, optional
Fraud score.
customer
object
Associated customer.
totals
object
Order totals.
shippingMethod
object
Shipping method.
shippingAddress
object
Shipping address.
remorsePeriodEnd
string, optional
Remorse period end.
paymentMethods
array, optional
Order payment.
warnings
array, optional
Warnings.

DELETE https://developer.foxcommerce.com/v1/carts/1/shipping-methods
Example Response
This response has no content.

Delete
DELETE/v1/carts/{refNum}/shipping-methods

Removes the shipping method from the cart.

URI Parameters
HideShow
refNum
string (required) Example: 1

Cart reference number

Response Definition

Shipping Address

POST https://developer.foxcommerce.com/v1/carts/ABC-123/shipping-address
Example Request
{
  "name": "John Smith",
  "regionId": 1,
  "address1": "555 E Lake Union St.",
  "address2": "Suite 200",
  "city": "Seattle",
  "zip": "98124",
  "isDefault": false,
  "phoneNumber": "555-555-555"
}
Example Response
{
  "id": 1,
  "referenceNumber": "ABC-123",
  "orderState": "Cart",
  "shippingState": "Cart",
  "paymentState": "Cart",
  "lineItems": {
    "skus": [
      {
        "imagePath": "http://lorempixel.com/75/75/fashion",
        "referenceNumber": "ABC-123",
        "name": "donkey product",
        "sku": "SKU-YAX",
        "price": 33,
        "quantity": 1,
        "state": "Cart",
        "totalPrice": 33
      }
    ],
    "giftCard": [
      {
        "id": 1,
        "createdAt": "2020-01-01T12:00:00Z",
        "code": "ABC-123",
        "originType": "csrAppeasement",
        "subTypeId": 1,
        "state": "onHold",
        "originalBalance": 50,
        "currentBalance": 50,
        "availableBalance": 50,
        "message": "Lorem ipsum",
        "customer": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com",
          "isGuest": false,
          "disabled": false,
          "isBlacklisted": false,
          "createdAt": "2020-01-01T12:00:00Z",
          "groups": [
            {
              "id": 1,
              "name": "Super Awesome Group",
              "type": "dynamic"
            }
          ],
          "storeCreditTotals": {
            "currentBalance": 50,
            "availableBalance": 50
          },
          "totalSales": 100
        },
        "storeAdmin": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com"
        }
      }
    ]
  },
  "adjustments": [
    {
      "id": 1,
      "amount": 10,
      "sourceId": 1,
      "sourceType": "order",
      "reason": "Lorem ipsum"
    }
  ],
  "fraudScore": 0,
  "customer": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com",
    "isGuest": false,
    "disabled": false,
    "isBlacklisted": false,
    "createdAt": "2020-01-01T12:00:00Z",
    "groups": [
      {
        "id": 1,
        "name": "Super Awesome Group",
        "type": "dynamic"
      }
    ],
    "storeCreditTotals": {
      "currentBalance": 50,
      "availableBalance": 50
    },
    "totalSales": 100
  },
  "totals": {
    "subTotal": 100,
    "taxes": 50,
    "shipping": 5,
    "adjustments": 50,
    "total": 100
  },
  "shippingMethod": {
    "id": 1,
    "name": "UPS Ground",
    "price": 10,
    "isEnabled": true
  },
  "shippingAddress": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555",
    "isDefault": false
  },
  "remorsePeriodEnd": "2020-01-01T12:00:00Z",
  "paymentMethods": [
    {
      "type": "CreditCard"
    }
  ],
  "warnings": [
    "List of validation errors and warnings"
  ]
}

Add
POST/v1/carts/{refNum}/shipping-address

URI Parameters
HideShow
refNum
string (required) Example: ABC-123

Cart reference number

Request Definition
attributes
name
string, optional
Recipient name.
regionId
number, optional
Region unique ID.
address1
string, optional
Address line 1.
address2
string, optional
Address line 2.
city
string, optional
City.
zip
string, optional
zip/postal code.
isDefault
boolean, optional
Default or not in address book.
phoneNumber
string, optional
Contact phone number.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
referenceNumber
string, optional
Order reference number.
orderState
string, optional
Order State.
shippingState
string, optional
Shipping state.
paymentState
string, optional
Credit Card payment state.
lineItems
object
Line items with different types.
adjustments
array, optional
Order adjustments.
fraudScore
number, optional
Fraud score.
customer
object
Associated customer.
totals
object
Order totals.
shippingMethod
object
Shipping method.
shippingAddress
object
Shipping address.
remorsePeriodEnd
string, optional
Remorse period end.
paymentMethods
array, optional
Order payment.
warnings
array, optional
Warnings.

PATCH https://developer.foxcommerce.com/v1/carts/ABC-123/shipping-address/1
Example Response
{
  "id": 1,
  "referenceNumber": "ABC-123",
  "orderState": "Cart",
  "shippingState": "Cart",
  "paymentState": "Cart",
  "lineItems": {
    "skus": [
      {
        "imagePath": "http://lorempixel.com/75/75/fashion",
        "referenceNumber": "ABC-123",
        "name": "donkey product",
        "sku": "SKU-YAX",
        "price": 33,
        "quantity": 1,
        "state": "Cart",
        "totalPrice": 33
      }
    ],
    "giftCard": [
      {
        "id": 1,
        "createdAt": "2020-01-01T12:00:00Z",
        "code": "ABC-123",
        "originType": "csrAppeasement",
        "subTypeId": 1,
        "state": "onHold",
        "originalBalance": 50,
        "currentBalance": 50,
        "availableBalance": 50,
        "message": "Lorem ipsum",
        "customer": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com",
          "isGuest": false,
          "disabled": false,
          "isBlacklisted": false,
          "createdAt": "2020-01-01T12:00:00Z",
          "groups": [
            {
              "id": 1,
              "name": "Super Awesome Group",
              "type": "dynamic"
            }
          ],
          "storeCreditTotals": {
            "currentBalance": 50,
            "availableBalance": 50
          },
          "totalSales": 100
        },
        "storeAdmin": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com"
        }
      }
    ]
  },
  "adjustments": [
    {
      "id": 1,
      "amount": 10,
      "sourceId": 1,
      "sourceType": "order",
      "reason": "Lorem ipsum"
    }
  ],
  "fraudScore": 0,
  "customer": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com",
    "isGuest": false,
    "disabled": false,
    "isBlacklisted": false,
    "createdAt": "2020-01-01T12:00:00Z",
    "groups": [
      {
        "id": 1,
        "name": "Super Awesome Group",
        "type": "dynamic"
      }
    ],
    "storeCreditTotals": {
      "currentBalance": 50,
      "availableBalance": 50
    },
    "totalSales": 100
  },
  "totals": {
    "subTotal": 100,
    "taxes": 50,
    "shipping": 5,
    "adjustments": 50,
    "total": 100
  },
  "shippingMethod": {
    "id": 1,
    "name": "UPS Ground",
    "price": 10,
    "isEnabled": true
  },
  "shippingAddress": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555",
    "isDefault": false
  },
  "remorsePeriodEnd": "2020-01-01T12:00:00Z",
  "paymentMethods": [
    {
      "type": "CreditCard"
    }
  ],
  "warnings": [
    "List of validation errors and warnings"
  ]
}

Add By Address ID
PATCH/v1/carts/{refNum}/shipping-address/{addressId}

URI Parameters
HideShow
refNum
string (required) Example: ABC-123

Cart reference number.

addressId
number (required) Example: 1

Address ID.

Response Definition
attributes
id
number, optional
Unique identifier.
referenceNumber
string, optional
Order reference number.
orderState
string, optional
Order State.
shippingState
string, optional
Shipping state.
paymentState
string, optional
Credit Card payment state.
lineItems
object
Line items with different types.
adjustments
array, optional
Order adjustments.
fraudScore
number, optional
Fraud score.
customer
object
Associated customer.
totals
object
Order totals.
shippingMethod
object
Shipping method.
shippingAddress
object
Shipping address.
remorsePeriodEnd
string, optional
Remorse period end.
paymentMethods
array, optional
Order payment.
warnings
array, optional
Warnings.

PATCH https://developer.foxcommerce.com/v1/carts/ABC-123/shipping-address
Example Request
{
  "name": "John Smith",
  "regionId": 1,
  "address1": "555 E Lake Union St.",
  "address2": "Suite 200",
  "city": "Seattle",
  "zip": "98124",
  "isDefault": false,
  "phoneNumber": "555-555-555"
}
Example Response
{
  "id": 1,
  "referenceNumber": "ABC-123",
  "orderState": "Cart",
  "shippingState": "Cart",
  "paymentState": "Cart",
  "lineItems": {
    "skus": [
      {
        "imagePath": "http://lorempixel.com/75/75/fashion",
        "referenceNumber": "ABC-123",
        "name": "donkey product",
        "sku": "SKU-YAX",
        "price": 33,
        "quantity": 1,
        "state": "Cart",
        "totalPrice": 33
      }
    ],
    "giftCard": [
      {
        "id": 1,
        "createdAt": "2020-01-01T12:00:00Z",
        "code": "ABC-123",
        "originType": "csrAppeasement",
        "subTypeId": 1,
        "state": "onHold",
        "originalBalance": 50,
        "currentBalance": 50,
        "availableBalance": 50,
        "message": "Lorem ipsum",
        "customer": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com",
          "isGuest": false,
          "disabled": false,
          "isBlacklisted": false,
          "createdAt": "2020-01-01T12:00:00Z",
          "groups": [
            {
              "id": 1,
              "name": "Super Awesome Group",
              "type": "dynamic"
            }
          ],
          "storeCreditTotals": {
            "currentBalance": 50,
            "availableBalance": 50
          },
          "totalSales": 100
        },
        "storeAdmin": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com"
        }
      }
    ]
  },
  "adjustments": [
    {
      "id": 1,
      "amount": 10,
      "sourceId": 1,
      "sourceType": "order",
      "reason": "Lorem ipsum"
    }
  ],
  "fraudScore": 0,
  "customer": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com",
    "isGuest": false,
    "disabled": false,
    "isBlacklisted": false,
    "createdAt": "2020-01-01T12:00:00Z",
    "groups": [
      {
        "id": 1,
        "name": "Super Awesome Group",
        "type": "dynamic"
      }
    ],
    "storeCreditTotals": {
      "currentBalance": 50,
      "availableBalance": 50
    },
    "totalSales": 100
  },
  "totals": {
    "subTotal": 100,
    "taxes": 50,
    "shipping": 5,
    "adjustments": 50,
    "total": 100
  },
  "shippingMethod": {
    "id": 1,
    "name": "UPS Ground",
    "price": 10,
    "isEnabled": true
  },
  "shippingAddress": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555",
    "isDefault": false
  },
  "remorsePeriodEnd": "2020-01-01T12:00:00Z",
  "paymentMethods": [
    {
      "type": "CreditCard"
    }
  ],
  "warnings": [
    "List of validation errors and warnings"
  ]
}

Update
PATCH/v1/carts/{refNum}/shipping-address

URI Parameters
HideShow
refNum
string (required) Example: ABC-123

Cart reference number

Request Definition
attributes
name
string, optional
Recipient name.
regionId
number, optional
Region unique ID.
address1
string, optional
Address line 1.
address2
string, optional
Address line 2.
city
string, optional
City.
zip
string, optional
zip/postal code.
isDefault
boolean, optional
Default or not in address book.
phoneNumber
string, optional
Contact phone number.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
referenceNumber
string, optional
Order reference number.
orderState
string, optional
Order State.
shippingState
string, optional
Shipping state.
paymentState
string, optional
Credit Card payment state.
lineItems
object
Line items with different types.
adjustments
array, optional
Order adjustments.
fraudScore
number, optional
Fraud score.
customer
object
Associated customer.
totals
object
Order totals.
shippingMethod
object
Shipping method.
shippingAddress
object
Shipping address.
remorsePeriodEnd
string, optional
Remorse period end.
paymentMethods
array, optional
Order payment.
warnings
array, optional
Warnings.

DELETE https://developer.foxcommerce.com/v1/carts/ABC-123/shipping-address
Example Response
{
  "id": 1,
  "referenceNumber": "ABC-123",
  "orderState": "Cart",
  "shippingState": "Cart",
  "paymentState": "Cart",
  "lineItems": {
    "skus": [
      {
        "imagePath": "http://lorempixel.com/75/75/fashion",
        "referenceNumber": "ABC-123",
        "name": "donkey product",
        "sku": "SKU-YAX",
        "price": 33,
        "quantity": 1,
        "state": "Cart",
        "totalPrice": 33
      }
    ],
    "giftCard": [
      {
        "id": 1,
        "createdAt": "2020-01-01T12:00:00Z",
        "code": "ABC-123",
        "originType": "csrAppeasement",
        "subTypeId": 1,
        "state": "onHold",
        "originalBalance": 50,
        "currentBalance": 50,
        "availableBalance": 50,
        "message": "Lorem ipsum",
        "customer": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com",
          "isGuest": false,
          "disabled": false,
          "isBlacklisted": false,
          "createdAt": "2020-01-01T12:00:00Z",
          "groups": [
            {
              "id": 1,
              "name": "Super Awesome Group",
              "type": "dynamic"
            }
          ],
          "storeCreditTotals": {
            "currentBalance": 50,
            "availableBalance": 50
          },
          "totalSales": 100
        },
        "storeAdmin": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com"
        }
      }
    ]
  },
  "adjustments": [
    {
      "id": 1,
      "amount": 10,
      "sourceId": 1,
      "sourceType": "order",
      "reason": "Lorem ipsum"
    }
  ],
  "fraudScore": 0,
  "customer": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com",
    "isGuest": false,
    "disabled": false,
    "isBlacklisted": false,
    "createdAt": "2020-01-01T12:00:00Z",
    "groups": [
      {
        "id": 1,
        "name": "Super Awesome Group",
        "type": "dynamic"
      }
    ],
    "storeCreditTotals": {
      "currentBalance": 50,
      "availableBalance": 50
    },
    "totalSales": 100
  },
  "totals": {
    "subTotal": 100,
    "taxes": 50,
    "shipping": 5,
    "adjustments": 50,
    "total": 100
  },
  "shippingMethod": {
    "id": 1,
    "name": "UPS Ground",
    "price": 10,
    "isEnabled": true
  },
  "shippingAddress": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555",
    "isDefault": false
  },
  "remorsePeriodEnd": "2020-01-01T12:00:00Z",
  "paymentMethods": [
    {
      "type": "CreditCard"
    }
  ],
  "warnings": [
    "List of validation errors and warnings"
  ]
}

Delete
DELETE/v1/carts/{refNum}/shipping-address

URI Parameters
HideShow
refNum
string (required) Example: ABC-123

Cart reference number

Response Definition
attributes
id
number, optional
Unique identifier.
referenceNumber
string, optional
Order reference number.
orderState
string, optional
Order State.
shippingState
string, optional
Shipping state.
paymentState
string, optional
Credit Card payment state.
lineItems
object
Line items with different types.
adjustments
array, optional
Order adjustments.
fraudScore
number, optional
Fraud score.
customer
object
Associated customer.
totals
object
Order totals.
shippingMethod
object
Shipping method.
shippingAddress
object
Shipping address.
remorsePeriodEnd
string, optional
Remorse period end.
paymentMethods
array, optional
Order payment.
warnings
array, optional
Warnings.

Orders

attributes
id
number, optional
Unique identifier.
referenceNumber
string, optional
Order reference number.
orderState
string, optional
Order State.
shippingState
string, optional
Shipping state.
paymentState
string, optional
Credit Card payment state.
lineItems
object
Line items with different types.
adjustments
array, optional
Order adjustments.
fraudScore
number, optional
Fraud score.
customer
object
Associated customer.
totals
object
Order totals.
shippingMethod
object
Shipping method.
shippingAddress
object
Shipping address.
remorsePeriodEnd
string, optional
Remorse period end.
paymentMethods
array, optional
Order payment.
warnings
array, optional
Warnings.
GET https://developer.foxcommerce.com/v1/orders/ABC-123
Example Response
{
  "id": 1,
  "referenceNumber": "ABC-123",
  "orderState": "Cart",
  "shippingState": "Cart",
  "paymentState": "Cart",
  "lineItems": {
    "skus": [
      {
        "imagePath": "http://lorempixel.com/75/75/fashion",
        "referenceNumber": "ABC-123",
        "name": "donkey product",
        "sku": "SKU-YAX",
        "price": 33,
        "quantity": 1,
        "state": "Cart",
        "totalPrice": 33
      }
    ],
    "giftCard": [
      {
        "id": 1,
        "createdAt": "2020-01-01T12:00:00Z",
        "code": "ABC-123",
        "originType": "csrAppeasement",
        "subTypeId": 1,
        "state": "onHold",
        "originalBalance": 50,
        "currentBalance": 50,
        "availableBalance": 50,
        "message": "Lorem ipsum",
        "customer": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com",
          "isGuest": false,
          "disabled": false,
          "isBlacklisted": false,
          "createdAt": "2020-01-01T12:00:00Z",
          "groups": [
            {
              "id": 1,
              "name": "Super Awesome Group",
              "type": "dynamic"
            }
          ],
          "storeCreditTotals": {
            "currentBalance": 50,
            "availableBalance": 50
          },
          "totalSales": 100
        },
        "storeAdmin": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com"
        }
      }
    ]
  },
  "adjustments": [
    {
      "id": 1,
      "amount": 10,
      "sourceId": 1,
      "sourceType": "order",
      "reason": "Lorem ipsum"
    }
  ],
  "fraudScore": 0,
  "customer": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com",
    "isGuest": false,
    "disabled": false,
    "isBlacklisted": false,
    "createdAt": "2020-01-01T12:00:00Z",
    "groups": [
      {
        "id": 1,
        "name": "Super Awesome Group",
        "type": "dynamic"
      }
    ],
    "storeCreditTotals": {
      "currentBalance": 50,
      "availableBalance": 50
    },
    "totalSales": 100
  },
  "totals": {
    "subTotal": 100,
    "taxes": 50,
    "shipping": 5,
    "adjustments": 50,
    "total": 100
  },
  "shippingMethod": {
    "id": 1,
    "name": "UPS Ground",
    "price": 10,
    "isEnabled": true
  },
  "shippingAddress": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555",
    "isDefault": false
  },
  "remorsePeriodEnd": "2020-01-01T12:00:00Z",
  "paymentMethods": [
    {
      "type": "CreditCard"
    }
  ],
  "warnings": [
    "List of validation errors and warnings"
  ]
}

View
GET/v1/orders/{refNum}

URI Parameters
HideShow
refNum
string (required) Example: ABC-123

Order referenceNumber.

Response Definition
attributes
id
number, optional
Unique identifier.
referenceNumber
string, optional
Order reference number.
orderState
string, optional
Order State.
shippingState
string, optional
Shipping state.
paymentState
string, optional
Credit Card payment state.
lineItems
object
Line items with different types.
adjustments
array, optional
Order adjustments.
fraudScore
number, optional
Fraud score.
customer
object
Associated customer.
totals
object
Order totals.
shippingMethod
object
Shipping method.
shippingAddress
object
Shipping address.
remorsePeriodEnd
string, optional
Remorse period end.
paymentMethods
array, optional
Order payment.
warnings
array, optional
Warnings.

PATCH https://developer.foxcommerce.com/v1/orders
Example Request
{
  "referenceNumbers": [
    "ABC-123"
  ],
  "state": "cart",
  "reasonId": 1
}
Example Response
{
  "result": [
    {
      "referenceNumber": "ABC-123",
      "name": "John Smith",
      "email": "john@smith.com",
      "orderState": "Cart",
      "paymentState": "Cart",
      "shippingState": "Cart",
      "placedAt": "2020-01-01T12:00:00Z",
      "total": 1
    }
  ]
}

Bulk Update State
PATCH/v1/orders

Request Definition
attributes
referenceNumbers
array, optional
Order reference numbers.
state
string, optional
Order State.
reasonId
number, optional
Cancellation reason.
Response Definition
Status Code 200
attributes
result
array, optional
The resulting list of ListOrder-s.

POST https://developer.foxcommerce.com/v1/orders/ABC-123/increase-remorse-period
Example Response
{
  "id": 1,
  "referenceNumber": "ABC-123",
  "orderState": "Cart",
  "shippingState": "Cart",
  "paymentState": "Cart",
  "lineItems": {
    "skus": [
      {
        "imagePath": "http://lorempixel.com/75/75/fashion",
        "referenceNumber": "ABC-123",
        "name": "donkey product",
        "sku": "SKU-YAX",
        "price": 33,
        "quantity": 1,
        "state": "Cart",
        "totalPrice": 33
      }
    ],
    "giftCard": [
      {
        "id": 1,
        "createdAt": "2020-01-01T12:00:00Z",
        "code": "ABC-123",
        "originType": "csrAppeasement",
        "subTypeId": 1,
        "state": "onHold",
        "originalBalance": 50,
        "currentBalance": 50,
        "availableBalance": 50,
        "message": "Lorem ipsum",
        "customer": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com",
          "isGuest": false,
          "disabled": false,
          "isBlacklisted": false,
          "createdAt": "2020-01-01T12:00:00Z",
          "groups": [
            {
              "id": 1,
              "name": "Super Awesome Group",
              "type": "dynamic"
            }
          ],
          "storeCreditTotals": {
            "currentBalance": 50,
            "availableBalance": 50
          },
          "totalSales": 100
        },
        "storeAdmin": {
          "id": 1,
          "name": "John Smith",
          "email": "john@smith.com"
        }
      }
    ]
  },
  "adjustments": [
    {
      "id": 1,
      "amount": 10,
      "sourceId": 1,
      "sourceType": "order",
      "reason": "Lorem ipsum"
    }
  ],
  "fraudScore": 0,
  "customer": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com",
    "isGuest": false,
    "disabled": false,
    "isBlacklisted": false,
    "createdAt": "2020-01-01T12:00:00Z",
    "groups": [
      {
        "id": 1,
        "name": "Super Awesome Group",
        "type": "dynamic"
      }
    ],
    "storeCreditTotals": {
      "currentBalance": 50,
      "availableBalance": 50
    },
    "totalSales": 100
  },
  "totals": {
    "subTotal": 100,
    "taxes": 50,
    "shipping": 5,
    "adjustments": 50,
    "total": 100
  },
  "shippingMethod": {
    "id": 1,
    "name": "UPS Ground",
    "price": 10,
    "isEnabled": true
  },
  "shippingAddress": {
    "id": 1,
    "region": {
      "id": 1,
      "countryId": 2794,
      "name": "Washington"
    },
    "name": "Home",
    "address1": "38 Baker Street",
    "address2": "39 Baker Street",
    "city": "Donkeyville",
    "zip": "55555",
    "isDefault": false
  },
  "remorsePeriodEnd": "2020-01-01T12:00:00Z",
  "paymentMethods": [
    {
      "type": "CreditCard"
    }
  ],
  "warnings": [
    "List of validation errors and warnings"
  ]
}

Increase Remorse Period
POST/v1/orders/{refNum}/increase-remorse-period

Order must be in remorseHold state.

URI Parameters
HideShow
refNum
string (required) Example: ABC-123

Order reference number

Response Definition
attributes
id
number, optional
Unique identifier.
referenceNumber
string, optional
Order reference number.
orderState
string, optional
Order State.
shippingState
string, optional
Shipping state.
paymentState
string, optional
Credit Card payment state.
lineItems
object
Line items with different types.
adjustments
array, optional
Order adjustments.
fraudScore
number, optional
Fraud score.
customer
object
Associated customer.
totals
object
Order totals.
shippingMethod
object
Shipping method.
shippingAddress
object
Shipping address.
remorsePeriodEnd
string, optional
Remorse period end.
paymentMethods
array, optional
Order payment.
warnings
array, optional
Warnings.

Payments

The Fox Platform supports three main ways to pay for products purchased on supported sites: credit cards, gift cards, and store credit. Credit card processing is handled through Stripe, while gift cards and store credit is built deeply into the platform.

Gift Card

Gift card is a tender type maintained by the Fox Platform that is specific to an individual site or tenant. Gift cards each have a balance that can be spent against in multiple orders. A gift card is different from a store credit in that it is not tied to a specific custoomer, but is instead identified by a unique code.

attributes
id
number, optional
Unique identifier.
createdAt
string, optional
Creation date.
code
string, optional
Public unique identifier.
originType
string, optional
GC origin type.
subTypeId
number, optional
Optional subtype.
state
string, optional
GC state.
originalBalance
number, optional
Opening balance for GC (amount it was issued for).
currentBalance
number, optional
Opening balance minus "captured" debits.
availableBalance
number, optional
Opening balance minus "auth" debits.
message
string, optional
Optional message entered by CSR or customer.
customer
object
If customer have purchased GiftCard, returns his info.
storeAdmin
object
If CSR created GiftCard, return his info.
GET https://developer.foxcommerce.com/v1/gift-cards/ABC-123
Example Response
{
  "id": 1,
  "createdAt": "2020-01-01T12:00:00Z",
  "code": "ABC-123",
  "originType": "csrAppeasement",
  "subTypeId": 1,
  "state": "onHold",
  "originalBalance": 50,
  "currentBalance": 50,
  "availableBalance": 50,
  "message": "Lorem ipsum",
  "customer": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com",
    "isGuest": false,
    "disabled": false,
    "isBlacklisted": false,
    "createdAt": "2020-01-01T12:00:00Z",
    "groups": [
      {
        "id": 1,
        "name": "Super Awesome Group",
        "type": "dynamic"
      }
    ],
    "storeCreditTotals": {
      "currentBalance": 50,
      "availableBalance": 50
    },
    "totalSales": 100
  },
  "storeAdmin": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com"
  }
}

View
GET/v1/gift-cards/{code}

URI Parameters
HideShow
code
string (required) Example: ABC-123

Gift card code

Response Definition
attributes
id
number, optional
Unique identifier.
createdAt
string, optional
Creation date.
code
string, optional
Public unique identifier.
originType
string, optional
GC origin type.
subTypeId
number, optional
Optional subtype.
state
string, optional
GC state.
originalBalance
number, optional
Opening balance for GC (amount it was issued for).
currentBalance
number, optional
Opening balance minus "captured" debits.
availableBalance
number, optional
Opening balance minus "auth" debits.
message
string, optional
Optional message entered by CSR or customer.
customer
object
If customer have purchased GiftCard, returns his info.
storeAdmin
object
If CSR created GiftCard, return his info.

POST https://developer.foxcommerce.com/v1/gift-cards
Example Request
{
  "balance": 10,
  "reasonId": 1,
  "currency": "USD",
  "subTypeId": 1
}
Example Response
{
  "id": 1,
  "createdAt": "2020-01-01T12:00:00Z",
  "code": "ABC-123",
  "originType": "csrAppeasement",
  "subTypeId": 1,
  "state": "onHold",
  "originalBalance": 50,
  "currentBalance": 50,
  "availableBalance": 50,
  "message": "Lorem ipsum",
  "customer": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com",
    "isGuest": false,
    "disabled": false,
    "isBlacklisted": false,
    "createdAt": "2020-01-01T12:00:00Z",
    "groups": [
      {
        "id": 1,
        "name": "Super Awesome Group",
        "type": "dynamic"
      }
    ],
    "storeCreditTotals": {
      "currentBalance": 50,
      "availableBalance": 50
    },
    "totalSales": 100
  },
  "storeAdmin": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com"
  }
}

Create
POST/v1/gift-cards

Creates a GiftCard with CsrAppeasement type.

Request Definition
attributes
balance
number, optional
Gift card balance.
reasonId
number, optional
Reason ID for generation.
currency
string, optional
Gift card currency.
subTypeId
number, optional
Possible subtype ID.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
createdAt
string, optional
Creation date.
code
string, optional
Public unique identifier.
originType
string, optional
GC origin type.
subTypeId
number, optional
Optional subtype.
state
string, optional
GC state.
originalBalance
number, optional
Opening balance for GC (amount it was issued for).
currentBalance
number, optional
Opening balance minus "captured" debits.
availableBalance
number, optional
Opening balance minus "auth" debits.
message
string, optional
Optional message entered by CSR or customer.
customer
object
If customer have purchased GiftCard, returns his info.
storeAdmin
object
If CSR created GiftCard, return his info.

POST https://developer.foxcommerce.com/v1/gift-cards/bulk
Example Request
{
  "balance": 10,
  "quantity": 1,
  "reasonId": 1,
  "currency": "USD",
  "subTypeId": 1
}
Example Response
{
  "id": 1,
  "createdAt": "2020-01-01T12:00:00Z",
  "code": "ABC-123",
  "originType": "csrAppeasement",
  "subTypeId": 1,
  "state": "onHold",
  "originalBalance": 50,
  "currentBalance": 50,
  "availableBalance": 50,
  "message": "Lorem ipsum",
  "customer": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com",
    "isGuest": false,
    "disabled": false,
    "isBlacklisted": false,
    "createdAt": "2020-01-01T12:00:00Z",
    "groups": [
      {
        "id": 1,
        "name": "Super Awesome Group",
        "type": "dynamic"
      }
    ],
    "storeCreditTotals": {
      "currentBalance": 50,
      "availableBalance": 50
    },
    "totalSales": 100
  },
  "storeAdmin": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com"
  }
}

Bulk Create
POST/v1/gift-cards/bulk

Creates multiple GiftCards with CsrAppeasement type.

Request Definition
attributes
balance
number, optional
Gift card balance.
quantity
number, optional
Quantity.
reasonId
number, optional
Reason ID for generation.
currency
string, optional
Gift card currency.
subTypeId
number, optional
Possible subtype ID.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
createdAt
string, optional
Creation date.
code
string, optional
Public unique identifier.
originType
string, optional
GC origin type.
subTypeId
number, optional
Optional subtype.
state
string, optional
GC state.
originalBalance
number, optional
Opening balance for GC (amount it was issued for).
currentBalance
number, optional
Opening balance minus "captured" debits.
availableBalance
number, optional
Opening balance minus "auth" debits.
message
string, optional
Optional message entered by CSR or customer.
customer
object
If customer have purchased GiftCard, returns his info.
storeAdmin
object
If CSR created GiftCard, return his info.

PATCH https://developer.foxcommerce.com/v1/gift-cards/ABC-123
Example Request
{
  "state": "onHold",
  "reasonId": 1
}
Example Response
{
  "id": 1,
  "createdAt": "2020-01-01T12:00:00Z",
  "code": "ABC-123",
  "originType": "csrAppeasement",
  "subTypeId": 1,
  "state": "onHold",
  "originalBalance": 50,
  "currentBalance": 50,
  "availableBalance": 50,
  "message": "Lorem ipsum",
  "customer": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com",
    "isGuest": false,
    "disabled": false,
    "isBlacklisted": false,
    "createdAt": "2020-01-01T12:00:00Z",
    "groups": [
      {
        "id": 1,
        "name": "Super Awesome Group",
        "type": "dynamic"
      }
    ],
    "storeCreditTotals": {
      "currentBalance": 50,
      "availableBalance": 50
    },
    "totalSales": 100
  },
  "storeAdmin": {
    "id": 1,
    "name": "John Smith",
    "email": "john@smith.com"
  }
}

Update State
PATCH/v1/gift-cards/{code}

URI Parameters
HideShow
code
string (required) Example: ABC-123

Gift card code

Request Definition
attributes
state
string, optional
New gift card state.
reasonId
number, optional
ID of cancellation reason.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
createdAt
string, optional
Creation date.
code
string, optional
Public unique identifier.
originType
string, optional
GC origin type.
subTypeId
number, optional
Optional subtype.
state
string, optional
GC state.
originalBalance
number, optional
Opening balance for GC (amount it was issued for).
currentBalance
number, optional
Opening balance minus "captured" debits.
availableBalance
number, optional
Opening balance minus "auth" debits.
message
string, optional
Optional message entered by CSR or customer.
customer
object
If customer have purchased GiftCard, returns his info.
storeAdmin
object
If CSR created GiftCard, return his info.

PATCH https://developer.foxcommerce.com/v1/gift-cards/bulk
Example Request
{
  "codes": [
    "ABC-123",
    "ABC-345"
  ],
  "state": "onHold",
  "reasonId": 1
}
Example Response
[
  {
    "success": true,
    "code": "ABC-123",
    "errors": [
      "Hello, world!"
    ],
    "giftCard": {
      "id": 1,
      "createdAt": "2020-01-01T12:00:00Z",
      "code": "ABC-123",
      "originType": "csrAppeasement",
      "subTypeId": 1,
      "state": "onHold",
      "originalBalance": 50,
      "currentBalance": 50,
      "availableBalance": 50,
      "message": "Lorem ipsum",
      "customer": {
        "id": 1,
        "name": "John Smith",
        "email": "john@smith.com",
        "isGuest": false,
        "disabled": false,
        "isBlacklisted": false,
        "createdAt": "2020-01-01T12:00:00Z",
        "groups": [
          {
            "id": 1,
            "name": "Super Awesome Group",
            "type": "dynamic"
          }
        ],
        "storeCreditTotals": {
          "currentBalance": 50,
          "availableBalance": 50
        },
        "totalSales": 100
      },
      "storeAdmin": {
        "id": 1,
        "name": "John Smith",
        "email": "john@smith.com"
      }
    }
  }
]

Bulk Update State
PATCH/v1/gift-cards/bulk

Request Definition
attributes
codes
array, optional
List of Gift Card codes.
state
string, optional
State to be switched to.
reasonId
number, optional
ID of cancellation reason.
Response Definition
Status Code 200
attributes

POST https://developer.foxcommerce.com/v1/gift-cards/ABC-123/convert/1
Example Response
{
  "id": 1,
  "createdAt": "2020-01-01T12:00:00Z",
  "currency": "USD",
  "originType": "csrAppeasement",
  "subTypeId": 1,
  "state": "onHold",
  "originalBalance": 50,
  "currentBalance": 50,
  "availableBalance": 50,
  "canceledReason": "Lorem ipsum"
}

Convert to StoreCredit
POST/v1/gift-cards/{code}/convert/{customerId}

Converts GiftCard to specified customer’s Store Credit if it’s active and has no open adjustments.

URI Parameters
HideShow
code
string (required) Example: ABC-123

Gift card code.

customerId
number (required) Example: 1

Customer ID.

Response Definition
attributes
id
number, optional
Unique identifier.
createdAt
string, optional
Creation date.
currency
string, optional
SC currency.
originType
string, optional
SC origin type.
subTypeId
number, optional
Optional subtype.
state
string, optional
SC state.
originalBalance
number, optional
Opening balance for SC (amount it was issued for).
currentBalance
number, optional
Opening balance minus "captured" debits.
availableBalance
number, optional
Opening balance minus "auth" debits.
canceledReason
string, optional
Cancellation reason (present if SC canceled).

Store Credit

Store credit is a tender type maintained by the Fox Platform that is specific to an individual customer within a site or tenant.Store credits each have a balance that can be spent against in multiple orders. Store credit is different from gift cards in that no code is required to use the credit, it is automatically available to each user if their store credit balance is greater than zero.

attributes
id
number, optional
Unique identifier.
createdAt
string, optional
Creation date.
currency
string, optional
SC currency.
originType
string, optional
SC origin type.
subTypeId
number, optional
Optional subtype.
state
string, optional
SC state.
originalBalance
number, optional
Opening balance for SC (amount it was issued for).
currentBalance
number, optional
Opening balance minus "captured" debits.
availableBalance
number, optional
Opening balance minus "auth" debits.
canceledReason
string, optional
Cancellation reason (present if SC canceled).
GET https://developer.foxcommerce.com/v1/store-credits/1
Example Response
{
  "id": 1,
  "createdAt": "2020-01-01T12:00:00Z",
  "currency": "USD",
  "originType": "csrAppeasement",
  "subTypeId": 1,
  "state": "onHold",
  "originalBalance": 50,
  "currentBalance": 50,
  "availableBalance": 50,
  "canceledReason": "Lorem ipsum"
}

View
GET/v1/store-credits/{id}

URI Parameters
HideShow
id
number (required) Example: 1

Store Credit ID

Response Definition
attributes
id
number, optional
Unique identifier.
createdAt
string, optional
Creation date.
currency
string, optional
SC currency.
originType
string, optional
SC origin type.
subTypeId
number, optional
Optional subtype.
state
string, optional
SC state.
originalBalance
number, optional
Opening balance for SC (amount it was issued for).
currentBalance
number, optional
Opening balance minus "captured" debits.
availableBalance
number, optional
Opening balance minus "auth" debits.
canceledReason
string, optional
Cancellation reason (present if SC canceled).

PATCH https://developer.foxcommerce.com/v1/store-credits/
Example Request
{
  "state": "onHold",
  "reasonId": 1
}
Example Response
{
  "id": 1,
  "createdAt": "2020-01-01T12:00:00Z",
  "currency": "USD",
  "originType": "csrAppeasement",
  "subTypeId": 1,
  "state": "onHold",
  "originalBalance": 50,
  "currentBalance": 50,
  "availableBalance": 50,
  "canceledReason": "Lorem ipsum"
}

Update State
PATCH/v1/store-credits/

Request Definition
attributes
state
string, optional
New store credit state.
reasonId
number, optional
ID of cancellation reason.
Response Definition
Status Code 200
attributes
id
number, optional
Unique identifier.
createdAt
string, optional
Creation date.
currency
string, optional
SC currency.
originType
string, optional
SC origin type.
subTypeId
number, optional
Optional subtype.
state
string, optional
SC state.
originalBalance
number, optional
Opening balance for SC (amount it was issued for).
currentBalance
number, optional
Opening balance minus "captured" debits.
availableBalance
number, optional
Opening balance minus "auth" debits.
canceledReason
string, optional
Cancellation reason (present if SC canceled).

PATCH https://developer.foxcommerce.com/v1/store-credits
Example Request
{
  "ids": [
    1
  ],
  "state": "onHold",
  "reasonId": 1
}
Example Response
[
  {
    "success": true,
    "id": 1,
    "errors": [
      "Hello, world!"
    ],
    "storeCredit": {
      "id": 1,
      "createdAt": "2020-01-01T12:00:00Z",
      "currency": "USD",
      "originType": "csrAppeasement",
      "subTypeId": 1,
      "state": "onHold",
      "originalBalance": 50,
      "currentBalance": 50,
      "availableBalance": 50,
      "canceledReason": "Lorem ipsum"
    }
  }
]

Bulk Update State
PATCH/v1/store-credits

Request Definition
attributes
ids
array, optional
List of Store Credit ID's.
state
string, optional
State to be switched to.
reasonId
number, optional
ID of cancellation reason.
Response Definition
Status Code 200
attributes

Export

Entities export endpoint.

Export

POST https://developer.foxcommerce.com/v1/export/products
Example Request
{
  "payloadType": "ids",
  "description": "whatever",
  "fields": [
    {
      "name": "customer.email",
      "displayName": "Customer Email"
    }
  ],
  "ids": [
    1
  ]
}
Example Response
id
1
2
{
  "payloadType": "query",
  "description": "whatever",
  "fields": [
    {
      "name": "customer.email",
      "displayName": "Customer Email"
    }
  ],
  "query": {
    "bool": {}
  },
  "sort": [
    {
      "_score": "asc"
    }
  ]
}
Example Response
id
1
2

Export
POST/v1/export/{entity}

URI Parameters
HideShow
entity
string (required) Example: products

Entity type

Choices: carts couponCodes coupons customerGroups customerItems customers giftCards giftCardTransactions inventory inventoryTransactions notes orders products promotions skus storeAdmins storeCredits storeCreditTransactions taxonomies taxons

Request Definition
attributes
payloadType
string, optional
Payload discriminator.
description
string, optional
Description of an export.
fields
array, optional
List of fields to export.
ids
array, optional
List of ids.
Response Definition
Status Code 200
attributes
payloadType
string, optional
Payload discriminator.
description
string, optional
Description of an export.
fields
array, optional
List of fields to export.
query
object, optional
Search query in format accepted by ElasticSearch.
sort
array, optional
Search sort in format accepted by ElasticSearch.
Response Definition
Status Code 200

Discounts

Promotions

POST https://developer.foxcommerce.com/v1/promotions/default
Example Request
{
  "applyType": "auto",
  "attributes": "<json>",
  "discounts": [
    {
      "attributes": "<json>"
    }
  ]
}
Example Response
{
  "applyType": "auto",
  "form": {
    "id": 1,
    "attributes": "<json>",
    "createdAt": "2020-01-01T12:00:00Z"
  },
  "shadow": {
    "id": 1,
    "formId": 1,
    "attributes": "<json>",
    "discounts": [
      {
        "id": 1,
        "attributes": "<json>",
        "createdAt": "2020-01-01T12:00:00Z"
      }
    ],
    "createdAt": "2020-01-01T12:00:00Z"
  },
  "archivedAt": "2020-01-01T12:00:00Z"
}

Create
POST/v1/promotions/{context}

URI Parameters
HideShow
context
string (required) Example: default

The context in which the promotion will be viewable.

Request Definition
attributes
applyType
string, optional
Promotion apply-type (either coupon or automatic).
attributes
string, optional
Promotion form attributes.
discounts
array, optional
Promotion form discounts.
Response Definition
Status Code 200
attributes
applyType
string, optional
Promotion apply-type (either coupon or automatic).
form
object
Promotion form.
shadow
object
Promotion shadow.
archivedAt
string, optional
Archiving date.

GET https://developer.foxcommerce.com/v1/promotions/default/1
Example Response
{
  "applyType": "auto",
  "form": {
    "id": 1,
    "attributes": "<json>",
    "createdAt": "2020-01-01T12:00:00Z"
  },
  "shadow": {
    "id": 1,
    "formId": 1,
    "attributes": "<json>",
    "discounts": [
      {
        "id": 1,
        "attributes": "<json>",
        "createdAt": "2020-01-01T12:00:00Z"
      }
    ],
    "createdAt": "2020-01-01T12:00:00Z"
  },
  "archivedAt": "2020-01-01T12:00:00Z"
}

View
GET/v1/promotions/{context}/{id}

URI Parameters
HideShow
context
string (required) Example: default

The context in which the promotion is viewable.

id
number (required) Example: 1

Promotion ID.

Response Definition
attributes
applyType
string, optional
Promotion apply-type (either coupon or automatic).
form
object
Promotion form.
shadow
object
Promotion shadow.
archivedAt
string, optional
Archiving date.

GET https://developer.foxcommerce.com/v1/promotions/default/1/baked
Example Response
{
  "id": 1,
  "context": "default",
  "applyType": "auto",
  "attributes": "<json>",
  "discounts": [
    {
      "id": 1,
      "context": "default",
      "attributes": "<json>"
    }
  ]
}

View Illuminated
GET/v1/promotions/{context}/{id}/baked

Return illuminated version of promotion.

URI Parameters
HideShow
context
string (required) Example: default

The context in which the coupon is viewable.

id
number (required) Example: 1

Coupon ID.

Response Definition
attributes
id
number, optional
Promotion ID.
context
string, optional
Related context.
applyType
string, optional
Promotion apply-type (either coupon or automatic).
attributes
string, optional
Promotion attributes.
discounts
array, optional
Related illuminated discounts.

GET https://developer.foxcommerce.com/v1/promotions/forms/1
Example Response
{
  "id": 1,
  "attributes": "<json>",
  "createdAt": "2020-01-01T12:00:00Z"
}

View Form
GET/v1/promotions/forms/{id}

URI Parameters
HideShow
id
number (required) Example: 1

Promotion Form ID.

Response Definition
attributes
id
number, optional
Promotion form ID.
attributes
string, optional
Promotion form attributes.
createdAt
string, optional
Creation date.

GET https://developer.foxcommerce.com/v1/promotions/shadows/default/1
Example Response
{
  "id": 1,
  "formId": 1,
  "attributes": "<json>",
  "discounts": [
    {
      "id": 1,
      "attributes": "<json>",
      "createdAt": "2020-01-01T12:00:00Z"
    }
  ],
  "createdAt": "2020-01-01T12:00:00Z"
}

View Shadow
GET/v1/promotions/shadows/{context}/{id}

URI Parameters
HideShow
context
string (required) Example: default

The context in which the promotion is viewable.

id
number (required) Example: 1

Promotion Form ID.

Response Definition
attributes
id
number, optional
Promotion shadow ID.
formId
number, optional
Related promotion form ID.
attributes
string, optional
Promotion shadow attributes.
discounts
array, optional
Related discount shadows.
createdAt
string, optional
Creation date.

PATCH https://developer.foxcommerce.com/v1/promotions/default/1
Example Request
{
  "applyType": "auto",
  "attributes": "<json>",
  "discounts": [
    {
      "attributes": "<json>"
    }
  ]
}
Example Response
{
  "applyType": "auto",
  "form": {
    "id": 1,
    "attributes": "<json>",
    "createdAt": "2020-01-01T12:00:00Z"
  },
  "shadow": {
    "id": 1,
    "formId": 1,
    "attributes": "<json>",
    "discounts": [
      {
        "id": 1,
        "attributes": "<json>",
        "createdAt": "2020-01-01T12:00:00Z"
      }
    ],
    "createdAt": "2020-01-01T12:00:00Z"
  },
  "archivedAt": "2020-01-01T12:00:00Z"
}

Update
PATCH/v1/promotions/{context}/{id}

URI Parameters
HideShow
context
string (required) Example: default

The context in which the promotion is viewable.

id
number (required) Example: 1

Promotion ID.

Request Definition
attributes
applyType
string, optional
Promotion apply-type (either coupon or automatic).
attributes
string, optional
Promotion form attributes.
discounts
array, optional
Promotion form discounts.
Response Definition
Status Code 200
attributes
applyType
string, optional
Promotion apply-type (either coupon or automatic).
form
object
Promotion form.
shadow
object
Promotion shadow.
archivedAt
string, optional
Archiving date.

DELETE https://developer.foxcommerce.com/v1/promotions/default/1
Example Response
{
  "applyType": "auto",
  "form": {
    "id": 1,
    "attributes": "<json>",
    "createdAt": "2020-01-01T12:00:00Z"
  },
  "shadow": {
    "id": 1,
    "formId": 1,
    "attributes": "<json>",
    "discounts": [
      {
        "id": 1,
        "attributes": "<json>",
        "createdAt": "2020-01-01T12:00:00Z"
      }
    ],
    "createdAt": "2020-01-01T12:00:00Z"
  },
  "archivedAt": "2020-01-01T12:00:00Z"
}

Archive
DELETE/v1/promotions/{context}/{id}

URI Parameters
HideShow
context
string (required) Example: default

The context in which the promotion is viewable.

id
number (required) Example: 1

Promotion ID.

Response Definition
attributes
applyType
string, optional
Promotion apply-type (either coupon or automatic).
form
object
Promotion form.
shadow
object
Promotion shadow.
archivedAt
string, optional
Archiving date.

Coupons

POST https://developer.foxcommerce.com/v1/coupons/default
Example Request
{
  "promotion": 1,
  "attributes": "<json>"
}
Example Response
{
  "id": 1,
  "promotion": 1,
  "attributes": "<json>",
  "archivedAt": "2020-01-01T12:00:00Z"
}

Create
POST/v1/coupons/{context}

URI Parameters
HideShow
context
string (required) Example: default

The context in which the coupon will be viewable.

Request Definition
attributes
promotion
number, optional
Related promotion ID.
attributes
string, optional
Coupon attributes.
Response Definition
Status Code 200
attributes
id
number, optional
Coupon ID.
promotion
number, optional
Related promotion ID.
attributes
string, optional
Coupon attributes.
archivedAt
string, optional
Archiving date.

GET https://developer.foxcommerce.com/v1/coupons/default/1
Example Response
{
  "id": 1,
  "promotion": 1,
  "attributes": "<json>",
  "archivedAt": "2020-01-01T12:00:00Z"
}

View
GET/v1/coupons/{context}/{id}

URI Parameters
HideShow
context
string (required) Example: default

The context in which the coupon is viewable.

id
number (required) Example: 1

Coupon ID.

Response Definition
attributes
id
number, optional
Coupon ID.
promotion
number, optional
Related promotion ID.
attributes
string, optional
Coupon attributes.
archivedAt
string, optional
Archiving date.

GET https://developer.foxcommerce.com/v1/coupons/default/1/baked
Example Response
{
  "id": 1,
  "context": {
    "name": "default",
    "attributes": "<json>"
  },
  "attributes": "<json>",
  "promotion": 1
}

View Illuminated
GET/v1/coupons/{context}/{id}/baked

Return illuminated version of coupon.

URI Parameters
HideShow
context
string (required) Example: default

The context in which the coupon is viewable.

id
number (required) Example: 1

Coupon ID.

Response Definition
attributes
id
number, optional
Coupon ID.
context
object
Related context.
attributes
string, optional
Coupon attributes.
promotion
number, optional
Related promotion ID.

GET https://developer.foxcommerce.com/v1/coupons/default/ABC-123/baked
Example Response
{
  "id": 1,
  "context": {
    "name": "default",
    "attributes": "<json>"
  },
  "attributes": "<json>",
  "promotion": 1
}

View Illuminated By Code
GET/v1/coupons/{context}/{code}/baked

Return illuminated version of coupon.

URI Parameters
HideShow
context
string (required) Example: default

The context in which the coupon is viewable.

code
string (required) Example: ABC-123

Related coupon code.

Response Definition
attributes
id
number, optional
Coupon ID.
context
object
Related context.
attributes
string, optional
Coupon attributes.
promotion
number, optional
Related promotion ID.

GET https://developer.foxcommerce.com/v1/coupons/forms/1
Example Response
{
  "id": 1,
  "attributes": "<json>",
  "createdAt": "2020-01-01T12:00:00Z"
}

View Form
GET/v1/coupons/forms/{id}

URI Parameters
HideShow
id
number (required) Example: 1

Coupon Form ID.

Response Definition
attributes
id
number, optional
Coupon form ID.
attributes
string, optional
Coupon form attributes.
createdAt
string, optional
Creation date.

GET https://developer.foxcommerce.com/v1/coupons/shadows/default/1
Example Response
{
  "id": 1,
  "formId": 1,
  "attributes": "<json>",
  "createdAt": "2020-01-01T12:00:00Z"
}

View Shadow
GET/v1/coupons/shadows/{context}/{id}

URI Parameters
HideShow
context
string (required) Example: default

The context in which the coupon is viewable.

id
number (required) Example: 1

Coupon Form ID.

Response Definition
attributes
id
number, optional
Coupon shadow ID.
formId
number, optional
Related promotion form ID.
attributes
string, optional
Coupon shadow attributes.
createdAt
string, optional
Creation date.

PATCH https://developer.foxcommerce.com/v1/coupons/default/1
Example Request
{
  "form": {
    "attributes": "<json>"
  },
  "shadow": {
    "attributes": "<json>"
  },
  "promotion": 1
}
Example Response
{
  "id": 1,
  "promotion": 1,
  "attributes": "<json>",
  "archivedAt": "2020-01-01T12:00:00Z"
}

Update
PATCH/v1/coupons/{context}/{id}

URI Parameters
HideShow
context
string (required) Example: default

The context in which the coupon is viewable.

id
number (required) Example: 1

Coupon ID.

Request Definition
attributes
form
object
Coupon form.
shadow
object
Coupon shadow.
promotion
number, optional
Related promotion ID.
Response Definition
Status Code 200
attributes
id
number, optional
Coupon ID.
promotion
number, optional
Related promotion ID.
attributes
string, optional
Coupon attributes.
archivedAt
string, optional
Archiving date.

DELETE https://developer.foxcommerce.com/v1/coupons/default/1
Example Response
{
  "id": 1,
  "promotion": 1,
  "attributes": "<json>",
  "archivedAt": "2020-01-01T12:00:00Z"
}

Archive
DELETE/v1/coupons/{context}/{id}

URI Parameters
HideShow
context
string (required) Example: default

The context in which the coupon is viewable.

id
number (required) Example: 1

Coupon ID.

Response Definition
attributes
id
number, optional
Coupon ID.
promotion
number, optional
Related promotion ID.
attributes
string, optional
Coupon attributes.
archivedAt
string, optional
Archiving date.

POST https://developer.foxcommerce.com/v1/coupons/codes/generate/1/ABC-123
Example Response
"Hello, world!"

Generate Single Code
POST/v1/coupons/codes/generate/{id}/{code}

URI Parameters
HideShow
id
number (required) Example: 1

Related coupon ID.

code
string (required) Example: ABC-123

Preferred coupon code to generate.

Response Definition
attributes

POST https://developer.foxcommerce.com/v1/coupons/codes/generate/1
Example Request
{
  "prefix": "ABC",
  "quantity": 1,
  "length": 10
}
Example Response
[
  "Hello, world!"
]

Generate Multiple Codes
POST/v1/coupons/codes/generate/{id}

URI Parameters
HideShow
id
number (required) Example: 1

Related coupon ID.

Request Definition
attributes
prefix
string, optional
Coupon codes prefix.
quantity
number, optional
Number of coupon codes to generate.
length
number, optional
Resulting coupons code length.
Response Definition
Status Code 200
attributes

GET https://developer.foxcommerce.com/v1/coupons/codes/1
Example Response
[
  {
    "code": "ABC-123",
    "createdAt": "2020-01-01T12:00:00Z"
  }
]

Get Coupon Codes
GET/v1/coupons/codes/{id}

URI Parameters
HideShow
id
number (required) Example: 1

Related coupon ID.

Response Definition
attributes

Generated by aglio on 22 Jun 2017