This API is a way for developers and technical staff of businesses to smoothly send sales and customer data to a TrendSeam account so that it may automatically generate personalised graphs and insights on your dashboard.

First Principles

The TrendSeam API is based on RESTful principles, and allows you to transfer your product, order and customer data directly into the TrendSeam system, and then we will process that into extraordinary visual insights and reports you see in your dashboard and reports.

The Data You Should Send

To get the most from TrendSeam, you should be regularly sending us three key streams of data. These are:

• Customers (which will reference Orders)
• Products (and their Variants)
• Orders (and their Order Items)

If you want to get up and running quickly, we can get by with just the Order information, but if you want to get the full benefit of TrendSeam, all three streams will be needed.

Data Format

The API accepts JSON formatted data.

The documentation on these pages demonstrates what data and how it should be formatted in order to successfully submit it into the TrendSeam API.

We understand that there are many, many ways of representing sales data, and much of it comes in proprietary formats. It's possible that this API doesn't direct map to your own data yet, and chances are you will need to build some form of convertor in order to process it into a workable format.

Our aim is to provide a level playing field, to which any retailer can submit their data, but if for whatever reason you can't immediately submit all your data in the exact format we need, this usually isn't a huge problem.

For example, the way you process tax may make it hard to import it the way we ask, so you can omit that as long as you provide the other minimum level of key data (which are each indicated as 'required' in this documentation). With the most fundamental 'required' data sent, TrendSeam can make sense of the general dataset as a whole, but what you get out of TrendSeam maybe a little limited until you can find a way to provide that additional data.

Your API Key

You will need a TrendSeam API Key to start communicating with us via the API. You can email us to request one.

Once you have your key, you will need to create a simple hash from it. View the instructions.

Any Questions?

Just email us and we'll be happy to help.

Code Samples

We will show sample code alongside each section of this documentation. Code will be shown in blocks as so:

{ 'key' : 'value' }

Connecting to the API

You can connect to the API using your hashed TrendSeam API Key, submitted in each API call on the TrendSeam API Endpoint.

The base API Endpoint URL is:

So for example, when you submit a list of Products, you will use our API's Product method – the URL logically created using a standard RESTful pattern – sending formatted JSON Product data using POST to the following URL:

Request Headers

You will need to submit a number of HTTP headers with every request.

Header	Value
Accept	application/json
Content-Type	application/json; charset=UTF-8
Authorization	Basic [Your API Key Hash - see note]

Creating your Hashed API Key

Your TrendSeam API Key needs to be hashed before you add it into your Request Headers. Follow these steps to hash the key:

1. Request a TrendSeam API key from us
2. Create a string by concatenating your API key, a colon and your API key again, as such YOURKEY:YOURKEY
3. Base64 encode this newly created string (you can use this online tool)

Here is a worked example using the fictional API key:

All Set!

You should now be able to successfully connect to the server.

At this time we do not provide libraries for connecting, however if you are looking for ways of starting to use the API, you should consider tools such as cURL.

Example Request Headers (PHP)

/* Use your own TrendSeam API Key Hash, not the 
   one shown below!
   Replace the string after "Basic" with your
   own API Key Hash */

$headers = [
 'Accept: application/json',
 'Content-Type: application/json; charset=UTF-8',
 'Authorization: Basic WXloc0g3RHNoMjMyYTc5MmRnUzpZeWhzSDdEc2gyMzJhNzkyZGdT'
];

Definition

A Order is a single transaction made by a Customer.

It may comprise of Customer, Address and Product data.

Method Endpoint

To upload orders you should POST an Array of JSON-formatted data to this URL:

Data Format

Each Order should be represented as an Object in the array, and should be defined as such:

