SparkLayer logo
API docs by Redocly

SparkLayer API Reference (0.1.0)

Download OpenAPI specification:Download

Introduction

The SparkLayer API lets you connect your backend systems (e.g. ERP, CRM, PIM, or iPaas) and send through B2B data such as product and pricing information, customer rules, and much more! Once you've completed the API integration, you can then install the SparkLayer Frontend, converting your eCommerce website into a B2B ordering system.

The SparkLayer API is designed to be as extensive as you need it to be and you can control which data you send. It's important to note that if you use one of the ready made connectors your integration can be streamlined and we advise reading our guide before you begin.

Key Principles

The SparkLayer API follows REST principles with predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. The API expects incoming data to be valid JSON objects with requests containing the header Content-Type: application/json. All responses of the API, including errors, are in JSON.

Endpoints

All endpoints of the API are version 1 and this is part of the URL. For Cross-Origin Resource Sharing, all responses have a wildcard same-origin which makes them completely public.

Access details

Within your SparkLayer Dashboard, you can generate API keys from the Configuration section. Each time you generate an API key, you'll be given a Client ID and Client Secret used for authentication. You'll also need your unique site-id and this can be found within the My Account section of the SparkLayer Dashboard (this typically follows the format of your Company Name e.g. Test Store would teststore). If you would like a site-id to be created on our staging system, please email contact@sparklayer.io.

Base URL

The base URL of the API for available environments are as follows:

Environment Base URL
Live https://app.sparklayer.io
Test https://test.app.sparklayer.io

Support

Backwards compatible changes are made regularly to improve the API and there is a changelog within our support documentation. Please email contact@sparklayer.io if you require any technical support and we'll be happy to help!

Authentication

Authentication with SparkLayer works by creating an application and authenticating with an OAuth2 flow so that every user that uses the application gets assigned an individualised token.

The access_token retrieved, is then sent with the requests as so "Authorization: Bearer bza87*example_token*aksdn".

Permissions

Scope Description
customers.read read customer data
customers read/write customer data
orders.read read order data
orders read/write order data
products.read read core product data
products read/write core product data
products.pricing.read read product pricing data
products.pricing read/write product pricing data
products.stock.read read product stock data
products.stock read/write product stock data
setup.read read setup data*
setup read/write setup data*

You can use the route POST /api/auth/token with the parameters client_id, client_secret and grant_type=client_credentials to get the user access token. This is the token that is used in the Authorization header for all requests in the SparkLayer API.

OAuth Token

header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Request Body schema: application/json
grant_type
string
Enum: "client_credentials" "refresh_token" "password"
client_id
string
client_secret
string
username
string
password
string
refresh_token
string

Responses

Request samples

Content type
application/json
{
  • "grant_type": "client_credentials",
  • "client_id": "c466d1fb-1af1-4437-a25c-03e8f94814bf",
  • "client_secret": "7zA5ltJNkiI2WzhU90fTmYJANRcXYJPXsB8SnIEM3x37B2genuwqyv5tVdfLkUWV"
}

Response samples

Content type
application/json
{
  • "token_type": "string",
  • "expires_in": 0,
  • "access_token": "string",
  • "refresh_token": "string"
}

Errors

Error Response Status Codes

The API uses the following error status codes:

Code Status
400 Bad Request Unable to validate the request body
401 Unauthorized Authorisation header was invalid or if posting to /auth/token, the details were incorrect
403 Forbidden Permission denied, the required permissions not available for your access token
404 Not Found The requested object could not be found
405 Method Not Allowed An invalid method was used for the endpoint
409 Conflict The requested action conflicts with the current state of the object
500 Internal Server Error A problem occurred server side, try again later or contact support
503 Service Unavailable Temporary issue with infrastructure, try again later

Error Response Body

The API uses the following error response object which follows RFC-7807. This may not always be the case for 5xx errors.

detail
string

Human-readable summary of the error

status
integer

HTTP Status code returned from API

title
string

Machine-readable error code

type
string
Array of objects or null

A list of errors related to the call

{}

Products

Create a Product

Authorizations:
oauth
header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Request Body schema: application/json
Array of objects (ProductVariant-2)
external_id
string <= 100 characters

External ID (cannot start with pp_ and must be unique)

title
required
string <= 255 characters

Product Title

slug
required
string <= 255 characters

Product Slug (Used as the link identifier)

Responses

Request samples

