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
Production https://api.sparklayer.io
Staging https://api.staging.sparklayer.io

Simulation environment

You can test out the SparkLayer API using our Postman simulation environment. An integral element to SparkLayer is price lists and this will guide you through how to send through sample price list data via the API.

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/oauth/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 Nullable

A list of errors related to the call

{}

Products

List Products

(Coming soon)

Authorizations:
oauth (products.read)
header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a Product

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

Spark Layer Site ID

Request Body schema: application/json
Array of objects (ProductVariant)
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 (products.read)
path Parameters
id
required
string

Either the SparkLayer ID or the external ID of the entity

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 (products)
path Parameters
id
required
string

Either the SparkLayer ID or the external ID of the entity

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

Spark Layer Site ID

Request Body schema: application/json
Array of objects (ProductVariant)
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 (products.read)
path Parameters
id
required
string

Either the SparkLayer ID or the external ID of the entity

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,
  • "default_option": true,
  • "cart_image_url": null,
  • "rrp": [
    ],
  • "options": [
    ],
  • "status": "live",
  • "settings": [
    ]
}

Update a Product Variant

Authorizations:
oauth (products)
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
required
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

default_option
boolean

Default product variant (otherwise first is used by default)

cart_image_url
string <= 255 characters Nullable
Deprecated

to be replaced with a more permanent solution

Array of objects

RRP price (sinlgeitem per currency_code)

Array of objects

Product Options (item per group)

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

Status - only live products are available frontend

Array of objects

Variant Settings (item per customer_group)

Responses

Request samples

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

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,
  • "default_option": true,
  • "cart_image_url": null,
  • "rrp": [
    ],
  • "options": [
    ],
  • "status": "live",
  • "settings": [
    ]
}

Stock

Get Product Stock

Authorizations:
oauth (products.stock.read)
path Parameters
id
required
string

Either the SparkLayer ID or the external ID of the entity

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 (products.stock)
path Parameters
id
required
string

Either the SparkLayer ID or the external ID of the entity

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 <date> Nullable

Restock Date

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/problem+json
{}

Pricing

Get Product Pricing

Authorizations:
oauth (products.pricing.read)
path Parameters
id
required
string

Either the SparkLayer ID or the external ID of the entity

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.

Authorizations:
oauth (products.pricing)
path Parameters
id
required
string

Either the SparkLayer ID or the external ID of the entity

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

List Customers

(Coming soon)

Authorizations:
oauth (customers.read)
header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a Customer

Authorizations:
oauth (customers)
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)

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 Nullable

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

default_shipping_address_id
string Nullable

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

currency_code
string 3 characters Nullable

ISO 4217 currency code, not required if price_lists is specified

price_lists
Array of strings

Customer specifc price lists (overrides customer group settings)

vatin_numbers
Array of strings

Validated against VAT identification numbers

tax_exempt
boolean
Default: false

Tax Exempt (overrides vatin_numbers and not recommeneded)

payment_by_invoice
boolean Nullable
Default: null

Allow payments via invoice (overrides customer group settings)

object Nullable
Default: null

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

metadata
object Nullable

Metadata

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",
  • "status": "active",
  • "group": "default",
  • "default_billing_address_id": "ca_1234",
  • "default_shipping_address_id": "ca_1234",
  • "currency_code": "gbp",
  • "price_lists": [
    ],
  • "vatin_numbers": [
    ],
  • "tax_exempt": false,
  • "payment_by_invoice": null,
  • "payment_on_account": null,
  • "metadata": null
}

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",
  • "status": "active",
  • "group": "default",
  • "default_billing_address_id": "ca_1234",
  • "default_shipping_address_id": "ca_1234",
  • "currency_code": "gbp",
  • "price_lists": [
    ],
  • "vatin_numbers": [
    ],
  • "tax_exempt": false,
  • "payment_by_invoice": null,
  • "payment_on_account": null,
  • "metadata": null
}

Get a Customer

Authorizations:
oauth (customers.read)
path Parameters
id
required
string

Either the SparkLayer ID or the external ID of the entity

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",
  • "status": "active",
  • "group": "default",
  • "default_billing_address_id": "ca_1234",
  • "default_shipping_address_id": "ca_1234",
  • "currency_code": "gbp",
  • "price_lists": [
    ],
  • "vatin_numbers": [
    ],
  • "tax_exempt": false,
  • "payment_by_invoice": null,
  • "payment_on_account": null,
  • "metadata": null
}

Update a Customer

Authorizations:
oauth (customers)
path Parameters
id
required
string

Either the SparkLayer ID or the external ID of the entity

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)

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 Nullable

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

default_shipping_address_id
string Nullable

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

currency_code
string 3 characters Nullable

ISO 4217 currency code, not required if price_lists is specified

price_lists
Array of strings

Customer specifc price lists (overrides customer group settings)

vatin_numbers
Array of strings

Validated against VAT identification numbers

tax_exempt
boolean
Default: false

Tax Exempt (overrides vatin_numbers and not recommeneded)

payment_by_invoice
boolean Nullable
Default: null

Allow payments via invoice (overrides customer group settings)

object Nullable
Default: null

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

metadata
object Nullable

Metadata

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",
  • "status": "active",
  • "group": "default",
  • "default_billing_address_id": "ca_1234",
  • "default_shipping_address_id": "ca_1234",
  • "currency_code": "gbp",
  • "price_lists": [
    ],
  • "vatin_numbers": [
    ],
  • "tax_exempt": false,
  • "payment_by_invoice": null,
  • "payment_on_account": null,
  • "metadata": null
}

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",
  • "status": "active",
  • "group": "default",
  • "default_billing_address_id": "ca_1234",
  • "default_shipping_address_id": "ca_1234",
  • "currency_code": "gbp",
  • "price_lists": [
    ],
  • "vatin_numbers": [
    ],
  • "tax_exempt": false,
  • "payment_by_invoice": null,
  • "payment_on_account": null,
  • "metadata": null
}

