Python bindings for the Tictail API (API reference).
The easiest way to install tictail-python is via pip:
$ pip install tictailAlternatively, you can download the source and then run:
$ python setup.py installYou might get the following error on Mac OS X:
clang: error: unknown argument: '-mno-fused-madd' [-Wunused-command-line-argument-hard-error-in-future]
This is caused by the latest (5.1) version of Xcode which ships with a compiler that treats unknown passed parameters as errors. The workaround is to set the ARCHFLAGS environment variable to treat such errors as warnings:
$ ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future pip install tictailtictail-python supports Python 2.6 and 2.7. Python 3.2+ support is coming soon.
The following packages will be installed together with tictail-python:
requests==2.2.1pyasn1==0.1.6pyOpenSSL==0.13ndg-httpsclient==0.3.2
For bugs and feature requests, please open an issue. If you'd like to contribute
to the development of tictail-python – a fact of grandiose awesomeness – then clone the repo, install the development dependencies and hack away. Make sure you include tests, update the changelog and add your name to the contributors list.
The library uses pytest and coverage for unit and integration tests. Run make test to
run all the tests. Alternatively, you can use the py.test binary to run specific tests.
The Tictail platform uses OAuth 2.0 for authentication so you need to create your application and obtain an access token for a store. The details of how to do that are not in the scope of this document, but the authentication section of the documentation has a nice set of instructions and best practices.
Once you have an access token you can instantiate the Tictail client and get the store associated with the token:
from tictail import Tictail
client = Tictail('<access_token>')
store = client.me()The Tictail client comes preconfigured with sane defaults. If you wish to
override the default configuration, you can supply the constructor with a configuration
dictionary:
from tictail import Tictail
config = {
'timeout': 40
}
client = Tictail('<access_token>', config=config)See client.py for details on what can be overriden.
Reference: Store
The Store resource is the only top-level API object and exposes properties for
all its subresources which are documented further below.
Retrieving a store
from tictail import Tictail
client = Tictail('<access_token>')
store = client.me()An example (partial) response:
>>> print store
Store({
'contact_email': u'thestartupstore@example.com',
'country': u'SE',
'currency': u'SEK',
'dashboard_url': u'https://tictail.com/dashboard/store/thestartupstore',
'description': u'Support your local Startup! ...',
'id': u't',
'language': u'en',
'logotype': [...],
'name': u'The Startup Store',
'sandbox': False,
'storekeeper_email': u'johndoe@example.com',
'url': u'http://thestartupstore.tictail.com'
})Reference: Card
Cards are how you get your content into the feed of the store. The Card resource
only allows for creating cards at this point.
Creating a new card
from tictail import Tictail
client = Tictail('<access_token>')
store = client.me()
card = store.cards.create({
'title': 'Check out this amazing site',
'action': 'http://example.com',
'card_type': 'media',
'content': {
'header': 'You will not regret this'
}
})An example response:
>>> print card
Card({
'action': u'http://example.com',
'card_type': u'media',
'content': {
u'header': u'You will not regret this'
},
'created_at': u'2014-04-23T20:25:47.745085',
'id': u'fREx',
'modified_at': u'2014-04-23T20:25:47.752799',
'title': u'Check out this amazing site'
})Reference: Product
Using the Product resource you can list all the visible products of a store or get a specific product by id.
Listing products accepts four optional query parameters:
limitfor page sizebeforeandafterfor paginating on products created before or after a product with a given idcategoriesfor filtering products on certain categories
List 50 products created after the product with id '7bxv'
from tictail import Tictail
client = Tictail('<access_token>')
store = client.me()
products = store.products.all(after='7bxv', limit=50)List all shirts (id:'aVr') and jeans (id: 'bEt2')
from tictail import Tictail
client = Tictail('<access_token>')
store = client.me()
products = store.products.all(categories=['aVr', 'bEt2'])Retrieve a specific product
from tictail import Tictail
client = Tictail('<access_token>')
store = client.me()
product = store.products.get('7bxv')An example response:
>>> print product
Product({
'created_at': u'2014-01-29T13:41:43',
'currency': u'PLN',
'description': u'',
'id': u'7bxv',
'images': [],
'modified_at': u'2014-01-29T13:41:43',
'price': 1200,
'price_includes_tax': True,
'quantity': None,
'slug': u'super-duper-tshirt',
'status': u'published',
'store_id': u'scV',
'title': u'super duper tshirt',
'unlimited': True,
'variations': []
})Reference: Customer
The Customer resource returns all the customers of a store, i.e people that bought
something at least once from that store. Listing customers accepts three optional
query parameters:
limitfor page sizebeforeandafterfor paginating on customers created before or after a customers with a given id
Retrieve a specific customer
from tictail import Tictail
client = Tictail('<access_token>')
store = client.me()
customer = store.customers.get('7')List all customers
from tictail import Tictail
client = Tictail('<access_token>')
store = client.me()
customers = store.customers.all()An example response:
>>> print customer
Customer({
'country': u'SE',
'created_at': u'2012-12-10T19:31:07',
'email': u'johndoe@example.com',
'id': u'bz21',
'language': u'en',
'modified_at': None,
'name': u'John Doe'
})Reference: Follower
The Follower resource returns all the followers of a store. Listing followers accepts three optional
query parameters:
limitfor page sizebeforeandafterfor paginating on followers created before or after a follower with a given id
Create a follower
from tictail import Tictail
client = Tictail('<access_token>')
store = client.me()
follower = store.followers.create({'email': 'newfollower@example.com'})Delete a follower
from tictail import Tictail
client = Tictail('<access_token>')
store = client.me()
# You can either delete a follower from the `Collection`...
deleted = store.followers.delete(7)
assert deleted
# ...or from the `Resource` itself.
follower = store.followers.all()[0]
deleted = follower.delete()
assert deletedList all followers
from tictail import Tictail
client = Tictail('<access_token>')
store = client.me()
followers = store.followers.all()List all followers created before the follower with id '7aN'
from tictail import Tictail
client = Tictail('<access_token>')
store = client.me()
followers = store.followers.all(before='7aN')An example response:
>>> print follower
Follower({
'created_at': u'2013-12-10T19:31:07',
'modified_at': None,
'email': u'johndoe@example.com',
'id': u'NZUr'
})Reference: Order
The Order resource returns all the orders of a store. If you wish to get the customers
of the store then use the Customer resource instead. Listing orders accepts
five optional query parameters:
limitfor page sizebeforeandafterfor for paginating on orders created before or after a orders with a given idmodified_beforeandmodified_afterfor paginating on orders modified before or after a given date (the date can be either a string inISO 8601format or adatetimeobject)
List all orders after a specific id
from tictail import Tictail
client = Tictail('<access_token>')
store = client.me()
orders = store.orders.all(after='aFQX')List all orders modified after a date
from datetime import datetime
from tictail import Tictail
client = Tictail('<access_token>')
store = client.me()
# Using a datetime object...
now = datetime.now()
orders = store.orders.all(modified_after=now)
# ...or a string.
orders = store.orders.all(modified_after=now.isoformat())Retrieve a specific order
from tictail import Tictail
client = Tictail('<access_token>')
store = client.me()
order = store.orders.get('aFQX')An example (partial) response:
>>> print order
Order({
'customer': {
'name': u'John Doe',
...
},
'transaction': {
'status': u'paid',
...
},
'prices_include_vat': True,
'discounts': [],
'items': [{
'currency': u'SEK',
'price': 0,
...
},
...
],
'fullfilment': {
'status': u'unhandled',
...
},
'price': 0,
'id': u'aFQX',
'vat': {
'price': 0,
'rate': u'0.250000'
}
})Reference: Theme
The Theme resource is a singleton resource that returns the currently active
theme of the store.
Get the theme
from tictail import Tictail
client = Tictail('<access_token>')
store = client.me()
theme = store.theme.get()An example (partial) response:
>>> print theme
Theme({
'id': u'Ag',
'markup': u'<!DOCTYPE html>\n<html lang="en">\n<head>\n...'
})Reference: Category
The Category resource returns the categories which make up the store's navigation.
They are implemented as a classical parent-child hierarchy, limited to one level of depth.
List all categories
from tictail import Tictail
client = Tictail('<access_token>')
store = client.me()
categories = store.categories.all()An example (partial) response:
>>> print categories
[
Category({
'created_at': u'2012-05-01T00:47:16',
'id': u'dn',
'modified_at': u'2012-02-13T16:58:40',
'parent_id': None,
'position': 0,
'title': u'Stickers'
}),
Category({
'created_at': u'2012-10-29T12:02:09',
'id': u'dA',
'modified_at': None,
'parent_id': u'dn',
'position': 1,
'title': u'DevAwsmbx'
})
...
]