Property	Value
OrderNumber	Unique ID of this order [required]
OrderDate	Date order was created Format: YYYY-MM-DD HH:MM:SS
SubTotal	Total gross amount [required]
DeliveryCost	The total cost to the customer for any delivery -can include or exclude tax
DeliveryTax	The total amount of tax charged to the customer for any delivery costs
GrandTotal	The total amount the customer paid for the order including any delivery charges, taxes and discounts -this should be the total amount paid by the customer.
Currency	Expressed as ISO 4217 currency codes
SalesChannel	Where the sale was made e.g. Online Store, or Retail Outlet. This can be anything you desire and will be used when graphing your sales. It is useful if you want to separate out one store from another.
Cashier	A Cashier is a particular location within a SalesChannel. If a physical store this could be a Till, Floor or Department allowing you to compare different department's performance. For online transactions, you could use this to store the pament method.
SalesAssistant	SalesAssistant is another level of grouping within SalesChannel and allows you to compare performance. This could be the name of the assistant or another narrative of your chosing. For online transactions, you could use this to store the source of the sale i.e. Google AdWords.
BillingAddress	A billing Address Object
ShippingAddress	A shipping Address Object
Customer	The associated Customer Object
OrderItems	The associated Array of Products in the Order

Example JSON Order Object

{
  'OrderNumber': 'RS001234',
  'OrderDate': '2013-02-12 15:12:04',
  'SubTotal': '326.00',
  'DeliveryCost': '20.00',
  'DeliveryTax': '4.00',
  'GrandTotal': '350.00',
  'Currency': 'gbp',
  'SalesChannel': 'Website',
  'Cashier': 'PayPal',
  'SalesAssistant': 'Google AdWords',
  'BillingAddress': {
	...
  },
  'ShippingAddress': {
	...
  },
  'Customer': {
	...
  },
  'OrderItems': [
  	...
  ]
}

Definition

An Order Item is a lightweight version of a Product and a Variant which allows you to send over the minimal amount of information possible.

An Order Product must have a unique SKU or identifying ID to be imported into TrendSeam, if TrendSeam does not recognise the identifier then it will create a new Product and Variant automatically.

Order Items do not have their own endpoint as they are a sub-type of a OrderItems, and therefore should be sent to the API within the Array inside a Order Object.

Data Format

Each Order Item should be represented as an Object in the Order's Order Items array, and should be defined as such:

Property	Value
Sku	Product SKU or unique ID (must be different to child Variant SKU) [required]
ProductName	Human readable title of product
VariantSku	Variant SKU or unique ID (must be different to parent Product SKU)
VariantName	Human readable title of product variant
Barcode	The item's Barcode (string)
VariantCreatedOn	Date item was first created. If this is not supplied, TrendSeam will use the first date/time the Sku/VariantSku is used. Format: YYYY-MM-DD HH:MM:SS
Quantity	The number of items purchased
CostEach	The cost to the retailer to purchase the item (used to calculate sales margins)
ItemPrice	The amount paid by the customer for the item
ItemTax	The amount of tax paid by the customer for the item
LineTotal	The ItemPrice multiplied by the Quantity (this should include any taxes)

Example JSON Order Item Array (inside an Order Object)

[
  {
    'Name' : 'Double-Breasted Winter Peacoat',
    'Sku' : 'AW13DBPGRY001',
    'VariantSku': 'AW13DBPGRY001-RED',
    'VariantName': 'Red',
    'Barcode': '7501031311309',
    'VariantCreatedOn' : '2013-02-03 14:12:02',
    'Quantity': '10',
    'CostEach': '5.00',
    'ItemPrice': '10.00',
    'ItemTax': '2.00',
    'LineTotal': '120.00',
  },
  { ... }
]

Definition

A product is a single line of stock such as a scarf, or a coat.

It may or may not have Variants (e.g. red, blue or small, medium, large). A product must have a unique SKU or identifying code. Variants must have their own unique identifying codes.

Method Endpoint

To upload products you should POST an Array of JSON-formatted data to this URL:

Data Format

Each Product should be represented as an Object in the array, and should be defined as such:

Property	Value
Name	Human readable title of product [required]
Sku	Product SKU or unique ID [required]
DateCreated	Date product was first created Format: YYYY-MM-DD HH:MM:SS
Variants	Array of Variants

Example JSON Products Array

[
  {
    'Name' : 'Double-Breasted Winter Peacoat',
    'Sku' : 'AW13DBPGRY001',
    'DateCreated' : '2013-02-03 14:12:02',
    'Variants' :
      [ ... ]
  },
  { ... }
]

Definition

A Variant is a sub-type of Product. A variant must be the child of a Product.