Reset a Customer Password Deprecated

Internal Use Only (will be deprecated and removed long term)

Authorizations:
oauth (customers)
path Parameters
id
required
string

Either the SparkLayer ID or the external ID of the entity

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

Spark Layer Site ID

Responses

Response samples

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

Addresses

List Customer Addresses

Authorizations:
oauth (customers.read)
path Parameters
id
required
string

Either the SparkLayer ID or the external ID of the entity

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 (customers)
path Parameters
id
required
string

Either the SparkLayer ID or the external ID of the entity

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 <= 4 characters Nullable

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 <= 50 characters Nullable

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 (customers)
path Parameters
id
required
string

Either the SparkLayer ID or the external ID of the entity

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 (orders)
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
Default: true

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

external_id
string Nullable

External Id

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

Payment Method

visible_id
string Nullable

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

customer_id
required
string

Customer Id (internal/external ID accepted)

customer_reference
string <= 50 characters Nullable

Customer Reference

currency_code
required
string

ISO 4217 currency code.

object Nullable

Either pass a billing_address_id or a billing_address

billing_address_id
string Nullable

Address Id (internal/external ID accepted)

required
Array of objects (OrderPackageCreate) non-empty
metadata
object Nullable

Metadata

Responses

Request samples

Content type
application/json
{
  • "created_at": "2021-01-30T08:30:00Z",
  • "spark_billing_chargeable": true,
  • "external_id": 21231231,
  • "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
}

Response samples

Content type
application/json
{
  • "id": "o_123",
  • "customer_id": "cu_123",
  • "spark_billing_chargeable": true,
  • "payment_method": "upfrontPayment",
  • "status": "incoming",
  • "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": {
    },
  • "metadata": null
}

Get a Order

Authorizations:
oauth (orders.read)
path Parameters
id
required
string

Either the SparkLayer ID or the external ID of the entity

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": "incoming",
  • "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": {
    },
  • "metadata": null
}

Ship Items

Authorizations:
oauth (orders.read)
path Parameters
id
required
string

Either the SparkLayer ID or the external ID of the entity

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

Spark Layer Site ID

Request Body schema: application/json
external_id
string Nullable

External Id

visible_id
string Nullable

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

shipped_at
required
string <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": "Ship01",
  • "shipped_at": "2019-08-24T14:15:22Z",
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "o_123",
  • "customer_id": "cu_123",
  • "spark_billing_chargeable": true,
  • "payment_method": "upfrontPayment",
  • "status": "incoming",
  • "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": {
    },
  • "metadata": null
}

Cancel Items

The items must not be shipped

Authorizations:
oauth (orders.read)
path Parameters
id
required
string

Either the SparkLayer ID or the external ID of the entity

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

Spark Layer Site ID

Request Body schema: application/json
external_id
string Nullable

External Id

visible_id
string Nullable

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

cancelled_at
required
string <date-time> Nullable
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": "incoming",
  • "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": {
    },
  • "metadata": null
}

Return Items

Authorizations:
oauth (orders.read)
path Parameters
id
required
string

Either the SparkLayer ID or the external ID of the entity

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

Spark Layer Site ID

Request Body schema: application/json
external_id
string Nullable

External Id

visible_id
string Nullable

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

returned_at
required
string <date-time> Nullable
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": "incoming",
  • "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": {
    },
  • "metadata": null
}

Customer Groups

List Customer Groups

Authorizations:
oauth (settings)
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 (settings)
header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Request Body schema: application/json
slug
required
string <= 30 characters
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
[
  • {
    }
]

Delete Customer Group

Authorizations:
oauth (settings)
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 (setup.read)
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 (setup)
header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

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

Shipping SKU

title
required
string

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

Array of objects

Responses

Request samples

Content type
application/json
{
  • "sku": "SKU001",
  • "title": "Standard Shipping",
  • "prority": 0,
  • "countries": [
    ],
  • "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": [
    ],
  • "bands": [
    ]
}

Get a Shipping Method

Authorizations:
oauth (setup.read)
path Parameters
id
required
string

Either the SparkLayer ID or the external ID of the entity

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": [
    ],
  • "bands": [
    ]
}

Update a Shipping Method

Authorizations:
oauth (setup.read)
path Parameters
id
required
string

Either the SparkLayer ID or the external ID of the entity

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

Spark Layer Site ID

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

Shipping SKU

title
string

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

Array of objects

Responses

Request samples

Content type
application/json
{
  • "sku": "SKU001",
  • "title": "Standard Shipping",
  • "prority": 0,
  • "countries": [
    ],
  • "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": [
    ],
  • "bands": [
    ]
}

Stock Locations

List of Stock Location

Authorizations:
oauth (setup.read)
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 (setup)
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 (setup.read)
path Parameters
id
required
string

Either the SparkLayer ID or the external ID of the entity

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 (setup)
path Parameters
id
required
string

Either the SparkLayer ID or the external ID of the entity

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 (settings)
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 (settings)
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: "shopifyAuthentication"
required
object

(Internal Only)

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 (settings)
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 (settings)
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 (setup.read)
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 (setup)
header Parameters
Site-Id
required
string
Example: jones-climbing

Spark Layer Site ID

Request Body schema: application/json
slug
required
string [ 1 .. 32 ] 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"
}