Content type
application/json
{
  • "variants": [
    ],
  • "external_id": "ID001",
  • "title": "Striped Jumper",
  • "slug": "striped-jumper"
}

Response samples

Content type
application/json
{
  • "id": "pp_123",
  • "variants": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "external_id": "ID001",
  • "title": "Striped Jumper",
  • "slug": "striped-jumper"
}

Get a Product

Authorizations:
oauth
path Parameters
id
required
string

Either the Internal or External ID

header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Responses

Response samples

Content type
application/json
{
  • "id": "pp_123",
  • "variants": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "external_id": "ID001",
  • "title": "Striped Jumper",
  • "slug": "striped-jumper"
}

Update a Product

Authorizations:
oauth
path Parameters
id
required
string

Either the Internal or External ID

header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Request Body schema: application/json
Array of objects (ProductVariant-2)
external_id
string <= 100 characters

External ID (cannot start with pp_ and must be unique)

title
string <= 255 characters

Product Title

slug
string <= 255 characters

Product Slug (Used as the link identifier)

Responses

Request samples

Content type
application/json
{
  • "variants": [
    ],
  • "external_id": "ID001",
  • "title": "Striped Jumper",
  • "slug": "striped-jumper"
}

Response samples

Content type
application/json
{
  • "id": "pp_123",
  • "variants": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "external_id": "ID001",
  • "title": "Striped Jumper",
  • "slug": "striped-jumper"
}

Get Product Variant

Authorizations:
oauth
path Parameters
id
required
string

Either the Internal or External ID

header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Responses

Response samples

Content type
application/json
{
  • "product_id": "pp_123",
  • "id": "pv_234",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "external_id": "IDV001",
  • "sku": "IDV001",
  • "weight_in_grams": 0,
  • "tax_type": 1,
  • "position": 1,
  • "cart_image_url": null,
  • "rrp": [
    ],
  • "options": [
    ],
  • "status": "live",
  • "settings": [
    ],
  • "stock": [
    ]
}

Update a Product Variant

Authorizations:
oauth
path Parameters
id
required
string

Either the Internal or External ID

header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Request Body schema: application/json
external_id
string <= 100 characters

External ID (cannot start with pv_ and must be unique)

sku
string [ 1 .. 100 ] characters

SKU

weight_in_grams
number

Product weight in grams

tax_type
number
Deprecated
Default: 1

Tax type ID - to be replaced with a more permanent solution

position
number or null
Default: 1

Position

cart_image_url
string or null <= 512 characters
Deprecated

to be replaced with a more permanent solution

Array of objects (ProductVariantRRP)

RRP price (single item per currency_code)

Array of objects (ProductVariantOptions)

Product Options (item per group)

status
string
Default: "pending"
Enum: "pending" "discontinued" "suspended" "live"

Status - only live products are available frontend

Array of objects (ProductVariantSettings)

Variant Settings (item per customer_group)

Array of objects (ProductStock-2)

Responses

Request samples

Content type
application/json
{
  • "external_id": "IDV001",
  • "sku": "IDV001",
  • "weight_in_grams": 0,
  • "tax_type": 1,
  • "position": 1,
  • "cart_image_url": null,
  • "rrp": [
    ],
  • "options": [
    ],
  • "status": "live",
  • "settings": [
    ],
  • "stock": [
    ]
}

Response samples

Content type
application/json
{
  • "product_id": "pp_123",
  • "id": "pv_234",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "external_id": "IDV001",
  • "sku": "IDV001",
  • "weight_in_grams": 0,
  • "tax_type": 1,
  • "position": 1,
  • "cart_image_url": null,
  • "rrp": [
    ],
  • "options": [
    ],
  • "status": "live",
  • "settings": [
    ],
  • "stock": [
    ]
}

Stock

Get Product Stock

Authorizations:
oauth
path Parameters
SKU
required
string

Product Variant SKU

header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update Product Stock

Authorizations:
oauth
path Parameters
SKU
required
string

Product Variant SKU

header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Request Body schema: application/json
Array
stock_location_id
required
string

Stock Location ID (internal or external ID)

stock_level
required
integer <int32>
Default: 0

Quantity of stock held at the location

restock_date
string or null <date>

Restock Date

min_stock_level
integer <int32>
Default: 0

Allow pre-ordering / overselling up to this qty. For example, if set to -9 and stock level was 0, 9 units could be sold.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/problem+json
{}

Pricing

Get Product Pricing