A Variant must have a unique SKU or identifying ID to be imported into TrendSeam..

Variants do not have their own endpoint as they are a sub-type of a Product, and therefore should be sent to the API within the Array inside a Product Object.

Data Format

Each Variant should be represented as an Object in the Product's Variants array, and should be defined as such:

Property	Value
VariantSku	Variant SKU or unique ID (must be different to parent Product SKU)
Name	Human readable title of product variant
Description	A longer description of the variant
Barcode	The item's Barcode (string)
DateCreated	Date item was first created. If this is not supplied, TrendSeam will use the first date/time the VariantSku is used. Format: YYYY-MM-DD HH:MM:SS
UnitCost	The cost to the retailer to purchase the item (used to calculate sales margins)
UnitPrice	The amount the customer would pay for the item
UnitTax	The amount of tax customer would pay for the item
Properties	An array of Key/Value pairs which can contain any extra product attributes you would like to store e.g. colour or material

Example JSON Variants Array (inside a Product Object)

[
  {
        'VariantSku': 'AW13DBPGRY001-RED'
        'Name': 'Red'
        'Description': 'Lovely red version of our Double-Breasted Winter Peacoat'
        'Size': 'Large'
        'Barcode': '7501031311309'
        'UnitCost': '5.00'
        'UnitPrice': '10.00'
        'UnitTax': '2.00'
        'DateCreated': '2013-02-03 14:12:02'
        'Properties': [
        	['Colour','Red'],
        	['Length','180cm'],
        	['Material','Cotton'],
        	...
    	]
  },
  { ... }
]

Definition

A customer must have a unique reference or identifying code. Each customer can have multiple Orders.

Method Endpoint

To upload customers you should POST an Array of JSON-formatted data to this URL:

Data Format

Each Customer should be defined as such:

Property	Value
RetailerReference	Retailer's unique identifying code for this customer. If you don't have a specific ID, you might use the customer's email address here, as it just needs to be a unique value to that customer. [required]
Title	Titular prefix e.g. Mrs, Dr or Miss
FirstName	Customer first name
MiddleName	Customer middle names if any
LastName	Customer last/family name
Address	Customer's Address object
Email	Customer email address
MobilePhone	Customer mobile phone
HomePhone	Customer home phone
WorkPhone	Customer work phone
OtherPhone	Customer other phone
DateCreated	Date customer first created Format: YYYY-MM-DD HH:MM:SS
DateOfBirth	Date of birth Format: YYYY-MM-DD
Gender	The gender of the customer can be one of: M, Male, F or Female. If not supplied but the title is, the gender will be identified from the customer's title (if possible)

Example JSON Customer Object

{
  'RetailerReference': '0012345',
  'Title': 'Mr',
  'FirstName': 'John',
  'MiddleName': 'Mark',
  'LastName': 'Doe',
  'Address': {
	'Line1' : 'Brockhampton Business Park',
	'City' : 'Near Hereford',
	'County' : 'Herefordshire',
  	...
  },
  'MobilePhone': '07771 123 123',
  'HomePhone': '0123 123 124',
  'WorkPhone': '0123 123 123',
  'DateCreated': '2013-01-02 14:12:00',
  'DateOfBirth': '1979-05-06',
  'Gender': 'M'
}

Definition

An Address is a structure attached to either an Order or a Customer as a Billing Address or Shipping Address.

Addresses do not have their own endpoint, and should be sent to the API as an Object inside a Order or Customer Object.

Data Format

Each Address should be represented as such:

Property	Value
Line1	First line of the address
Line2	Second line of the address
Line3	Third line of the address
City	Name of the city
County	Name of the county or state
Postcode	Postal code
CountryCode	Two-letter ISO 3166-1 code for the country
Phone	Phone number for this address
CompanyName	Company name if applicable

Example Request

{			
  'Line1' : 'Great Barn',
  'Line2 : 'Brockhampton Business Park',
  'Line3 : 'Brockhampton',
  'City : 'Near Hereford',
  'County : 'Herefordshire',
  'Postcode : 'HR1 4PP',
  'CountryCode : 'gb',
  'Phone : '01234 123 123',
  'CompanyName : 'TrendSeam'
}