Authorizations:
oauth
path Parameters
SKU
required
string

Product Variant SKU

header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update Product Pricing

This patch endpoint will remove all pricing for the price list slugs provided and apply provided pricing against the provided price lists. It is also important to note you can upload multiple price lists in one call.

Authorizations:
oauth
path Parameters
SKU
required
string

Product Variant SKU

header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Request Body schema: application/json
Array
price_list_slug
required
string

Price List Slug

required
Array of objects

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Customers

Create a Customer

Authorizations:
oauth
header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Request Body schema: application/json
title
string <= 30 characters

Title

first_name
required
string <= 128 characters

First Name

last_name
required
string <= 128 characters

Last Name

email
required
string <= 255 characters

Email Address (Unique)

company_name
string <= 255 characters

Company Name

external_id
string <= 255 characters

External Id (cannot start with cu_ and must be unique)

accounting_id
string <= 255 characters

Accounting Id

status
any
Default: "active"
Enum: "pending" "active" "inactive" "rejected"

Status - login is allowed only via the active status

group
string <= 30 characters
Default: "default"

Customer Group

default_billing_address_id
string or null

Default Billing Address ID (returned as ID but can be provided by the external ID)

default_shipping_address_id
string or null

Default Billing Address ID (returned as ID but can be provided by the external ID)

currency_code
string or null = 3 characters

ISO 4217 currency code, not required if price_lists is specified

sales_agent_groups
Array of strings[ items [ 1 .. 64 ] characters ^[a-zA-Z0-9]+(?:-[a-zA-Z0-9]+)*$ ]

Sales Agent Groups If a sales agent/customer, access is only given to other sales agents/customers with one of the groups specified. If a customer, access is only given to other sales agents with one of the groups specified. If empty for a customer, only sales agents with an empty list can access the customer. If empty for a sales agent, any customer is accessible.

price_lists
Array of strings

Customer specifc price lists (overrides customer group settings)

vatin_numbers
Array of strings

Validated against VAT identification numbers

discount_percentage
number or null <float> [ 0 .. 100 ]

Customer specific percentage discount

tax_exempt
boolean
Default: false

Tax Exempt (overrides vatin_numbers and not recommeneded)

payment_by_invoice
boolean or null
Default: null

Allow payments via invoice (overrides customer group settings)

object or null
Default: null

Allow payments on account when the order total meets available credit (overrides customer group settings)

metadata
object or null

Metadata

parent_customer_id
string or null

Either SparkLayer Customer ID or External ID

Responses

Request samples

Content type
application/json
{
  • "title": "Mr",
  • "first_name": "Tom",
  • "last_name": "Jones",
  • "email": "Tom.jones@climbing.com",
  • "company_name": "Tom Jones Climbing Ltd",
  • "external_id": "XXXX00123",
  • "accounting_id": "XXXX00123",
  • "status": "pending",
  • "group": "default",
  • "default_billing_address_id": "ca_1234",
  • "default_shipping_address_id": "ca_1234",
  • "currency_code": "gbp",
  • "sales_agent_groups": [
    ],
  • "price_lists": [
    ],
  • "vatin_numbers": [
    ],
  • "discount_percentage": 100,
  • "tax_exempt": false,
  • "payment_by_invoice": null,
  • "payment_on_account": null,
  • "metadata": null,
  • "parent_customer_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "cu_123",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "addresses": [
    ],
  • "title": "Mr",
  • "first_name": "Tom",
  • "last_name": "Jones",
  • "email": "Tom.jones@climbing.com",
  • "company_name": "Tom Jones Climbing Ltd",
  • "external_id": "XXXX00123",
  • "accounting_id": "XXXX00123",
  • "status": "pending",
  • "group": "default",
  • "default_billing_address_id": "ca_1234",
  • "default_shipping_address_id": "ca_1234",
  • "currency_code": "gbp",
  • "sales_agent_groups": [
    ],
  • "price_lists": [
    ],
  • "vatin_numbers": [
    ],
  • "discount_percentage": 100,
  • "tax_exempt": false,
  • "payment_by_invoice": null,
  • "payment_on_account": null,
  • "metadata": null,
  • "parent_customer": {
    }
}

Get a Customer

Authorizations:
oauth
path Parameters
id
required
string

Either the Internal or External ID

header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Responses

Response samples

Content type
application/json
{
  • "id": "cu_123",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "addresses": [
    ],
  • "title": "Mr",
  • "first_name": "Tom",
  • "last_name": "Jones",
  • "email": "Tom.jones@climbing.com",
  • "company_name": "Tom Jones Climbing Ltd",
  • "external_id": "XXXX00123",
  • "accounting_id": "XXXX00123",
  • "status": "pending",
  • "group": "default",
  • "default_billing_address_id": "ca_1234",
  • "default_shipping_address_id": "ca_1234",
  • "currency_code": "gbp",
  • "sales_agent_groups": [
    ],
  • "price_lists": [
    ],
  • "vatin_numbers": [
    ],
  • "discount_percentage": 100,
  • "tax_exempt": false,
  • "payment_by_invoice": null,
  • "payment_on_account": null,
  • "metadata": null,
  • "parent_customer": {
    }
}

Update a Customer

Authorizations:
oauth
path Parameters
id
required
string

Either the Internal or External ID

header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Request Body schema: application/json
title
string <= 30 characters

Title

first_name
string <= 128 characters

First Name

last_name
string <= 128 characters

Last Name

email
string <= 255 characters

Email Address (Unique)

company_name
string <= 255 characters

Company Name

external_id
string <= 255 characters

External Id (cannot start with cu_ and must be unique)

accounting_id
string <= 255 characters

Accounting Id

status
any
Default: "active"
Enum: "pending" "active" "inactive" "rejected"

Status - login is allowed only via the active status

group
string <= 30 characters
Default: "default"

Customer Group

default_billing_address_id
string or null

Default Billing Address ID (returned as ID but can be provided by the external ID)

default_shipping_address_id
string or null

Default Billing Address ID (returned as ID but can be provided by the external ID)

currency_code
string or null = 3 characters

ISO 4217 currency code, not required if price_lists is specified

sales_agent_groups
Array of strings[ items [ 1 .. 64 ] characters ^[a-zA-Z0-9]+(?:-[a-zA-Z0-9]+)*$ ]

Sales Agent Groups If a sales agent/customer, access is only given to other sales agents/customers with one of the groups specified. If a customer, access is only given to other sales agents with one of the groups specified. If empty for a customer, only sales agents with an empty list can access the customer. If empty for a sales agent, any customer is accessible.

price_lists
Array of strings

Customer specifc price lists (overrides customer group settings)

vatin_numbers
Array of strings

Validated against VAT identification numbers

discount_percentage
number or null <float> [ 0 .. 100 ]

Customer specific percentage discount

tax_exempt
boolean
Default: false

Tax Exempt (overrides vatin_numbers and not recommeneded)

payment_by_invoice
boolean or null
Default: null

Allow payments via invoice (overrides customer group settings)

object or null
Default: null

Allow payments on account when the order total meets available credit (overrides customer group settings)

metadata
object or null

Metadata

parent_customer_id
string or null

Either SparkLayer Customer ID or External ID

Responses

Request samples

Content type
application/json
{
  • "title": "Mr",
  • "first_name": "Tom",
  • "last_name": "Jones",
  • "email": "Tom.jones@climbing.com",
  • "company_name": "Tom Jones Climbing Ltd",
  • "external_id": "XXXX00123",
  • "accounting_id": "XXXX00123",
  • "status": "pending",
  • "group": "default",
  • "default_billing_address_id": "ca_1234",
  • "default_shipping_address_id": "ca_1234",
  • "currency_code": "gbp",
  • "sales_agent_groups": [
    ],
  • "price_lists": [
    ],
  • "vatin_numbers": [
    ],
  • "discount_percentage": 100,
  • "tax_exempt": false,
  • "payment_by_invoice": null,
  • "payment_on_account": null,
  • "metadata": null,
  • "parent_customer_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "cu_123",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "addresses": [
    ],
  • "title": "Mr",
  • "first_name": "Tom",
  • "last_name": "Jones",
  • "email": "Tom.jones@climbing.com",
  • "company_name": "Tom Jones Climbing Ltd",
  • "external_id": "XXXX00123",
  • "accounting_id": "XXXX00123",
  • "status": "pending",
  • "group": "default",
  • "default_billing_address_id": "ca_1234",
  • "default_shipping_address_id": "ca_1234",
  • "currency_code": "gbp",
  • "sales_agent_groups": [
    ],
  • "price_lists": [
    ],
  • "vatin_numbers": [
    ],
  • "discount_percentage": 100,
  • "tax_exempt": false,
  • "payment_by_invoice": null,
  • "payment_on_account": null,
  • "metadata": null,
  • "parent_customer": {
    }
}

Delete a Customer

Authorizations:
oauth
path Parameters
id
required
string

Either the Internal or External ID

header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Responses

Response samples

Content type
application/problem+json
{}

Addresses

List Customer Addresses

Authorizations:
oauth
path Parameters
id
required
string

Either the Internal or External ID

header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a Customer Address

Authorizations:
oauth
path Parameters
id
required
string

Either the Internal or External ID

header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Request Body schema: application/json
title
string <= 30 characters

Title

first_name
string <= 50 characters

First Name

last_name
string <= 50 characters

Last Name

company
string <= 128 characters

Company

address_line1
required
string <= 255 characters

Address Line 1

address_line2
string <= 255 characters

Address Line 2

city
required
string <= 128 characters

City

region_code
string or null <= 10 characters

Region

postal_code
string <= 20 characters

Postal Code

country_code
required
string <= 3 characters

Country Code

phone
string <= 20 characters

Phone

mobile
string <= 20 characters

Phone - Mobile

external_id
string or null <= 50 characters

External ID (cannot start with ca_ and must be unique)

nickname
string <= 50 characters

Nickname

Responses

Request samples

Content type
application/json
{
  • "title": "Mr",
  • "first_name": "Bob",
  • "last_name": "Jones",
  • "company": "Tom Jones Climbing Ltd",
  • "address_line1": "Example Industrial Estate",
  • "address_line2": "North Country",
  • "city": "Cityland",
  • "region_code": "CA",
  • "postal_code": "12345",
  • "country_code": "USA",
  • "phone": "+44 (0) 123456789",
  • "mobile": "+44 (0) 723456789",
  • "external_id": "ADD1234567",
  • "nickname": "Warehouse - Cityland"
}

Response samples

Content type
application/json
{
  • "id": "ca_123",
  • "title": "Mr",
  • "first_name": "Bob",
  • "last_name": "Jones",
  • "company": "Tom Jones Climbing Ltd",
  • "address_line1": "Example Industrial Estate",
  • "address_line2": "North Country",
  • "city": "Cityland",
  • "region_code": "CA",
  • "postal_code": "12345",
  • "country_code": "USA",
  • "phone": "+44 (0) 123456789",
  • "mobile": "+44 (0) 723456789",
  • "external_id": "ADD1234567",
  • "nickname": "Warehouse - Cityland"
}

Delete Customer Address

Authorizations:
oauth
path Parameters
id
required
string

Either the Internal or External ID

id2
required
string

Spark Layer ID of record (or external ID of the entity)

header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Responses

Response samples

Content type
application/problem+json
{}

Orders

Create Order

Authorizations:
oauth
header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Request Body schema: application/json
created_at
required
string <date-time>

Checkout Completed At

spark_billing_chargeable
boolean
Deprecated
Default: true

Spark Billing Chargable Order - set to false for imported orders from other systems

external_id
string or null

External Id

payment_method
required
string
Enum: "upfrontPayment" "paymentByInvoice" "paymentOnAccount" "hokodoPayment" "other"

Payment Method

visible_id
string or null

Visible Id (shown in the My A/c Section)

customer_id
required
string

Customer Id (internal/external ID accepted)

customer_reference
string or null <= 512 characters

Customer Reference

currency_code
required
string

ISO 4217 currency code.

object or null

Either pass a billing_address_id or a billing_address

billing_address_id
string or null

Address Id (internal/external ID accepted)

required
Array of objects (OrderPackageCreate-2) non-empty
metadata
object or null

Metadata

invoice_url
string or null

Invoice URL

Responses

Request samples

Content type
application/json
{
  • "created_at": "2021-01-30T08:30:00Z",
  • "spark_billing_chargeable": true,
  • "external_id": "ORD21231231",
  • "payment_method": "upfrontPayment",
  • "visible_id": "B2B00123",
  • "customer_id": "cu_123",
  • "customer_reference": "PO123",
  • "currency_code": "gbp",
  • "billing_address": {
    },
  • "billing_address_id": "ca_123",
  • "packages": [
    ],
  • "metadata": null,
  • "invoice_url": "string"
}

Response samples

Content type
application/json
{
  • "id": "o_123",
  • "customer_id": "cu_123",
  • "spark_billing_chargeable": true,
  • "payment_method": "upfrontPayment",
  • "status": "processing",
  • "currency_code": "string",
  • "external_id": "B2B00123",
  • "visible_id": "B2B00123",
  • "customer_reference": "PO123",
  • "created_at": "2021-01-30T08:30:00Z",
  • "billing_address": {
    },
  • "packages": [
    ],
  • "total_sub": {
    },
  • "total_shipping": {
    },
  • "total": {
    },
  • "invoice_url": "string",
  • "metadata": null,
  • "custom_fields": [
    ]
}

Get a Order

Authorizations:
oauth
path Parameters
id
required
string

Either the Internal or External ID

header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Responses

Response samples

Content type
application/json
{
  • "id": "o_123",
  • "customer_id": "cu_123",
  • "spark_billing_chargeable": true,
  • "payment_method": "upfrontPayment",
  • "status": "processing",
  • "currency_code": "string",
  • "external_id": "B2B00123",
  • "visible_id": "B2B00123",
  • "customer_reference": "PO123",
  • "created_at": "2021-01-30T08:30:00Z",
  • "billing_address": {
    },
  • "packages": [
    ],
  • "total_sub": {
    },
  • "total_shipping": {
    },
  • "total": {
    },
  • "invoice_url": "string",
  • "metadata": null,
  • "custom_fields": [
    ]
}

Update Order Details

Authorizations:
oauth
path Parameters
id
required
string

Either the Internal or External ID

header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Request Body schema: application/json
invoice_url
string or null

Invoice URL

Responses

Request samples

Content type
application/json
{
  • "invoice_url": "string"
}

Response samples

Content type
application/json
{
  • "id": "o_123",
  • "customer_id": "cu_123",
  • "spark_billing_chargeable": true,
  • "payment_method": "upfrontPayment",
  • "status": "processing",
  • "currency_code": "string",
  • "external_id": "B2B00123",
  • "visible_id": "B2B00123",
  • "customer_reference": "PO123",
  • "created_at": "2021-01-30T08:30:00Z",
  • "billing_address": {
    },
  • "packages": [
    ],
  • "total_sub": {
    },
  • "total_shipping": {
    },
  • "total": {
    },
  • "invoice_url": "string",
  • "metadata": null,
  • "custom_fields": [
    ]
}

Ship Items

Authorizations:
oauth
path Parameters
id
required
string

Either the Internal or External ID

header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Request Body schema: application/json
external_id
string or null

External Id

visible_id
string or null

Visible Id (shown in the My A/c Section)

shipped_at
required
string <date-time>
Array of objects (OrderPackageItemShipmentTracking-2)
object or null

Either pass a shipping_address_id or a shipping_address.

shipping_address_id
string or null

Customer Address Id (can be supplied as internal or external)

object

Total price for shipping

required
Array of objects non-empty

Items will be matched on variant internal / external ID and then fall back to SKU.

Responses

Request samples

Content type
application/json
{
  • "external_id": "Pkg123",
  • "visible_id": "Ship01",
  • "shipped_at": "2019-08-24T14:15:22Z",
  • "shipment_tracking": [
    ],
  • "shipping_address": {
    },
  • "shipping_address_id": "ca_123",
  • "total_shipping": {
    },
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "o_123",
  • "customer_id": "cu_123",
  • "spark_billing_chargeable": true,
  • "payment_method": "upfrontPayment",
  • "status": "processing",
  • "currency_code": "string",
  • "external_id": "B2B00123",
  • "visible_id": "B2B00123",
  • "customer_reference": "PO123",
  • "created_at": "2021-01-30T08:30:00Z",
  • "billing_address": {
    },
  • "packages": [
    ],
  • "total_sub": {
    },
  • "total_shipping": {
    },
  • "total": {
    },
  • "invoice_url": "string",
  • "metadata": null,
  • "custom_fields": [
    ]
}

Cancel Items

The items must not be shipped

Authorizations:
oauth
path Parameters
id
required
string

Either the Internal or External ID

header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Request Body schema: application/json
external_id
string or null

External Id

visible_id
string or null

Visible Id (shown in the My A/c Section)

cancelled_at
required
string or null <date-time>
required
Array of objects non-empty

Items will be matched on variant internal / external ID and then fall back to SKU.

Responses

Request samples

Content type
application/json
{
  • "external_id": "Pkg123",
  • "visible_id": "Cancel01",
  • "cancelled_at": null,
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "o_123",
  • "customer_id": "cu_123",
  • "spark_billing_chargeable": true,
  • "payment_method": "upfrontPayment",
  • "status": "processing",
  • "currency_code": "string",
  • "external_id": "B2B00123",
  • "visible_id": "B2B00123",
  • "customer_reference": "PO123",
  • "created_at": "2021-01-30T08:30:00Z",
  • "billing_address": {
    },
  • "packages": [
    ],
  • "total_sub": {
    },
  • "total_shipping": {
    },
  • "total": {
    },
  • "invoice_url": "string",
  • "metadata": null,
  • "custom_fields": [
    ]
}

Return Items

Authorizations:
oauth
path Parameters
id
required
string

Either the Internal or External ID

header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Request Body schema: application/json
external_id
string or null

External Id

visible_id
string or null

Visible Id (shown in the My A/c Section)

returned_at
required
string or null <date-time>
required
Array of objects non-empty

Items will be matched on variant internal / external ID and then fall back to SKU.

object

Returned Shipping Cost

Responses

Request samples

Content type
application/json
{
  • "external_id": "Pkg123",
  • "visible_id": "Retun01",
  • "returned_at": null,
  • "items": [
    ],
  • "refund_shipping": {
    }
}

Response samples

Content type
application/json
{
  • "id": "o_123",
  • "customer_id": "cu_123",
  • "spark_billing_chargeable": true,
  • "payment_method": "upfrontPayment",
  • "status": "processing",
  • "currency_code": "string",
  • "external_id": "B2B00123",
  • "visible_id": "B2B00123",
  • "customer_reference": "PO123",
  • "created_at": "2021-01-30T08:30:00Z",
  • "billing_address": {
    },
  • "packages": [
    ],
  • "total_sub": {
    },
  • "total_shipping": {
    },
  • "total": {
    },
  • "invoice_url": "string",
  • "metadata": null,
  • "custom_fields": [
    ]
}

Update Items

Authorizations:
oauth
path Parameters
id
required
string

Either the Internal or External ID

packageId
required
string

Spark Layer Package ID

header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Request Body schema: application/json
object

Total price for shipping

required
Array of objects non-empty

Responses

Request samples

Content type
application/json
{
  • "total_shipping": {
    },
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "o_123",
  • "customer_id": "cu_123",
  • "spark_billing_chargeable": true,
  • "payment_method": "upfrontPayment",
  • "status": "processing",
  • "currency_code": "string",
  • "external_id": "B2B00123",
  • "visible_id": "B2B00123",
  • "customer_reference": "PO123",
  • "created_at": "2021-01-30T08:30:00Z",
  • "billing_address": {
    },
  • "packages": [
    ],
  • "total_sub": {
    },
  • "total_shipping": {
    },
  • "total": {
    },
  • "invoice_url": "string",
  • "metadata": null,
  • "custom_fields": [
    ]
}

Customer Groups

List Customer Groups

Authorizations:
oauth
header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

New Customer Group

Authorizations:
oauth
header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Request Body schema: application/json
slug
required
string <= 30 characters ^(?!^\d+$)^.+$
name
required
string <= 256 characters

Responses

Request samples

Content type
application/json
{
  • "slug": "eu_gbp",
  • "name": "Europe (GBP) Customers"
}

Response samples

Content type
application/json
[
  • {
    }
]

Update Customer Group

Authorizations:
oauth
path Parameters
slug
required
string
header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Request Body schema: application/json
name
required
string <= 256 characters

Responses

Request samples

Content type
application/json
{
  • "name": "Europe (GBP) Customers"
}

Response samples

Content type
application/json
[
  • {
    }
]

Delete Customer Group

Authorizations:
oauth
path Parameters
slug
required
string
header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Responses

Response samples

Content type
application/problem+json
{}

Shipping

List of Shipping Methods

Authorizations:
oauth
header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a Shipping Method

Authorizations:
oauth
header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Request Body schema: application/json
sku
required
string <= 50 characters

Shipping SKU

title
required
string <= 50 characters

Shiping Method Name shown at checkout

prority
number [ 0 .. 127 ]
Default: 0

Shown by order (lower first)

countries
required
Array of strings

Countries covered by this shipping method

groups
Array of strings

Customer groups covered by this shipping method (use default to cover all groups)

Array of objects

Responses

Request samples

Content type
application/json
{
  • "sku": "SKU001",
  • "title": "Standard Shipping",
  • "prority": 0,
  • "countries": [
    ],
  • "groups": [
    ],
  • "bands": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "sm_123",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "sku": "SKU001",
  • "title": "Standard Shipping",
  • "prority": 0,
  • "countries": [
    ],
  • "groups": [
    ],
  • "bands": [
    ]
}

Get a Shipping Method

Authorizations:
oauth
path Parameters
id
required
string

Either the Internal or External ID

header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Responses

Response samples

Content type
application/json
{
  • "id": "sm_123",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "sku": "SKU001",
  • "title": "Standard Shipping",
  • "prority": 0,
  • "countries": [
    ],
  • "groups": [
    ],
  • "bands": [
    ]
}

Update a Shipping Method

Authorizations:
oauth
path Parameters
id
required
string

Either the Internal or External ID

header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Request Body schema: application/json
sku
string <= 50 characters

Shipping SKU

title
string <= 50 characters

Shiping Method Name shown at checkout

prority
number [ 0 .. 127 ]
Default: 0

Shown by order (lower first)

countries
Array of strings

Countries covered by this shipping method

groups
Array of strings

Customer groups covered by this shipping method (use default to cover all groups)

Array of objects

Responses

Request samples

Content type
application/json
{
  • "sku": "SKU001",
  • "title": "Standard Shipping",
  • "prority": 0,
  • "countries": [
    ],
  • "groups": [
    ],
  • "bands": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "sm_123",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "sku": "SKU001",
  • "title": "Standard Shipping",
  • "prority": 0,
  • "countries": [
    ],
  • "groups": [
    ],
  • "bands": [
    ]
}

Stock Locations

List of Stock Location

Authorizations:
oauth
header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a Stock Locations

Authorizations:
oauth
header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Request Body schema: application/json
name
required
string <= 255 characters

Name

external_id
required
string <= 255 characters

External ID (cannot start with sl_ and must be unique)

Responses

Request samples

Content type
application/json
{
  • "name": "Stock Warehouse 1",
  • "external_id": "warehouse-1"
}

Response samples

Content type
application/json
{
  • "id": "sl_2",
  • "name": "Stock Warehouse 1",
  • "external_id": "warehouse-1"
}

Get a Stock Locations

Authorizations:
oauth
path Parameters
id
required
string

Either the Internal or External ID

header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Responses

Response samples

Content type
application/json
{
  • "id": "sl_2",
  • "name": "Stock Warehouse 1",
  • "external_id": "warehouse-1"
}

Update a Stock Locations

Authorizations:
oauth
path Parameters
id
required
string

Either the Internal or External ID

header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Request Body schema: application/json
name
string <= 255 characters

Name

external_id
string <= 255 characters

External ID (cannot start with sl_ and must be unique)

Responses

Request samples

Content type
application/json
{
  • "name": "Stock Warehouse 1",
  • "external_id": "warehouse-1"
}

Response samples

Content type
application/json
{
  • "id": "sl_2",
  • "name": "Stock Warehouse 1",
  • "external_id": "warehouse-1"
}

Settings

List Global Settings

Lists Global settings (minus settings which include authentication details)

Authorizations:
oauth
header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update Global Setting

Authorizations:
oauth
header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Request Body schema: application/json
Array
key
required
string
value
required
any or null

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/problem+json
{}

List Customer Group Settings

Lists Customer Group settings by Customer Group

Authorizations:
oauth
path Parameters
slug
required
string
header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update Customer Group Setting

Authorizations:
oauth
path Parameters
slug
required
string
header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Request Body schema: application/json
Array
One of
key
required
string
Value: "orderTotalsValidation"
required
Array of objects

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/problem+json
{}

Price Lists

A base-list is used by default as a fallback price list.

List Price Lists

Authorizations:
oauth
header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a Price List

Authorizations:
oauth
header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Request Body schema: application/json
slug
required
string [ 1 .. 64 ] characters

Slug

name
required
string [ 1 .. 64 ] characters

Name

currency_code
required
string = 3 characters

ISO 4217 currency code.

Responses

Request samples

Content type
application/json
{
  • "slug": "base-list",
  • "name": "Base Price List",
  • "currency_code": "gbp"
}

Response samples

Content type
application/json
{
  • "slug": "base-list",
  • "name": "Base Price List",
  • "currency_code": "gbp"
}

Delete a Price List

Authorizations:
oauth
header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Responses

Response samples

Content type
application/problem+json
{}