Introduction
Welcome to the CycleSoftware API documentation
Documentation overview
- CycleSoftware API docs
- Warehouse API docs
- Supplier integration API docs
- Stock platform API docs
- TWSC API docs
API endpoints
Use the API endpoint hosts according to the country of your account;
| Country code | API endpoint host |
|---|---|
NL |
api.cyclesoftware.nl |
BE |
api.cyclesoftware.be |
FR |
api.cyclesoftware.fr |
other |
api.cyclesoftware.nl |
Requirements
To use the APIs you'll need API credentials. The API credentials are provided by CS or available in your account.
- You should access the API over HTTPS
- Where possible use Accept-encoding: gzip. For data api's this might be required.
Request/Response Format
The APIs consist of SOAP/WSDL webservices and JSON endpoints.
The default response format is JSON. Requests with a message-body use plain JSON to set or update resource attributes.
Successful requests will return a 200 OK HTTP status.
Errors
Occasionally you might encounter errors when accessing the REST API. There are four possible types:
| Error Code | Error Type |
|---|---|
400 Bad Request |
Invalid request, e.g. using an unsupported HTTP method, or GET variable |
401 Unauthorized |
Authentication or permission error, e.g. incorrect credentials |
403 Forbidden |
Authentication or permission error |
404 Not Found |
Requests to resources that don't exist or are missing |
429 Too Many Requests |
API limit reached, see api limiting |
500 Internal Server Error |
Server error |
JSON error response
{
"error": true,
"error_message": "Unauthorized"
}
XML error response
<?xml version="1.0"?>
<result>
<error>1</error>
<error_message>Unauthorized</error_message>
</result>
SOAP error response
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>400</faultcode>
<faultstring>The problem description</faultstring>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Errors return both an appropriate HTTP status code and response object which contains a error, and error_message
API Parameters
Almost all endpoints accept optional parameters which can be passed as an HTTP query string parameter,
e.g. GET /v1/endpoint?status=completed. All parameters are documented along each endpoint.
API Pagination
For certain endpoints pagination is implemented. The mechanism differs per endpoint. But the default pagination mechanism is as follows:
JSON response
{
"error": false,
"error_message": null,
"data": [],
"pagination": {
"next_offset": 1000
}
}
GET /v1/endpoint?offset=1000
In the response the next_offset is suggested. You can pass the next offset in the offset GET parameter.
API Types
Some general information about responses:
- Amounts could be specified in cents (which will be clear by the fieldname) or with decimal-strings
| Scope | Description | Example |
|---|---|---|
string |
An UTF-8 string of variadic length | Hello world! |
boolean |
Boolean true or false |
true |
integer |
64-bit signed integer | 1212 |
decimal |
Decimal number with 2 decimals e.g. 0.22 |
0.22 |
float |
A floating-point number with . used as the separator |
123.22 |
date |
Date in yyyy-mm-dd format |
2023-01-23 |
datetime |
Datetime in yyyy-mm-dd hh:mm:ss format |
2023-01-23 12:34:33 |
timestamp |
UNIX timestamp (seconds since Unix Epoch) | 1678348370 |
uuid |
UUID string | 20c5d026-68b3-11ec-90d6-0242ac120003 |
array |
List of sub types | [10,22] |
object |
An object | {"field": 1} |
API Limits
Since may 2022 api-limits are introduced. For endpoints that implement limits the following HTTP response headers are available.
If the limit is reached, the server will respond with an HTTP 429 - Too Many Requests error.
The following HTTP headers are present in an limited endpoint response
| HTTP Response header | Description |
|---|---|
X-RateLimit-Minutely-Limit |
Contains the number of allowed requests per minute |
X-RateLimit-Minutely-Remaining |
Contains the number of remaining requests available within moving minutely interval |
X-RateLimit-Daily-Limit |
Contains the number of daily allowed requests |
X-RateLimit-Daily-Remaining |
Contains the number of daily remaining requests |
X-RateLimit-Daily-Reset |
Contains the UNIX timestamp when the daily limit is reset |
API Scopes
| Scope | Description |
|---|---|
common |
Access common data such as employees, enums, suppliers |
e-commerce |
Access e-commerce related endpoints (stock, order-creation, articledata) |
resources |
Access object resources such as customers, workshop-orders, repair-objects etc. |
stock-export |
Bulk export stock data |
sales-export |
Bulk export sales data |
rental |
Rental related information |
warehouse |
Warehouse related data |
platform |
Access authorized dealer-data for sales-platforms |
Authentication
CycleSoftware uses different authentication mechanisms.
HTTP Basic Authentication
The credentials consist of a username, password and api-key. The username and password should be provided using the Basic HTTP authentication http header. The api-key is usage is documented per service.
SOAP/WSDL Authentication
The credentials consist of a username, password and api-key. The username and password should be provided within the Authentication element as documented per request. For dealer_id the actual store id within the account or api-key can be provided.
Common
Access common data
Authentication mechanism
- Basic HTTP Authentication
- Scope(s):
common
Enums
Get a set of enums with identifiers and descriptions used in various APIs
GET
/api/v1/common/enum.json
Types
| Subject | Description |
|---|---|
sales_order_types |
Sales order type descriptions |
sales_order_status |
Sales order status descriptions |
sales_order_item_status |
Sales order item status descriptions |
cancellation_types |
Cancellation reasons |
pos_groups |
POS / Sales group descriptions |
payment_methods |
Payment method descriptions |
delivery_methods |
Delivery method descriptions |
vat_codes |
VAT codes |
workshop_order_status |
Workshop order status descriptions |
workshop_order_types |
Workshop order type descriptions |
workshop_rates |
Workshop rates descriptions |
customer_types |
Customer type descriptions |
transaction_item_types |
Transaction item type descriptions (item_type / row_type) |
service_item_status |
Status descriptions for object service items |
entity_types |
Entity types and descriptions, used as reference to an object in API requests and responses |
voucher_types |
Voucher types and descriptions |
consignment_status |
Object consignment type and descriptions |
HTTP Request
GET /api/v1/common/enum.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
HTTP Response (limited)
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 571
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
json
{
"error": false,
"error_message": null,
"data": {
"sales_order_types": [
{
"id": 0,
"description": "Bestelling",
"description_en": "Order"
},
{
"id": 1,
"description": "E-commerce",
"description_en": "E-commerce"
}
],
"sales_order_status": [
{
"id": 2,
"description": "In behandeling",
"description_en": "Pending"
},
{
"id": 8,
"description": "Nog niet besteld",
"description_en": "Not ordered"
}
]
}
}
Employees
Get a list of employees associated with the account
HTTP request examples
GET
/api/v1/common/employees.json
Properties
| Property | Type | Description |
|---|---|---|
| error | boolean |
e.g. false |
| error_message | ?string |
e.g. Unauthorized |
| data | object[] |
array of objects |
| data[].employee_id | integer |
e.g. 4475 |
| data[].employee_name | string |
e.g. John |
| data[].verification_hash | string |
e.g. 8fa5a0b532ca29bdc06b97586993e04d8432ac37d9ed6632b63ccc967f28dbcb sha256 hash mac with api-key as secret |
| data[].roles | string[] |
array of strings |
| data[].roles[] | string |
e.g. employee |
| data[].is_active | boolean |
e.g. false |
| data[].is_default | boolean |
e.g. false |
| data[].is_administrator | boolean |
e.g. false |
| data[].avatar | ?string |
URL to avatar or null |
| data[].authorization[] | string[] |
Array of authorizations e.g. ["MAY_ACCEPT_SALES_LEADS"] |
| data[].authorizations_warehouse[] | ?string[] |
Array of authorizations for warehouse if warehouse account e.g. ["AUTH_ACCOUNTING"] |
HTTP Request
GET /api/v1/common/employees.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
Content-type: application/json; charset=utf-8
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 1220
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"error": false,
"error_message": null,
"data": [
{
"employee_id": 44269,
"employee_name": "John Doe",
"verification_hash": "345ef8a695fded5cff8c2bfb83fa1bffc39f7bc9d13c589facac9ed2b41ebefe",
"roles": [
"employee"
],
"is_active": true,
"is_default": true,
"is_administrator": false,
"avatar": "https://s01.cyclesoftware.nl/app/cs/img/img_1_large_medewerker_44269.jpg",
"authorizations": [
"MAY_PERFORM_CYCLE_COUNT",
"MAY_MODIFY_ARTICLE_PRICES",
"MAY_REPLACE_ARTICLE",
"MAY_MODIFY_ARTICLES",
"MAY_IMPORT_SUPPLIER_ORDER",
"MAY_SEND_SUPPLIER_ORDERS",
"MAY_MANAGE_SUPPLIER_ORDERS",
"MAY_DO_ANALYTICS"
]
},
{
"employee_id": 1133,
"employee_name": "Jane Doe",
"verification_hash": "69baca4df93b1f213aff9d8582178ec6875da7d8c9bd030340d2de623aa19a69",
"roles": [
"mechanic"
],
"is_active": true,
"is_default": false,
"is_administrator": false,
"avatar": null,
"authorizations": [
"MAY_PERFORM_CYCLE_COUNT",
"MAY_MODIFY_ARTICLE_PRICES",
"MAY_REPLACE_ARTICLE"
]
}
]
}
<?php
// example on how to check personal code of employee
$api_key = 'your-api-key';
$code = '1234';
$hash = \hash_hmac('sha256', $code, $api_key);
if(\hash_equals('data[].verification_hash', $hash)){
// code is correct
}
Supplier list
Get a list of suppliers
HTTP request examples
GET
/api/v1/common/suppliers.json
Properties
| Property | Type | Description |
|---|---|---|
error |
boolean |
e.g. false |
error_message |
?string |
Error message if occured |
data |
object[] |
Array of suppliers |
data[].type |
string |
supplier, bike-brand or moped-brand |
data[].supplier_id |
integer |
Unique supplier ID 580 |
data[].supplier_name |
string |
Name of supplier e.g. Accell NL |
data[].parent_supplier_id |
?integer |
Brands may be linked to a parent supplier-id |
HTTP Request
GET /api/v1/common/suppliers.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 331
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"error": false,
"error_message": null,
"data": [
{
"type": "supplier",
"supplier_id": 122,
"supplier_name": "Supplier A",
"parent_supplier_id": null
},
{
"type": "bike-brand",
"supplier_id": 580,
"supplier_name": "Brand one",
"parent_supplier_id": 122
}
]
}
Article data
The articledata APIs are designed for pulling article-information for e-commerce environments.
Authentication
- Basic HTTP Authentication
- Scope(s):
e-commerce
Articledata - V3
Get article data available for e-commerce environments or for a specific barcode.
GET
/app/api/v3/articledata/
GET
/app/api/v3/articledata/:next_resultset
GET
/app/api/v3/articleinfo/:barcode
Pagination
In every response you'll find a path to the next resultset. In the example the next resultset
is /app/api/v3/articledata/750-750-0/. If next_resultset is null no additional data is available.
HTTP Request
GET /app/api/v3/articledata/ HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
HTTP Response
{
"error": false,
"error_message": "",
"results": 750,
"next_resultset": "/app/api/v3/articledata/750-750-0/",
"property_definition": "/app/api/v3/articledata/definition/",
"supplier_data_columns": [
"reference",
"supplier_name",
"supplier_id",
"article_id",
"barcode",
"brand",
"model",
"color",
"pos_description",
"size",
"purchase_price",
"vat_code",
"rrp",
"model_year",
"product_pos_group_id",
"main_group",
"sub_group",
"sub_sub_group",
"supplier_sub_group",
"supplier_subsub_group",
"order_code",
"order_quantity",
"min_order_quantity",
"status_code",
"package_contents_quantity",
"customer_group",
"keyword",
{
"properties": {
"33": "location",
"34": "primary_color",
"35": "secundary_basic_color",
"36": "weight_bruto",
"37": "weight_netto",
"43": "long_description",
"46": "wheelsize",
"47": "frametype",
"105": "keyword",
"106": "customer_group",
"108": "model_id",
"131": "url_article_information",
"133": "highres_image_url",
"137": "image_url",
"139": "video_url",
"140": "basic_color",
"141": "size",
"142": "pos_description",
"143": "description",
"203": "width_package",
"205": "height_package",
"206": "length_package",
"232": "user_manual",
"233": "technical_guide"
}
}
],
"data": [
{
"modified_at": "26-07-2020",
"barcode": "0008022142197",
"parent_barcode": null,
"is_bicycle": false,
"bicycle_id": null,
"has_stock": false,
"is_discontinued": false,
"salesprice": "40.75",
"rrp": "39.95",
"lease_options": [],
"removal_fee": "0.00",
"purchase_price": "0.00",
"pos_description": "STANDAARD URSUS 26 TWEEPOOT ZWART",
"brand": "Ursus",
"promo_salesprice": "0.00",
"promo_startdate": null,
"promo_enddate": null,
"sales_text": "",
"custom_variable_1": null,
"custom_variable_2": null,
"custom_variable_3": null,
"custom_variable_4": null,
"custom_variable_5": null,
"custom_variable_6": "",
"images": [
{
"date_modified": "08-05-2012 08:02:58",
"url_thumb": "http://s02.cyclesoftware.nl/app/img/Y/artPic_public_T_18563.jpg",
"url_large": "http://s02.cyclesoftware.nl/app/img/Y/artPic_public_L_18563.jpg"
}
],
"product_group_main": "O&A",
"product_group_sub": "Onderdelen/Reparatie",
"product_group_sub_sub": "Standaarden",
"product_group_id": "2_N_1",
"product_pos_group_id": "21",
"article_location": null,
"supplier_data": [
[
"7177049",
"ACCELL NL",
"5229",
"680862",
"0008022142197",
"URSUS",
"JUMBO",
"ZWART",
"STANDAARD URSUS 26 JUMBO TWEEPOOT ZWART",
"",
"0.00",
"H",
"39.95",
"0",
"21",
"O&A",
"Onderdelen/Reparatie",
"Standaarden",
null,
null,
"",
"1",
"1",
"VERVALLEN",
"1",
"",
"STANDAARD",
{
"34": "ZWART",
"43": "STANDAARD URSUS 26 JUMBO TWEEPOOT ZWART",
"105": "STANDAARD",
"137": [
"http://www.accentry.com/upload/Juncker/680862.JPG"
],
"140": "ZWART",
"142": "STANDAARD URSUS 26 JUMBO",
"143": "STANDAARD URSUS 26 JUMBO TWEEPOOT ZWART"
}
]
]
},
{
"modified_at": "10-02-2022",
"barcode": "0091021578005",
"parent_barcode": null,
"is_bicycle": false,
"bicycle_id": null,
"has_stock": false,
"is_discontinued": false,
"salesprice": "139.95",
"rrp": "139.95",
"lease_options": [],
"removal_fee": "0.00",
"purchase_price": "0.00",
"pos_description": "Thule yepp kinderzitje nexxt maxi bagagedrager vib",
"brand": "THULE",
"promo_salesprice": "0.00",
"promo_startdate": null,
"promo_enddate": null,
"sales_text": "",
"custom_variable_1": null,
"custom_variable_2": null,
"custom_variable_3": null,
"custom_variable_4": null,
"custom_variable_5": null,
"custom_variable_6": "",
"images": [
{
"date_modified": "12-02-2019 11:03:31",
"url_thumb": "http://s02.cyclesoftware.nl/app/img/Y/artPic_public_T_1741674.jpg",
"url_large": "http://s02.cyclesoftware.nl/app/img/Y/artPic_public_L_1741674.jpg"
}
],
"product_group_main": "O&A",
"product_group_sub": "Kinderzitjes",
"product_group_sub_sub": "Kinderzitje achter",
"product_group_id": "2_D_2",
"product_pos_group_id": "21",
"article_location": null,
"supplier_data": [
[
"7967511",
"THULE",
"5285",
"12080205",
"0091021578005",
"THULE",
"Yepp Nexxt Maxi Universal Mount Vibrant Orange",
"",
"Yepp Nexxt Maxi Universal Mount Vibrant Orange",
"",
"0.00",
"H",
"139.95",
"0",
"21",
"O&A",
"Kinderzitjes",
"Kinderzitje achter",
null,
null,
"",
"1",
"1",
"COURANT",
"1",
"",
"ZITJE",
{
"36": "3.73",
"37": "2.70",
"43": "\"Lichtgewicht en veilig fietszitje voor montage op de bagagedrager met een eigentijds ontwerp dat hoogwaardig comfort voor uw kind biedt.\"",
"105": "ZITJE",
"131": "https://www.thule.com/nl-nl/nl/child-bike-seats/rear-mounted-child-bike-seats/thule-yepp-nexxt-maxi-_-12080205",
"133": [
"https://cdn1.static-tgdp.com/ui/productimages/Approved/std.lang.all/44/49/604449_sized_900x600.jpg"
],
"137": [
"https://cdn1.static-tgdp.com/ui/productimages/Approved/std.lang.all/44/49/604449_sized_900x600.jpg"
],
"139": [
"https://www.youtube.com/embed/6KGMZFZW58E"
],
"142": "Yepp Nexxt Maxi Universal",
"143": "Yepp Nexxt Maxi Universal Mount Vibrant Orange",
"203": "0.43",
"205": "0.89",
"206": "0.28",
"232": [
{
"type": "GEBRUIKERS HANDLEIDING",
"type_omschrijving": "Gebruikers handleiding",
"url": "https://www.thule.com/assetloader.axd?pimid=12080205&id=574173&brand=Thule&market=NL&att=1"
}
],
"233": [
{
"type": "SERVICE DOCUMENTATIE",
"type_omschrijving": "Service documentatie",
"url": "https://www.thule.com/assetloader.axd?pimid=12080205&id=580543&brand=Thule&market=NL&att=1"
}
]
}
],
[
"7996325",
"AGU",
"1",
"130383",
"0091021578005",
"THULE",
"",
"Oranje",
"Thule yepp kinderzitje nexxt maxi bagagedrager vib",
"",
"0.00",
"H",
"139.95",
"0",
"21",
"O&A",
"Kinderzitjes",
"Kinderzitje achter",
null,
null,
"130383",
"0",
"0",
"VERVALLEN",
"0",
"",
"ZITJE",
{
"33": "A",
"34": "ORANJE",
"36": "3.50",
"37": "3.00",
"43": "Lichtgewicht en veilig fietszitje, voor montage op de bagagedrager, met een eigentijds ontwerp dat hoogwaardig comfort voor uw kind biedt.<b>Specificaties</b>\u2022 Merk: Thule\u2022 Upgrade: nvt\u2022 Introductiejaar: 2017\u2022 Alternatief: Thule Yepp Nexxt\u2022 Kleur: Oranje\u2022 Locatie Fiets: Achter\u2022 Montage: Bagagedrager\u2022 Diameter Bevestiging: nvt\u2022 Inhoud Pakket: Compleet FietszitjeVoor alle specificaties, kijk onderaan de pagina.<b>USP</b>- Maximaal comfort voor uw kind en een veilige en goede pasvorm dankzij de verstelbare, vijfpuntsgordel met zachte schouderpads - Biedt uw kind een soepele rit in het zachte en schokabsorberende zitje - Lichtgewicht maar robuust zitje waarin een harde buitenkant wordt gecombineerd met een zachte zitting voor optimaal comfort voor het kind - Zet uw kind zeer snel, gemakkelijk en handig vast met de magnetische kindveilige gesp - Gemak en flexibiliteit zijn verzekerd naarmate ...",
"105": "ZITJE",
"137": [
"http://www.abcb2b.eu/afbeelding.aspx?a=130383&t=jpgextra"
],
"140": "Oranje",
"142": "ORANJE Zitje",
"143": "Thule yepp kinderzitje nexxt maxi bagagedrager vib"
}
]
]
},
{
"modified_at": "08-03-2021",
"barcode": "0193751005308",
"parent_barcode": null,
"is_bicycle": false,
"bicycle_id": null,
"has_stock": false,
"is_discontinued": false,
"salesprice": "39.90",
"rrp": "39.90",
"lease_options": [],
"removal_fee": "0.00",
"purchase_price": "0.00",
"pos_description": null,
"brand": "TANNUS",
"promo_salesprice": "0.00",
"promo_startdate": null,
"promo_enddate": null,
"sales_text": "",
"custom_variable_1": null,
"custom_variable_2": null,
"custom_variable_3": null,
"custom_variable_4": null,
"custom_variable_5": null,
"custom_variable_6": "",
"images": [],
"product_group_main": "O&A",
"product_group_sub": "Banden",
"product_group_sub_sub": "Banden accessoires en onderdelen",
"product_group_id": "2_A_3",
"product_pos_group_id": "21",
"article_location": null,
"supplier_data": [
[
"9650393",
"GRANSIERBV",
"7069",
"30129528",
"0193751005308",
"TANNUS",
"",
"Rood",
"Armour 3 in 1 fietsband anti-lek systeem 28 x 1.65",
"28\"",
"0.00",
"H",
"39.90",
"0",
"21",
"O&A",
"Banden",
"Banden accessoires en onderdelen",
null,
null,
"30129528",
"1",
"1",
"COURANT",
"1",
"",
"VELGLINT",
{
"34": "ROOD",
"43": "Rij sneller en met meer vertrouwen met het Armour anti-lek systeem van Tannus. Deze extra beschermlaag wordt tussen de binnen- en buitenband geplaatst. Herbruikbaar Eenvoudige montage tussen band en binnenband Hogere grip en lagere rolweerstand Heel licht All-round anti-lekbescherming Universeel voor de bandengrootte 28x 1.65 - 1.85, 42/47-700. De aanbevolen binnenbandgrootte is 28/40-622. Past in de velgmaten 19/25-622.",
"105": "VELGLINT",
"131": "https://www.gransier.nl/nl/tannus-armour-3-in-1-fietsband-anti-lek-systeem-28-x-1-65-1-85-700-x-42-47c",
"133": null,
"140": "Rood",
"141": "28\"",
"142": "Armour 3 in 1 fietsband",
"143": "Armour 3 in 1 fietsband anti-lek systeem 28 x 1.65"
}
]
]
}
]
}
Articledata definitions - V3
Use /app/api/v3/articledata/definition/ and /app/api/groups/ for more information about possible field values.
GET
/app/api/v3/articledata/definition/
GET
/app/api/groups/
Main object
| Element | Description |
|---|---|
error |
boolean |
error_message |
Error message description |
results |
Number of results (max 750) |
next_result_set |
Next result set url e.g. /load/ci_app/api/article_data/750-750-0 |
supplier_data_columns |
Definition of fields used in supplier_data element |
Data object
| Property | Description | Length |
|---|---|---|
barcode |
Article barcode (alpha numeric) | 20 |
parent_barcode |
20 | |
is_bicycle |
Boolean article is bicycle | |
bicycle_id |
Multiple unique bicycle identifiers | 0..* |
salesprice |
Price without promo | decimal string |
has_stock |
Boolean, if true there is stock for this article at supplier | |
is_discontinued |
Boolean, whether the article is marked by dealer as discontinued | |
rrp |
Recommended Retail Price | decimal string |
lease_options |
Array of objects with lease option | |
removal_fee |
The default removal fee for elo bikes | decimal string |
pos_description |
Description used in POS and Invoices | 255 |
brand |
Brand name | 30 |
promo_salesprice |
Promo price | decimal string |
promo_startdate |
yyyy-mm-dd hh:mm:ss | 19 |
promo_enddate |
yyyy-mm-dd hh:mm:ss | 19 |
sales_text |
Product description | 10000 |
custom_variable_1 |
Custom defined variable | 100 |
custom_variable_2 |
Custom defined variable | 100 |
custom_variable_3 |
Custom defined variable | 100 |
custom_variable_4 |
Custom defined variable | 100 |
custom_variable_5 |
Custom defined variable | 100 |
images |
Object with image urls see images object | |
product_group_main |
DST main group description | 40 |
product_group_sub |
DST sub group description | 40 |
product_group_sub_sub |
DST sub sub group description | 80 |
product_group_id |
DST group code | 8 |
product_pos_group_id |
POS sales group see request /load/ci_app/api/groups | 1 = new product 20 = used product |
supplier_data |
Supplier data object, the field columns are defined in the supplier_data_columns column | 0..* |
Lease option object
| Property | Description | Type |
|---|---|---|
type |
b2b or b2c | String |
platform |
Name of the lease platform e.g. “cyclelease” | String |
rrp |
RRP used to calculate the fee | Decimal string |
duration_months |
Contract length | Integer |
fee_monthly_ex_vat |
The estimated base lease fee ex vat | Decimal string |
service |
Services included | Array of strings |
options |
Additional selectable options with description and fee_monthly_ex_vat for each option | Array of object with elements description and fee_monthly_ex_vat |
Images object
| Property | Description | Length |
|---|---|---|
date_modified |
dd-mm-yyyy hh:mm:ss | 19 |
url_thumb |
url to thumb image | 100 |
url_large |
url to large image | 100 |
Supplier_data object
| Property | Description |
|---|---|
reference |
ID of article, or reference to bicycle |
supplier_name |
Supplier name |
supplier_id |
Supplier id (see groups api) |
article_id |
Article code |
barcode |
Barcode (ean, upc or string) |
brand |
Brand name |
model |
Model name |
color |
Color |
pos_description |
Description used in POS |
size |
Size |
purchase_price |
Purchase price (= null) |
vat_code |
Code: H, L, G |
rrp |
Recommended retail price |
model_year |
Year of model |
product_pos_group_id |
Group id of POS group (see groups api) |
main_group |
DST main group |
sub_group |
DST sub group |
sub_sub_group |
DST subsub group |
supplier_sub_group |
Supplier groupname |
supplier_subsub_group |
Supplier sub groupname |
order_code |
Order code, see also article_id |
order_quantity |
Quantity in which it is ordered at supplier |
min_order_quantity |
Minimal order quantity for order to supplier |
status_code |
Status code (current = COURANT) |
package_contents_quantity |
If multiple items in package |
customer_group |
Customer group name (Heren, Dames etc) |
keyword |
Key description word (e.g. FIETS) |
basic_color |
Basic color description |
primary_color |
Basic color description |
secundary_basic_color |
Secundary color description |
weight_bruto |
Weight kg |
weight_netto |
Weight net kg |
description |
Description of product |
wheelsize |
Wheelsize in inch |
frametype |
Frametype (e.g. HEREN, DAMES) |
framesize |
Framesize in cm |
framesize_description |
Framesize description |
material |
Frame material |
brand_gearsystem_rear |
Brand of gear rear |
model_gearsystem_rear |
Model of gear rear |
type_gearsystem_rear |
Type of gear rear |
gears |
Number of gears |
brand_primary_brake_system_rear |
Brand of primary brake rear |
type_primary_brake_system_rear |
Type of primary brake rear |
model_primary_brake_system_rear |
Model of primary brake rear |
brand_secondary_brake_system_rear |
Brand of secondary brake rear |
type_secondary_brake_system_rear |
Type of secondary brake rear |
model_secondary_brake_system_rear |
Model of secondary brake rear |
brand_brake_system_front |
Brand of primary brake front |
model_brake_system_front |
Type of primary brake front |
type_brake_system_front |
Model of primary brake front |
Articledata - V4
This endpoint is currently in beta-phase.
Get article data available for e-commerce environments or for a specific barcode.
GET
/api/v4/articledata/entries.json
GET
/api/v4/articledata/entries.json?token=:token
GET
/api/v4/articledata/entries.json?barcode=:barcode
| GET parameter | Type | Description |
|---|---|---|
:modified_since |
integer |
Only return entries with modification after this value |
:barcode |
string |
Only return entry for specific barcode |
:exclude_ecommerce |
boolean |
If true exclude ecommerce information (defaults to false) |
:exclude_articles |
boolean |
If true exclude articles (defaults to false) |
:exclude_objects |
boolean |
If true exclude objects / bicycles (defaults to false) |
:per_store_id |
boolean |
If true only return for store associated with credentials (defaults to false) |
Important*
- Stock only present for non-objects
- Objects lists the available stock objects
Response properties
| Property | Type | Omittable | Description |
|---|---|---|---|
data |
object[] |
false |
|
data[].modified_at |
datetime |
false |
Last modification of underlying data e.g. 2024-07-24 16:23:45 |
data[].barcode |
string |
false |
The barcode of the article e.g. 5400928076890 (usually an EAN code) |
data[].pricing |
object |
false |
Object with pricing information about the article` |
data[].pricing.currency |
string |
false |
The currency code e.g. EUR |
data[].pricing.rrp_cents |
integer |
false |
Recommended retail price in cents e.g. 269900 |
data[].pricing.pos_sales_price_cents |
integer |
false |
POS sales price in cents e.g. 269900 |
data[].pricing.ecommerce_price_cents |
integer |
true |
E-commerce sales price in cents e.g. 269900 |
data[].pricing.purchase_price_cents |
integer |
true |
Purchase price in cents (excluding VAT) e.g. 99500 |
data[].pricing.pos_group_id |
integer |
false |
POS group ID e.g. 1 (see common enum) |
data[].pricing.vat_code |
?integer |
true |
VAT code if specified e.g. 2, if no specified the default VAT-code of POS group is applied |
data[].pricing.pos_promo_price_cents |
?integer |
true |
POS promo price in cents e.g. 4000 |
data[].pricing.pos_promo_price_from |
?date |
true |
POS promo start date e.g. 2024-07-03 |
data[].pricing.pos_promo_price_until |
?date |
true |
POS promo end date e.g. 2024-10-19 |
data[].pricing.ecommerce_promo_price_cents |
?integer |
true |
E-commerce promo price in cents e.g. 3900 |
data[].pricing.ecommerce_promo_price_from |
?date |
true |
E-commerce promo start date e.g. 2024-07-01 |
data[].pricing.ecommerce_promo_price_until |
?date |
true |
E-commerce promo end date e.g. 2024-10-19 |
data[].objects |
?object[] |
false |
When the article is an object (bicycle, moped) this element is present and contains unique objects |
data[].objects[].object_code |
string |
false |
e.g. F.1-232432 |
data[].objects[].object_id |
integer |
false |
e.g. 232432 |
data[].objects[].store_id |
integer |
false |
e.g. 1 |
data[].objects[].available |
boolean |
false |
e.g. true |
data[].objects[].expected_at |
null |
true |
|
data[].objects[].is_demo |
boolean |
false |
e.g. false |
data[].objects[].is_used |
boolean |
false |
e.g. false |
data[].objects[].currency |
string |
false |
e.g. EUR |
data[].objects[].ecommerce_price_cents |
integer |
false |
e.g. 269900 |
data[].objects[].pos_sales_price_cents |
integer |
false |
e.g. 269900 |
data[].objects[].purchase_price_cents |
integer |
false |
e.g. 0 |
data[].objects[].km_age |
null |
true |
|
data[].suppliers |
object[] |
false |
List of suppliers associated with the article |
data[].suppliers[]._id |
integer |
false |
Internal ID e.g. 11043281 |
data[].suppliers[].supplier_id |
integer |
false |
Supplier ID e.g. 13005 (see common supplier list) |
data[].suppliers[].supplier_name |
string |
false |
Supplier code name e.g. BELGIAN CYCLING FACTORY |
data[].suppliers[].article_id |
string |
false |
Article number e.g. SBIELARID023 |
data[].suppliers[].model_id |
null |
true |
Model ID, if other entries have the same model_id they could be grouped |
data[].suppliers[].parent_barcode |
null |
true |
Parent barcode (if grouped within model_id) |
data[].suppliers[].currency |
string |
false |
Currency code e.g. EUR |
data[].suppliers[].rrp_cents |
integer |
false |
Recommended retail price in cents e.g. 269900 |
data[].suppliers[].purchase_price_cents |
integer |
false |
Purchase price in cents e.g. 0 |
data[].suppliers[].package.package_contents |
integer |
false |
Number of consumer goods within delivery from supplier e.g. 1 |
data[].suppliers[].package.min_order_quantity |
integer |
false |
Minimal order quantity for this supplier e.g. 1 |
data[].suppliers[].package.order_unit |
integer |
false |
Order unit for this supplier e.g. 1 |
data[].properties<:property_name>.type |
string |
false |
The data type of the property e.g. codelist:article_main_group (see Data-types for possible types) |
data[].properties<:property_name>.unit |
?string |
true |
The unit of data e.g. kg or cm if available. |
data[].properties<:property_name>.values |
object[] |
false |
Different values for the property (different values may be present sourced from different suppliers and or objects) |
data[].properties<:property_name>.values[].supplier_ids |
?integer[] |
true |
The list of supplier-ids which have this property in their article definition |
data[].properties<:property_name>.values[].object_ids |
?integer[] |
true |
The list of object-ids which have this property in their definition |
data[].properties<:property_name>.values[].code |
?string |
true |
If the data-type refers to a code list, this is the code value e.g. 1 |
data[].properties<:property_name>.values[].code_international |
?string |
true |
If the data-type refers to a code list, this is the international code value e.g. 1 |
data[].properties<:property_name>.values[].value |
mixed |
false |
The value of the property, the structure depends on data[].properties<:property_name>.type e.g. 2021 |
data[].stock |
?object |
false |
Only present for non object entries, contains stock information within stores |
data[].stock.available |
boolean |
false |
true if there is stock available within stores e.g. false |
data[].stock.stores |
object |
false |
Array with object information per store-id |
data[].stock.stores[].store_id |
integer |
false |
Store ID e.g. 1 |
data[].stock.stores[].stock_level |
integer |
false |
Stock level in this store e.g. 0 |
data[].stock.stores[].locations |
array |
false |
Stock locations associated with this article |
data[].stock.stores[].locations[].store_id |
integer |
false |
e.g. 1 |
data[].stock.stores[].locations[].location_id |
integer |
false |
ID of the location e.g. 3 |
data[].stock.stores[].locations[].location_x |
integer |
false |
Location x-axis e.g. 1 |
data[].stock.stores[].locations[].location_y |
integer |
false |
Location y-axis e.g. 2 |
data[].stock.stores[].locations[].location_capacity |
integer |
false |
Capacity e.g. 33 |
data[].stock.stores[].locations[].location_bulk |
string |
false |
Bulk location name e.g. Magazijn |
pagination.next_url |
?string |
true |
If there is more data this is the URL to the next API request. https://api.cyclesoftware.nl/api/v4/articledata/entries.json?token=abc... |
HTTP Request
GET /api/v4/articledata/entries.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
HTTP Response
{
"data": [
{
"modified_at": "2024-07-24 16:23:45",
"barcode": "5400928076890",
"pricing": {
"currency": "EUR",
"rrp_cents": 269900,
"pos_sales_price_cents": 269900,
"ecommerce_price_cents": 269900,
"purchase_price_cents": 100,
"pos_group_id": 1,
"vat_code": 2
},
"objects": [
{
"object_code": "F.1-232432",
"object_id": 232432,
"store_id": 1,
"available": true,
"expected_at": null,
"is_demo": false,
"is_used": false,
"currency": "EUR",
"ecommerce_price_cents": 269900,
"pos_sales_price_cents": 269900,
"purchase_price_cents": 100,
"km_age": null
}
],
"suppliers": [
{
"_id": 11043281,
"supplier_id": 13005,
"supplier_name": "BELGIAN CYCLING FACTORY",
"article_id": "SBIELARID023",
"model_id": null,
"parent_barcode": null,
"currency": "EUR",
"rrp_cents": 269900,
"purchase_price_cents": 100,
"package": {
"package_contents": 1,
"min_order_quantity": 1,
"order_unit": 1
}
}
],
"properties": {
"article_main_group": {
"type": "codelist:article_main_group",
"values": [
{
"supplier_ids": [
13005
],
"object_ids": [
232432
],
"code": "1",
"code_international": "1",
"value": {
"nl": "Fietsen",
"en": "Bikes",
"fr": "Vélos"
}
}
]
},
"article_group": {
"type": "codelist:article_group",
"values": [
{
"supplier_ids": [
13005
],
"object_ids": [
232432
],
"code": "1A",
"code_international": "1A",
"value": {
"nl": "Stadsfietsen",
"en": "Citybike",
"fr": "Vélos De Ville"
}
}
]
},
"article_sub_group": {
"type": "codelist:article_sub_group",
"values": [
{
"supplier_ids": [
13005
],
"object_ids": [
232432
],
"code": "1A00",
"code_international": "1A00",
"value": {
"nl": "Stadsfiets",
"en": "City bike without gear or with hub gear",
"fr": "Vélo de Ville"
}
}
]
},
"model_year": {
"type": "integer",
"values": [
{
"supplier_ids": [
13005
],
"object_ids": [
232432
],
"value": 2021
}
]
},
"basic_color": {
"type": "codelist:base_color",
"values": [
{
"object_ids": [
232432
],
"code": "ZWART",
"code_international": "BLACK",
"value": {
"nl": "Zwart",
"en": "Black",
"fr": "Noir"
}
},
{
"supplier_ids": [
13005
],
"value": "Black Powder Coating // Alumin"
}
]
},
"description": {
"type": "string",
"values": [
{
"object_ids": [
232432
],
"value": {
"user": "Ridley Elykx A Black Powder Coating // Aluminium B"
}
},
{
"supplier_ids": [
13005
],
"value": {
"nl": "Ridley Elykx A Black Powder Coating // Aluminium Bikes Only // PC8 2021"
}
}
]
},
"frametype": {
"type": "codelist:frame",
"values": [
{
"supplier_ids": [
13005
],
"object_ids": [
232432
],
"code": "UNI",
"code_international": "UNI",
"value": {
"nl": "Uni",
"en": "Unisex",
"fr": "Uni"
}
}
]
},
"framesize_description": {
"type": "localized-strings",
"values": [
{
"supplier_ids": [
13005
],
"object_ids": [
232432
],
"value": {
"user": "L"
}
}
]
},
"gears": {
"type": "integer",
"values": [
{
"object_ids": [
232432
],
"value": 0
}
]
},
"keyword": {
"type": "codelist:keyword",
"values": [
{
"supplier_ids": [
13005
],
"code": "FIETS",
"code_international": "BICYCLE",
"value": {
"nl": "Fiets",
"en": "Bicycle",
"fr": "Vélo"
}
}
]
},
"brand": {
"type": "codelist:brand",
"values": [
{
"supplier_ids": [
13005
],
"value": "Ridley"
}
]
},
"model": {
"type": "localized-strings",
"values": [
{
"supplier_ids": [
13005
],
"value": {
"nl": "Elykx A"
}
}
]
},
"image_url": {
"type": "string[]",
"values": [
{
"supplier_ids": [
13005
],
"value": [
"https://images.cyclingfactory.be/SBIELARID023_image_2048x.jpg"
]
}
]
},
"color_description": {
"type": "localized-strings",
"values": [
{
"supplier_ids": [
13005
],
"value": {
"nl": "ZWART"
}
}
]
},
"pos_description": {
"type": "localized-strings",
"values": [
{
"supplier_ids": [
13005
],
"value": {
"nl": "Ridley Elykx A Black Powder Coating // Aluminium"
}
}
]
},
"gearsystem_rear_model": {
"type": "localized-strings",
"values": [
{
"supplier_ids": [
13005
],
"value": {
"nl": "Shimano XT"
}
}
]
}
}
},
{
"modified_at": "2024-07-24 16:26:35",
"barcode": "0008022142197",
"pricing": {
"currency": "EUR",
"rrp_cents": 3995,
"pos_sales_price_cents": 4075,
"pos_promo_price_cents": 4000,
"pos_promo_price_from": "2024-07-03",
"pos_promo_price_until": "2024-10-19",
"ecommerce_price_cents": 4075,
"ecommerce_promo_price_cents": 3900,
"ecommerce_promo_price_from": "2024-07-01",
"ecommerce_promo_price_until": "2024-10-19",
"purchase_price_cents": 100,
"pos_group_id": 21
},
"stock": {
"available": false,
"stores": [
{
"store_id": 1,
"stock_level": 0,
"locations": [
{
"store_id": 1,
"location_id": 3,
"location_x": 1,
"location_y": 2,
"location_capacity": 33,
"location_bulk": "Magazijn"
}
]
},
{
"store_id": 2,
"stock_level": 0,
"locations": []
},
{
"store_id": 3,
"stock_level": 0,
"locations": []
}
]
},
"suppliers": [
{
"_id": 7177049,
"supplier_id": 5229,
"supplier_name": "ACCELL NL",
"article_id": "680862",
"model_id": null,
"parent_barcode": null,
"currency": "EUR",
"rrp_cents": 3995,
"purchase_price_cents": 100,
"package": {
"package_contents": 1,
"min_order_quantity": 1,
"order_unit": 1
}
}
],
"properties": {
"images": {
"type": "image[]",
"values": [
{
"value": [
{
"date_modified": "2012-05-08 08:02:58",
"url_thumb": "https://cdn.cyclesoftware.nl/app/img/Y/artPic_public_T_18563.jpg",
"url_large": "https://cdn.cyclesoftware.nl/app/img/Y/artPic_public_L_18563.jpg"
}
]
}
]
},
"pos_description": {
"type": "localized-strings",
"values": [
{
"supplier_ids": [
5229
],
"value": {
"user": "STANDAARD URSUS 26 JUMBO",
"nl": "STANDAARD URSUS 26 TWEEPOOT ZWART nl_NL"
}
},
{
"supplier_ids": [
5229
],
"value": {
"nl": "STANDAARD URSUS 26 JUMBO"
}
}
]
},
"brand": {
"type": "codelist:brand",
"values": [
{
"supplier_ids": [
5229
],
"value": "URSUS"
}
]
},
"article_main_group": {
"type": "codelist:article_main_group",
"values": [
{
"supplier_ids": [
5229
],
"code": "2",
"code_international": "2",
"value": {
"nl": "O&A",
"en": "Parts and accessories",
"fr": "Pièces et accessoires"
}
}
]
},
"article_group": {
"type": "codelist:article_group",
"values": [
{
"supplier_ids": [
5229
],
"code": "2N",
"code_international": "2N",
"value": {
"nl": "Onderdelen/Reparatie",
"en": "Parts/Repair",
"fr": "Pièces de rechange"
}
}
]
},
"article_sub_group": {
"type": "codelist:article_sub_group",
"values": [
{
"supplier_ids": [
5229
],
"code": "2N01",
"code_international": "2N01",
"value": {
"nl": "Standaarden",
"en": "Kickstand",
"fr": "Béquilles"
}
}
]
},
"keyword": {
"type": "codelist:keyword",
"values": [
{
"supplier_ids": [
5229
],
"code": "STANDAARD",
"code_international": "KICKSTAND",
"value": {
"nl": "Standaard",
"en": "Kickstand",
"fr": "Standard"
}
}
]
},
"model": {
"type": "localized-strings",
"values": [
{
"supplier_ids": [
5229
],
"value": {
"nl": "JUMBO"
}
}
]
},
"image_url": {
"type": "string[]",
"values": [
{
"supplier_ids": [
5229
],
"value": [
"http://www.accentry.com/upload/Juncker/680862.JPG"
]
}
]
},
"basic_color": {
"type": "codelist:base_color",
"values": [
{
"supplier_ids": [
5229
],
"code": "ZWART",
"code_international": "BLACK",
"value": {
"nl": "Zwart",
"en": "Black",
"fr": "Noir"
}
}
]
},
"color_description": {
"type": "localized-strings",
"values": [
{
"supplier_ids": [
5229
],
"value": {
"nl": "ZWART"
}
}
]
},
"description": {
"type": "string",
"values": [
{
"supplier_ids": [
5229
],
"value": {
"nl": "STANDAARD URSUS 26 JUMBO TWEEPOOT ZWART"
}
}
]
},
"long_description": {
"type": "localized-strings",
"values": [
{
"supplier_ids": [
5229
],
"value": {
"nl": "STANDAARD URSUS 26 JUMBO TWEEPOOT ZWART"
}
}
]
}
}
}
],
"pagination": {
"next_url": "https://s01.cyclesoftware.nl/api/v4/articledata/entries.json?token=ABC"
}
}
Data-types - V4
Every property has it's own value structure. See the properties endpoint for example values.
| Data-type | Description |
|---|---|
codelist:article_group |
https://api.cyclesoftware.nl/api/v4/codelists/article_group.json |
codelist:article_main_group |
https://api.cyclesoftware.nl/api/v4/codelists/article_main_group.json |
codelist:article_sub_group |
https://api.cyclesoftware.nl/api/v4/codelists/article_sub_group.json |
codelist:base_color |
https://api.cyclesoftware.nl/api/v4/codelists/base_color.json |
codelist:battery_position |
https://api.cyclesoftware.nl/api/v4/codelists/battery_position.json |
codelist:battery_type |
https://api.cyclesoftware.nl/api/v4/codelists/battery_type.json |
codelist:brake_system |
https://api.cyclesoftware.nl/api/v4/codelists/brake_system.json |
codelist:brand |
https://api.cyclesoftware.nl/api/v4/codelists/brand.json |
codelist:customer_group |
https://api.cyclesoftware.nl/api/v4/codelists/customer_group.json |
codelist:display_handling |
https://api.cyclesoftware.nl/api/v4/codelists/display_handling.json |
codelist:display_type |
https://api.cyclesoftware.nl/api/v4/codelists/display_type.json |
codelist:ebike_system |
https://api.cyclesoftware.nl/api/v4/codelists/ebike_system.json |
codelist:electric_bicycle_type |
https://api.cyclesoftware.nl/api/v4/codelists/electric_bicycle_type.json |
codelist:etrto_wheelsize |
https://api.cyclesoftware.nl/api/v4/codelists/etrto_wheelsize.json |
codelist:frame |
https://api.cyclesoftware.nl/api/v4/codelists/frame.json |
codelist:frame_material |
https://api.cyclesoftware.nl/api/v4/codelists/frame_material.json |
codelist:function |
https://api.cyclesoftware.nl/api/v4/codelists/function.json |
codelist:gear_system |
https://api.cyclesoftware.nl/api/v4/codelists/gear_system.json |
codelist:keyword |
https://api.cyclesoftware.nl/api/v4/codelists/keyword.json |
codelist:moped_category |
https://api.cyclesoftware.nl/api/v4/codelists/moped_category.json |
codelist:moped_engine |
https://api.cyclesoftware.nl/api/v4/codelists/moped_engine.json |
codelist:moped_transmission |
https://api.cyclesoftware.nl/api/v4/codelists/moped_transmission.json |
codelist:motor_position |
https://api.cyclesoftware.nl/api/v4/codelists/motor_position.json |
codelist:position |
https://api.cyclesoftware.nl/api/v4/codelists/position.json |
codelist:qualitymark |
https://api.cyclesoftware.nl/api/v4/codelists/qualitymark.json |
codelist:sensor_type[] |
https://api.cyclesoftware.nl/api/v4/codelists/sensor_type.json |
codelist:status |
https://api.cyclesoftware.nl/api/v4/codelists/status.json |
codelist:supplier |
https://api.cyclesoftware.nl/api/v4/codelists/supplier.json |
codelist:surcharge |
https://api.cyclesoftware.nl/api/v4/codelists/surcharge.json |
codelist:vat |
https://api.cyclesoftware.nl/api/v4/codelists/vat.json |
boolean |
Boolean value |
date |
Date (Y-m-d) |
decimal |
Decimal or float value |
integer |
Integer value |
localized-strings |
Localized string object |
object[] |
Array of objects |
string |
String value |
string[] |
Array of strings |
image[] |
Array of images |
battery[] |
Array of battery options |
document[] |
Array of documents |
bundle[] |
Array of product bundles |
Localized-strings type
{
"user": "User defined description",
"nl": "Description in Dutch",
"en": "Description in English",
"fr": "Description in French"
}
This object provides translations for a description in the available languages. If a language is not available the key is omitted from the body.
| Property | Type | Nullable | Description |
|---|---|---|---|
user |
string |
true |
The user defined description e.g. User defined description (primarily used when language code is unsure) |
nl |
string |
true |
The description for language code nl e.g. Description in Dutch |
en |
string |
true |
The description for language code en e.g. Description in English |
fr |
string |
true |
The description for language code fr e.g. Description in French |
Image type
{
"date_modified": "2012-05-08 08:02:58",
"url_thumb": "https://cdn.cyclesoftware.nl/app/img/Y/artPic_public_T_18563.jpg",
"url_large": "https://cdn.cyclesoftware.nl/app/img/Y/artPic_public_L_18563.jpg"
}
| Property | Type | Description |
|---|---|---|
date_modified |
datetime |
Modification datetime e.g. 2012-05-08 08:02:58 |
url_thumb |
string |
URL to thumb image e.g. https://cdn.cyclesoftware.nl/app/img/Y/artPic_public_T_18563.jpg |
url_large |
string |
URL to large image e.g. https://cdn.cyclesoftware.nl/app/img/Y/artPic_public_L_18563.jpg |
Battery type
{
"battery_additional_costs": 200,
"battery_ampere_hour": 1,
"battery_brand": "BOSCH",
"battery_capacity": 400,
"battery_chargeable_in_bike": false,
"battery_fast_recharge_time": 2,
"battery_included_in_base_price": false,
"battery_location": "FRAME",
"battery_model": "Model name 1",
"battery_ranges": [
{
"range_avg": 50,
"range_description": "Fast",
"range_max": 100,
"range_min": 10
},
{
"range_avg": 30,
"range_description": "Medium",
"range_max": 150,
"range_min": 75
}
],
"battery_recharge_time": 3,
"battery_removeable": true,
"battery_type": "LI-ION",
"battery_voltage": 20,
"battery_weight": 5
}
| Property | Type | Omittable | Description |
|---|---|---|---|
battery_additional_costs |
integer |
true |
Additional costs against retail price e.g. 200 |
battery_ampere_hour |
integer |
true |
Battery ampére e.g. 20 |
battery_brand |
string |
true |
Brand name of battery e.g. BOSCH |
battery_capacity |
integer |
true |
Capacity in Wh e.g. 400 |
battery_chargeable_in_bike |
boolean |
true |
true if you can charge in the bike e.g. false |
battery_fast_recharge_time |
integer |
true |
Time in hours to recharche in fast mode e.g. 2 |
battery_recharge_time |
integer |
true |
Default recharche time e.g. 3 hours |
battery_included_in_base_price |
boolean |
true |
Wether the price of this option is included in the retail price e.g. true |
battery_location |
string |
true |
Location see codelist:battery_position e.g. FRAME |
battery_model |
string |
true |
The model description of battery e.g. Model name 1 |
battery_ranges |
array |
true |
Array of ranges for different modes |
battery_ranges[].range_avg |
integer |
true |
Average range in km e.g. 50 |
battery_ranges[].range_description |
string |
true |
e.g. Fast |
battery_ranges[].range_max |
integer |
true |
Maximum range in kme.g. 100 |
battery_ranges[].range_min |
integer |
true |
Minimal range in kme.g. 10 |
battery_removeable |
boolean |
true |
true if you can demount the battery from bike e.g. true |
battery_type |
string |
true |
Battery type see code list codelist:battery_type e.g. LI-ION |
battery_voltage |
integer |
true |
Voltage of battery e.g. 20 |
battery_weight |
integer |
true |
Weight in kg e.g. 5 |
Document type
{
"url": "https://url.to.guid",
"type": "USER GUIDE"
}
Refers to a document with documentation
| Property | Type | Description |
|---|---|---|
url |
string |
URL to document e.g. https://url.to.guid |
type |
string |
Type e.g. USER GUIDE |
Properties - V4
Get definition of properties with types and examples.
| Property | Type | Description |
|---|---|---|
error |
boolean |
true if an error occurred |
error_message |
?string |
Error message if occurred |
data<:property_name>.property_id |
integer |
ID of property e.g. 310 |
data<:property_name>.property_name |
string |
Property definition e.g. article_main_group |
data<:property_name>.data_type |
string |
Data type e.g. boolean, integer, or referring to codelistcodelist:article_main_group |
data<:property_name>.unit |
?string |
Unit e.g. cm, kg or null if no unit applicable |
data<:property_name>.description |
localized-string |
Object with localized descriptions of property |
data<:property_name>.description.nl |
string |
e.g. Hoofdgroep |
data<:property_name>.description.en |
string |
e.g. Main group |
data<:property_name>.description.fr |
string |
e.g. Groupe principal |
data<:property_name>.example_value |
mixed |
An example value found in article data endpoint. e.g. 1 or an object |
data<:property_name>.code_list |
?string |
If codelist associated the URL to code list e.g. https://s01.cyclesoftware.nl/api/v4/articledata/codelist/article_main_group.json |
HTTP Request
GET /api/v4/articledata/properties.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
HTTP Response
{
"error": false,
"error_message": null,
"data": {
"article_main_group": {
"property_id": 310,
"property_name": "article_main_group",
"data_type": "codelist:article_main_group",
"unit": null,
"description": {
"nl": "Hoofdgroep",
"en": "Main group",
"fr": "Groupe principal"
},
"example_value": "1",
"code_list": "https://s01.cyclesoftware.nl/api/v4/articledata/codelist/article_main_group.json"
},
"handle_operation": {
"property_id": 114,
"property_name": "handle_operation",
"data_type": "boolean",
"unit": null,
"description": {
"nl": "Handvatbediening",
"en": "Handle operation",
"fr": "Fonctionnement de la poignée"
},
"example_value": true
},
"model_year": {
"property_id": 120,
"property_name": "model_year",
"data_type": "integer",
"unit": null,
"description": {
"nl": "Modeljaar",
"en": "Model year",
"fr": "Année modèle"
},
"example_value": 2024
},
"highres_image_url": {
"property_id": 133,
"property_name": "highres_image_url",
"data_type": "string[]",
"unit": null,
"description": {
"nl": "High resolution afbeelding URL",
"en": "Highres image URL",
"fr": "URL de l'image haute résolution"
},
"example_value": [
"http://meridaxtraazz.nl/bikeimages/merida/2013/2048/3140.jpg"
]
},
"weight_bruto": {
"property_id": 36,
"property_name": "weight_bruto",
"data_type": "decimal",
"unit": "kg",
"description": {
"nl": "Bruto gewicht",
"en": "Gross weight",
"fr": "Poids brut"
},
"example_value": 10
},
"pos_description": {
"property_id": 142,
"property_name": "pos_description",
"data_type": "string",
"unit": null,
"description": {
"nl": "Kassabontekst",
"en": "Receipt text",
"fr": "Texte du reçu"
},
"example_value": {
"user": "Kassabontekst stored in account",
"nl": "Omschrijving - Kassabontekst",
"en": "Description - Receipt text",
"fr": "Description - Texte du reçu"
}
}
}
}
Code lists - V4
Get code list entries.
Properties
| Property | Type | Description | |
|---|---|---|---|
error |
boolean |
true if an error occurred e.g. false |
|
error_message |
?string |
Error message if available | |
data |
object[] |
Array of code list entries | |
data[].code |
string |
Code value e.g. 2A |
|
data[].code_international |
string |
International code value e.g. BLACK |
|
data[].codelist |
string |
e.g. codelist:name-of-list |
|
data[].description |
localized-string |
Object with localized descriptions | |
data[].description.de |
string |
e.g. Description in German |
|
data[].description.en |
string |
e.g. Description in English |
|
data[].description.fr |
string |
e.g. Description in French |
|
data[].description.nl |
string |
e.g. Description in Dutch |
HTTP Request
GET /api/v4/articledata/codelist/article_main_group.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
HTTP Response
{
"error": false,
"error_message": null,
"data": [
{
"codelist": "codelist:article_main_group",
"code": "1",
"code_international": "1",
"description": {
"nl": "Fietsen",
"fr": "Vélos",
"en": "Bikes",
"de": "Radfahren"
}
},
{
"codelist": "codelist:article_main_group",
"code": "2",
"code_international": "2",
"description": {
"nl": "O&A",
"fr": "Pièces et accessoires",
"en": "Parts and accessories",
"de": "Teile und Zubehör"
}
},
{
"codelist": "codelist:article_main_group",
"code": "3",
"code_international": "3",
"description": {
"nl": "Kleding",
"fr": "Vêtements",
"en": "Clothing",
"de": "Kleidung"
}
},
{
"codelist": "codelist:article_main_group",
"code": "4",
"code_international": "4",
"description": {
"nl": "Fitness",
"fr": "Fitness",
"en": "Fitness",
"de": "Fitness"
}
},
{
"codelist": "codelist:article_main_group",
"code": "5",
"code_international": "5",
"description": {
"nl": "Occasions/Doorlevering",
"fr": "Occasions / Livraison",
"en": "Second hand / b2b sales",
"de": "Anlässe / Lieferung"
}
},
{
"codelist": "codelist:article_main_group",
"code": "6",
"code_international": "6",
"description": {
"nl": "Overigen",
"fr": "Autres",
"en": "Miscellaneous",
"de": "Andere"
}
},
{
"codelist": "codelist:article_main_group",
"code": "7",
"code_international": "7",
"description": {
"nl": "Bromfietsen",
"fr": "Cyclomoteurs",
"en": "Mopeds",
"de": "Mopeds"
}
},
{
"codelist": "codelist:article_main_group",
"code": "8",
"code_international": "8",
"description": {
"nl": "Bromfietsonderdelen",
"fr": "Pièces de cyclomoteur",
"en": "Moped parts",
"de": "Moped Teile"
}
},
{
"codelist": "codelist:article_main_group",
"code": "9",
"code_international": "9",
"description": {
"nl": "Tarieven",
"fr": "Tarifs",
"en": "Rates",
"de": "Preise"
}
}
]
}
Customers
Find, create and update customers
Scope(s)
resources
Customer (object)
| Property | Type | Modify | Description |
|---|---|---|---|
customer_id |
integer |
readonly |
Customer ID e.g. 6 |
customer_type_name |
string |
PUT|POST |
See common enum customer_types e.g. Klant |
customer_reference |
string |
PUT|POST |
Reference of customer e.g. OwnRef |
postcode |
string |
PUT|POST |
Postcode of customer e.g. 5488HM |
house_number |
string |
PUT|POST |
House number of customer e.g. 1 |
house_number_postfix |
string |
PUT|POST |
House number postfix of customer e.g. c |
attn |
string |
PUT|POST |
Attn name Name of address |
title |
string |
PUT|POST |
Name prefix e.g. Dhr./Mevr. |
initials |
string |
PUT|POST |
Initials e.g. T |
insertion |
string |
PUT|POST |
Insertion e.g. van |
first_name |
string |
PUT|POST |
First name e.g. Tim |
name |
string |
PUT|POST |
Last name e.g. LastName |
street |
string |
PUT|POST |
Street e.g. Raadhuisplein |
city |
string |
PUT|POST |
City e.g. Nistelrode |
country_code_iso_3166 |
string |
PUT|POST |
Country code e.g. NL |
email |
string |
PUT|POST |
E-mail e.g. name@domain.nl |
discount_percentage |
decimal |
PUT|POST |
Default discount percentage e.g. 10 |
datetime_created |
?datetime |
readonly |
Created at if available e.g. 2023-01-03 12:30:44 |
phone_numbers |
object[] |
PUT|POST |
array of phone numbers |
phone_numbers[].phone_number_id |
string |
PUT|POST |
ID of phone number e.g. tel (landline) mob (mobile) or ID |
phone_numbers[].customer_id |
integer |
readonly |
Customer ID e.g. 6 |
phone_numbers[].phone_number |
string |
PUT|POST |
Phone number e.g. 0733030050 |
phone_numbers[].name |
string |
PUT|POST |
Name of number e.g. Dhr./Mevr. T UnitTest |
Get Customer
Get customer
GET
/api/v1/customers/:customer_id.json
| URI parameter | Type | Description |
|---|---|---|
customer_id |
int |
Customer ID e.g. 1006 |
The result will be a Customer (object)
HTTP request
GET /api/v1/customers/1006.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
Content-length: 914
{
"customer_id": 1006,
"customer_type_name": "Klant",
"customer_reference": "OwnRef",
"postcode": "5388GM",
"house_number": "1",
"house_number_postfix": "c",
"attn": "Name of address",
"title": "Dhr./Mevr. ",
"initials": "T",
"insertion": "van",
"first_name": "Tim",
"name": "LastName",
"street": "Raadhuisplein",
"city": "Nistelrode",
"country_code_iso_3166": "NL",
"email": "name@domain.nl",
"discount_percentage": 0,
"datetime_created": "2023-01-03 12:30:44",
"phone_numbers": [
{
"phone_number_id": "mob",
"customer_id": 6,
"phone_number": "06-12345678",
"name": "Dhr./Mevr. T UnitTest"
},
{
"phone_number_id": "tel",
"customer_id": 6,
"phone_number": "0733030050",
"name": "Dhr./Mevr. T UnitTest"
}
]
}
Create customer
Create a customer
POST
/api/v1/customers.json
HTTP request
POST /api/v1/customers.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
Content-type: application/json; charset=utf-8
Content-length: 1030
{
"customer_type_name": "Zakelijk",
"customer_reference": "",
"postcode": "18000",
"house_number": "1",
"house_number_postfix": "2",
"attn": "attn",
"title": "M",
"initials": "A",
"insertion": "S",
"first_name": "Adri",
"name": "Aleksnadar",
"street": "street",
"city": "city",
"country_code_iso_3166": "sr",
"email": "email@mail.com",
"discount_percentage": 10,
"datetime_created": null,
"phone_numbers": [
{
"phone_number_id": "mob",
"customer_id": 26196,
"phone_number": "+381 60 2222222",
"name": "Adri S Aleksnadar"
},
{
"phone_number_id": "tel",
"customer_id": 26196,
"phone_number": "",
"name": "Adri S Aleksnadar"
},
{
"phone_number_id": "714253",
"customer_id": 26196,
"phone_number": "+381 60 3333333",
"name": "Extra 1"
}
]
}
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
Content-length: 1030
{
"customer_id": 26196,
"customer_type_name": "Zakelijk",
"customer_reference": "",
"postcode": "18000",
"house_number": "1",
"house_number_postfix": "2",
"attn": "attn",
"title": "M",
"initials": "A",
"insertion": "S",
"first_name": "Adri",
"name": "Aleksnadar",
"street": "street",
"city": "city",
"country_code_iso_3166": "sr",
"email": "email@mail.com",
"discount_percentage": 10,
"datetime_created": null,
"phone_numbers": [
{
"phone_number_id": "mob",
"customer_id": 26196,
"phone_number": "+381 60 2222222",
"name": "Adri S Aleksnadar"
},
{
"phone_number_id": "tel",
"customer_id": 26196,
"phone_number": "",
"name": "Adri S Aleksnadar"
},
{
"phone_number_id": "714253",
"customer_id": 26196,
"phone_number": "+381 60 3333333",
"name": "Extra 1"
}
]
}
Update customer
Update a customer
PUT
/api/v1/customers/:customer_id.json
| URI parameter | Type | Description |
|---|---|---|
customer_id |
int |
Customer ID e.g. 4 |
HTTP request
PUT /api/v1/customers/4.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic
Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
Content-type: application/json; charset=utf-8
Content-length: 873
{
"customer_id": 4,
"customer_type_name": "Klant",
"customer_reference": "",
"postcode": "5243RB",
"house_number": "38",
"house_number_postfix": "",
"attn": "",
"title": "Dhr./Mevr. ",
"initials": "G",
"insertion": "",
"first_name": "",
"name": "Name 64070233d1b8c",
"street": "Bruggen",
"city": "Rosmalen",
"country_code_iso_3166": "NL",
"email": "test@hotmail.com",
"discount_percentage": 0,
"datetime_created": null,
"phone_numbers": [
{
"phone_number_id": "mob",
"customer_id": 4,
"phone_number": "",
"name": "Dhr./Mevr. G Name 64070233d1b8c"
},
{
"phone_number_id": "tel",
"customer_id": 4,
"phone_number": "",
"name": "Dhr./Mevr. G Name 64070233d1b8c"
}
]
}
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
Content-length: 873
{
"customer_id": 4,
"customer_type_name": "Klant",
"customer_reference": "",
"postcode": "5243RB",
"house_number": "38",
"house_number_postfix": "",
"attn": "",
"title": "Dhr./Mevr. ",
"initials": "G",
"insertion": "",
"first_name": "",
"name": "Name 64070233d1b8c",
"street": "Bruggen",
"city": "Rosmalen",
"country_code_iso_3166": "NL",
"email": "test@hotmail.com",
"discount_percentage": 0,
"datetime_created": null,
"phone_numbers": [
{
"phone_number_id": "mob",
"customer_id": 4,
"phone_number": "",
"name": "Dhr./Mevr. G Name 64070233d1b8c"
},
{
"phone_number_id": "tel",
"customer_id": 4,
"phone_number": "",
"name": "Dhr./Mevr. G Name 64070233d1b8c"
}
]
}
Find customers
Find existing customers
GET
/api/v1/customers/find.json?phone_number=:phone_number&..
| GET parameter | Type | Description |
|---|---|---|
phone_number |
?string |
Phone number of customer e.g. 0733030050 |
postal_code |
?string |
Postal code of customer e.g. 5388GM |
housenumber |
?string |
Housenumber of customer e.g. 1 |
housenumber_postfix |
?string |
Housenumber_postfix of customer e.g. a |
email |
?string |
E-mail of customer e.g. name@domain.nl |
query |
?string |
Query to search for e.g. name of customer |
country_code |
?string |
Country code of customer e.g. NL |
customer_type_id |
?integer |
Customer type e.g. 2 see common enum customer_types |
The result will be an array of Customer (object)
HTTP request
GET /api/v1/customers/find.json?phone_number=0733030050 HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
Content-type: application/json; charset=utf-8
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 44656
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
[
{
"customer_id": 8,
"customer_type_name": "Klant",
"customer_reference": "REF46",
"postcode": "8448PE",
"house_number": "32",
"house_number_postfix": "B",
"attn": "",
"title": "Dhr.",
"initials": "A",
"insertion": "Van",
"first_name": "Adri",
"name": "Name 235238848",
"street": "Mauritslaan",
"city": "Heerenveen",
"country_code_iso_3166": "NL",
"email": "test235238848@cyclesoftware.nl",
"discount_percentage": 0,
"datetime_created": null,
"phone_numbers": [
{
"phone_number_id": "mob",
"customer_id": 8,
"phone_number": "0733030050",
"name": "Adri Van Name 235238848"
},
{
"phone_number_id": "tel",
"customer_id": 8,
"phone_number": "",
"name": "Adri Van Name 235238848"
},
{
"phone_number_id": "453383",
"customer_id": 8,
"phone_number": "06 24238848",
"name": "Extra 1"
}
]
},
{
"customer_id": 11,
"customer_type_name": "E-commerce",
"customer_reference": "REFBE1",
"postcode": "1000",
"house_number": "2",
"house_number_postfix": "B",
"attn": "",
"title": "Dhr.",
"initials": "G",
"insertion": "van",
"first_name": "Giel",
"name": "Wijgergangs",
"street": "Belgische weg",
"city": "Belgcity",
"country_code_iso_3166": "BE",
"email": "gielwijgergangs@example.com",
"discount_percentage": 0,
"datetime_created": null,
"phone_numbers": [
{
"phone_number_id": "mob",
"customer_id": 11,
"phone_number": "06 22903913",
"name": "Giel van Wijgergangs"
},
{
"phone_number_id": "tel",
"customer_id": 11,
"phone_number": "073 303 0050",
"name": "Giel van Wijgergangs"
}
]
}
]
List customers
List customers
GET
/api/v1/customers/list.json?modified_since=:modified_since&offset=:offset
GET
/api/v1/customers/list.json?offset=:offset
| GET parameter | Type | Description |
|---|---|---|
offset |
?integer |
Optional offset, see pagination pagination.next_offset in result |
modified_since |
?datetime |
Filter on modified customers since datetime e.g. 2023-01-12 12:30:00 |
Properties
| Property | Type | Description |
|---|---|---|
error |
boolean |
true if an error occured e.g. false |
error_message |
?string |
The error message if occured. |
customers |
object[] |
Array of Customer (object) |
pagination.count |
integer |
Number of customers the customers element e.g. 500 |
pagination.next_offset |
?integer |
null if no next page available, otherwise value for offset GET variable |
HTTP request
GET /api/v1/customers/list.json?modified_since=2019-01-01%2012:00:00 HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
Content-type: application/json; charset=utf-8
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 2689
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"error": false,
"error_message": null,
"customers": [
{
"customer_id": 8,
"customer_type_name": "Klant",
"customer_reference": "REF46",
"postcode": "8448PE",
"house_number": "32",
"house_number_postfix": "B",
"attn": "",
"title": "Dhr.",
"initials": "A",
"insertion": "Van",
"first_name": "Adri",
"name": "Name 235238848",
"street": "Mauritslaan",
"city": "Heerenveen",
"country_code_iso_3166": "NL",
"email": "test235238848@cyclesoftware.nl",
"discount_percentage": 0,
"datetime_created": null,
"phone_numbers": [
{
"phone_number_id": "mob",
"customer_id": 8,
"phone_number": "0733030050",
"name": "Adri Van Name 235238848"
},
{
"phone_number_id": "tel",
"customer_id": 8,
"phone_number": "",
"name": "Adri Van Name 235238848"
},
{
"phone_number_id": "453383",
"customer_id": 8,
"phone_number": "06 24238848",
"name": "Extra 1"
}
]
},
{
"customer_id": 11,
"customer_type_name": "E-commerce",
"customer_reference": "REFBE1",
"postcode": "1000",
"house_number": "2",
"house_number_postfix": "B",
"attn": "",
"title": "Dhr.",
"initials": "G",
"insertion": "van",
"first_name": "Giel",
"name": "Wijgergangs",
"street": "Belgische weg",
"city": "Belgcity",
"country_code_iso_3166": "BE",
"email": "gielwijgergangs@example.com",
"discount_percentage": 0,
"datetime_created": null,
"phone_numbers": [
{
"phone_number_id": "mob",
"customer_id": 11,
"phone_number": "06 22903913",
"name": "Giel van Wijgergangs"
},
{
"phone_number_id": "tel",
"customer_id": 11,
"phone_number": "073 303 0050",
"name": "Giel van Wijgergangs"
}
]
}
],
"pagination": {
"count": 2,
"next_offset": null
}
}
E-commerce
The e-commerce APIs are designed for pushing e-commerce orders to CycleSoftware.
Authentication
The authentication is handled in the Authentication element of the SOAP requests.
| Field | Type | Description |
|---|---|---|
username |
string | API credentials username |
password |
string | API credentials password |
dealer_id |
string | Leave empty or specify the store_id or use the API-key |
Scope(s)
e-commerce
Definition
The latest definition of the WSDL specification can be found at:
WSDL-SOAP
/app/cs/api/ecommerce/soap_2_11/?wsdl
Properties
| Property | Type | Description |
|---|---|---|
Authentication[].username |
string |
e.g. your-username |
Authentication[].password |
string |
e.g. your-password |
Authentication[].dealer_id |
string |
store-id or api-key. e.g. 1 |
Order.order_reference_id |
string |
Unique order reference id 319813049 |
Order.order_reference_text |
string |
Unique order reference text 5640c085abba9 |
Order.order_payment_method_description |
string |
Legacy payment description field. This field will not trigger a payment (e.g. iDEAL, Bancontact) |
Order.order_ship_to_customer |
boolean |
boolean 1 or 0 |
Order.order_shipment_method_description |
string |
e.g. tnt |
Order.order_date_preferred_delivery |
date |
e.g. 2015-12-01 |
Order.order_remarks |
string |
e.g. remark example |
Order.order_vat_country_code |
string |
Apply the VAT rates of this country code. CS will only apply the VAT rates if enabled in account settings and if order_ship_to_customer is true. If the VAT rates are not applied or the same as the country of the account, it will default back to null in the OrderStatusResponse |
Order.order_sales_employee_id |
integer |
e.g. 10001 see Common / Employees endpoint for employee_id values |
Order.Customer |
object |
see Customer.* property |
Order.Customer.DeliveryAddress.delivery_address_use_delivery_address |
boolean |
Boolean 1 or 0 |
Order.Customer.DeliveryAddress.delivery_address_name |
string |
e.g. CycleSoftware |
Order.Customer.DeliveryAddress.delivery_address_street_name |
string |
e.g. Kievitsven |
Order.Customer.DeliveryAddress.delivery_address_postal_code |
string |
e.g. 5249JJ |
Order.Customer.DeliveryAddress.delivery_address_housenumber |
string |
e.g. 4 |
Order.Customer.DeliveryAddress.delivery_address_housenumber_suffix |
string |
e.g. b |
Order.Customer.DeliveryAddress.delivery_address_city |
string |
e.g. Rosmalen |
Order.Customer.DeliveryAddress.delivery_address_country_code_iso_3166 |
string |
e.g. NL |
Order.Customer.DeliveryAddress.delivery_address_remarks |
string |
e.g. Bam |
Order.OrderItems.OrderItem |
object[] |
Array of OrderItem objects |
Order.OrderItems.OrderItem[].order_item_is_bicycle |
boolean |
Indicate whether this order item is a sold bicycle (0 or 1) |
Order.OrderItems.OrderItem[].order_item_barcode |
string |
e.g. 1000 |
Order.OrderItems.OrderItem[].order_item_quantity |
integer |
e.g. 2 |
Order.OrderItems.OrderItem[].order_item_description |
string |
e.g. Test product |
Order.OrderItems.OrderItem[].order_item_unit_price_in_vat |
decimal |
e.g. 12.99 |
Order.OrderItems.OrderItem[].order_item_unit_discount_amount_in_vat |
decimal |
e.g. 2.99 |
Order.OrderItems.OrderItem[].order_item_vat_code |
integer |
0: no VAT, 1: Low VAT, 2 High VAT |
Order.OrderItems.OrderItem[].order_item_supplier_order_mode |
string |
0: no supplier order or reservation on objects 1:automatically create supplier order for this sales order 2: automatically reserve available stock objects based on the object_id in order_item_object_id or order_item_barcode field. 4: Same as mode=2 with pool orders via warehouse |
Order.OrderItems.OrderItem[].order_item_supplier_id |
integer |
When order_item_supplier_mode = 1, make the supplier order for this supplier. Supplier IDs can be looked up in https://api.cyclesoftware.nl/app/api/groups/ |
Order.OrderItems.OrderItem[].order_item_object_id |
integer |
Reserve this specific object for this order item |
Order.OrderItems.OrderItem[].order_item_invoice_customer_id |
integer |
If supplied with integer value > 0 this order item will be invoiced to this customer id (SplitOrder) All the customer info in the SaveOrder should be the “rider” or “consumer” |
UpdateValues.UpdateValue |
object[] |
Array of UpdateValue objects |
UpdateValues.UpdateValue[].name |
string |
Field to update: order_reference_text, order_payment_method_description,order_ship_to_customer,order_shipment_method_description,order_date_preferred_delivery,order_track_trace_reference,order_remarks |
UpdateValues.UpdateValue[].value |
string |
e.g. Will pickup at 13.00 |
Customer.customer_type_name |
string |
One of the following: Klant, Leverancier, E-commerce, Zakelijk, Lease-rijder, Lease-maatschappij, Werkgever |
Customer.customer_cs_customer_id |
string |
e.g. 235238848 |
Customer.customer_reference |
string |
Should be an unique reference to the customer to prevent re-use / overwrites of existing customers |
Customer.customer_name_prefix |
string |
e.g. Dhr. |
Customer.customer_first_name |
string |
e.g. Adri |
Customer.customer_name_initials |
string |
e.g. A |
Customer.customer_middle_name |
string |
e.g. Van |
Customer.customer_last_name |
string |
e.g. Name 235238848 |
Customer.customer_postal_code |
string |
e.g. 8448PE |
Customer.customer_housenumber |
string |
e.g. 32 |
Customer.customer_housenumber_suffix |
string |
e.g. B |
Customer.customer_street_name |
string |
e.g. Mauritslaan |
Customer.customer_city |
string |
e.g. Heerenveen |
Customer.customer_phone |
string |
e.g. 073-1234567 |
Customer.customer_mobile |
string |
e.g. 06-124235335 |
Customer.customer_country_code_iso_3166 |
string |
Country code iso3166 e.g. NL |
Customer.customer_email |
string |
e.g. test235238848@cyclesoftware.nl |
Customer.customer_newsletter |
boolean |
Toggle newsletter option boolean 1 or 0 |
Customer.customer_date_of_birth |
date |
e.g. 1980-01-01 |
Customer.customer_iban |
string |
e.g. NL69INGB0123456789 |
Payments.Payment |
object[] |
Array of Payment objects |
Payments.Payment[].payment_method_id |
integer|string |
The payment method ID or description e.g. 1 or PSP . See common enum API payment_methods |
Payments.Payment[].payment_amount |
decimal |
The payment amount e.g. 100.00 |
Payments.Payment[].voucher_or_discount_code |
?string |
The voucher code e.g. 1000-2000-3000-4000 |
Payments.Payment[].payment_for_customer_id |
?integer |
The customer ID to assign the payment to when using order_item_invoice_customer_id |
SaveOrder
Creates a new order in CycleSoftware
<?php
try {
$client = new \SoapClient(
'https://api.cyclesoftware.nl/app/cs/api/ecommerce/soap_2_11/?wsdl',
[
'trace' => true,
'use' => SOAP_LITERAL,
'encoding' => 'UTF-8',
]
);
$input = (object)[
'Authentication' =>
(object)[
'username' => 'your-username',
'password' => 'your-password',
'dealer_id' => '1', // store-id within account
],
'Order' =>
(object)[
'order_reference_text' => '5640c085abba9',
'order_reference_id' => '319813049',
'order_payment_method_description' => 'psp',
'order_ship_to_customer' => '1',
'order_shipment_method_description' => 'tnt',
'order_date_preferred_delivery' => '2015-12-01',
'order_remarks' => 'remark example',
'order_vat_country_code' => 'NL',
'order_sales_employee_id ' => null,
'Customer' =>
(object)[
'customer_cs_customer_id' => '11',
'customer_reference' => 'unique-reference-customer',
'customer_name_prefix' => 'Dhr.',
'customer_name_initials' => 'J',
'customer_first_name' => 'Jan',
'customer_middle_name' => 'van',
'customer_last_name' => 'Dijk',
'customer_postal_code' => '1000AA',
'customer_housenumber' => '2',
'customer_housenumber_suffix' => 'B',
'customer_street_name' => 'Steenweg',
'customer_city' => 'Amsterdam',
'customer_phone' => '0733030050',
'customer_mobile' => '0612345678',
'customer_country_code_iso_3166' => 'NL',
'customer_email' => 'test@test.com',
'customer_newsletter' => '1',
'customer_date_of_birth' => '',
'customer_iban' => '',
'DeliveryAddress' =>
(object)[
'delivery_address_use_delivery_address' => '1',
'delivery_address_name' => 'Bedrijfsnaam',
'delivery_address_street_name' => 'Steenweg',
'delivery_address_postal_code' => '1000AA',
'delivery_address_housenumber' => '2',
'delivery_address_housenumber_suffix' => 'B',
'delivery_address_city' => 'Amsterdam',
'delivery_address_country_code_iso_3166' => 'NL',
'delivery_address_remarks' => 'Extra opmerking',
],
],
'OrderItems' =>
(object)[
'OrderItem' =>
[
(object)[
'order_item_is_bicycle' => '0',
'order_item_barcode' => '88237237239',
'order_item_quantity' => '-1',
'order_item_description' => 'Some article',
'order_item_unit_price_in_vat' => '1021',
'order_item_unit_discount_amount_in_vat' => '21',
'order_item_vat_code' => '2',
'order_item_supplier_order_mode' => '0',
'order_item_invoice_customer_id' => 4,
],
(object)[
'order_item_is_bicycle' => '0',
'order_item_barcode' => '47348340934',
'order_item_quantity' => '1',
'order_item_description' => 'Some Article',
'order_item_unit_price_in_vat' => '1521',
'order_item_unit_discount_amount_in_vat' => '21',
'order_item_vat_code' => '2',
'order_item_supplier_order_mode' => '0',
'order_item_invoice_customer_id' => '2',
],
(object)[
'order_item_is_bicycle' => '0',
'order_item_barcode' => '43934939344',
'order_item_quantity' => '3',
'order_item_description' => 'Some article',
'order_item_unit_price_in_vat' => '1021',
'order_item_unit_discount_amount_in_vat' => '21',
'order_item_vat_code' => '2',
'order_item_supplier_order_mode' => '0',
'order_item_invoice_customer_id' => null,
],
],
],
],
'Payments' =>
(object)[
'Payment' =>
[
(object)[
'payment_method_id' => '2',
'payment_amount' => '-1021.00',
'voucher_or_discount_code' => null,
'payment_for_customer_id' => '4',
],
(object)[
'payment_method_id' => '5',
'payment_amount' => '1521.00',
'voucher_or_discount_code' => '1000-2000-3000-4000',
'payment_for_customer_id' => '2',
],
(object)[
'payment_method_id' => '3',
'payment_amount' => '3063.00',
'voucher_or_discount_code' => null,
'payment_for_customer_id' => null,
],
],
],
],
]
];
$result = $client->SaveOrder($input);
$order_id = $result->order_id;
$customer_id = $result->customer_id;
var_dump($result);
}
catch (\SoapFault $e) {
var_dump($e->getMessage());
}
HTTP Request
POST /app/cs/api/ecommerce/soap_2_11/ HTTP/1.1
Host: api.cyclesoftware.nl
Accept-encoding: gzip
Accept: text/xml
Content-type: text/xml; charset=utf-8
User-agent: SoapClient
Soapaction: "SaveOrder"
Content-length: 4614
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://api.cyclesoftware.nl/app/cs/api/ecommerce/soap_2_0/">
<SOAP-ENV:Body>
<ns1:SaveOrderRequest>
<Authentication>
<username>your-username</username>
<password>your-password</password>
<dealer_id>1</dealer_id>
</Authentication>
<Order>
<order_reference_id>319813049</order_reference_id>
<order_reference_text>5640c085abba9</order_reference_text>
<order_payment_method_description>psp</order_payment_method_description>
<order_ship_to_customer>1</order_ship_to_customer>
<order_shipment_method_description>tnt</order_shipment_method_description>
<order_date_preferred_delivery>2015-12-01</order_date_preferred_delivery>
<order_remarks>remark example</order_remarks>
<order_vat_country_code>NL</order_vat_country_code>
<order_sales_employee_id/>
<Customer>
<customer_cs_customer_id>0</customer_cs_customer_id>
<customer_reference>unique-reference-customer</customer_reference>
<customer_name_prefix>J</customer_name_prefix>
<customer_middle_name>van</customer_middle_name>
<customer_last_name>Dijk</customer_last_name>
<customer_postal_code>1000AA</customer_postal_code>
<customer_housenumber>2</customer_housenumber>
<customer_housenumber_suffix>B</customer_housenumber_suffix>
<customer_street_name>Steenweg</customer_street_name>
<customer_city>Amsterdam</customer_city>
<customer_phone>0733030050</customer_phone>
<customer_mobile>0612345678</customer_mobile>
<customer_country_code_iso_3166>NL</customer_country_code_iso_3166>
<customer_email>test@test.com</customer_email>
<customer_newsletter>1</customer_newsletter>
<customer_iban>NL69INGB0123456789</customer_iban>
<customer_date_of_birth>1988-09-29</customer_date_of_birth>
<DeliveryAddress>
<delivery_address_use_delivery_address>1</delivery_address_use_delivery_address>
<delivery_address_name>CycleSoftware</delivery_address_name>
<delivery_address_street_name>Kievitsven</delivery_address_street_name>
<delivery_address_postal_code>5249JJ</delivery_address_postal_code>
<delivery_address_housenumber>4</delivery_address_housenumber>
<delivery_address_housenumber_suffix>b</delivery_address_housenumber_suffix>
<delivery_address_city>Rosmalen</delivery_address_city>
<delivery_address_country_code_iso_3166>NL</delivery_address_country_code_iso_3166>
<delivery_address_remarks>Bam</delivery_address_remarks>
</DeliveryAddress>
</Customer>
<OrderItems>
<OrderItem>
<order_item_is_bicycle>0</order_item_is_bicycle>
<order_item_barcode>1000</order_item_barcode>
<order_item_quantity>2</order_item_quantity>
<order_item_description>DescriptionTest</order_item_description>
<order_item_unit_price_in_vat>12.99</order_item_unit_price_in_vat>
<order_item_unit_discount_amount_in_vat>2.99</order_item_unit_discount_amount_in_vat>
<order_item_vat_code>2</order_item_vat_code>
<order_item_supplier_order_mode>0</order_item_supplier_order_mode>
<order_item_supplier_id>0</order_item_supplier_id>
<order_item_object_id>0</order_item_object_id>
<order_item_invoice_customer_id>0</order_item_invoice_customer_id>
</OrderItem>
<OrderItem>
<order_item_is_bicycle>0</order_item_is_bicycle>
<order_item_barcode>1000</order_item_barcode>
<order_item_quantity>2</order_item_quantity>
<order_item_description>DescriptionTest</order_item_description>
<order_item_unit_price_in_vat>12.99</order_item_unit_price_in_vat>
<order_item_unit_discount_amount_in_vat>2.99</order_item_unit_discount_amount_in_vat>
<order_item_vat_code>2</order_item_vat_code>
<order_item_supplier_order_mode>0</order_item_supplier_order_mode>
<order_item_supplier_id>0</order_item_supplier_id>
<order_item_object_id>0</order_item_object_id>
<order_item_invoice_customer_id>1000</order_item_invoice_customer_id>
</OrderItem>
</OrderItems>
</Order>
<Payments>
<Payment>
<payment_method_id>12</payment_method_id>
<payment_amount>10.00</payment_amount>
<payment_for_customer_id>1000</payment_for_customer_id>
</Payment>
<Payment>
<payment_method_id>12</payment_method_id>
<payment_amount>10.00</payment_amount>
</Payment>
<Payment>
<payment_method_id>5</payment_method_id>
<payment_amount>0.01</payment_amount>
<voucher_or_discount_code>1000-2000-3000-4000</voucher_or_discount_code>
</Payment>
</Payments>
</ns1:SaveOrderRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
HTTP/1.1 200
Content-type: application/xml; charset=utf-8
Content-length: 2083
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<SaveOrderResponse>
<order_id>3688</order_id>
<customer_id>1498</customer_id>
<created_new_order>1</created_new_order>
<order_type_id>1</order_type_id>
<remarks>
</remarks>
<OrderItems>
<OrderItem>
<order_item_status_id>0</order_item_status_id>
<order_item_status_text>Geen status</order_item_status_text>
<order_item_is_bicycle>0</order_item_is_bicycle>
<order_item_object_id>0</order_item_object_id>
<order_item_barcode>1000</order_item_barcode>
<order_item_quantity>2</order_item_quantity>
<order_item_description>Test product</order_item_description>
<order_item_unit_price_in_vat>12.99</order_item_unit_price_in_vat>
<order_item_unit_discount_amount_in_vat>2.99</order_item_unit_discount_amount_in_vat>
<order_item_vat_code>2</order_item_vat_code>
<order_item_line_id>1</order_item_line_id>
<order_item_object_id/>
<order_item_invoice_customer_id/>
</OrderItem>
<OrderItem>
<order_item_status_id>0</order_item_status_id>
<order_item_status_text>Geen status</order_item_status_text>
<order_item_is_bicycle>0</order_item_is_bicycle>
<order_item_object_id>0</order_item_object_id>
<order_item_barcode>1000</order_item_barcode>
<order_item_quantity>2</order_item_quantity>
<order_item_description>Test product</order_item_description>
<order_item_unit_price_in_vat>12.99</order_item_unit_price_in_vat>
<order_item_unit_discount_amount_in_vat>2.99</order_item_unit_discount_amount_in_vat>
<order_item_vat_code>2</order_item_vat_code>
<order_item_line_id>2</order_item_line_id>
<order_item_object_id/>
<order_item_invoice_customer_id>1000</order_item_invoice_customer_id>
</OrderItem>
</SaveOrderResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
SaveQuote
Creates a new quote in CycleSoftware
<?php
try {
$client = new \SoapClient(
'https://api.cyclesoftware.nl/app/cs/api/ecommerce/soap_2_11/?wsdl',
[
'trace' => true,
'use' => SOAP_LITERAL,
'encoding' => 'UTF-8',
]
);
$input = (object)[
'Authentication' =>
(object)[
'username' => 'your-username',
'password' => 'your-password',
'dealer_id' => '1', // store-id within account
],
'Order' =>
(object)[
'order_reference_text' => '5640c085abba9',
'order_reference_id' => '319813049',
'order_payment_method_description' => 'psp',
'order_ship_to_customer' => '1',
'order_shipment_method_description' => 'tnt',
'order_date_preferred_delivery' => '2015-12-01',
'order_remarks' => 'remark example',
'order_vat_country_code' => 'NL',
'order_sales_employee_id ' => null,
'Customer' =>
(object)[
'customer_cs_customer_id' => '11',
'customer_reference' => 'unique-reference-customer',
'customer_name_prefix' => 'Dhr.',
'customer_name_initials' => 'J',
'customer_first_name' => 'Jan',
'customer_middle_name' => 'van',
'customer_last_name' => 'Dijk',
'customer_postal_code' => '1000AA',
'customer_housenumber' => '2',
'customer_housenumber_suffix' => 'B',
'customer_street_name' => 'Steenweg',
'customer_city' => 'Amsterdam',
'customer_phone' => '0733030050',
'customer_mobile' => '0612345678',
'customer_country_code_iso_3166' => 'NL',
'customer_email' => 'test@test.com',
'customer_newsletter' => '1',
'customer_date_of_birth' => '',
'customer_iban' => '',
'DeliveryAddress' =>
(object)[
'delivery_address_use_delivery_address' => '1',
'delivery_address_name' => 'Bedrijfsnaam',
'delivery_address_street_name' => 'Steenweg',
'delivery_address_postal_code' => '1000AA',
'delivery_address_housenumber' => '2',
'delivery_address_housenumber_suffix' => 'B',
'delivery_address_city' => 'Amsterdam',
'delivery_address_country_code_iso_3166' => 'NL',
'delivery_address_remarks' => 'Extra opmerking',
],
],
'OrderItems' =>
(object)[
'OrderItem' =>
[
(object)[
'order_item_is_bicycle' => '0',
'order_item_barcode' => '88237237239',
'order_item_quantity' => '-1',
'order_item_description' => 'Some article',
'order_item_unit_price_in_vat' => '1021',
'order_item_unit_discount_amount_in_vat' => '21',
'order_item_vat_code' => '2',
'order_item_supplier_order_mode' => '0',
'order_item_invoice_customer_id' => 4,
],
(object)[
'order_item_is_bicycle' => '0',
'order_item_barcode' => '47348340934',
'order_item_quantity' => '1',
'order_item_description' => 'Some Article',
'order_item_unit_price_in_vat' => '1521',
'order_item_unit_discount_amount_in_vat' => '21',
'order_item_vat_code' => '2',
'order_item_supplier_order_mode' => '0',
'order_item_invoice_customer_id' => '2',
],
(object)[
'order_item_is_bicycle' => '0',
'order_item_barcode' => '43934939344',
'order_item_quantity' => '3',
'order_item_description' => 'Some article',
'order_item_unit_price_in_vat' => '1021',
'order_item_unit_discount_amount_in_vat' => '21',
'order_item_vat_code' => '2',
'order_item_supplier_order_mode' => '0',
'order_item_invoice_customer_id' => null,
],
],
],
],
];
$result = $client->SaveQuote($input);
$order_id = $result->order_id;
$customer_id = $result->customer_id;
var_dump($result);
}
catch (\SoapFault $e) {
var_dump($e->getMessage());
}
HTTP Request
POST /app/cs/api/ecommerce/soap_2_11/ HTTP/1.1
Host: api.cyclesoftware.nl
Accept-encoding: gzip
Accept: text/xml
Content-type: text/xml; charset=utf-8
User-agent: SoapClient
Soapaction: "SaveQuote"
Content-length: 4614
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://api.cyclesoftware.nl/app/cs/api/ecommerce/soap_2_0/">
<SOAP-ENV:Body>
<ns1:SaveQuoteRequest>
<Authentication>
<username>your-username</username>
<password>your-password</password>
<dealer_id>1</dealer_id>
</Authentication>
<Order>
<order_reference_id>319813049</order_reference_id>
<order_reference_text>5640c085abba9</order_reference_text>
<order_payment_method_description>psp</order_payment_method_description>
<order_ship_to_customer>1</order_ship_to_customer>
<order_shipment_method_description>tnt</order_shipment_method_description>
<order_date_preferred_delivery>2015-12-01</order_date_preferred_delivery>
<order_remarks>remark example</order_remarks>
<order_vat_country_code>NL</order_vat_country_code>
<order_sales_employee_id/>
<Customer>
<customer_cs_customer_id>0</customer_cs_customer_id>
<customer_reference>unique-reference-customer</customer_reference>
<customer_name_prefix>J</customer_name_prefix>
<customer_middle_name>van</customer_middle_name>
<customer_last_name>Dijk</customer_last_name>
<customer_postal_code>1000AA</customer_postal_code>
<customer_housenumber>2</customer_housenumber>
<customer_housenumber_suffix>B</customer_housenumber_suffix>
<customer_street_name>Steenweg</customer_street_name>
<customer_city>Amsterdam</customer_city>
<customer_phone>0733030050</customer_phone>
<customer_mobile>0612345678</customer_mobile>
<customer_country_code_iso_3166>NL</customer_country_code_iso_3166>
<customer_email>test@test.com</customer_email>
<customer_newsletter>1</customer_newsletter>
<customer_iban>NL69INGB0123456789</customer_iban>
<customer_date_of_birth>1988-09-29</customer_date_of_birth>
<DeliveryAddress>
<delivery_address_use_delivery_address>1</delivery_address_use_delivery_address>
<delivery_address_name>CycleSoftware</delivery_address_name>
<delivery_address_street_name>Kievitsven</delivery_address_street_name>
<delivery_address_postal_code>5249JJ</delivery_address_postal_code>
<delivery_address_housenumber>4</delivery_address_housenumber>
<delivery_address_housenumber_suffix>b</delivery_address_housenumber_suffix>
<delivery_address_city>Rosmalen</delivery_address_city>
<delivery_address_country_code_iso_3166>NL</delivery_address_country_code_iso_3166>
<delivery_address_remarks>Bam</delivery_address_remarks>
</DeliveryAddress>
</Customer>
<OrderItems>
<OrderItem>
<order_item_is_bicycle>0</order_item_is_bicycle>
<order_item_barcode>1000</order_item_barcode>
<order_item_quantity>2</order_item_quantity>
<order_item_description>DescriptionTest</order_item_description>
<order_item_unit_price_in_vat>12.99</order_item_unit_price_in_vat>
<order_item_unit_discount_amount_in_vat>2.99</order_item_unit_discount_amount_in_vat>
<order_item_vat_code>2</order_item_vat_code>
<order_item_supplier_order_mode>0</order_item_supplier_order_mode>
<order_item_supplier_id>0</order_item_supplier_id>
<order_item_object_id>0</order_item_object_id>
<order_item_invoice_customer_id>0</order_item_invoice_customer_id>
</OrderItem>
<OrderItem>
<order_item_is_bicycle>0</order_item_is_bicycle>
<order_item_barcode>1000</order_item_barcode>
<order_item_quantity>2</order_item_quantity>
<order_item_description>DescriptionTest</order_item_description>
<order_item_unit_price_in_vat>12.99</order_item_unit_price_in_vat>
<order_item_unit_discount_amount_in_vat>2.99</order_item_unit_discount_amount_in_vat>
<order_item_vat_code>2</order_item_vat_code>
<order_item_supplier_order_mode>0</order_item_supplier_order_mode>
<order_item_supplier_id>0</order_item_supplier_id>
<order_item_object_id>0</order_item_object_id>
<order_item_invoice_customer_id>1000</order_item_invoice_customer_id>
</OrderItem>
</OrderItems>
</Order>
</ns1:SaveQuoteRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
HTTP/1.1 200
Content-type: application/xml; charset=utf-8
Content-length: 2083
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<SaveQuoteResponse>
<order_id>3688</order_id>
<customer_id>1498</customer_id>
<created_new_order>1</created_new_order>
<order_type_id>5</order_type_id>
<remarks>
</remarks>
<OrderItems>
<OrderItem>
<order_item_status_id>0</order_item_status_id>
<order_item_status_text>Geen status</order_item_status_text>
<order_item_is_bicycle>0</order_item_is_bicycle>
<order_item_object_id>0</order_item_object_id>
<order_item_barcode>1000</order_item_barcode>
<order_item_quantity>2</order_item_quantity>
<order_item_description>Test product</order_item_description>
<order_item_unit_price_in_vat>12.99</order_item_unit_price_in_vat>
<order_item_unit_discount_amount_in_vat>2.99</order_item_unit_discount_amount_in_vat>
<order_item_vat_code>2</order_item_vat_code>
<order_item_line_id>1</order_item_line_id>
<order_item_object_id/>
<order_item_invoice_customer_id/>
</OrderItem>
<OrderItem>
<order_item_status_id>0</order_item_status_id>
<order_item_status_text>Geen status</order_item_status_text>
<order_item_is_bicycle>0</order_item_is_bicycle>
<order_item_object_id>0</order_item_object_id>
<order_item_barcode>1000</order_item_barcode>
<order_item_quantity>2</order_item_quantity>
<order_item_description>Test product</order_item_description>
<order_item_unit_price_in_vat>12.99</order_item_unit_price_in_vat>
<order_item_unit_discount_amount_in_vat>2.99</order_item_unit_discount_amount_in_vat>
<order_item_vat_code>2</order_item_vat_code>
<order_item_line_id>2</order_item_line_id>
<order_item_object_id/>
<order_item_invoice_customer_id>1000</order_item_invoice_customer_id>
</OrderItem>
</SaveQuoteResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
UpdateOrder
Update some header fields in the sales order. The following fields can be updated:
| Property | Type | Description |
|---|---|---|
order_reference_text |
string |
Order reference text value |
order_payment_method_description |
string |
Legacy field with description of the payment method, this will not process a payment on the order |
order_ship_to_customer |
bool |
true if the order will be shipped to the customer, false for pickup in store |
order_shipment_method_description |
string |
Description of shipment method |
order_date_preferred_delivery |
date |
Date of preferred delivery e.g. 2023-01-01 |
order_track_trace_reference |
string |
Track and Trace ID |
order_remarks |
string |
General remarks about the order |
AddPayments |
object[] |
Add payments to the order, see Payments.Payment structure |
<?php
try {
$client = new \SoapClient(
'https://api.cyclesoftware.nl/app/cs/api/ecommerce/soap_2_11/?wsdl',
[
'trace' => true,
'use' => SOAP_LITERAL,
'encoding' => 'UTF-8',
]
);
$input = (object)[
'Authentication' =>
(object)[
'username' => 'your-username',
'password' => 'your-password',
'dealer_id' => '1', // store-id within account
],
'order_id' => '3623',
'order_reference_id' => '',
'UpdateValues' =>
(object)[
'UpdateValue' =>
[
0 =>
(object)[
'name' => 'order_date_preferred_delivery',
'value' => '2021-10-05 08:03:31',
],
1 =>
(object)[
'name' => 'order_reference_text',
'value' => '615beab217c75',
],
2 =>
(object)[
'name' => 'order_track_trace_reference',
'value' => '615beab217c76',
],
],
],
'AddPayments' => (object)[
'Payment' => [
(object)[
'payment_method_id' => '2',
'payment_amount' => '100.00',
'voucher_or_discount_code' => null,
'payment_for_customer_id' => '4',
],
(object)[
'payment_method_id' => '5',
'payment_amount' => '1521.00',
'voucher_or_discount_code' => '1000-2000-3000-4000',
],
],
],
];
$result = $client->UpdateOrder($input);
var_dump($result);
}
catch (\SoapFault $e) {
var_dump($e->getMessage());
}
Request
POST /app/cs/api/ecommerce/soap_2_11/ HTTP/1.1
Host: api.cyclesoftware.nl
Accept-encoding: gzip
Accept: text/xml
Content-type: text/xml; charset=utf-8
User-agent: SoapClient
Soapaction: "UpdateOrder"
Content-length: 846
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://api.cyclesoftware.nl/app/cs/api/ecommerce/soap_2_0/">
<SOAP-ENV:Body>
<ns1:UpdateOrderRequest>
<Authentication>
<username>your-username</username>
<password>your-password</password>
<dealer_id>1</dealer_id>
</Authentication>
<order_id>3623</order_id>
<order_reference_id>
</order_reference_id>
<UpdateValues>
<UpdateValue>
<name>order_date_preferred_delivery</name>
<value>2015-11-09 15:50:35</value>
</UpdateValue>
<UpdateValue>
<name>order_remarks</name>
<value>Will pickup at 13.00</value>
</UpdateValue>
</UpdateValues>
<AddPayments>
<Payment>
<payment_method_id>12</payment_method_id>
<payment_amount>10.00</payment_amount>
<payment_for_customer_id>1000</payment_for_customer_id>
</Payment>
<Payment>
<payment_method_id>12</payment_method_id>
<payment_amount>10.00</payment_amount>
</Payment>
<Payment>
<payment_method_id>5</payment_method_id>
<payment_amount>0.01</payment_amount>
<voucher_or_discount_code>1000-2000-3000-4000</voucher_or_discount_code>
</Payment>
</AddPayments>
</ns1:UpdateOrderRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
HTTP/1.1 200
Content-type: application/xml; charset=utf-8
Content-length: 2446
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://api.cyclesoftware.nl/app/cs/api/ecommerce/soap_2_0/">
<SOAP-ENV:Body>
<ns1:OrderStatusResponse>
<order_id>3623</order_id>
<order_reference_text>563c8b1bc4ada</order_reference_text>
<order_reference_id>-663982782</order_reference_id>
<order_status_text>In behandeling</order_status_text>
<order_track_trace_reference>563c8b1bc4ada</order_track_trace_reference>
<order_date_preferred_delivery>2015-11-09 15:50:35</order_date_preferred_delivery>
<order_vat_country_code/>
<order_sales_employee_id>11111</order_sales_employee_id>
<customer_id>1498</customer_id>
<invoice_id>0</invoice_id>
<OrderResultItems>
<OrderResultItem>
<order_item_status_id>0</order_item_status_id>
<order_item_status_text>Geen status</order_item_status_text>
<order_item_is_bicycle>1</order_item_is_bicycle>
<order_item_barcode>1000</order_item_barcode>
<order_item_quantity>2</order_item_quantity>
<order_item_description>Test product</order_item_description>
<order_item_unit_price_in_vat>10.00</order_item_unit_price_in_vat>
<order_item_unit_discount_amount_in_vat>2.99</order_item_unit_discount_amount_in_vat>
<order_item_vat_code>2</order_item_vat_code>
<order_item_line_id>3</order_item_line_id>
<order_item_object_id/>
<order_item_invoice_customer_id/>
</OrderResultItem>
<OrderResultItem>
<order_item_status_id>0</order_item_status_id>
<order_item_status_text>Geen status</order_item_status_text>
<order_item_is_bicycle>0</order_item_is_bicycle>
<order_item_barcode>1000</order_item_barcode>
<order_item_quantity>2</order_item_quantity>
<order_item_description>Test product</order_item_description>
<order_item_unit_price_in_vat>10.00</order_item_unit_price_in_vat>
<order_item_unit_discount_amount_in_vat>2.99</order_item_unit_discount_amount_in_vat>
<order_item_vat_code>2</order_item_vat_code>
<order_item_line_id>5</order_item_line_id>
<order_item_object_id>0</order_item_object_id>
<order_item_invoice_customer_id>1000</order_item_invoice_customer_id>
</OrderResultItem>
</OrderResultItems>
</ns1:OrderStatusResponse>
</SOAP-ENV:Body>
Create invoice(s)
Create invoice(s) for sales order. If the sales-order is split amongst several customers, the result will yield multiple invoices.
- Scope(s):
e-commerce
POST
/api/v1/sales/orders/:sales_order_id/create-invoices.json
| URL parameter | Type | Description |
|---|---|---|
:sales_order_id |
integer |
Sales order ID required |
Limits
See API limits for more information about API rate limiting.
| Type | Limit | Description |
|---|---|---|
minutely-limit |
15 |
15 requests per minute allowed |
daily-limit |
default |
The default daily limit applies |
The following optional POST parameters can be used to specify specific behavior.
| POST parameter | Type | Default | Description |
|---|---|---|---|
employee_id |
integer |
The sales employee registered for the sales-order | Employee ID for registration |
order_status_id |
integer |
null |
New sales order status. See common endpoint |
book |
boolean |
false |
if true, the invoice will be booked in administration. Otherwise the invoice will be pro-forma |
customer_messages |
boolean |
true |
if true a phone- of e-mail message will be sent (according to account settings) to inform the customer |
allow_resend_messages |
boolean |
false |
if true a phone- of e-mail message will be sent again if there were previous messages |
apply_service_vat_correction |
boolean |
true (after 15-06-2024) |
if true service VAT correction will be applied if active in account settings |
split_items_as_text_on_default_customer_invoice |
boolean |
true (after 15-06-2024) |
if true in case of split order the invoice items will be displayed as text items on default customer invoice |
Properties
| Property | Type | Description |
|---|---|---|
error |
boolean |
true if an error occurred |
error_message |
?string |
Error message if occurred |
invoices |
object[] |
Array of created invoices |
invoices[].invoice_number |
integer |
Invoice number e.g. 20173383 |
invoices[].customer_id |
integer |
Customer number of invoice e.g. 9011 |
invoices[].sent_messages.phone_message |
boolean |
true if a phone message was sent |
invoices[].sent_messages.email_message |
boolean |
true if an e-mail message was sent |
invoices[].documents |
object[] |
Array of generated documents |
invoices[].documents[].document_mime_type |
string |
Mime type of the document e.g. application/pdf |
invoices[].documents[].document_base64 |
string |
Base64 encoded string of document |
HTTP request
POST /api/v1/sales/orders/1000/create-invoices.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
Content-type: application/x-www-form-urlencoded; charset=utf-8
Content-length: 299
employee_id=1005&order_status_id=9&book=1&customer_messages=1&allow_resend_messages=1
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 900
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"error": false,
"error_message": null,
"invoices": [
{
"invoice_number": 20173382,
"customer_id": 6298,
"sent_messages": {
"phone_message": true,
"email_message": false
},
"documents": [
{
"document_mime_type": "application/pdf",
"document_base64": "VBERi0xLjcKJ..."
}
]
},
{
"invoice_number": 20173383,
"customer_id": 9011,
"sent_messages": {
"phone_message": false,
"email_message": false
},
"documents": [
{
"document_mime_type": "application/pdf",
"document_base64": "VBERi0xLjcKJ..."
}
]
}
]
}
AddOrderItems
Add new order items to an existing order.
try {
$client = new \SoapClient(
'https://api.cyclesoftware.nl/app/cs/api/ecommerce/soap_2_11/?wsdl',
[
'trace' => true,
'use' => SOAP_LITERAL,
'encoding' => 'UTF-8',
]
);
$input = (object)[
'Authentication' =>
(object)[
'username' => 'your-username',
'password' => 'your-password',
'dealer_id' => '1', // store-id within account
],
'order_id' => '684476',
'order_reference_id' => '',
'OrderItems' => (object)[
'OrderItem' =>
[
(object)[
'order_item_is_bicycle' => '0',
'order_item_barcode' => '872382382323',
'order_item_quantity' => '2',
'order_item_description' => 'DescriptionTest',
'order_item_unit_price_in_vat' => '12.99',
'order_item_unit_discount_amount_in_vat' => '2.99',
'order_item_invoice_customer_id' => null,
],
(object)[
'order_item_is_bicycle' => '0',
'order_item_barcode' => '4624824934349',
'order_item_quantity' => '2',
'order_item_description' => 'For lease company',
'order_item_unit_price_in_vat' => '12.99',
'order_item_unit_discount_amount_in_vat' => '2.99',
'order_item_vat_code' => '2',
'order_item_invoice_customer_id' => '10003',
],
],
],
];
$result = $client->AddOrderItems($input);
var_dump($result);
}
catch (\SoapFault $e) {
var_dump($e->getMessage());
}
Request
POST /app/cs/api/ecommerce/soap_2_11/ HTTP/1.1
Host: api.cyclesoftware.nl
Accept-encoding: gzip
Accept: text/xml
Content-type: text/xml; charset=utf-8
User-agent: SoapClient
Soapaction: "AddOrderItems"
Content-length: 1373
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://api.cyclesoftware.nl/app/cs/api/ecommerce/soap_2_0/">
<SOAP-ENV:Body>
<ns1:AddOrderItemsRequest>
<Authentication>
<username>your-username</username>
<password>your-password</password>
<dealer_id>1</dealer_id>
</Authentication>
<order_id>3692</order_id>
<order_reference_id>
</order_reference_id>
<OrderItems>
<OrderItem>
<order_item_is_bicycle>0</order_item_is_bicycle>
<order_item_barcode>5640c122a30b9</order_item_barcode>
<order_item_quantity>2</order_item_quantity>
<order_item_description>DescriptionTest</order_item_description>
<order_item_unit_price_in_vat>12.99</order_item_unit_price_in_vat>
<order_item_unit_discount_amount_in_vat>2.99</order_item_unit_discount_amount_in_vat>
<order_item_vat_code>2</order_item_vat_code>
<order_item_supplier_order_mode>0</order_item_supplier_order_mode>
<order_item_supplier_id>0</order_item_supplier_id>
<order_item_object_id>0</order_item_object_id>
<order_item_invoice_customer_id>1000</order_item_invoice_customer_id>
</OrderItem>
</OrderItems>
</ns1:AddOrderItemsRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
HTTP/1.1 200
Content-type: application/xml; charset=utf-8
Content-length: 2464
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://api.cyclesoftware.nl/app/cs/api/ecommerce/soap_2_0/">
<SOAP-ENV:Body>
<ns1:OrderStatusResponse>
<order_id>3692</order_id>
<order_reference_text>5640c122154db</order_reference_text>
<order_reference_id>-319656665</order_reference_id>
<order_status_text>In behandeling</order_status_text>
<order_track_trace_reference>
</order_track_trace_reference>
<order_date_preferred_delivery>2015-12-01 00:00:00</order_date_preferred_delivery>
<order_sales_employee_id>1212</order_sales_employee_id>
<customer_id>1498</customer_id>
<invoice_id>0</invoice_id>
<OrderResultItems>
<OrderResultItem>
<order_item_status_id>0</order_item_status_id>
<order_item_status_text>Geen status</order_item_status_text>
<order_item_is_bicycle>1</order_item_is_bicycle>
<order_item_barcode>1000</order_item_barcode>
<order_item_quantity>2</order_item_quantity>
<order_item_description>Test product</order_item_description>
<order_item_unit_price_in_vat>10.00</order_item_unit_price_in_vat>
<order_item_unit_discount_amount_in_vat>2.99</order_item_unit_discount_amount_in_vat>
<order_item_vat_code>1</order_item_vat_code>
<order_item_line_id>3</order_item_line_id>
<order_item_object_id>0</order_item_object_id>
<order_item_invoice_customer_id/>
</OrderResultItem>
<OrderResultItem>
<order_item_status_id>0</order_item_status_id>
<order_item_status_text>Geen status</order_item_status_text>
<order_item_is_bicycle>0</order_item_is_bicycle>
<order_item_barcode>5640c122a30b9</order_item_barcode>
<order_item_quantity>2</order_item_quantity>
<order_item_description>DescriptionTest</order_item_description>
<order_item_unit_price_in_vat>10.00</order_item_unit_price_in_vat>
<order_item_unit_discount_amount_in_vat>2.99</order_item_unit_discount_amount_in_vat>
<order_item_vat_code>2</order_item_vat_code>
<order_item_line_id>5</order_item_line_id>
<order_item_object_id>0</order_item_object_id>
<order_item_invoice_customer_id>1000</order_item_invoice_customer_id>
</OrderResultItem>
</OrderResultItems>
</ns1:OrderStatusResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
GetInvoiceDocument
Get an invoice document based on the invoice-number.
<?php
try {
$client = new \SoapClient(
'https://api.cyclesoftware.nl/app/cs/api/ecommerce/soap_2_11/?wsdl',
[
'trace' => true,
'use' => SOAP_LITERAL,
'encoding' => 'UTF-8',
]
);
$input = (object)[];
$input->Authentication = (object)[];
$input->Authentication->username = 'your-username';
$input->Authentication->password = 'your-password';
$input->Authentication->dealer_id = '1';
$input->invoice_number = '44848';
$result = $client->GetInvoiceDocument($input);
var_dump($result);
} catch (\SoapFault $e) {
var_dump($e->getMessage());
}
Request
POST /app/cs/api/ecommerce/soap_2_11/ HTTP/1.1
Host: api.cyclesoftware.nl
Accept-encoding: gzip
Accept: text/xml
Content-type: text/xml; charset=utf-8
User-agent: SoapClient
Soapaction: "GetInvoiceDocument"
Content-length: 514
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://api.cyclesoftware.nl/app/cs/api/ecommerce/soap_2_0/">
<SOAP-ENV:Body>
<ns1:GetInvoiceDocumentRequest>
<Authentication>
<username>your-username</username>
<password>your-password</password>
<dealer_id>1</dealer_id>
</Authentication>
<invoice_number>44848</invoice_number>
</ns1:GetInvoiceDocumentRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
HTTP/1.1 200
Content-type: application/xml; charset=utf-8
Content-length: 396
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<GetInvoiceDocumentResponse>
<invoice_number>44848</invoice_number>
<data>data:application/pdf;base64,JVBERi0xLjcKMyAwIG9iago8PC9UeXBlIC9QYWdlIC9QYXJlbnQgMS.....==</data>
</GetInvoiceDocumentResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
GetOrderStatus
Get an invoice document based on the sales order id or order reference.
<?php
try {
$client = new \SoapClient(
'https://api.cyclesoftware.nl/app/cs/api/ecommerce/soap_2_11/?wsdl',
[
'trace' => true,
'use' => SOAP_LITERAL,
'encoding' => 'UTF-8',
]
);
$input = (object)[];
$input->Authentication = (object)[];
$input->Authentication->username = 'your-username';
$input->Authentication->password = 'your-password';
$input->Authentication->dealer_id = '1';
$input->order_id = '44848';
$input->order_reference_id = '61a0d79989fa3';//optional
$result = $client->GetOrderStatus($input);
var_dump($result);
} catch (\SoapFault $e) {
var_dump($e->getMessage());
}
Request
POST /app/cs/api/ecommerce/soap_2_11/ HTTP/1.1
Host: api.cyclesoftware.nl
Accept-encoding: gzip
Accept: text/xml
Content-type: text/xml; charset=utf-8
User-agent: SoapClient
Soapaction: "GetOrderStatus"
Content-length: 580
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://api.cyclesoftware.nl/app/cs/api/ecommerce/soap_2_0/">
<SOAP-ENV:Body>
<ns1:GetInvoiceDocumentRequest>
<Authentication>
<username>your-username</username>
<password>your-password</password>
<dealer_id>1</dealer_id>
</Authentication>
<order_id>711075</order_id>
<order_reference_id>61a0d79989fa3</order_reference_id>
</ns1:GetInvoiceDocumentRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
HTTP/1.1 200
Content-type: application/xml; charset=utf-8
Content-length: 2595
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns1="http://api.cyclesoftware.nl/app/cs/api/ecommerce/soap_2_0/">
<SOAP-ENV:Body>
<ns1:OrderStatusResponse>
<order_id>711075</order_id>
<order_reference_text>61a0d79989fa3</order_reference_text>
<order_reference_id>1637930905565</order_reference_id>
<order_status_text>In behandeling</order_status_text>
<order_track_trace_reference/>
<order_date_preferred_delivery>2020-12-01 00:00:00</order_date_preferred_delivery>
<order_vat_country_code>BE</order_vat_country_code>
<customer_id>11</customer_id>
<invoice_id>0</invoice_id>
<order_sales_employee_id>10369</order_sales_employee_id>
<OrderResultItems>
<OrderResultItem>
<order_item_is_bicycle>0</order_item_is_bicycle>
<order_item_object_id xsi:nil="true"/>
<order_item_barcode>$barcode</order_item_barcode>
<order_item_quantity>-1</order_item_quantity>
<order_item_description>SomeBatavus</order_item_description>
<order_item_unit_price_in_vat>1021.00</order_item_unit_price_in_vat>
<order_item_unit_discount_amount_in_vat>21.00</order_item_unit_discount_amount_in_vat>
<order_item_vat_code>2</order_item_vat_code>
<order_item_status_id>0</order_item_status_id>
<order_item_status_text>Geen status</order_item_status_text>
<order_item_line_id>1</order_item_line_id>
<order_item_invoice_customer_id>4</order_item_invoice_customer_id>
</OrderResultItem>
<OrderResultItem>
<order_item_is_bicycle>0</order_item_is_bicycle>
<order_item_object_id xsi:nil="true"/>
<order_item_barcode>$barcode</order_item_barcode>
<order_item_quantity>1</order_item_quantity>
<order_item_description>SomeBatavus</order_item_description>
<order_item_unit_price_in_vat>1521.00</order_item_unit_price_in_vat>
<order_item_unit_discount_amount_in_vat>21.00</order_item_unit_discount_amount_in_vat>
<order_item_vat_code>2</order_item_vat_code>
<order_item_status_id>0</order_item_status_id>
<order_item_status_text>Geen status</order_item_status_text>
<order_item_line_id>2</order_item_line_id>
<order_item_invoice_customer_id>2</order_item_invoice_customer_id>
</OrderResultItem>
</ns1:OrderStatusResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
CreateOrUpdateCustomer
This method creates or updates an existing customer. Existing customers are matched on customer_id, customer_phone
, customer_mobile, customer_reference or customer_email.
<?php
try {
$client = new \SoapClient(
'https://api.cyclesoftware.nl/app/cs/api/ecommerce/soap_2_11/?wsdl',
[
'trace' => true,
'use' => SOAP_LITERAL,
'encoding' => 'UTF-8',
]
);
$input = (object) array(
'Authentication' => (object) array(
'username' => 'your-username',
'password' => 'your-password',
'dealer_id' => '1', // store-id within account
),
'customer_type_name' => '',
'Customer' => (object)array(
'customer_id' => 46,
'customer_cs_customer_id' => 235238848,
'customer_reference' => 'unique-reference-customer',
'customer_name_prefix' => 'Dhr.',
'customer_name_initials' => 'A',
'customer_first_name' => 'Adri',
'customer_middle_name' => 'Van',
'customer_last_name' => 'Name 235238848',
'customer_postal_code' => '8448PE',
'customer_housenumber' => '32',
'customer_housenumber_suffix' => 'B',
'customer_street_name' => 'Mauritslaan',
'customer_city' => 'Heerenveen',
'customer_phone' => '073-3030050',
'customer_mobile' => '06-24238848',
'customer_country_code_iso_3166' => 'NL',
'customer_email' => 'test235238848@cyclesoftware.nl',
'customer_newsletter' => '0',
'customer_date_of_birth' => NULL,
'customer_iban' => 'NL69INGB0123456789',
'DeliveryAddress' => NULL,
)
);
$result = $client->CreateOrUpdateCustomer($input);
var_dump($result);
} catch (\SoapFault $e) {
var_dump($e->getMessage());
}
Request
POST /app/cs/api/ecommerce/soap_2_11/ HTTP/1.1
Host: api.cyclesoftware.nl
Accept-encoding: gzip
Accept: text/xml
Content-type: text/xml; charset=utf-8
User-agent: SoapClient
Soapaction: "CreateOrderUpdateCustomer"
Content-length: 1648
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="http://api.cyclesoftware.nl/app/cs/api/ecommerce/soap_2_0/">
<SOAP-ENV:Body>
<ns1:CreateOrUpdateCustomerRequest>
<Authentication>
<username>your-username</username>
<password>your-password</password>
<dealer_id>1</dealer_id>
</Authentication>
<Customer>
<customer_type_name>Lease-maatschappij</customer_type_name>
<customer_cs_customer_id>235238848</customer_cs_customer_id>
<customer_reference>unique-reference-customer</customer_reference>
<customer_name_prefix>Dhr.</customer_name_prefix>
<customer_first_name>Adri</customer_first_name>
<customer_name_initials>A</customer_name_initials>
<customer_middle_name>Van</customer_middle_name>
<customer_last_name>Name 235238848</customer_last_name>
<customer_postal_code>8448PE</customer_postal_code>
<customer_housenumber>32</customer_housenumber>
<customer_housenumber_suffix>B</customer_housenumber_suffix>
<customer_street_name>Mauritslaan</customer_street_name>
<customer_city>Heerenveen</customer_city>
<customer_phone>073-1234567</customer_phone>
<customer_mobile>06-124235335</customer_mobile>
<customer_country_code_iso_3166>NL</customer_country_code_iso_3166>
<customer_email>test235238848@cyclesoftware.nl</customer_email>
<customer_newsletter>0</customer_newsletter>
<customer_date_of_birth/>
<customer_iban>NL69INGB0123456789</customer_iban>
</Customer>
</ns1:CreateOrUpdateCustomerRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
HTTP/1.1 200
Content-type: application/xml; charset=utf-8
Content-length: 1448
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="http://api.cyclesoftware.nl/app/cs/api/ecommerce/soap_2_0/">
<SOAP-ENV:Body>
<ns1:CreateOrUpdateCustomerResponse>
<is_new_customer>false</is_new_customer>
<Customer>
<customer_cs_customer_id>235238848</customer_cs_customer_id>
<customer_reference>REF46</customer_reference>
<customer_name_prefix>Dhr.</customer_name_prefix>
<customer_first_name>Adri</customer_first_name>
<customer_name_initials>A</customer_name_initials>
<customer_middle_name>Van</customer_middle_name>
<customer_last_name>Name 235238848</customer_last_name>
<customer_postal_code>8448PE</customer_postal_code>
<customer_housenumber>32</customer_housenumber>
<customer_housenumber_suffix>B</customer_housenumber_suffix>
<customer_street_name>Mauritslaan</customer_street_name>
<customer_city>Heerenveen</customer_city>
<customer_phone></customer_phone>
<customer_mobile>0733030050</customer_mobile>
<customer_country_code_iso_3166>NL</customer_country_code_iso_3166>
<customer_email>test235238848@cyclesoftware.nl</customer_email>
<customer_newsletter>0</customer_newsletter>
<customer_date_of_birth/>
<customer_iban></customer_iban>
</Customer>
</ns1:CreateOrUpdateCustomerResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Labels
Attach or detach labels on entities
Authentication mechanism
- Basic HTTP Authentication
- Scope(s):
e-commerce,common,warehouse
Label properties
Properties used in create, get and send endpoints.
| Property | Type | Description |
|---|---|---|
error |
boolean |
true if an error occured |
error_message |
?string |
Error message, null if no error occured |
entity_type_id |
integer |
Entity type e.g. 7, see common API entity_types |
entity_id |
integer |
Entity ID e.g. sales order number when entity_type_id is 7 |
labels |
string[] |
Array of labels in CS e.g. ["Label"] |
Get entity labels
Get the labels currently attached to the entity
GET
/api/v1/labels/:entity_type_id/:entity_id/get.json
HTTP request
POST /api/v1/labels/7/51208/get.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 158
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"error": false,
"error_message": null,
"entity_type_id": 7,
"entity_id": 51208,
"labels": [
"Label 1",
"Label 2"
]
}
HTTP Error Response
HTTP/1.1 400
Content-type: application/json; charset=utf-8
Content-length: 57
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"error": true,
"error_message": "Bad request"
}
Attach labels
Attach labels to an entity
POST
/api/v1/labels/:entity_type_id/:entity_id/attach.json
HTTP request
POST /api/v1/labels/7/51208/attach.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
Content-length: 27
Content-type: application/json; charset=utf-8
["Label new", "Label new2"]
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 989
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"error": false,
"error_message": null,
"entity_type_id": 7,
"entity_id": 51208,
"labels": [
"Label 1",
"Label 2",
"Label new",
"Label new2"
]
}
Detach labels
Detach labels from an entity
POST
/api/v1/labels/:entity_type_id/:entity_id/detach.json
HTTP request
POST /api/v1/labels/7/51208/detach.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
Content-type: application/json; charset=utf-8
["Label 1", "Label new2"]
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 160
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"error": false,
"error_message": null,
"entity_type_id": 7,
"entity_id": 51208,
"labels": [
"Label 2",
"Label new"
]
}
Leads
Create, read and cancel sales leads
Authentication mechanism
- Basic HTTP Authentication
- Scope(s):
resources
Properties
| Field | Type | Description | Example value |
|---|---|---|---|
error |
boolean |
true if an error occurred | false |
error_message |
?string |
Empty if no error | |
sales_lead.uuid |
string |
Unique identifier of the lead (null on creation) | 0c6b40a4-a217-11e8-92bb-005056a46320 |
sales_lead.store_id |
string |
The store identification format of [account]-[store] | 1000-2 |
sales_lead.type |
string |
Type of the lead (see type list) | information |
sales_lead.status |
string |
Status of the lead (see status list) | open |
sales_lead.title |
string |
Short title of lead description | Kieskeurig: proefrit Batavus Crescendo |
sales_lead.message |
string |
Message to the dealer about the lead | Een potientiele klant wil een proefrit maken |
sales_lead.costs_ex_vat_cents |
integer |
The costs that the platform charges to the dealer on acceptance of the lead, not relevant for resources scope |
1500 |
sales_lead.options.test_ride_requested |
boolean |
provide true if a test-ride is requested | false |
sales_lead.options.phone_call_requested |
boolean |
provide true if the dealer should call the customer | false |
sales_lead.options.finance_information_requested |
boolean |
provide true if the dealer should provide financial information | false |
sales_lead.options.insurance_information_requested |
boolean |
provide true if the dealer should provide insurance information | false |
sales_lead.object.description |
string |
Description of the object | Batavus Crescendo |
sales_lead.object.object_id |
integer |
Object id in stock dealer (can be retrieved in stock locator api) | 12212 |
sales_lead.object.article_number |
string |
Article number of the object | ART1 |
sales_lead.object.barcode |
string |
EAN barcode of the object | 877474749349 |
sales_lead.exchange_object.exchange_description |
string |
Description of the exchange object | |
sales_lead.exchange_object.exchange_remarks |
string |
Remarks about the exchange object | |
sales_lead.customer.customer_address_id |
?integer |
ID of the customer address (null on creation) | 91953 |
sales_lead.customer.address_type |
string |
lead null on creation | lead |
sales_lead.customer.customer_id |
integer |
Customer ID if address is linked to a customer null on creation) | 235240102 |
sales_lead.customer.is_business_address |
boolean |
true if address is for a company | false |
sales_lead.customer.company_name |
string |
The company name | |
sales_lead.customer.name |
string |
Name of the customer | Name 91953 |
sales_lead.customer.street |
string |
Street of the address | Slangenburg |
sales_lead.customer.house_number |
string |
Housenumber | 314 |
sales_lead.customer.house_number_postfix |
string |
Housenumber suffix | B |
sales_lead.customer.postal_code |
string |
Postalcode | 7423ZR |
sales_lead.customer.city |
string |
City | Deventer |
sales_lead.customer.country_code |
string |
Country code (ISO 3166) | NL |
sales_lead.customer.phone_number |
string |
Phonenumber | 06 38668303 |
sales_lead.customer.email |
string |
E-mail address | email91953@example.nl |
sales_lead.customer.notes |
string |
Extra information about the customer address | |
sales_lead.created_at |
datetime |
When the lead was created (null on creation) | 2020-04-14T06:33:26+02:00 |
sales_lead.modified_at |
datetime |
When the lead was last modified (null on creation) | 2020-04-14T06:33:26+02:00 |
Sales lead types
Possible values for sales_lead.type
| Field | Description |
|---|---|
information |
The customer would like to receive information |
sales_offer |
The customer would like to buy the object |
test_ride |
The customer would like to make a test-ride |
contact_request |
The customer would like to be contacted |
exchange |
The customer would like to exchange an object |
complaint |
The customer has a complaint |
other |
- |
Sales lead status
Possible values for sales_lead.status
| Field | Description |
|---|---|
open |
The dealer did not take any action on the lead |
noticed |
The dealer has noticed the lead but did not accept or decline it |
accepted |
The dealer has accepted the lead |
declined |
The dealer has declined the lead |
succeeded |
The dealer has successfully converted the lead |
failed |
The dealer has not coverted the lead |
cancelled |
The lead was cancelled |
Create lead
Get a list of stores
POST
/api/v1/leads/create.json
HTTP request
POST /api/v1/leads/create.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
Content-type: application/json; charset=utf-8
{
"store_id": "1-1",
"type": "test_ride",
"status": "open",
"title": "Kieskeurig: proefrit Batavus Crescendo",
"message": "NaamKlant wil een proefrit maken",
"options": {
"test_ride_requested": true,
"phone_call_requested": true,
"finance_information_requested": false,
"insurance_information_requested": false
},
"object": {
"description": "Batavus Crescendo",
"object_id": 11212,
"article_number": null,
"barcode": "877474749349"
},
"exchange_object": {
"exchange_description": null,
"exchange_remarks": null
},
"customer": {
"customer_address_id": null,
"address_type": "lead",
"customer_id": null,
"is_business_address": false,
"company_name": "",
"name": "NaamKlant",
"street": "Hoofdstraat",
"house_number": "10",
"house_number_postfix": "B",
"postal_code": "5238HL",
"city": "Berlicum",
"country_code": "NL",
"phone_number": "0612345678",
"email": "voorbeeld@host.nl",
"notes": "Bellen tussen 12.00-17.00"
}
}
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 1357
{
"error": false,
"error_message": null,
"sales_lead": {
"uuid": "0c6b40a4-a217-11e8-92bb-005056a46320",
"store_id": "1-1",
"type": "information",
"status": "open",
"title": "Kieskeurig: proefrit",
"message": "Een potientiele klant wil een proefrit maken",
"costs_ex_vat_cents": 0,
"options": {
"test_ride_requested": false,
"phone_call_requested": false,
"finance_information_requested": false,
"insurance_information_requested": false
},
"object": {
"description": "Batavus Crescendo",
"object_id": 12212,
"article_number": "ART1",
"barcode": "877474749349"
},
"exchange_object": {
"exchange_description": "",
"exchange_remarks": ""
},
"customer": {
"customer_address_id": 91953,
"address_type": "delivery_address",
"customer_id": 235240102,
"is_business_address": false,
"company_name": "",
"name": "Name 91953",
"street": "Slangenburg",
"house_number": "314",
"house_number_postfix": "",
"postal_code": "7423ZR",
"city": "Deventer",
"country_code": "NL",
"phone_number": "06 38668303",
"email": "email91953@example.nl",
"notes": ""
},
"created_at": "2020-04-14T06:33:26+02:00",
"modified_at": "2020-04-14T06:33:26+02:00"
}
}
Get lead
GET
/api/v1/leads/:uuid.json
| URI parameter | Type | Description |
|---|---|---|
uuid |
uuid |
The UUID of the lead e.g. 0c6b40a4-a217-11e8-92bb-005056a46320 |
HTTP request
GET /api/v1/leads/0c6b40a4-a217-11e8-92bb-005056a46320.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
Content-type: application/json; charset=utf-8
Content-length: 65
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 1357
{
"error": false,
"error_message": null,
"sales_lead": {
"uuid": "0c6b40a4-a217-11e8-92bb-005056a46320",
"store_id": "1-1",
"type": "information",
"status": "open",
"title": "Kieskeurig: proefrit",
"message": "Een potientiele klant wil een proefrit maken",
"costs_ex_vat_cents": 0,
"options": {
"test_ride_requested": false,
"phone_call_requested": false,
"finance_information_requested": false,
"insurance_information_requested": false
},
"object": {
"description": "Batavus Crescendo",
"object_id": 12212,
"article_number": "ART1",
"barcode": "877474749349"
},
"exchange_object": {
"exchange_description": "",
"exchange_remarks": ""
},
"customer": {
"customer_address_id": 91953,
"address_type": "delivery_address",
"customer_id": 235240102,
"is_business_address": false,
"company_name": "",
"name": "Name 91953",
"street": "Slangenburg",
"house_number": "314",
"house_number_postfix": "",
"postal_code": "7423ZR",
"city": "Deventer",
"country_code": "NL",
"phone_number": "06 38668303",
"email": "email91953@example.nl",
"notes": ""
},
"created_at": "2020-04-14T06:33:26+02:00",
"modified_at": "2020-04-14T06:33:26+02:00"
}
}
Cancel lead
POST
/api/v1/leads/:uuid/cancel.json
| URI parameter | Type | Description |
|---|---|---|
uuid |
uuid |
The UUID of the lead e.g. 0c6b40a4-a217-11e8-92bb-005056a46320 |
HTTP request
POST /api/v1/leads/0c6b40a4-a217-11e8-92bb-005056a46320/cancel.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
Content-type: application/json; charset=utf-8
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 45
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"error": false,
"error_message": null
}
Payments
Access payment portal links
Authentication mechanism
- Basic HTTP Authentication
- Scopes:
e-commerce
Payment links
GET
/api/v1/payments/order/:id/payment-link.json
GET
/api/v1/payments/invoice/:id/payment-link.json
| URI parameter | Type | Description |
|---|---|---|
id |
integer |
Sales order ID or the invoice / sales transaction number |
| GET parameter | Type | Description |
|---|---|---|
payment_amount_cents |
integer |
The payment amount in cents. Only applicable for advance order payments endpoint |
dynamic_payment_amount |
bool |
true if the amount in the payment link should depend dynamically on unpayed amount of the order. If a payment_amount_cents this option will be ignored |
dynamic_payment_amount |
bool |
true if the amount in the payment link should depend dynamically on unpayed amount of the order. If a payment_amount_cents this option will be ignored |
payment_for_customer_id |
integer |
If the the order is a split order, you can provide the customer_id for this payment |
| Property | Type | Description |
|---|---|---|
error |
boolean |
true if an error occurred |
error_message |
?string |
The error message if an error occurred |
data.sales_order_id |
?integer |
The sales order ID 1000 |
data.customer_id |
?integer |
The customer ID who makes the payment 10006 |
data.sales_transaction_number |
?integer |
The sales transaction number (invoice number) |
data.payment_url |
string |
Payment portal URL https://twsc.nl/p/xM4iatg |
data.total_amount_cents |
integer |
Total amount in cents of the order or invoice 100000 |
data.already_payed_cents |
integer |
The amount already payed in cents e.g. 50000 |
data.payment_link_amount_cents |
integer |
The payment amount in the portal e.g. 25000 |
data.dynamic_payment_amount |
bool |
true if the amount to be payed is dynamic and depends on unpayed amount of the order or invoice |
data.qr_code |
string |
The QR code of the payment portal url as data uri data:image/png;base64,iVBORw0KGgoAAAANSUhEU.... |
HTTP request
GET /api/v1/payments/order/1012/payment-link.json?payment_amount_cents=10000 HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 425
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"error": false,
"error_message": null,
"data": {
"sales_order_id": 1012,
"customer_id": 10006,
"sales_transaction_number": null,
"payment_url": "https://twsc.nl/p/xM4iatg",
"total_amount_cents": 250000,
"already_payed_cents": 10000,
"payment_link_amount_cents": 10000,
"dynamic_payment_amount": false,
"qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEU...."
}
}
Rental
Access rental object data
Authentication mechanism
- Basic HTTP Authentication
- Scope(s):
rental
Rental objects
Get a list of objects available for rental fleet.
GET
/api/v1/rental/objects.json
HTTP request
GET /api/v1/rental/objects.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
Content-type: application/json; charset=utf-8
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 1530
[
{
"code": "F1-20297",
"account_id": 1,
"article_id": "HT150507",
"barcode": "8713568237697",
"store_id": 1,
"stock_object_id": 20297,
"is_elo": false,
"is_moped": false,
"category_name": "Stadsfietsen",
"dst_main_id": 1,
"dst_sub_id": "A",
"dst_sub_sub_id": 0,
"is_reserved": false,
"is_demo": false,
"is_rental": false,
"brand_name": "Batavus",
"frame_type": "Heren",
"brakes_or_transmission": "",
"name_brakes": "",
"object_barcode": "sdgfhdskfvgsil",
"model_name": "BLOCKBUSTER",
"color": "Zwart mat",
"gears": "7",
"year_description": "2015",
"size": "",
"frame_height": "50",
"wheel_size": "28",
"frame_size_supplier": "",
"tyre_size": "",
"customer_group": "Heren",
"material_description": "Aluminium",
"basic_color": "Zwart",
"basic_color_secondary": "",
"frame_number": "",
"chip_number": "",
"lock_number": "",
"key_number": "",
"license_plate_number": "licence_plate",
"engine_number": "",
"battery_number": "",
"images": [
{
"date_modified": "2021-01-01T12:00:99",
"url_thumb": "https://s01.cyclesoftare.nl/link-to-thumb-image.jpg",
"url_large": "https://s01.cyclesoftare.nl/link-to-image.jpg"
}
]
}
]
Repair objects
Read, create or update repair objects for a customer
Scope(s)
resources
Repair object (object)
| Property | Type | Modify | Description |
|---|---|---|---|
customer_id |
integer |
readonly |
Customer ID of owner e.g. 6 |
object_id |
integer |
readonly |
ID of the object e.g. 208410 |
object_barcode |
string |
PUT|POST |
e.g. object_barcode |
is_active |
boolean |
PUT|POST |
Whether this object is still owned by customer e.g. true |
object_type_name |
string |
PUT|POST |
e.g. fiets |
category |
string |
PUT|POST |
Category name e.g. Racefietsen |
brand |
string |
PUT|POST |
Brand name e.g. BrandName |
model |
string |
PUT|POST |
Model name e.g. ModelName |
model_year |
string |
PUT|POST |
Model year e.g. 2017 |
color |
string |
PUT|POST |
Color of object e.g. Black |
variant |
string |
PUT|POST |
Variant name e.g. Heren |
phone_number_id |
string |
PUT|POST |
Phone number ID for communication e.g. 12345 |
license_plate |
string |
PUT|POST |
License plate number e.g. xx-zz-yy |
km_mileage |
string |
PUT|POST |
Kilometer age e.g. 200 |
frame_id |
string |
PUT|POST |
Frame number e.g. frame_id |
chip_id |
string |
PUT|POST |
Chip number e.g. chip_id |
key_id |
string |
PUT|POST |
Key number e.g. key_id |
engine_id |
string |
PUT|POST |
Engine number e.g. engine_id |
battery_id |
string |
PUT|POST |
Battery number e.g. 1234 |
lock_id |
string |
PUT|POST |
Lock number e.g. 1234 |
workshop_rate_id |
integer |
PUT|POST |
See common API workshop_rates e.g. 1 |
service_level_id |
integer |
PUT|POST |
Service level ID e.g. 0 |
images |
object[] |
readonly |
Array of images |
images[].date_modified |
datetime|null |
readonly |
Modification date e.g. 2016-05-24 11:15:02 |
images[].url_thumb |
string |
readonly |
URL to thumbnail e.g. https://s01.cyclesoftware.nl/app/img/artPic_public_T_1317089.jpg |
images[].url_large |
string |
readonly |
URL to large image e.g. https://s01.cyclesoftware.nl/app/img/artPic_public_L_1317089.jpg |
List repair objects
Get a list of repair objects for a customer
GET
/api/v1/customers/:customer_id/objects.json
| URI parameter | Type | Description |
|---|---|---|
customer_id |
int |
Customer ID to get objects for e.g. 1006 |
This endpoint will return a list of Repair object (object).
HTTP request
GET /api/v1/customers/1006/objects.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 1676
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
[
{
"customer_id": 1006,
"object_id": 1004,
"object_barcode": "",
"is_active": true,
"object_type_name": "fiets",
"category": "Hybride fietsen",
"brand": "Batavus",
"model": "Apache Deluxe",
"model_year": "",
"color": "Scumzilver",
"variant": "Dames",
"phone_number_id": "mob",
"license_plate": "",
"km_mileage": "0",
"frame_id": "",
"chip_id": "",
"key_id": "",
"engine_id": "",
"battery_id": "",
"lock_id": "",
"workshop_rate_id": 1,
"service_level_id": 0,
"images": [
{
"date_modified": "2016-05-24 11:15:02",
"url_thumb": "https://s01.cyclesoftware.nl/app/img/artPic_public_T_1317089.jpg",
"url_large": "https://s01.cyclesoftware.nl/app/img/artPic_public_L_1317089.jpg"
}
]
},
{
"customer_id": 1006,
"object_id": 208410,
"object_barcode": "object_barcode",
"is_active": true,
"object_type_name": "fiets",
"category": "Racefietsen",
"brand": "brand",
"model": "model",
"model_year": "2017",
"color": "color",
"variant": "Heren",
"phone_number_id": "12345",
"license_plate": "license_plate",
"km_mileage": "200",
"frame_id": "frame_id",
"chip_id": "chip_id",
"key_id": "key_id",
"engine_id": "engine_id",
"battery_id": "1234",
"lock_id": "lock_id",
"workshop_rate_id": 1,
"service_level_id": 0,
"images": []
}
]
Get repair object
Get a repair object
GET
/api/v1/customers/:customer_id/objects/:object_id.json
| URI parameter | Type | Description |
|---|---|---|
customer_id |
int |
Customer ID e.g. 1006 |
object_id |
int |
Repair object ID e.g. 1004 |
See Repair object (object) for the response definition
HTTP request
GET /api/v1/customers/1006/objects/1004.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic
Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
Content-type: application/json; charset=utf-8
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 827
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"customer_id": 1006,
"object_id": 1004,
"object_barcode": "",
"is_active": true,
"object_type_name": "fiets",
"category": "Hybride fietsen",
"brand": "Batavus",
"model": "Apache Deluxe",
"model_year": "",
"color": "Scumzilver",
"variant": "Dames",
"phone_number_id": "mob",
"license_plate": "",
"km_mileage": "0",
"frame_id": "",
"chip_id": "",
"key_id": "",
"engine_id": "",
"battery_id": "",
"lock_id": "",
"workshop_rate_id": 1,
"service_level_id": 0,
"images": [
{
"date_modified": "2016-05-24 11:15:02",
"url_thumb": "https://s01.cyclesoftware.nl/app/img/artPic_public_T_1317089.jpg",
"url_large": "https://s01.cyclesoftware.nl/app/img/artPic_public_L_1317089.jpg"
}
]
}
Create repair object
Create a repair object for a customer
POST
/api/v1/customers/:customer_id/objects.json
| URI parameter | Type | Description |
|---|---|---|
customer_id |
int |
Customer ID e.g. 24 |
See Repair object (object) for the request and response definition
HTTP request
POST /api/v1/customers/24/objects.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic
Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
Content-type: application/json; charset=utf-8
Content-length: 620
{
"object_id": 208694,
"object_barcode": "object_barcode",
"is_active": true,
"object_type_name": "fiets",
"category": "Racefietsen",
"brand": "brand",
"model": "model",
"model_year": "2017",
"color": "color",
"variant": "Heren",
"phone_number_id": "12345",
"license_plate": "license_plate",
"km_mileage": "200",
"frame_id": "frame_id",
"chip_id": "chip_id",
"key_id": "key_id",
"engine_id": "engine_id",
"battery_id": "1234",
"lock_id": "lock_id",
"workshop_rate_id": 1,
"service_level_id": 0
}
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 620
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"customer_id": 24,
"object_id": 208694,
"object_barcode": "object_barcode",
"is_active": true,
"object_type_name": "fiets",
"category": "Racefietsen",
"brand": "brand",
"model": "model",
"model_year": "2017",
"color": "color",
"variant": "Heren",
"phone_number_id": "12345",
"license_plate": "license_plate",
"km_mileage": "200",
"frame_id": "frame_id",
"chip_id": "chip_id",
"key_id": "key_id",
"engine_id": "engine_id",
"battery_id": "1234",
"lock_id": "lock_id",
"workshop_rate_id": 1,
"service_level_id": 0,
"images": []
}
Update repair object
Update a repair object
PUT
/api/v1/customers/:customer_id/objects/:object_id.json
| URI parameter | Type | Description |
|---|---|---|
customer_id |
int |
Customer ID e.g. 1900 |
object_id |
int |
Repair Object ID e.g. 152614 |
See Repair object (object) for the request and response definition
HTTP request
PUT /api/v1/customers/1900/objects/152614.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
Content-type: application/json; charset=utf-8
Content-length: 853
{
"object_barcode": "barcode_object",
"is_active": true,
"category": "Mountainbikes",
"brand": "Cube",
"model": "6407189221756",
"model_year": "2023",
"color": "Carbon´n´blue",
"variant": "Dames",
"phone_number_id": "mob"
}
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 853
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"customer_id": 1900,
"object_id": 152614,
"object_barcode": "barcode_object",
"is_active": true,
"object_type_name": "fiets",
"category": "Mountainbikes",
"brand": "Cube",
"model": "6407189221756",
"model_year": "2023",
"color": "Carbon´n´blue",
"variant": "Dames",
"phone_number_id": "mob",
"license_plate": "",
"km_mileage": "0",
"frame_id": "",
"chip_id": "",
"key_id": "",
"engine_id": "",
"battery_id": "",
"lock_id": "",
"workshop_rate_id": 1,
"service_level_id": 1,
"images": [
{
"date_modified": "2014-12-19 08:35:58",
"url_thumb": "https://s01.cyclesoftware.nl/app/img/artPic_public_T_1215427.jpg",
"url_large": "https://s01.cyclesoftware.nl/app/img/artPic_public_L_1215427.jpg"
}
]
}
Sales data
Access sales data
Authentication mechanism
- Basic HTTP Authentication
- Scopes:
sales-export
Sales transactions - V1
This API endpoint is deprecated, please use V2.
Get sales transactions within interval of specified date field (max 31 days). By default the book-date is used.
GET
/app/api/salesdata/json/:start_date/:end_date/
GET
/app/api/salesdata/json/:start_date/:end_date/?date_field=datetime_modified
| URI parameter | Type | Description |
|---|---|---|
start_date |
date |
end date e.g. 2020-01-01 |
end_date |
date |
end date e.g. 2020-01-01 |
| GET parameter | Type | Description |
|---|---|---|
date_field |
string |
kassadatum (default) interval as booked datedatetime_modified interval as modification datesfactuurdatum interval as invoice proforma date |
Sales transactions - V2
Get sales transactions and related data such as customers, article and object data. By default the book-date is used.
This endpoint is currently in BETA test phase and will replace the v1 version. Properties may change throughout the beta-phase.
GET
/api/v2/salesdata/transactions.json?date_field=:date_field&date_start=:date_start&date_end=:date_end&only_booked_transactions=:only_booked_transactions&store_id=:store_id&dealer_ids=:dealer_ids
GET
/api/v2/salesdata/transactions.json?token=:pagination_token
| GET parameter | Type | Description |
|---|---|---|
date_field |
?string |
Type of date field book_date,modified_at, transaction_date, defaults to book_date |
date_start |
?date |
Start date of interval for date_field e.g. 2024-01-01 |
date_end |
?date |
End date of interval for date_field e.g. 2024-01-01 |
only_booked_transactions |
?bool |
If true only final / booked transactions will be given |
store_id |
?int |
Store ID for filtering |
dealer_ids |
?string |
CSV of dealer_ids (only applicable for warehouse accounts), dealer_ids are converted to account to get all data from that account |
token |
?string |
The token of next result set in pagination. In pagination.next_url the full URL for next result set if given if available |
Properties
| Property | Type | Description |
|---|---|---|
data |
object[] |
Array with data objects |
data[].account_id |
integer |
Account ID within CycleSoftware e.g. 1 |
data[].store_id |
integer |
Store ID within account e.g. 1 |
data[].sales_transaction_number |
integer |
Sales transaction number / invoice number e.g. 233233 |
data[].type_name |
string |
Type name of transaction e.g. normaal |
data[].is_final |
boolean |
true when the transaction is booked |
data[].book_location_id |
?integer |
Book location ID e.g. 1 |
data[].transaction_date |
date |
Transaction date e.g. 2009-08-17 |
data[].created_at |
datetime |
Creation date-time e.g. 2009-08-17 00:00:00 |
data[].modified_at |
datetime |
Modified date-time e.g. 2016-06-27 09:12:39 |
data[].booked_at |
?datetime |
Book date time e.g. 2009-08-17 15:24:00 |
data[].vat_number |
?string |
VAT-number of customer |
data[].vat_country_code |
?string |
VAT country code if VAT from other country is applied |
data[].total_amount_cents |
integer |
Total amount in cents of the transaction e.g. 99900 |
data[].unpayed_amount_cents |
integer |
Total amount that is unpayed e.g. 5000 |
data[].sales_employee_name |
string |
Employee name of sales person e.g. John |
data[].sales_employee_id |
integer |
Employee ID of sales person e.g. 3 |
data[].booked_by_employee_name |
string |
Employee name who booked the transaction e.g. John |
data[].booked_by_employee_id |
integer |
Employee ID who booked the transaction e.g. 3 |
data[].last_update_by_employee_name |
string |
Employee name who last updated the transaction e.g. John |
data[].last_update_by_employee_id |
integer |
Employee ID who last updated the transaction e.g. 3 |
data[].customer_phone_number_id |
?string |
Preferred phone number ID of customer for communication e.g. mob |
data[].customer |
?object |
Object with customer details if known null otherwise. See Customer (object) |
data[].debit_sales_transaction_number |
?integer |
If transaction is a credit this is referring to the debit transaction e.g. 1199 |
data[].credit_sales_transaction_number |
?integer |
If transaction has a credit this is referring to the credit transaction e.g. 1199 |
data[].sales_order |
?object |
Object with information about the sales order |
data[].sales_order.delivery_method_id |
integer |
Delivery method ID e.g. 0 (see common enum delivery_methods) |
data[].sales_order.reference_id |
string |
Reference ID of the sales order |
data[].sales_order.reference_text |
string |
Reference text of the sales order |
data[].sales_order.sales_order_id |
integer |
Sales order ID 48143 |
data[].sales_order.sales_order_status_id |
integer |
Sales order status ID e.g. 9 (see common enum sales_order_status) |
data[].sales_order.sales_order_type_id |
integer |
Sales order type ID e.g. 6 (see common enum sales_order_types) |
data[].sales_order.track_trace_reference |
string |
Track and trace reference |
data[].workshop_order |
?object |
Workshop / repair related information |
data[].workshop_order.workshop_order_id |
integer |
Workshop order ID e.g. 40573 |
data[].workshop_order.repair_object_id |
integer |
Repair object ID e.g. 425 |
data[].workshop_order.workshop_order_type_id |
integer |
Workshop type ID e.g. 1 (see common enum workshop_order_types) |
data[].workshop_order.workshop_order_status_id |
integer |
Workshop status ID e.g. 8 (see common enum workshop_order_status) |
data[].workshop_order.workshop_rate_id |
integer |
Workshop rate ID e.g. 1 (see common enum workshop_rates) |
data[].workshop_order.mechanic_employee_id |
?integer |
Workshop mechanic ID e.g. 1 (see employees endpoint) if available |
data[].workshop_order.mechanic_employee_name |
?string |
Workshop mechanic name e.g. John if available |
data[].workshop_order.delivery_method_id |
integer |
Delivery method ID e.g. 0 (see common enum delivery_methods) |
data[].workshop_order.reference_text |
string |
Reference of order e.g. 85 |
data[].workshop_order.km_age |
?integer |
KM age of object if registered with this order |
data[].sales_items |
object[] |
Array with sold items |
data[].sales_items[].sales_item_id |
integer |
Unique sales item ID e.g. 63883 |
data[].sales_items[].item_type_id |
integer |
Item type ID e.g. 1 (see common enum item_types) |
data[].sales_items[].pos_group_id |
integer |
POS group ID e.g. 1 (see common enum pos_groups) |
data[].sales_items[].pos_group_name |
string |
POS group name e.g. Diversen |
data[].sales_items[].barcode |
string |
Barcode or article identification e.g. 8713504001924 |
data[].sales_items[].quantity |
integer |
Number of items sold e.g. 1 |
data[].sales_items[].gross_unit_price_in_vat_cents |
integer |
Gross unit price including VAT in cents e.g. 0 |
data[].sales_items[].gross_unit_price_ex_vat_cents |
integer |
Gross unit price excluding VAT in cents e.g. 0 |
data[].sales_items[].unit_discount_in_vat_cents |
integer |
Unit discount amount including VAT in cents e.g. 0 |
data[].sales_items[].unit_discount_ex_vat_cents |
integer |
Unit discount amount excluding VAT in cents e.g. 0 |
data[].sales_items[].line_discount_in_vat_cents |
integer |
Line discount amount including VAT in cents .g. 0 |
data[].sales_items[].line_discount_ex_vat_cents |
integer |
Line discount amount excluding VAT in cents e.g. 0 |
data[].sales_items[].nett_line_price_in_vat_cents |
integer |
Nett line price including VAT in cents e.g. 12100 |
data[].sales_items[].nett_line_price_ex_vat_cents |
integer |
Nett line price excluding VAT in cents e.g. 10000 |
data[].sales_items[].ex_vat_based_prices |
boolean |
true if the prices were based on the amounts excluding VAT |
data[].sales_items[].discount_percentage |
decimal |
Discount percentage e.g. 10 |
data[].sales_items[].vat_code |
integer |
VAT code e.g. 2 (see common enum vat_codes) |
data[].sales_items[].vat_percentage |
integer|decimal |
VAT percentage e.g. 21 |
data[].sales_items[].vat_amount_cents |
integer |
Line VAT amount in cents e.g. 21, for margin VAT always 0 |
data[].sales_items[].purchase_price_ex_vat_cents |
?integer |
Purchase price recorded on creation of sales_item e.g. 4900 |
data[].sales_items[].description |
string |
Sales item description e.g. Cyclon All weather spray 250ml |
data[].sales_items[].description_extended |
?string |
Extended description e.g. Something extra |
data[].sales_items[].article |
?object |
Object with sold article information |
data[].sales_items[].article.brand_name |
string |
Brand name from article details e.g. CYCLON |
data[].sales_items[].article.description |
string |
Article description for article details or first supplier e.g. Cyclon All weather spray 250ml |
data[].sales_items[].article.dst_main_id |
?string |
DST category ID e.g. 2 |
data[].sales_items[].article.dst_main_name |
?string |
DST category name e.g. O&A |
data[].sales_items[].article.dst_sub_id |
?string |
DST sub category ID e.g. N |
data[].sales_items[].article.dst_sub_name |
?string |
DST sub category name e.g. Onderdelen/Reparatie |
data[].sales_items[].article.dst_sub_sub_id |
?string |
DST sub-sub category ID e.g. 8 |
data[].sales_items[].article.dst_sub_sub_name |
?string |
DST sub-sub category name e.g. Smeer-, poets- en onderhoudsmiddelen |
data[].sales_items[].article.sales_price_cents |
integer |
Recommended retail price in cents set in article details or determined from first supplier e.g. 1375 |
data[].sales_items[].article.purchase_price_ex_vat_cents |
integer |
Purchase price in cents set in article details or determined from first supplier e.g. 688 |
data[].sales_items[].article.suppliers |
object[] |
List of suppliers for article (priority sorted) |
data[].sales_items[].article.suppliers[].supplier_id |
integer |
Supplier ID e.g. 2 (see common suppliers endpoint) |
data[].sales_items[].article.suppliers[].supplier_name |
string |
Supplier name e.g. Kruitbosch |
data[].sales_items[].article.suppliers[].article_id |
string |
Article number CCS250 |
data[].sales_items[].article.suppliers[].purchase_price_cents |
integer |
Gross purchase price in cents e.g. 688 |
data[].sales_items[].article.suppliers[].rrp_cents |
integer |
Recommended retail price in cents e.g. 1375 |
data[].sales_items[].object |
?object |
Sold object information, may be null if not related to an object |
data[].sales_items[].object.object_id |
integer |
Unique object ID within account e.g. 15651 |
data[].sales_items[].object.object_barcode |
string |
Internal barcode e.g. F23232323 |
data[].sales_items[].object.barcode |
string |
Barcode of article e.g. 8723723723 |
data[].sales_items[].object.article_id |
string |
Article number e.g. A2323 |
data[].sales_items[].object.object_type_id |
integer |
Object type e.g. 1 Bike 2 Moped |
data[].sales_items[].object.is_demo |
boolean |
true if demo-bike |
data[].sales_items[].object.stock_location_name |
string |
Stock location name e.g. store-floor |
data[].sales_items[].object.brand_name |
string |
Brand description e.g. Giant |
data[].sales_items[].object.brand_id |
integer |
Brand / supplier ID e.g. 2121 (see common suppliers endpoint) |
data[].sales_items[].object.model_name |
string |
Model name e.g. Foxx |
data[].sales_items[].object.category_name |
string |
Category description e.g. Stadsfietsen |
data[].sales_items[].object.is_elo_bike |
boolean |
Electric bike e.g. false |
data[].sales_items[].object.frame_type |
string |
Frame type e.g. Jongens |
data[].sales_items[].object.color |
string |
Color e.g. Blauw |
data[].sales_items[].object.basic_color |
string |
Basic color description e.g. BLUE |
data[].sales_items[].object.basic_color_secondary |
string |
2nd Basic color description e.g. BLACK |
data[].sales_items[].object.year |
integer |
Model year e.g. 2023 //@TODO NULL? |
data[].sales_items[].object.object_status |
string |
Status description new vs used e.g. Gebruikt |
data[].sales_items[].object.size |
?string |
Size e.g. Meisjes 20 |
data[].sales_items[].object.frame_height |
string |
Frame height in cm e.g. 38 |
data[].sales_items[].object.wheel_size |
?string |
Wheel size inches e.g. 24 |
data[].sales_items[].object.frame_size_supplier |
string |
Frame size description supplier e.g. L |
data[].sales_items[].object.tyre_size |
?string |
Tyre size description |
data[].sales_items[].object.material_description |
string |
Description of material e.g. CARBON |
data[].sales_items[].object.gross_weight_kg |
?decimal |
Gross weight e.g. 20 |
data[].sales_items[].object.weight_kg |
?decimal |
Weight e.g. 17 |
data[].sales_items[].object.gear_count |
?integer |
Number of gears e.g. 20 |
data[].sales_items[].object.description_extra |
string |
Extra description e.g. Some text |
data[].sales_items[].object.ecommerce_price_cents |
integer |
E-commerce price in cents e.g. 999900 |
data[].sales_items[].object.road_worthy_costs_cents |
integer |
Costs for making road worthy in cents e.g. 0 |
data[].sales_items[].object.internal_workshop_costs_ex_vat_cents |
?integer |
Costs made in internal workshop in cents |
data[].sales_items[].object.purchased_from_customer_id |
integer |
If purchased from a customer, this is the customer id e.g. 4071 |
data[].sales_items[].object.description |
string |
Description e.g. Some text to desribe |
data[].sales_items[].object.supplier_order_reference |
?string |
Supplier order reference e.g. 12435647 |
data[].sales_items[].object.supplier_invoice_reference |
?string |
Supplier invoice reference e.g. INV322323 |
data[].sales_items[].object.kilometer_age |
integer |
KM age of object e.g. 0 |
data[].sales_items[].object.consignment_status |
integer |
Consignment status see see common enum for list e.g. 0 |
data[].sales_items[].identification |
?object |
Object with identification such as serial numbers |
data[].sales_items[].identification.stock_object_id |
integer |
Unique stock object ID within account e.g. 15651 |
data[].sales_items[].identification.frame_number |
?string |
Frame number e.g. WOW238C |
data[].sales_items[].identification.key_number |
?string |
Key number e.g. 97804 |
data[].sales_items[].identification.key_number_2 |
?string |
Key number 2 e.g. 97804-2 |
data[].sales_items[].identification.lock_number |
?string |
Lock number e.g. R334320-08 |
data[].sales_items[].identification.lock_number_2 |
?string |
Lock number 2 e.g. R334320-08-2 |
data[].sales_items[].identification.battery_number |
?string |
Battery number e.g. BA223432323-1231-08 |
data[].sales_items[].identification.battery_number_2 |
?string |
Battery number 2 e.g. BA223432323-1231-08-2 |
data[].sales_items[].identification.engine_number |
?string |
Engine number e.g. E43434343443 |
data[].sales_items[].identification.serial_number |
?string |
Serial number e.g. 975-0528-1296-2005-06 |
data[].sales_items[].identification.imei_number |
?string |
IMEI number e.g. 975-0528-1296-2005-06 |
data[].sales_items[].identification.license_plate_number |
?string |
License plate number e.g. DT-GX-22 |
data[].sales_items[].identification.velopass_code |
?string |
Velopass code e.g. VP3D3G4KD3 |
data[].sales_items[].identification.warehouse_stock_item_id |
?integer |
For warehouse accounts the stock item ID if known e.g. 1000 |
data[].sales_items[].identification.warehouse_outbound_shipment_id |
?integer |
For warehouse accounts the outbound shipment ID if known e.g. 10033 |
pagination.next_url |
?string |
URL to next result set null if no more data e.g. https://api.cyclesoftware.nl/api/v2/salesdata/transactions.json?token=NDA3MzcwNT....lBVmUw |
HTTP request
GET /api/v2/salesdata/transactions.json?date_field=modified_at&date_start=2024-01-01&date_end=2024-01-15&only_booked_transactions=true&store_id=1 HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 19744
{
"data": [
{
"account_id": 1,
"store_id": 1,
"sales_transaction_number": 22222890,
"type_name": "reparatie",
"is_final": true,
"book_location_id": 1,
"transaction_date": "2023-01-22",
"created_at": "2023-01-22 11:52:57",
"modified_at": "2023-02-09 18:29:01",
"booked_at": "2023-02-09 18:29:01",
"vat_number": null,
"vat_country_code": null,
"total_amount_cents": 18994,
"unpayed_amount_cents": 0,
"sales_employee_name": "Sander",
"sales_employee_id": 49075,
"booked_by_employee_name": "Giel",
"booked_by_employee_id": 1001,
"last_update_by_employee_name": "Giel",
"last_update_by_employee_id": 1001,
"customer_phone_number_id": "mob",
"customer": {
"customer_id": 235268968,
"customer_full_name": "Sander",
"street": "Langeveld",
"housenumber": "12",
"housenumber_postfix": "",
"city": "Het dorp",
"postcode": "3420",
"country": "BE",
"loyalty_points": 430,
"email": "sander@example.nl",
"global_discount": 0,
"country_code": "BE",
"iban": "",
"date_of_birth": null,
"phone_numbers": [
{
"phone_number_id": "mob",
"phone_number": "0412345678",
"name": "Basis mobiel"
}
],
"language_code": "nl_NL"
},
"sales_order": {
"sales_order_id": 55339,
"sales_order_type_id": 6,
"sales_order_status_id": 9,
"reference_id": "",
"reference_text": "",
"delivery_method_id": 0,
"track_trace_reference": ""
},
"workshop_order": {
"workshop_order_id": 55339,
"repair_object_id": 19224,
"workshop_order_type_id": 1,
"workshop_order_status_id": 8,
"workshop_rate_id": 1,
"delivery_method_id": 0,
"reference_text": "",
"km_age": null
},
"sales_items": [
{
"sales_item_id": 170603180,
"item_type_id": 11,
"pos_group_id": 2,
"pos_group_name": "Reparatie",
"barcode": null,
"quantity": 1,
"gross_unit_price_in_vat_cents": 13000,
"gross_unit_price_ex_vat_cents": 11927,
"unit_discount_in_vat_cents": 0,
"unit_discount_ex_vat_cents": 0,
"line_discount_in_vat_cents": 0,
"line_discount_ex_vat_cents": 0,
"nett_line_price_in_vat_cents": 13000,
"nett_line_price_ex_vat_cents": 11927,
"ex_vat_based_prices": false,
"discount_percentage": null,
"vat_code": 1,
"vat_percentage": 9,
"vat_amount_cents": 1073,
"purchase_price_ex_vat_cents": null,
"description": "Reparatie",
"description_extended": null,
"article": null,
"object": null,
"identification": null
},
{
"sales_item_id": 170603182,
"item_type_id": 1,
"pos_group_id": 21,
"pos_group_name": "Onderdelen",
"barcode": "8710177990203",
"quantity": 1,
"gross_unit_price_in_vat_cents": 2095,
"gross_unit_price_ex_vat_cents": 1731,
"unit_discount_in_vat_cents": -904,
"unit_discount_ex_vat_cents": -747,
"line_discount_in_vat_cents": -747,
"line_discount_ex_vat_cents": -747,
"nett_line_price_in_vat_cents": 2999,
"nett_line_price_ex_vat_cents": 2479,
"ex_vat_based_prices": false,
"discount_percentage": null,
"vat_code": 2,
"vat_percentage": 21,
"vat_amount_cents": 520,
"purchase_price_ex_vat_cents": null,
"description": "Jumbo pomp op plank met slang",
"description_extended": null,
"article": {
"brand_name": "Jumbo",
"description": "POMP JUMBO VOET M/PLANK+SLANG",
"dst_main_id": "2",
"dst_main_name": "O&A",
"dst_sub_id": "I",
"dst_sub_name": "Pompen",
"dst_sub_sub_id": "1",
"dst_sub_sub_name": "Voetpomp",
"sales_price_cents": 2500,
"purchase_price_ex_vat_cents": 100,
"suppliers": [
{
"supplier_id": 5229,
"supplier_name": "Accell NL",
"article_id": "650353",
"purchase_price_cents": 100,
"rrp_cents": 1815
},
{
"supplier_id": 1,
"supplier_name": "Agu",
"article_id": "131026",
"purchase_price_cents": 100,
"rrp_cents": 2995
},
{
"supplier_id": 117,
"supplier_name": "Aalten B.V.",
"article_id": "46551850",
"purchase_price_cents": 100,
"rrp_cents": 2695
}
]
},
"object": null,
"identification": null
},
{
"sales_item_id": 170603184,
"item_type_id": 1,
"pos_group_id": 5,
"pos_group_name": "Banden",
"barcode": "8714692239588",
"quantity": 1,
"gross_unit_price_in_vat_cents": 2995,
"gross_unit_price_ex_vat_cents": 2475,
"unit_discount_in_vat_cents": 2995,
"unit_discount_ex_vat_cents": 2475,
"line_discount_in_vat_cents": 2475,
"line_discount_ex_vat_cents": 2475,
"nett_line_price_in_vat_cents": 0,
"nett_line_price_ex_vat_cents": 0,
"ex_vat_based_prices": false,
"discount_percentage": 100,
"vat_code": 2,
"vat_percentage": 21,
"vat_amount_cents": 0,
"purchase_price_ex_vat_cents": 100,
"description": "23-622 Band vouw zwart 28919 Vredestein",
"description_extended": null,
"article": {
"brand_name": "VREDESTEIN",
"description": "23-622 Band vouw zwart 28919 Vredestein",
"dst_main_id": "2",
"dst_main_name": "O&A",
"dst_sub_id": "A",
"dst_sub_name": "Banden",
"dst_sub_sub_id": "2",
"dst_sub_sub_name": "Buitenbanden/tubes",
"sales_price_cents": 2995,
"purchase_price_ex_vat_cents": 100,
"suppliers": [
{
"supplier_id": 5229,
"supplier_name": "Accell NL",
"article_id": "685167",
"purchase_price_cents": 100,
"rrp_cents": 2995
}
]
},
"object": null,
"identification": null
},
{
"sales_item_id": 170603186,
"item_type_id": 1,
"pos_group_id": 5,
"pos_group_name": "Banden",
"barcode": "8714692239588",
"quantity": 1,
"gross_unit_price_in_vat_cents": 2995,
"gross_unit_price_ex_vat_cents": 2475,
"unit_discount_in_vat_cents": 0,
"unit_discount_ex_vat_cents": 0,
"line_discount_in_vat_cents": 0,
"line_discount_ex_vat_cents": 0,
"nett_line_price_in_vat_cents": 2995,
"nett_line_price_ex_vat_cents": 2475,
"ex_vat_based_prices": false,
"discount_percentage": null,
"vat_code": 2,
"vat_percentage": 21,
"vat_amount_cents": 520,
"purchase_price_ex_vat_cents": 100,
"description": "23-622 Band vouw zwart 28919 Vredestein",
"description_extended": null,
"article": {
"brand_name": "VREDESTEIN",
"description": "23-622 Band vouw zwart 28919 Vredestein",
"dst_main_id": "2",
"dst_main_name": "O&A",
"dst_sub_id": "A",
"dst_sub_name": "Banden",
"dst_sub_sub_id": "2",
"dst_sub_sub_name": "Buitenbanden/tubes",
"sales_price_cents": 2995,
"purchase_price_ex_vat_cents": 100,
"suppliers": [
{
"supplier_id": 5229,
"supplier_name": "Accell NL",
"article_id": "685167",
"purchase_price_cents": 100,
"rrp_cents": 2995
},
{
"supplier_id": 8,
"supplier_name": "Rutteman",
"article_id": "23vr622fiopz",
"purchase_price_cents": 100,
"rrp_cents": 2995
}
]
},
"object": null,
"identification": null
}
]
},
{
"account_id": 1,
"store_id": 1,
"sales_transaction_number": 22222924,
"type_name": "fiets",
"is_final": true,
"book_location_id": 1,
"transaction_date": "2023-01-27",
"created_at": "2023-01-27 09:52:52",
"modified_at": "2023-02-06 16:41:29",
"booked_at": "2023-02-06 16:40:05",
"vat_number": null,
"vat_country_code": null,
"total_amount_cents": 831150,
"unpayed_amount_cents": 798400,
"sales_employee_name": "Sander",
"sales_employee_id": 49075,
"booked_by_employee_name": "David",
"booked_by_employee_id": 65043,
"last_update_by_employee_name": "David",
"last_update_by_employee_id": 65043,
"customer_phone_number_id": "mob",
"customer": {
"customer_id": 235270696,
"customer_full_name": "John",
"street": "Betelgeuze",
"housenumber": "122",
"housenumber_postfix": "",
"city": "Utrecht",
"postcode": "3322AW",
"country": "NL",
"loyalty_points": 5000,
"email": "robin@example.nl",
"global_discount": 0,
"country_code": "NL",
"iban": "",
"date_of_birth": "2000-01-01",
"phone_numbers": [
{
"phone_number_id": "mob",
"phone_number": "06-12650321",
"name": "Basis mobiel"
},
{
"phone_number_id": "816991",
"phone_number": "0612650321",
"name": "test"
}
],
"language_code": "nl_NL"
},
"sales_order": null,
"workshop_order": null,
"sales_items": [
{
"sales_item_id": 170918009,
"item_type_id": 2,
"pos_group_id": 1,
"pos_group_name": "Fietsen",
"barcode": "4712878754607",
"quantity": 1,
"gross_unit_price_in_vat_cents": 829900,
"gross_unit_price_ex_vat_cents": 761376,
"unit_discount_in_vat_cents": 0,
"unit_discount_ex_vat_cents": 0,
"line_discount_in_vat_cents": 0,
"line_discount_ex_vat_cents": 0,
"nett_line_price_in_vat_cents": 829900,
"nett_line_price_ex_vat_cents": 761376,
"ex_vat_based_prices": false,
"discount_percentage": null,
"vat_code": 1,
"vat_percentage": 9,
"vat_amount_cents": 68524,
"purchase_price_ex_vat_cents": 10000,
"description": "GIANT Stormguard E+, Hematite, XL, XL, 2023, FR000004",
"description_extended": null,
"article": {
"brand_name": "GIANT",
"description": "GIANT Stormguard E+ Hematite XL 2023",
"dst_main_id": 1,
"dst_main_name": "Fietsen",
"dst_sub_id": "F",
"dst_sub_name": "Crosshybrides",
"dst_sub_sub_id": 1,
"dst_sub_sub_name": "Crosshybride (elektrisch)",
"sales_price_cents": 829900,
"purchase_price_ex_vat_cents": 10000,
"suppliers": [
{
"supplier_id": 2121,
"supplier_name": "Giant",
"article_id": "2203712108",
"purchase_price_cents": 10000,
"rrp_cents": 829900
}
]
},
"object": {
"object_id": 34614,
"object_barcode": "",
"barcode": "4712878754607",
"article_id": "2203712108",
"object_type_id": 1,
"is_demo": false,
"stock_location_name": "",
"brand_name": "GIANT",
"brand_id": 2121,
"model_name": "Stormguard E+",
"category_name": "Crosshybrides - elektrisch",
"is_elo_bike": true,
"frame_type": "UNI",
"color": "Hematite",
"basic_color": "",
"basic_color_secondary": "",
"year": 2023,
"object_status": "Nieuw",
"size": "XL",
"frame_height": null,
"wheel_size": "27",
"frame_size_supplier": "XL",
"tyre_size": null,
"material_description": "ALUMINIUM",
"gross_weight_kg": 38,
"weight_kg": 30,
"gear_count": 999,
"description_extra": "Stormguard E+ 1 25km/h XL Hematite/Black",
"ecommerce_price_cents": 829900,
"road_worthy_costs_cents": 0,
"internal_workshop_costs_ex_vat_cents": null,
"purchased_from_customer_id": 0,
"description": "Stormguard E+ 1 25km/h",
"supplier_order_reference": null,
"supplier_invoice_reference": null,
"kilometer_age": 0,
"consignment_status": 0
},
"identification": {
"stock_object_id": 34614,
"frame_number": "FR000004",
"key_number": null,
"key_number_2": null,
"lock_number": null,
"lock_number_2": null,
"battery_number": null,
"battery_number_2": null,
"engine_number": null,
"serial_number": null,
"imei_number": null,
"license_plate_number": null,
"velopass_code": null
}
},
{
"sales_item_id": 170918011,
"item_type_id": 1,
"pos_group_id": 26,
"pos_group_name": "Verwijderingsbijdrage",
"barcode": null,
"quantity": 1,
"gross_unit_price_in_vat_cents": 1250,
"gross_unit_price_ex_vat_cents": 1033,
"unit_discount_in_vat_cents": 0,
"unit_discount_ex_vat_cents": 0,
"line_discount_in_vat_cents": 0,
"line_discount_ex_vat_cents": 0,
"nett_line_price_in_vat_cents": 1250,
"nett_line_price_ex_vat_cents": 1033,
"ex_vat_based_prices": false,
"discount_percentage": null,
"vat_code": 2,
"vat_percentage": 21,
"vat_amount_cents": 217,
"purchase_price_ex_vat_cents": null,
"description": "Verwijderingsbijdrage accu",
"description_extended": null,
"article": null,
"object": null,
"identification": null
}
]
}
],
"pagination": {
"next_url": "https://api.cyclesoftware.nl/api/v2/salesdata/transactions.json?token=...."
}
}
Pro-forma invoices
Get a list of proforma sales transactions / invoices.
GET
/api/v1/invoices/proforma.json
GET
/api/v1/invoices/proforma.json?offset=1000
| GET parameter | Type | Description |
|---|---|---|
offset |
integer | Pagination offset. optional |
HTTP request
GET /api/v1/invoices/unbooked.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 722
{
"data": [
{
"created_at": "2009-10-21 00:00:00",
"customer_id": 0,
"modified_at": "2016-06-27 09:12:39",
"sales_order_id": null,
"sales_transaction_number": 20171235,
"store_id": 1,
"total_amount_cents": 12500,
"transaction_date": "2009-10-21",
"unpayed_amount_cents": 12500
},
{
"created_at": "2009-10-21 00:00:00",
"customer_id": 0,
"modified_at": "2016-06-27 09:12:39",
"sales_order_id": null,
"sales_transaction_number": 20001,
"store_id": 1,
"total_amount_cents": 12500,
"transaction_date": "2009-10-21",
"unpayed_amount_cents": 12500
}
],
"pagination": {
"next_offset": null
}
}
Sales orders
Get modified orders within date interval (max 31 days)
GET
/api/v2/salesdata/orders.json?modified_start=:modified_start&modified_end=:modified_end
GET
/api/v2/salesdata/orders.json?modified_start=:modified_start&modified_end=:modified_end&offset=:offset&store_id=:store_id
| GET parameter | Type | Description |
|---|---|---|
store_id |
?integer |
optional store-id |
offset |
?integer |
optional offset, see pagination in result |
modified_start |
date |
end date e.g. 2020-01-01 |
modified_end |
date |
end date e.g. 2020-01-01 |
include_deleted |
?boolean |
If 1 deleted sales orders are included with status_id=CANCELLED |
| Property | Type | Description |
|---|---|---|
data[].account_id |
integer |
CS Account e.g. 1 |
data[].store_id |
integer |
Store id e.g. 1 |
data[].sales_order_id |
integer |
Sales order number e.g. 50032 |
data[].customer_id |
integer |
Customer number 6776 |
data[].order_type_id |
integer |
Order type id e.g. 6 (see common enum for list) |
data[].order_type_text |
string |
Order type name e.g. Reparatie |
data[].order_reference_id |
string |
Sales order reference id e.g. 212 |
data[].order_reference_text |
string |
Sales order reference id text e.g. TXT212 |
data[].datetime_created |
datetime |
Created at 2019-05-22 13:45:37 |
data[].datetime_modified |
datetime |
Modified at 2022-04-07 15:03:32 |
data[].datetime_preferred_delivery |
?date |
Preferred delivery date |
data[].sales_employee_id |
?integer |
Sales employee ID 9 |
data[].last_update_employee_id |
?integer |
Last updated by employee ID e.g. 9 |
data[].status_id |
integer |
Sales order status id e.g. 9 (see common enum for list) |
data[].status_text |
string |
Sales order status text e.g. Afgerond (see common enum for list) |
data[].cancellation_type_id |
integer |
Cancellation type id e.g. 0 (see common enum for list) |
data[].cancellation_description |
?string |
Cancellation description (see common enum for list) |
data[].has_invoice |
boolean |
If invoiced true |
data[].invoice_number |
?integer |
Invoice number 20173328 |
data[].delivery_method_id |
integer |
Delivery method id 0 (see common enum for list) |
data[].delivery_method_description |
string |
Delivery method description Afhalen in winkel (see common enum for list) |
data[].order_item_id |
integer |
Item id within sales order 0 |
data[].order_item_status |
string |
Order item status description Geen status (see common enum for list) |
data[].assigned_to_customer_id |
integer |
Sales order could be assigned to a different customer (lease) 6776 |
data[].item_type |
string |
Description of item type Artikelregel (see common enum for list) |
data[].barcode |
string |
Barcode of article 8237238723823 |
data[].object_id |
integer |
ID of linked stock object 0 |
data[].pos_group_id |
integer |
POS group id 0 (see common enum for list) |
data[].quantity |
integer |
Quantity 1 |
data[].description |
string |
Description of article Tire |
data[].gross_unit_price_in_vat_in_cents |
integer |
Gross unit price in cents 9900 |
data[].unit_discount_in_vat_in_cents |
integer |
Unit discount amount in cents 1000 |
data[].nett_line_price_in_vat_in_cents |
integer |
Nett line price in cents 8900 |
data[].vat_amount_cents |
integer |
VAT amount in cents e.g. 1546 |
data[].vat_percentage |
decimal |
VAT percentage 21 |
pagination.count |
integer |
Number of items 3 |
pagination.next_offset |
?integer |
If specified call the api again with offset parameter |
HTTP request
GET /api/v2/salesdata/orders.json?modified_start=2022-04-01&modified_end=2022-04-15 HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 1655
{
"data": [
{
"account_id": 1,
"store_id": 1,
"sales_order_id": 54230,
"customer_id": 235270570,
"order_type_id": 6,
"order_type_text": "Reparatie",
"order_reference_id": "",
"order_reference_text": "",
"datetime_created": "2022-04-13 17:04:00",
"datetime_modified": "2022-04-13 17:04:00",
"datetime_preferred_delivery": null,
"sales_employee_id": 2001,
"last_update_employee_id": 2001,
"status_id": 2,
"status_text": "In behandeling",
"cancellation_type_id": 0,
"cancellation_description": null,
"has_invoice": false,
"invoice_number": 0,
"delivery_method_id": 0,
"delivery_method_description": "Afhalen in winkel",
"order_item_id": 0,
"order_item_status": "Geen status",
"assigned_to_customer_id": 235270570,
"item_type": "Artikelregel",
"barcode": "",
"object_id": 0,
"pos_group_id": 0,
"quantity": 0,
"description": "-",
"gross_unit_price_in_vat_in_cents": 0,
"unit_discount_in_vat_in_cents": 0,
"nett_line_price_in_vat_in_cents": 0,
"vat_amount_cents": 0,
"vat_percentage": 0
},
{
"account_id": 1,
"store_id": 1,
"sales_order_id": 54228,
"customer_id": 235269158,
"order_type_id": 6,
"order_type_text": "Reparatie",
"order_reference_id": "",
"order_reference_text": "",
"datetime_created": "2022-04-13 17:03:15",
"datetime_modified": "2022-04-13 17:03:15",
"datetime_preferred_delivery": null,
"sales_employee_id": 2001,
"last_update_employee_id": 2001,
"status_id": 2,
"status_text": "In behandeling",
"cancellation_type_id": 0,
"cancellation_description": null,
"has_invoice": false,
"invoice_number": 0,
"delivery_method_id": 0,
"delivery_method_description": "Afhalen in winkel",
"order_item_id": 1,
"order_item_status": "Geen status",
"assigned_to_customer_id": 235269158,
"item_type": "Arbeid",
"barcode": "",
"object_id": 0,
"pos_group_id": 2,
"quantity": 1,
"description": "Reparatie laag BTW-tarief",
"gross_unit_price_in_vat_in_cents": 3792,
"unit_discount_in_vat_in_cents": 0,
"nett_line_price_in_vat_in_cents": 3792,
"vat_amount_cents": 313,
"vat_percentage": 9
},
{
"account_id": 1,
"store_id": 1,
"sales_order_id": 54228,
"customer_id": 235269158,
"order_type_id": 6,
"order_type_text": "Reparatie",
"order_reference_id": "",
"order_reference_text": "",
"datetime_created": "2022-04-13 17:03:15",
"datetime_modified": "2022-04-13 17:03:15",
"datetime_preferred_delivery": null,
"sales_employee_id": 2001,
"last_update_employee_id": 2001,
"status_id": 2,
"status_text": "In behandeling",
"cancellation_type_id": 0,
"cancellation_description": null,
"has_invoice": false,
"invoice_number": 0,
"delivery_method_id": 0,
"delivery_method_description": "Afhalen in winkel",
"order_item_id": 2,
"order_item_status": "Geen status",
"assigned_to_customer_id": 235269158,
"item_type": "Artikelregel",
"barcode": "4026495099707",
"object_id": 0,
"pos_group_id": 5,
"quantity": 1,
"description": "Schwalbe binnenband 28X1.1/2 SV19",
"gross_unit_price_in_vat_in_cents": 850,
"unit_discount_in_vat_in_cents": 0,
"nett_line_price_in_vat_in_cents": 850,
"vat_amount_cents": 148,
"vat_percentage": 21
}
],
"pagination": {
"count": 3,
"next_offset": null
}
}
Payments
Get payments within date interval (max 31 days)
GET
/api/v1/salesdata/payments.json?start_date=:start_date&end_date=:end_date
| GET parameter | Type | Description |
|---|---|---|
start_date |
date |
start date e.g. 2020-01-01 |
end_date |
date |
end date e.g. 2020-01-01 |
| Property | Type | Description |
|---|---|---|
customer_id |
?integer |
Customer id 332107 |
invoice_number |
?integer |
Invoice number 365259 (may be null for advance payments) |
related_to_invoice_number |
?integer |
Related to another parent invoice number |
sales_order_id |
?integer |
Sales order id 476953 |
ecommerce_reference_text |
?string |
Sales order reference text reference_129223 |
ecommerce_reference_id |
?string |
Sales order reference id 129223 |
payments |
object[] |
List of payments |
payments[].payment_id |
integer |
ID of payment 65444361 |
payments[].store_id |
integer |
Store id 1 |
payments[].book_location_id |
integer |
Book location id in POS 1 |
payments[].method |
string |
Payment method description Contant Creditcard Chip Tegoedbon(nen) Spaarpunten Retour Bank PSP Rembours Ecocheques |
payments[].method_id |
integer |
Payment method id 1 (see common enum for list) |
payments[].amount_cents |
integer |
Amount of payment in cents 6999 |
payments[].book_date |
string |
Date booked 01-04-2022 15:31:44 |
payments[].created_at |
string |
Date created 01-04-2022 15:31:44 |
psp |
object[] |
Array of payment service provider information (e.g. PAY.) |
psp[].psp_reference |
string |
PSP reference 17232323571X84a7d |
psp[].psp_reference_2 |
string |
PSP reference 2 fb9c911850f4edfe214ff3cdfb214dbef9e8e599 |
psp[].amount_cents |
integer |
Amount of PSP payment 6999 |
HTTP request
GET /api/v1/salesdata/payments.json?start_date=2022-04-01&end_date=2022-04-15 HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 1655
[
{
"customer_id": null,
"invoice_number": 365075,
"related_to_invoice_number": null,
"sales_order_id": null,
"ecommerce_reference_text": null,
"ecommerce_reference_id": null,
"payments": [
{
"payment_id": 65423367,
"store_id": 7,
"book_location_id": 1,
"method": "Pin",
"method_id": 1,
"amount_cents": 850,
"book_date": "01-04-2022 10:09:26",
"created_at": "01-04-2022 10:09:27"
}
],
"psp": [
{
"psp_reference": "1726172361X338a1",
"psp_reference_2": "4b94747349c0afa0e0f6ec58dcbe717e1b32d7b0",
"amount_cents": 850
}
]
},
{
"customer_id": 332107,
"invoice_number": 365259,
"related_to_invoice_number": null,
"sales_order_id": 476953,
"ecommerce_reference_text": "reference_129223",
"ecommerce_reference_id": "129223",
"payments": [
{
"payment_id": 65423591,
"store_id": 1,
"book_location_id": 1,
"method": "Bank",
"method_id": 11,
"amount_cents": 228900,
"book_date": "01-04-2022 10:14:18",
"created_at": "01-04-2022 10:14:18"
},
{
"payment_id": 65444361,
"store_id": 1,
"book_location_id": 1,
"method": "Pin",
"method_id": 1,
"amount_cents": 6999,
"book_date": "01-04-2022 15:31:44",
"created_at": "01-04-2022 15:31:44"
}
],
"psp": [
{
"psp_reference": "17232323571X84a7d",
"psp_reference_2": "fb9c911850f4edfe214ff3cdfb214dbef9e8e599",
"amount_cents": 6999
}
]
}
]
Insurances
Get insurances for objects created within date interval (max 31 days). The information may not be up-to-date with the information known at the insurance company. This information is based on created insurance applications.
GET
/api/v1/stock-objects/insurance/list.json?start_date=:start_date&end_date=:end_date
| GET parameter | Type | Description |
|---|---|---|
start_date |
date |
start date e.g. 2020-01-01 |
end_date |
date |
end date e.g. 2020-01-01 |
| Property | Type | Description |
|---|---|---|
insurance_id |
integer |
ID of insurance application 1182027 |
customer_id |
integer |
Customer ID e.g. 334357 |
created_at |
date |
Date created e.g. 15-04-2022 |
stock_object_id |
integer |
Stock object ID 786080 |
insurance_company |
string |
Name of insurance company KING |
reference_id |
integer |
Reference ID 0 |
policy_number |
integer |
Policy Number (if available) 12212 |
insurance_starting_date |
date |
Start date of the insurance 15-04-2022 |
description |
string |
Name of the insurance e.g. E-bike Casco Compleet - 3 jaar - Aut. Incasso |
policy_costs |
integer |
Costs of the policy in cents 650 |
insured_amount |
integer |
Insured amount in cents 299900 |
premium_amount |
integer |
Insurance premium in cents 19895 |
HTTP request
GET /api/v1/stock-objects/insurance/list.json??start_date=2022-04-01&end_date=2022-04-15 HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 903
[
{
"insurance_id": 1168101,
"customer_id": 317247,
"created_at": "01-04-2022",
"stock_object_id": 775832,
"insurance_company": "UNIGARANT",
"reference_id": 0,
"policy_number": 143123238,
"insurance_starting_date": "01-04-2022",
"description": "Onbekend",
"policy_costs": 968,
"insured_amount": 6300,
"premium_amount": 5371
},
{
"insurance_id": 1168175,
"customer_id": 332105,
"created_at": "01-04-2022",
"stock_object_id": 781192,
"insurance_company": "KING",
"reference_id": 0,
"policy_number": 0,
"insurance_starting_date": "01-04-2022",
"description": "E-bike casco compleet jaarpremie Aut. Incasso",
"policy_costs": 650,
"insured_amount": 176900,
"premium_amount": 7343
}
]
Sales orders
For create and update of sales orders see the E-commerce documentation section.
Authentication mechanism
- Basic HTTP Authentication
- Scope(s):
e-commerce
Update sales order store
Update the store of a sales order with the possibility to change the delivery type and address. This API call may only be used if your account has multiple stores. If no mode is specified in the items array objects the default mode will be used.
| URL parameter | Type | Description |
|---|---|---|
:sales_order_id |
integer |
Sales order id also referred to as order_id in SOAP APIs required |
HTTP request example
POST
/api/v1/sales/orders/:sales_order_id/update-store.json
Request properties
| Property | Type | Description |
|---|---|---|
to_store_id |
integer |
The new store id e.g. 2 |
default_mode |
integer |
Default transfer mode 2 (see common enum api sales_order_store_transfer_modes) |
new_delivery_method_id |
?integer |
New delivery method 3 (see common enum api delivery_methods) |
new_delivery_address |
?object |
New delivery address for the sales order (null if not changed or required) |
new_delivery_address.is_business_address |
bool |
true if business address |
new_delivery_address.company_name |
?string |
Company name or null |
new_delivery_address.name |
string |
The name of the address |
new_delivery_address.street |
string |
Street name of the address |
new_delivery_address.house_number |
string |
House number of the address |
new_delivery_address.house_number_postfix |
string |
House number postfix of the address |
new_delivery_address.postal_code |
string |
Postal code of the address |
new_delivery_address.city |
string |
City of the address |
new_delivery_address.country_code |
string |
Country_code of the address |
new_delivery_address.phone_number |
string |
Phone_number of the address |
new_delivery_address.email |
string |
E-mail of the address com` |
new_delivery_address.notes |
string |
Notes of the address |
items |
object[] |
List of sales order items and associated transfer mode |
items[].item_id |
integer |
The sales order item id, also referred to as order_item_line_id in e-commerce APIs |
items[].mode |
?integer |
Specify the transfer mode for this specific sales order item (see common enum api sales_order_store_transfer_modes) |
Response properties
| Property | Type | Description |
|---|---|---|
error |
boolean |
true if an error occcured |
error_message |
?string |
The error message if error is true |
created_store_order_id |
?integer |
The internal delivery store order id that was created 45287 |
affected_supplier_order_ids |
integer[] |
List of supplier order ids that may have a new store |
cancelled_store_order_ids |
integer[] |
List of store orders which were cancelled |
cancelled_supplier_order_ids |
integer[] |
List of supplier orders which were cancelled |
updated_outbound_order_ids |
?integer[] |
List of outbound order ids which were cancelled (if warehouse account) |
HTTP Request
POST /api/v1/sales/orders/102323/update-store.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept: application/json
Accept-encoding: gzip
Content-type: application/json; charset=utf-8
Content-Length: 688
{
"to_store_id": 2,
"default_mode": 2,
"new_delivery_method_id": 3,
"new_delivery_address": {
"address_type_id": "1",
"is_business_address": "0",
"company_name": "",
"name": "Name 1",
"street": "Streetname",
"house_number": "1",
"house_number_postfix": "a",
"postal_code": "1000AA",
"city": "Amsterdam",
"country_code": "NL",
"phone_number": "073031111",
"email": "test@test.com",
"notes": "Some note"
},
"items": [
{
"item_id": 1,
"mode": 1
},
{
"item_id": 2,
"mode": 1
}
]
}
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 45
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"error": false,
"error_message": null,
"created_store_order_id": 45287,
"affected_supplier_order_ids": [
1481,
20000
],
"cancelled_store_order_ids": [
3333,
4444
],
"cancelled_supplier_order_ids": [
102020,
102021
],
"updated_outbound_order_ids": [
32323,
32324
]
}
Update delivery method
Update sales order delivery type and/or address.
| URL parameter | Type | Description |
|---|---|---|
:sales_order_id |
integer |
Sales order id also referred to as order_id in SOAP APIs required |
HTTP request example
POST
/api/v1/sales/orders/:sales_order_id/update-delivery-method.json
Request properties
| Property | Type | Description |
|---|---|---|
new_delivery_method_id |
?integer |
New delivery method e.e. 3 (see common enum api delivery_methods) |
new_delivery_address |
?object |
New delivery address for the sales order (null if not changed or required) |
new_delivery_address.is_business_address |
bool |
true if business address |
new_delivery_address.company_name |
?string |
Company name or null |
new_delivery_address.name |
string |
The name of the address |
new_delivery_address.street |
string |
Street name of the address |
new_delivery_address.house_number |
string |
House number of the address |
new_delivery_address.house_number_postfix |
string |
House number postfix of the address |
new_delivery_address.postal_code |
string |
Postal code of the address |
new_delivery_address.city |
string |
City of the address |
new_delivery_address.country_code |
string |
Country_code of the address |
new_delivery_address.phone_number |
string |
Phone_number of the address |
new_delivery_address.email |
string |
E-mail of the address com` |
new_delivery_address.notes |
string |
Notes of the address |
Response properties
| Property | Type | Description |
|---|---|---|
error |
boolean |
true if an error occcured |
error_message |
?string |
The error message if error is true |
created_delivery_address_id |
?integer |
The ID of the delivery address e.g. 45287, null if no address is created |
HTTP Request
POST /api/v1/sales/orders/102323/update-delivery-method.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept: application/json
Accept-encoding: gzip
Content-type: application/json; charset=utf-8
Content-Length: 484
{
"new_delivery_method_id": 3,
"new_delivery_address": {
"address_type_id": "1",
"is_business_address": "0",
"company_name": "",
"name": "Name 1",
"street": "Streetname",
"house_number": "1",
"house_number_postfix": "a",
"postal_code": "1000AA",
"city": "Amsterdam",
"country_code": "NL",
"phone_number": "073031111",
"email": "test@test.com",
"notes": "Some note"
}
}
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 91
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"error": false,
"error_message": null,
"created_delivery_address_id": 45287
}
Cancel sales order
Mark a sales order as cancelled. An order may only be cancelled if there is no payment amount left and the sales orders is not invoiced.
| URL parameter | Type | Description |
|---|---|---|
:sales_order_id |
integer |
Sales order id also referred to as order_id in SOAP APIs required |
| GET parameter | Type | Description |
|---|---|---|
:cancellation_type_id |
integer |
Cancellation type ID see common api cancellation_types e.g. 1 |
:delete_exchange |
bool |
if true the exchange objects in the order will be deleted. Defaults to false |
HTTP request example
POST
/api/v1/sales/orders/:sales_order_id/cancel.json?cancellation_type_id=:cancellation_type_id&delete_exchange=:delete_exchange
HTTP Request
POST /api/v1/sales/orders/121212/cancel.json?cancellation_type_id=1&delete_exchange=true HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 45
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"error": false,
"error_message": null
}
Service items
Read, create or update repair objects for a customer
Scope(s)
resources
Service item (object)
| Property | Type | Description |
|---|---|---|
account_id |
integer |
Account ID within CS 1000 |
store_id |
integer |
Store ID of service item 1 |
service_id |
integer |
ID of service 1790811 |
service_item_id |
integer |
Iem ID of service item 4823371 |
service_barcode |
string |
Barcode of service item e.g. DSK-1790811-3 |
service_status_id |
integer |
Service status see common api service_item_status e.g. 1 |
invoice_number |
integer |
If positive number, the invoice which triggered creation of this item e.g. 20173208 |
customer_id |
integer |
ID of customer e.g. 235269422 |
object_id |
integer |
ID of object e.g. 24136 |
is_open |
boolean |
true if still open |
is_scheduled |
boolean |
true if scheduled in a workshop order |
title |
string |
Title e.g. 3e servicebeurt |
description |
string |
Description e.g. 3e servicebeurt |
gross_unit_price_cents |
integer |
Gross unit price in cents 6900 |
unit_discount_amount_cents |
integer |
Discount in cents 0 |
amount_payed_in_advance_cents |
integer |
Amount payed 0 |
time_minutes |
integer |
Time in minutes for workshop 60 |
scheduled_at |
date |
Scheduled for date e.g. 2021-12-22 |
scheduled_at_km_age |
integer |
Scheduled after X kilometer |
modified_at |
datetime |
Modification date time 2020-06-22 10:51:49 |
Service items for customer
Get service items for customer
GET
/api/v1/customers/:customer_id/service-items.json
| URI parameter | Type | Description |
|---|---|---|
customer_id |
int |
Customer ID e.g. 2001 |
HTTP request
GET /api/v1/customers/2/service-items.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 20471
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
[
{
"account_id": 5185,
"store_id": 1,
"service_id": 2302569,
"service_item_id": 6786341,
"service_barcode": "DSK-2302569-1",
"service_status_id": 2,
"invoice_number": 421236,
"customer_id": 2001,
"object_id": 175432,
"is_open": true,
"is_scheduled": false,
"description": "test",
"title": "test",
"gross_unit_price_cents": 3200,
"unit_discount_amount_cents": 2300,
"amount_payed_in_advance_cents": 900,
"time_minutes": 30,
"scheduled_at": "2021-07-22",
"scheduled_at_km_age": 0,
"modified_at": "2021-07-22 07:00:16"
},
{
"account_id": 5185,
"store_id": 1,
"service_id": 2302721,
"service_item_id": 6786899,
"service_barcode": "DSK-2302721-1",
"service_status_id": 2001,
"invoice_number": 421268,
"customer_id": 2,
"object_id": 175444,
"is_open": true,
"is_scheduled": false,
"description": "test",
"title": "test",
"gross_unit_price_cents": 3200,
"unit_discount_amount_cents": 2300,
"amount_payed_in_advance_cents": 900,
"time_minutes": 30,
"scheduled_at": "2021-07-22",
"scheduled_at_km_age": 0,
"modified_at": "2021-07-22 07:00:16"
}
]
Service items
Get service items for service ID
GET
/api/v1/customers/:customer_id/service-items/:service_id.json
| URI parameter | Type | Description |
|---|---|---|
customer_id |
int |
Customer ID e.g. 2001 |
service_id |
int |
Service ID e.g. 2302569 |
HTTP request
GET /api/v1/customers/2001/service-items/2302569.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic
Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 662
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
[
{
"account_id": 5185,
"store_id": 1,
"service_id": 2302569,
"service_item_id": 6786341,
"service_barcode": "DSK-2302569-1",
"service_status_id": 2,
"invoice_number": 421236,
"customer_id": 2001,
"object_id": 175432,
"is_open": true,
"is_scheduled": false,
"description": "test",
"title": "test",
"gross_unit_price_cents": 3200,
"unit_discount_amount_cents": 2300,
"amount_payed_in_advance_cents": 900,
"time_minutes": 30,
"scheduled_at": "2021-07-22",
"scheduled_at_km_age": 0,
"modified_at": "2021-07-22 07:00:16"
},
{
"account_id": 5185,
"store_id": 1,
"service_id": 2302569,
"service_item_id": 6786342,
"service_barcode": "DSK-2302569-2",
"service_status_id": 2,
"invoice_number": 421236,
"customer_id": 2001,
"object_id": 175432,
"is_open": true,
"is_scheduled": false,
"description": "test2",
"title": "test2",
"gross_unit_price_cents": 3200,
"unit_discount_amount_cents": 2300,
"amount_payed_in_advance_cents": 900,
"time_minutes": 30,
"scheduled_at": "2021-10-22",
"scheduled_at_km_age": 300,
"modified_at": "2021-07-22 07:00:16"
}
]
Service items list
Get list of service items for workshop.
- Scopes:
sales-export
GET
/api/v1/workshop/repair-objects/service-items.json
GET
/api/v1/workshop/repair-objects/service-items.json?modified_start=:modified_start&modified_end=:modified_end&offset=:offset
| GET parameter | Type | Description |
|---|---|---|
modified_start |
date |
end date e.g. 2020-01-01 |
modified_end |
date |
end date e.g. 2020-01-01 |
offset |
integer |
offset (omit or pagination.next_offset) |
Properties
| Property | Type | Description |
|---|---|---|
error |
boolean |
e.g. false |
error_message |
?string |
if not null the error message |
data |
object[] |
Array of service item objects |
data[].account_id |
integer |
Account ID within CS 1000 |
data[].store_id |
integer |
Store ID of associated to service item 1 |
data[].service_id |
integer |
ID of service 1790811 |
data[].service_item_id |
integer |
Iem ID of service item 4823371 |
data[].service_barcode |
string |
Barcode of service item e.g. DSK-1790811-3 |
data[].service_status_id |
integer |
Service status see common api service_item_status e.g. 1 |
data[].invoice_number |
integer |
If positive number, the invoice which triggered creation of this item e.g. 20173208 |
data[].customer_id |
integer |
ID of customer e.g. 235269422 |
data[].object_id |
integer |
ID of object e.g. 24136 |
data[].is_open |
boolean |
true if still open |
data[].is_scheduled |
boolean |
true if scheduled in a workshop order |
data[].title |
string |
Title e.g. 3e servicebeurt |
data[].description |
string |
Description e.g. 3e servicebeurt |
data[].gross_unit_price_cents |
integer |
Gross unit price in cents 6900 |
data[].unit_discount_amount_cents |
integer |
Discount in cents 0 |
data[].amount_payed_in_advance_cents |
integer |
Amount payed 0 |
data[].time_minutes |
integer |
Time in minutes for workshop 60 |
data[].scheduled_at |
date |
Scheduled for date e.g. 2021-12-22 |
data[].scheduled_at_km_age |
integer |
Scheduled after X kilometer |
data[].modified_at |
datetime |
Modification date time 2020-06-22 10:51:49 |
pagination.count |
integer |
Count of results |
pagination.next_offset |
?integer |
null if no next page available, otherwise value for offset GET variable |
GET /api/v1/workshop/repair-objects/service-items.json?modified_start=2022-06-01&modified_end=2022-06-25 HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 2392
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"error": false,
"error_message": null,
"data": [
{
"account_id": 1000,
"store_id": 1,
"service_id": 1790811,
"service_item_id": 4823367,
"service_barcode": "DSK-1790811-1",
"service_status_id": 1,
"invoice_number": 20173208,
"customer_id": 235269422,
"object_id": 24136,
"is_open": true,
"is_scheduled": false,
"title": "1e servicebeurt",
"description": "1e servicebeurt",
"gross_unit_price_cents": 8800,
"unit_discount_amount_cents": 6900,
"amount_payed_in_advance_cents": 0,
"time_minutes": 30,
"scheduled_at": "2022-09-22",
"scheduled_at_km_age": 0,
"modified_at": "2022-06-22 10:51:49"
},
{
"account_id": 1000,
"store_id": 1,
"service_item_id": 4823369,
"service_barcode": "DSK-1790811-2",
"service_status_id": 1,
"invoice_number": 20173208,
"customer_id": 235269422,
"object_id": 24136,
"is_open": true,
"is_scheduled": false,
"title": "2e servicebeurt",
"description": "2e servicebeurt",
"gross_unit_price_cents": 6900,
"unit_discount_amount_cents": 3400,
"amount_payed_in_advance_cents": 0,
"time_minutes": 30,
"scheduled_at": "2022-06-22",
"scheduled_at_km_age": 500,
"modified_at": "2022-06-22 10:51:49"
},
{
"account_id": 1000,
"store_id": 1,
"service_item_id": 4823371,
"service_barcode": "DSK-1790811-3",
"service_status_id": 1,
"invoice_number": 20173208,
"customer_id": 235269422,
"object_id": 24136,
"is_open": true,
"is_scheduled": false,
"title": "3e servicebeurt",
"description": "3e servicebeurt",
"gross_unit_price_cents": 6900,
"unit_discount_amount_cents": 0,
"amount_payed_in_advance_cents": 0,
"time_minutes": 60,
"scheduled_at": "2022-12-22",
"scheduled_at_km_age": 0,
"modified_at": "2022-06-22 10:51:49"
}
],
"pagination": {
"count": 3,
"next_offset": null
}
}
Service item close
To update the status of a service item to a closed status
Get list of service items for workshop.
- Scopes:
resourcesorservice-data
PUT
/api/v1/workshop/service-items/:service_barcode/close.json
| URL parameter | Type | Description |
|---|---|---|
:service_barcode |
string |
The code of the service item e.g. DSK-100022-2 |
Request properties
| Request object | Type | Description |
|---|---|---|
service_status_id |
integer |
The service status ID, defaults to 4 (closed), see service_item_status in common enum endpoint. Allowed values (4, 5) |
reference |
string |
Own reference to closing |
Response properties
| Property | Type | Description |
|---|---|---|
error |
boolean |
true if an error occurred. e.g. `false` |
error_message |
string |
true |
data |
object[] |
Array of service items associated with the :service_barcode, see definition in Service items list endpoint |
PUT /api/v1/workshop/service-items/DSK-2080494-1/close.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
Content-type: application/json
Content-length: 54
{
"service_status_id": 4,
"reference": "Ref-11"
}
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 1749
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"error": false,
"error_message": null,
"data": [
{
"account_id": 1,
"store_id": 1,
"service_id": 2080494,
"service_item_id": 5941806,
"service_barcode": "DSK-2080494-1",
"service_status_id": 4,
"invoice_number": 20174986,
"customer_id": 235269290,
"object_id": 25918,
"is_open": false,
"is_scheduled": false,
"description": "Rijklaar maken",
"title": "Rijklaar maken",
"gross_unit_price_cents": 0,
"unit_discount_amount_cents": 0,
"amount_payed_in_advance_cents": 0,
"time_minutes": 60,
"scheduled_at": "2024-01-05",
"scheduled_at_km_age": 0,
"modified_at": "2024-01-05 09:37:13"
},
{
"account_id": 1,
"store_id": 1,
"service_id": 2080494,
"service_item_id": 5941807,
"service_barcode": "DSK-2080494-2",
"service_status_id": 4,
"invoice_number": 20174986,
"customer_id": 235269290,
"object_id": 25918,
"is_open": false,
"is_scheduled": false,
"description": "Servicebeurt 1, 99,00 (100% korting) (Totaal zorgeloos servicepakket)",
"title": "Servicebeurt 1, 99,00 (100% korting)",
"gross_unit_price_cents": 9900,
"unit_discount_amount_cents": 9900,
"amount_payed_in_advance_cents": 0,
"time_minutes": 60,
"scheduled_at": "2024-03-29",
"scheduled_at_km_age": 0,
"modified_at": "2024-01-17 14:32:04"
}
]
}
Stock
Access stock data
Authentication mechanism
- Basic HTTP Authentication
Stockinfo
Get stock-info for a set of barcodes. The max number of barcodes is 10. If more are supplied remote supplier stock is not included.
- Scope(s):
e-commerce
GET
/app/api/v3/stockinfo/:barcode1/:barcode2/../../
| GET parameter | Type | Description |
|---|---|---|
only_supplier_stock |
integer | if 1 stock in stores is ignored optional |
only_supplier_id |
integer | If supplied only the stock of this supplier is checked optional |
remote_supplier_check |
integer | If 0, no remote supplier checks are performed optional |
Properties
| Property | Type | Description |
|---|---|---|
error |
boolean |
e.g. false |
error_message |
?string |
Error message if error is true |
data.result_items |
object[] |
array of result objects |
data.result_items[].barcode |
string |
e.g. 4026495856010 |
data.result_items[].stock_available |
boolean |
if true, there is stock available within stores |
data.result_items[].delivery_date |
?date |
expected delivery date from supplier or back-orders / expected stock |
data.result_items[].delivery_date_backlog |
?date |
expected delivery date based on back-orders or expected stock |
data.result_items[].stock_supplier |
?boolean |
true if supplier has stock, false if supplier has no stock, null if not checked |
data.result_items[].stock_quantity |
integer |
quantity available in stores |
data.result_items[].stock_stores |
object[] |
info per store |
data.result_items[].stock_stores[].dealer_id |
integer |
store number 1 |
data.result_items[].stock_stores[].store_name |
string |
Name of the store test |
data.result_items[].stock_stores[].store_phone |
string |
Phone of the store 0733030050 |
data.result_items[].stock_stores[].quantity |
integer |
quantity available including demo 0 |
data.result_items[].stock_stores[].quantity_demo |
integer |
Quantity of demo models |
data.result_items[].stock_stores[].quantity_expected |
integer |
Quantity expected from supplier |
data.result_items[].stock_stores[].delivery_dates |
string[] |
Delivery dates expected from supplier. If back-orders are available the date of back-order will be used. If objects are not assigned to a back-order and have a delivery date this date will be used |
data.result_items[].article_id |
string |
Article ID in request url |
HTTP request
GET /app/api/v3/stockinfo/4026495856010/4026495843614/ HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 1574
{
"error": false,
"error_message": "",
"data": {
"result_items": [
{
"barcode": "4026495843614",
"stock_available": true,
"delivery_date": null,
"stock_supplier": null,
"stock_quantity": 3,
"stock_stores": [
{
"dealer_id": 1,
"store_name": "test",
"store_phone": "0733030050",
"quantity": 3,
"quantity_demo": 0,
"quantity_expected": 0,
"delivery_dates": []
}
],
"article_id": "4026495843614"
},
{
"barcode": "4026495843690",
"stock_available": true,
"delivery_date": "01-01-2022",
"delivery_date_backlog": "01-01-2022",
"stock_supplier": null,
"stock_quantity": 3,
"stock_stores": [
{
"dealer_id": 1,
"store_name": "test",
"store_phone": "0733030050",
"quantity": 3,
"quantity_demo": 0,
"quantity_expected": 1,
"delivery_dates": [
"01-01-2022"
]
}
],
"article_id": "4026495843614"
},
{
"barcode": "4026495856010",
"stock_available": true,
"stock_quantity": 0,
"delivery_date": null,
"stock_supplier": true,
"stock_stores": [
{
"dealer_id": 1,
"store_name": "test",
"store_phone": "0733030050",
"quantity": 0,
"quantity_demo": 0,
"quantity_expected": 0,
"delivery_dates": []
}
],
"article_id": "4026495856010"
}
]
}
}
Stock list
Get a list of stocked objects with status available or pro-forma sold.
- Scope(s):
stock-export
HTTP request examples
GET
/api/v1/stock/pos-items.json
Properties
| Property | Type | Description |
|---|---|---|
error |
boolean |
e.g. false |
error_message |
?string |
|
data |
object[] |
Array of objects |
data[].account_id |
integer |
Account ID of store e.g. 1 |
data[].store_id |
integer |
ID of the POS store e.g. 1 |
data[].object_id |
integer |
POS Object ID e.g. 22952 |
data[].sales_order_id |
integer |
POS order id e.g. 0 |
data[].brand_name |
string |
Brand name e.g. ZNEN |
data[].article_id |
string |
Article number e.g. 787-25646 |
data[].barcode |
string |
Barcode e.g. 2200082836636 |
data[].description |
string |
Object brand + model e.g. ZNEN Scooter 8N 20" |
data[].frame_id |
string |
Framenumber e.g. FR121212 |
data[].purchase_price_cents |
integer |
Purchase price cents e.g. 205800 |
data[].dealer_rrp_cents |
integer |
RRP cents e.g. 349900 |
data[].is_sold_to_customer |
boolean |
Sold indicator e.g. true |
data[].is_demo |
boolean |
Demo indicator e.g. false |
data[].is_used |
boolean |
Used indicator e.g. false |
data[].has_invoice |
boolean |
Has an invoice e.g. true |
data[].stocked_at |
?date |
Date of stocking e.g. 2019-01-24 |
data[].custom_variable_1 |
string |
Custom variable e.g. Some value |
data[].is_deleted |
boolean |
Is deleted indicator e.g. false |
data[].is_rental |
boolean |
If rental object true |
data[].is_used |
boolean |
true if not a new object |
Response
{
"error": false,
"error_message": null,
"data": [
{
"account_id": 1,
"store_id": 1,
"object_id": 21016,
"sales_order_id": 0,
"supplier": "Votani",
"article_id": "99.Y2634.Q14",
"barcode": "2200054202292",
"description": "Votani X2 Mid Motor",
"frame_id": "",
"purchase_price_cents": 0,
"dealer_rrp_cents": 130000,
"is_sold_to_customer": true,
"is_demo": false,
"is_used": false,
"has_invoice": true,
"stocked_at": "2015-11-25",
"custom_variable_1": "",
"is_deleted": false,
"is_rental": false,
"is_new": true
},
{
"account_id": 1,
"store_id": 1,
"object_id": 22952,
"sales_order_id": 0,
"supplier": "ZNEN",
"article_id": "787-25646",
"barcode": "2200082836636",
"description": "ZNEN Scooter 8N 20\"",
"frame_id": "",
"purchase_price_cents": 205800,
"dealer_rrp_cents": 349900,
"is_sold_to_customer": true,
"is_demo": false,
"is_used": false,
"has_invoice": true,
"stocked_at": "2019-01-24",
"custom_variable_1": "",
"is_deleted": false,
"is_rental": true
"is_new": false
}
]
}
Supplier orders
Create and send supplier orders
Authentication mechanism
- Basic HTTP Authentication
- Scope(s):
e-commerce
Supplier order (object)
Properties used in create, get and send endpoints.
| Property | Type | POST | Description |
|---|---|---|---|
supplier_order_id |
integer |
Supplier order ID 2222 |
|
supplier_id |
integer |
POST |
Supplier ID see common suppliers endpoint e.g. 2113 |
store_id |
integer |
POST |
Store ID within account e.g. 2 |
order_type_id |
integer |
Order type see common enum supplier_order_types e.g. 1 |
|
status_id |
integer |
Order status see common enum supplier_order_status e.g. 0 |
|
supplier_comment |
string |
Comment given by supplier e.g. Some text |
|
supplier_reference |
string |
Reference from supplier ref-from-supplier |
|
own_reference |
string |
Own reference e.g. Own1212 |
|
created_at |
datetime |
Creation date 2022-01-12 12:30:30 |
|
items |
object[] |
Array of order items | |
items[].supplier_order_item_id |
integer |
Item ID 10012 |
|
items[].item_type_id |
integer |
Item type see common enum transaction_item_types e.g. 1 |
|
items[].article_id |
string |
POST |
Article Number. ART2 |
items[].barcode |
string |
POST |
Barcode e.g. BARCODE2 |
items[].quantity |
integer |
POST |
Quantity ordered e.g. 2 |
items[].quantity_delivered |
integer |
Quantity delivered e.g. 0 |
|
items[].quantity_open |
integer |
Quantity open (not delivered) e.g. 2 |
|
items[].supplier_delivery_date |
date |
Delivery date given by supplier e.g. 2022-01-20 |
|
items[].supplier_item_reference |
string |
Reference item from supplier e.g. ref-item-1 |
Create supplier order
Creates a supplier order. To actually dispatch and send the supplier order to the supplier call the send endpoint with the obtained supplier order ID.
POST
/api/v1/supplier/order.json
HTTP request
POST /api/v1/supplier/order.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
Content-type: application/json; charset=utf-8
Content-length: 299
{
"supplier_id": 2113,
"store_id": 2,
"own_reference": "ref1",
"items": [
{
"barcode": "87123456789",
"article_id": "art-no-1",
"quantity": 1
},
{
"barcode": "87123456790",
"article_id": "art-no-2",
"quantity": 2
}
]
}
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 1017
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"supplier_order_id": 2222,
"supplier_id": 2113,
"store_id": 2,
"order_type_id": 1,
"status_id": 0,
"supplier_comment": "Some text",
"own_reference": "ref1",
"supplier_reference": "ref-from-supplier",
"created_at": "2022-01-12 12:30:30",
"items": [
{
"supplier_order_item_id": 10010,
"item_type_id": 1,
"article_id": "art-no-1",
"barcode": "87123456789",
"quantity": 1,
"quantity_delivered": 0,
"quantity_open": 1,
"supplier_delivery_date": null,
"supplier_item_reference": ""
},
{
"supplier_order_item_id": 10012,
"item_type_id": 1,
"article_id": "ART2",
"barcode": "BARCODE2",
"quantity": 2,
"quantity_delivered": 0,
"quantity_open": 2,
"supplier_delivery_date": "2022-01-20",
"supplier_item_reference": "ref-item-1"
}
]
}
HTTP Error Response
HTTP/1.1 400
Content-type: application/json; charset=utf-8
Content-length: 57
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"error": true,
"error_message": "Bad request"
}
Get supplier order
GET
/api/v1/supplier/order/:id.json
HTTP request
GET /api/v1/supplier/order/2222.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 1022
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"supplier_order_id": 2222,
"supplier_id": 2113,
"store_id": 2,
"order_type_id": 1,
"status_id": 0,
"supplier_comment": "Some text",
"own_reference": "own-ref-1",
"supplier_reference": "ref-from-supplier",
"created_at": "2022-01-12 12:30:30",
"items": [
{
"supplier_order_item_id": 10010,
"item_type_id": 1,
"article_id": "art-no-1",
"barcode": "87123456789",
"quantity": 1,
"quantity_delivered": 0,
"quantity_open": 1,
"supplier_delivery_date": null,
"supplier_item_reference": ""
},
{
"supplier_order_item_id": 10012,
"item_type_id": 1,
"article_id": "ART2",
"barcode": "BARCODE2",
"quantity": 2,
"quantity_delivered": 0,
"quantity_open": 2,
"supplier_delivery_date": "2022-01-20",
"supplier_item_reference": "ref-item-1"
}
]
}
Send supplier order
Send a supplier order.
POST
/api/v1/supplier/order/:id/send.json
HTTP request
POST /api/v1/supplier/order/2222.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 1023
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"supplier_order_id": 2222,
"supplier_id": 2113,
"store_id": 2,
"order_type_id": 1,
"status_id": 1,
"supplier_comment": "Some text",
"supplier_reference": "ref-from-supplier",
"own_reference": "own-ref-1",
"created_at": "2022-01-12 12:30:30",
"items": [
{
"supplier_order_item_id": 10010,
"item_type_id": 1,
"article_id": "art-no-1",
"barcode": "87123456789",
"quantity": 1,
"quantity_delivered": 0,
"quantity_open": 1,
"supplier_delivery_date": null,
"supplier_item_reference": ""
},
{
"supplier_order_item_id": 10012,
"item_type_id": 1,
"article_id": "ART2",
"barcode": "BARCODE2",
"quantity": 2,
"quantity_delivered": 0,
"quantity_open": 2,
"supplier_delivery_date": "2022-01-20",
"supplier_item_reference": "ref-item-1",
}
]
}
HTTP Error Response
HTTP/1.1 400
Content-type: application/json; charset=utf-8
Content-length: 57
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"error": true,
"error_message": "Error given by supplier"
}
Process dropshipment packinglist
Process a packinglist for a dropshipment delivery.
POST
/api/v1/supplier/packinglist/process-dropshipment.json
Process packinglist (request object)
| Property | Type | Description |
|---|---|---|
supplier_id |
integer |
Supplier ID see common suppliers endpoint e.g. 2113 |
packinglist_number |
string |
Packinglist number to process e.g. PB23323 |
store_id |
integer |
Store ID where to process the packinglist e.g. 2 |
send_customer_messages |
boolean |
true if notifications should be enabled defaults to false |
update_sales_order_status_if_possible |
boolean |
true if sales-order statuses should be updated defaults to false |
ignore_already_processed |
boolean |
Defaults to false. iftrue` already processed errors are ignored |
Process packinglist (response object)
| Property | Type | Description |
|---|---|---|
error |
boolean |
true if error occurd |
error_message |
?string |
The error message or null |
result.supplier_id |
integer |
Supplier ID e.g. 2113 |
result.packinglist_numbers |
string[] |
The processed packinglist numbers. Usually array with 1 element |
result.articles |
object[] |
The articles that are processed |
result.articles[].barcode |
string |
Barcode of article e.g. 54423933323 |
result.articles[].stock |
integer |
Stock level e.g. 2 |
result.articles[].units_delivered |
integer |
The units delivered / processed e.g. 4 |
result.delivered_objects |
object[] |
Array of delivered objects |
result.delivered_objects[].customer_id |
?integer |
Customer ID of owner e.g. 1006 or null |
result.delivered_objects[].frame_number |
string |
Frame number of object e.g. FR1443433 |
result.delivered_objects[].object_id |
integer |
Object ID of object e.g. 10002 |
result.delivered_objects[].sales_order_id |
?integer |
Sales order ID related to the object or null |
result.sales_orders |
object[] |
Array of related sales orders |
result.sales_orders[].barcode |
string |
Barcode of item e.g. BARCODE2 |
result.sales_orders[].item_status_id |
integer |
Item status ID see common api sales_order_item_status e.g. 3 |
result.sales_orders[].quantity |
integer |
Quantity of sales order item e.g. 2 |
result.sales_orders[].sales_order_id |
integer |
The sales order ID e.g. 1002 |
result.sales_orders[].status_id |
integer |
The status ID of the sales order see common api sales_order_status e.g. 2 |
result.notifications |
object[] |
Array of sent notifications |
result.notifications[].entity_id |
integer |
Entity ID (usually sales order ID see entity_type_id) e.g. 1002 |
result.notifications[].entity_type_id |
integer |
Entity type see common api entity_types e.g. 7 |
result.notifications[].recipient |
string |
Recipient of message phone number or e-mail address e.g. test@mail.nl |
result.notifications[].status_text |
string |
Status text of the message e.g. succesvol verzonden |
HTTP request
POST /api/v1/supplier/packinglist/process-dropshipment.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
Content-type: application/json; charset=utf-8
Content-length: 172
{
"supplier_id": 2113,
"packinglist_number": "PB23323",
"store_id": 2,
"send_customer_messages": false,
"update_sales_order_status_if_possible": false
}
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 1759
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"error": false,
"error_message": null,
"result": {
"supplier_id": 2113
"packinglist_numbers": [
"PB23323"
],
"articles": [
{
"barcode": "8723823933323",
"stock": 2,
"units_delivered": 4
},
{
"barcode": "54423933323",
"stock": 2,
"units_delivered": 4
}
],
"delivered_objects": [
{
"customer_id": 1006,
"frame_number": "",
"object_id": 10001,
"sales_order_id": 1000
},
{
"customer_id": 1006,
"frame_number": "FR1443433",
"object_id": 10002,
"sales_order_id": null
}
],
"sales_orders": [
{
"barcode": "BARCODE1",
"item_status_id": 3,
"quantity": 1,
"sales_order_id": 1000,
"status_id": 2
},
{
"barcode": "BARCODE2",
"item_status_id": 3,
"quantity": 2,
"sales_order_id": 1002,
"status_id": 2
}
],
"notifications": [
{
"entity_id": 1000,
"entity_type_id": 7,
"recipient": "+3173030050",
"status_text": "succesvol verzonden"
},
{
"entity_id": 1002,
"entity_type_id": 7,
"recipient": "test@mail.nl",
"status_text": "succesvol verzonden"
}
]
}
}
Workshop
Access workshop related information such as trading hours, stores, workshop orders etc.
Scope(s)
resources
Trading hours (object)
| Property | Type | Description |
|---|---|---|
date |
date |
Date e.g. 2023-03-21 |
capacity_minutes |
integer |
Capacity in minutes for online scheduling e.g. 780 |
scheduled_minutes |
integer |
Scheduled workshop orders in minutes e.g. 0 |
available_minutes |
integer |
Available time in workshop for online scheduling duration in minutes e.g. 780 |
day_id |
integer |
Day number in the week Sunday=0 and Saturday =6 e.g. 2 |
week_no |
integer |
Week number e.g. 12 |
is_closed |
boolean |
true if store closed e.g. false |
workshop_trading_hours |
object[] |
Array of trading hours |
workshop_trading_hours[].start |
string |
Start of trading hours e.g. 07:00 |
workshop_trading_hours[].finish |
string |
End of trading hours e.g. 19:45 |
workshop_trading_hours[].duration_minutes |
integer |
Duration of trading hours in minutes e.g. 780 |
availability_per_employee |
object[] |
Availability per employee (since version v2) |
availability_per_employee[].employee_id |
integer |
Employee ID e.g. 56768 (see employees endpoint) |
availability_per_employee[].capacity_minutes |
integer |
The capacity in minutes availble for online scheduling e.g. 302 |
availability_per_employee[].scheduled_minutes |
integer |
The sum of workshop orders total time in minutes e.g. 0 |
availability_per_employee[].available_minutes |
integer |
The available minutes for online scheduling e.g. 302 |
availability_per_employee[].available_slots |
object[] |
List of available time blocks. The blocks are blocked if a workshop order is scheduled. If workshop orders overlap, extra blocks are marked unavailable. |
availability_per_employee[].available_slots[].start |
string |
Start time of available block e.g. 07:30 |
availability_per_employee[].available_slots[].finish |
string |
End time of available block e.g. 20:30 |
availability_per_employee[].available_slots[].duration_minutes |
integer |
The duration of the available block in minutes e.g. 780 (if the employee is not fully available for online scheduling, this time might be higher than available_minutes |
Trading hours
Workshop trading hours for default or specific store
GET
/api/v2/workshop/trading-hours.json?store_id=:store_id&day_count=:day_count
| GET parameter | Type | Description |
|---|---|---|
store_id |
integer |
Store ID to get info for .e.g 2 |
day_count |
integer |
Number of days to retrieve information for e.g. 3 |
Properties
The response is an object with in data the trading hours objects.
HTTP request
GET /api/v2/workshop/trading-hours.json?store_id=1&day_count=2 HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 2224
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"data": [
{
"date": "2024-11-19",
"capacity_minutes": 796,
"scheduled_minutes": 0,
"available_minutes": 796,
"day_id": 2,
"week_no": 47,
"is_closed": false,
"workshop_trading_hours": [
{
"start": "07:30",
"finish": "20:15",
"duration_minutes": 780
}
],
"availability_per_employee": [
{
"employee_id": 56768,
"capacity_minutes": 302,
"scheduled_minutes": 0,
"available_minutes": 302,
"available_slots": [
{
"start": "07:30",
"finish": "20:30",
"duration_minutes": 780
}
]
},
{
"employee_id": 1001,
"capacity_minutes": 494,
"scheduled_minutes": 0,
"available_minutes": 494,
"available_slots": [
{
"start": "07:30",
"finish": "20:30",
"duration_minutes": 780
}
]
}
]
},
{
"date": "2024-11-20",
"capacity_minutes": 780,
"scheduled_minutes": 0,
"available_minutes": 780,
"day_id": 3,
"week_no": 47,
"is_closed": false,
"workshop_trading_hours": [
{
"start": "07:30",
"finish": "20:15",
"duration_minutes": 780
}
],
"availability_per_employee": [
{
"employee_id": 56768,
"capacity_minutes": 780,
"scheduled_minutes": 0,
"available_minutes": 780,
"available_slots": [
{
"start": "07:30",
"finish": "20:30",
"duration_minutes": 780
}
]
},
{
"employee_id": 1001,
"capacity_minutes": 0,
"scheduled_minutes": 0,
"available_minutes": 0,
"available_slots": [
{
"start": "07:30",
"finish": "20:30",
"duration_minutes": 780
}
]
}
]
}
]
}
Trading hours per store
Get the workshop trading hours per store
GET
/api/v2/workshop/trading-hours-per-store.json?day_count=:day_count&offset=:offset
| GET parameter | Type | Description |
|---|---|---|
day_count |
integer |
Number of days to retrieve information for e.g. 3 |
offset |
integer |
Offset given in pagination.next_url pagination e.g. 3 |
Properties
| Property | Type | Description |
|---|---|---|
data[].store_id |
integer |
Store ID e.g. 2 |
data[].store_name |
string |
Store Name e.g. Store 1 |
data[].trading_hours |
object[] |
array of Trading hours objects |
pagination.next_url |
?string |
If there is more data this is the URL to the next API request. |
HTTP request
GET /api/v2/workshop/trading-hours-per-store.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 6075
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"data": [
{
"store_id": 1,
"store_name": "Cycle Store 1",
"trading_hours": [
{
"date": "2024-11-19",
"capacity_minutes": 796,
"scheduled_minutes": 0,
"available_minutes": 796,
"day_id": 2,
"week_no": 47,
"is_closed": false,
"workshop_trading_hours": [
{
"start": "07:30",
"finish": "20:15",
"duration_minutes": 780
}
],
"availability_per_employee": [
{
"employee_id": 56768,
"capacity_minutes": 302,
"scheduled_minutes": 0,
"available_minutes": 302,
"available_slots": [
{
"start": "07:30",
"finish": "20:30",
"duration_minutes": 780
}
]
},
{
"employee_id": 1001,
"capacity_minutes": 494,
"scheduled_minutes": 0,
"available_minutes": 494,
"available_slots": [
{
"start": "07:30",
"finish": "20:30",
"duration_minutes": 780
}
]
}
]
},
{
"date": "2024-11-20",
"capacity_minutes": 780,
"scheduled_minutes": 0,
"available_minutes": 780,
"day_id": 3,
"week_no": 47,
"is_closed": false,
"workshop_trading_hours": [
{
"start": "07:30",
"finish": "20:15",
"duration_minutes": 780
}
],
"availability_per_employee": [
{
"employee_id": 56768,
"capacity_minutes": 780,
"scheduled_minutes": 0,
"available_minutes": 780,
"available_slots": [
{
"start": "07:30",
"finish": "20:30",
"duration_minutes": 780
}
]
},
{
"employee_id": 1001,
"capacity_minutes": 0,
"scheduled_minutes": 0,
"available_minutes": 0,
"available_slots": [
{
"start": "07:30",
"finish": "20:30",
"duration_minutes": 780
}
]
}
]
}
]
},
{
"store_id": 2,
"store_name": "Cycle Store 2",
"trading_hours": [
{
"date": "2024-11-20",
"capacity_minutes": 780,
"scheduled_minutes": 0,
"available_minutes": 780,
"day_id": 3,
"week_no": 47,
"is_closed": false,
"workshop_trading_hours": [
{
"start": "07:30",
"finish": "20:15",
"duration_minutes": 780
}
],
"availability_per_employee": [
{
"employee_id": 526768,
"capacity_minutes": 780,
"scheduled_minutes": 0,
"available_minutes": 780,
"available_slots": [
{
"start": "07:30",
"finish": "20:30",
"duration_minutes": 780
}
]
},
{
"employee_id": 10201,
"capacity_minutes": 0,
"scheduled_minutes": 0,
"available_minutes": 0,
"available_slots": [
{
"start": "07:30",
"finish": "20:30",
"duration_minutes": 780
}
]
}
]
}
]
},
{
"store_id": 3,
"store_name": "DC",
"trading_hours": []
}
],
"pagination": {
"next_url": null
}
}
Repair codes
Get list of repair codes
GET
/api/v1/workshop/repair-codes.json
Repair code (object)
| Property | Type | Description |
|---|---|---|
code_id |
integer |
ID of repair code e.g. 90753 |
category |
string |
Category name e.g. Accu |
code |
string |
Code e.g. 999 |
description |
string |
Description e.g. Test Title |
extra_text |
string |
Description extra e.g. Omschrijving |
price_cents |
?integer |
Price in cents or null e.g. 12000 |
time_minutes |
integer |
Time in minutes required for code e.g. 60 |
workshop_rate_id |
integer |
Workshop rate see common api workshop_rates e.g. 1 |
vat_code |
integer |
Vat code see common api vat_codes e.g. 1 |
The result will return a list of Repair code (object)
HTTP request
GET /api/v1/workshop/repair-codes.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 278
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
[
{
"code_id": 90753,
"category": "Accu",
"code": "999",
"description": "Test Title",
"extra_text": "Omschrijving",
"price_cents": 12000,
"time_minutes": 60,
"workshop_rate_id": 1,
"vat_code": 1
},
{
"code_id": 90753,
"category": "Frame",
"code": "222",
"description": "Test Title",
"extra_text": "Omschrijving",
"price_cents": null,
"time_minutes": 60,
"workshop_rate_id": 1,
"vat_code": 1
}
]
Workshop orders
Read, create or update workshop orders
Scope(s)
resources
Workshop order (object)
| Property | Type | Description | |
|---|---|---|---|
workshop_order_id |
integer |
readonly |
Workshop order ID e.g. 978070 |
sales_order_id |
integer |
readonly |
Sales order ID e.g. 978070 |
customer_id |
integer |
POST |
Customer ID e.g. 24 |
store_id |
integer |
POST |
Store ID e.g. 1 |
repair_object_id |
integer |
POST |
Repair object ID e.g. 1105 |
is_active |
boolean |
POST|PUT |
If deleted false |
reference_text |
string |
POST |
Own reference e.g. work_number |
datetime_scheduled_start |
datetime |
POST|PUT |
Scheduled start e.g. 2023-03-07 12:13:47 |
datetime_scheduled_finished |
datetime |
readonly |
Scheduled finished e.g. 2023-03-07 12:43:47 |
datetime_created |
datetime |
readonly |
Created at e.g. 2023-03-07 12:13:47 |
datetime_modified |
datetime |
readonly |
Modified at e.g. 2023-03-07 12:13:47 |
mechanic_employee_id |
integer |
POST|PUT |
Employee ID of mechanic (see common employees) e.g. 12 |
created_by_employee_id |
integer |
POST |
Created by employee ID (see common employees) e.g. 1 |
last_update_employee_id |
integer |
POST |
Last update by employee ID (see common employees) e.g. 1 |
phone_number_id |
string |
POST |
Phone number ID for communication e.g. tel |
repair_description |
string |
POST |
Description of repair e.g. posted repair |
status_id |
integer |
POST |
Status see common enum workshop_order_status e.g. 7 |
status_text |
string |
readonly |
Status text see common enum workshop_order_status e.g. Reparatie voltooid |
invoice_number |
integer |
readonly |
Sales transaction / invoice number 0 if not invoiced |
borrowed_object_reference |
string |
POST|PUT |
Borrowed object reference |
total_repair_time_minutes |
integer |
readonly |
Total repair time scheduled in minutes e.g. 30 |
custom_repair_time_minutes |
integer |
POST |
Custom repair time (total time - repair codes time) e.g. 30 |
repair_codes |
?string[] |
POST |
On create a list of repair codes. See Repair codes (object) code |
service_card_codes |
?string[] |
POST |
On create a list of service-item codes. See Service item (object) service_barcode |
delivery_method_id |
integer |
POST|PUT |
Delivery method see common enum delivery_methods e.g. 0 |
workshop_order_type_id |
integer |
readonly |
Workshop order type id see common enum workshop_order_types e.g. 1 |
order_items |
?array |
POST|PUT |
Array of order items |
order_items[].item_id |
integer |
readonly |
Unique item id within the order e.g. 2 |
order_items[].item_type_id |
integer |
POST|PUT |
Order item type see common enum transaction_item_types e.g. 1 |
order_items[].special_type_id |
integer |
POST|PUT |
Related id for example object id e.g. 0 |
order_items[].quantity |
integer |
POST|PUT |
Quantity e.g. 1 |
order_items[].barcode |
string |
POST|PUT |
Barcode of item e.g. 102 |
order_items[].pos_group_id |
integer |
POST|PUT |
POS group see common enum pos_groups e.g. 2 |
order_items[].description |
string |
POST|PUT |
Description of item e.g. In- en uitbouwen electromotor in- en uitbouwen accu |
order_items[].unit_price_in_vat_cents |
integer |
POST|PUT |
Gross unit price including vat in cents e.g. 9000 |
order_items[].unit_discount_amount_in_vat_cents |
integer |
POST|PUT |
Unit discount amount including VAT in cents e.g. 0 |
order_items[].price_in_vat_cents |
integer |
POST|PUT |
Line price including VAT in cents e.g. 9000 |
order_items[].discount_percentage |
decimal |
POST|PUT |
Discount percentage e.g. 0 |
order_items[].vat_code |
integer |
POST|PUT |
Vat code see common enum vat_codes e.g. 1 |
order_items[].vat_percentage |
integer |
readonly |
Vat percentage e.g. 9 |
order_items[].vat_amount_cents |
integer |
readonly |
Line vat amount in cents e.g. 743 |
order_items[].item_status_id |
integer |
POST|PUT |
Status ID of item see common enum sales_order_item_status e.g. 0 |
order_items[].item_status_text |
string |
readonly |
Status text of item see common enum sales_order_item_status e.g. Geen status |
order_items[].unit_work_time_minutes |
integer |
POST|PUT |
Unit of work time in minutes e.g. 0 |
order_items[].assigned_to_customer_id |
integer |
POST|PUT |
The customer ID which will receive the e.g. 1006 (Split order / invoicing) |
order_items[].invoice_number |
?integer |
readonly |
Invoice number when invoice is created e.g. 20230303 |
List workshop orders
List workshop orders for a specific customer
@TODO
Get workshop order
Get workshop order
HTTP request
GET /api/v1/customers/24/workshop-order/978768.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 2814
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"workshop_order_id": 978768,
"sales_order_id": 978768,
"customer_id": 24,
"store_id": 1,
"repair_object_id": 1105,
"is_active": true,
"reference_text": "work_number",
"datetime_scheduled_start": "2023-03-07 16:54:23",
"datetime_scheduled_finished": "2023-03-07 17:54:23",
"datetime_created": "2023-03-07 16:54:23",
"datetime_modified": "2023-03-07 16:54:23",
"mechanic_employee_id": 12,
"created_by_employee_id": 1,
"last_update_employee_id": 1,
"phone_number_id": "tel",
"repair_description": "posted repair",
"status_id": 7,
"status_text": "Reparatie voltooid",
"invoice_number": 0,
"borrowed_object_reference": "",
"total_repair_time_minutes": 60,
"custom_repair_time_minutes": 0,
"delivery_method_id": 0,
"workshop_order_type_id": 1,
"order_items": [
{
"item_id": 1,
"item_type_id": 4,
"special_type_id": 0,
"quantity": 1,
"barcode": "102",
"pos_group_id": 2,
"description": "In- en uitbouwen electromotor in- en uitbouwen accu",
"unit_price_in_vat_cents": 9000,
"unit_discount_amount_in_vat_cents": 0,
"price_in_vat_cents": 9000,
"discount_percentage": 0,
"vat_code": 1,
"vat_percentage": 9,
"vat_amount_cents": 743,
"item_status_id": 0,
"item_status_text": "Geen status",
"unit_work_time_minutes": 0,
"assigned_to_customer_id": 24
},
{
"item_id": 2,
"item_type_id": 1,
"special_type_id": 0,
"quantity": 1,
"barcode": "102",
"pos_group_id": 2,
"description": "In- en uitbouwen electromotor in- en uitbouwen accu",
"unit_price_in_vat_cents": 9000,
"unit_discount_amount_in_vat_cents": 0,
"price_in_vat_cents": 9000,
"discount_percentage": 0,
"vat_code": 1,
"vat_percentage": 9,
"vat_amount_cents": 743,
"item_status_id": 0,
"item_status_text": "Geen status",
"unit_work_time_minutes": 0,
"assigned_to_customer_id": 24
},
{
"item_id": 3,
"item_type_id": 4,
"special_type_id": 0,
"quantity": 1,
"barcode": "999",
"pos_group_id": 2,
"description": "Test Title",
"unit_price_in_vat_cents": 12000,
"unit_discount_amount_in_vat_cents": 0,
"price_in_vat_cents": 12000,
"discount_percentage": 0,
"vat_code": 1,
"vat_percentage": 9,
"vat_amount_cents": 991,
"item_status_id": 0,
"item_status_text": "Geen status",
"unit_work_time_minutes": 60,
"assigned_to_customer_id": 24
}
]
}
Create workshop order
Create a workshop order
HTTP request
POST /api/v1/customers/24/workshop-order.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
Content-type: application/json; charset=utf-8
Content-length: 2814
{
"customer_id": 24,
"store_id": null,
"repair_object_id": 1105,
"is_active": true,
"reference_text": "work_number",
"datetime_scheduled_start": "2023-03-07T16:56:32+01:00",
"datetime_scheduled_finished": null,
"datetime_created": null,
"datetime_modified": null,
"mechanic_employee_id": 12,
"created_by_employee_id": null,
"last_update_employee_id": null,
"phone_number_id": "tel",
"repair_description": "posted repair",
"status_id": 7,
"status_text": null,
"invoice_number": null,
"borrowed_object_reference": null,
"total_repair_time_minutes": null,
"custom_repair_time_minutes": null,
"delivery_method_id": 0,
"repair_codes": [
"999"
],
"service_card_codes": [],
"order_items": [
{
"item_id": 1,
"item_type_id": 4,
"special_type_id": 0,
"quantity": 1,
"barcode": "102",
"pos_group_id": 2,
"description": "In- en uitbouwen electromotor in- en uitbouwen accu",
"unit_price_in_vat_cents": 9000,
"unit_discount_amount_in_vat_cents": 0,
"price_in_vat_cents": 9000,
"discount_percentage": 0,
"vat_code": 1,
"vat_percentage": 6,
"vat_amount_cents": 509,
"item_status_id": 0,
"item_status_text": "Geen status",
"unit_work_time_minutes": 0
},
{
"item_id": 2,
"item_type_id": 1,
"special_type_id": 0,
"quantity": 1,
"barcode": "102",
"pos_group_id": 2,
"description": "In- en uitbouwen electromotor in- en uitbouwen accu",
"unit_price_in_vat_cents": 9000,
"unit_discount_amount_in_vat_cents": 0,
"price_in_vat_cents": 9000,
"discount_percentage": 0,
"vat_code": 1,
"vat_percentage": 6,
"vat_amount_cents": 509,
"item_status_id": 0,
"item_status_text": "Geen status",
"unit_work_time_minutes": 0
}
]
}
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 2814
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"workshop_order_id": 978768,
"sales_order_id": 978768,
"customer_id": 24,
"store_id": 1,
"repair_object_id": 1105,
"is_active": true,
"reference_text": "work_number",
"datetime_scheduled_start": "2023-03-07 16:54:23",
"datetime_scheduled_finished": "2023-03-07 17:54:23",
"datetime_created": "2023-03-07 16:54:23",
"datetime_modified": "2023-03-07 16:54:23",
"mechanic_employee_id": 12,
"created_by_employee_id": 1,
"last_update_employee_id": 1,
"phone_number_id": "tel",
"repair_description": "posted repair",
"status_id": 7,
"status_text": "Reparatie voltooid",
"invoice_number": 0,
"borrowed_object_reference": "",
"total_repair_time_minutes": 60,
"custom_repair_time_minutes": 0,
"delivery_method_id": 0,
"workshop_order_type_id": 1,
"order_items": [
{
"item_id": 1,
"item_type_id": 4,
"special_type_id": 0,
"quantity": 1,
"barcode": "102",
"pos_group_id": 2,
"description": "In- en uitbouwen electromotor in- en uitbouwen accu",
"unit_price_in_vat_cents": 9000,
"unit_discount_amount_in_vat_cents": 0,
"price_in_vat_cents": 9000,
"discount_percentage": 0,
"vat_code": 1,
"vat_percentage": 9,
"vat_amount_cents": 743,
"item_status_id": 0,
"item_status_text": "Geen status",
"unit_work_time_minutes": 0
},
{
"item_id": 2,
"item_type_id": 1,
"special_type_id": 0,
"quantity": 1,
"barcode": "102",
"pos_group_id": 2,
"description": "In- en uitbouwen electromotor in- en uitbouwen accu",
"unit_price_in_vat_cents": 9000,
"unit_discount_amount_in_vat_cents": 0,
"price_in_vat_cents": 9000,
"discount_percentage": 0,
"vat_code": 1,
"vat_percentage": 9,
"vat_amount_cents": 743,
"item_status_id": 0,
"item_status_text": "Geen status",
"unit_work_time_minutes": 0
},
{
"item_id": 3,
"item_type_id": 4,
"special_type_id": 0,
"quantity": 1,
"barcode": "999",
"pos_group_id": 2,
"description": "Test Title",
"unit_price_in_vat_cents": 12000,
"unit_discount_amount_in_vat_cents": 0,
"price_in_vat_cents": 12000,
"discount_percentage": 0,
"vat_code": 1,
"vat_percentage": 9,
"vat_amount_cents": 991,
"item_status_id": 0,
"item_status_text": "Geen status",
"unit_work_time_minutes": 60
}
]
}
Update workshop order
Update a workshop order
HTTP request
PUT /api/v1/customers/24/workshop-order/397876.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic
Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
Content-type: application/json; charset=utf-8
Content-length: 2237
{
"is_active": true,
"datetime_scheduled_start": "2020-03-13 18:15:45",
"mechanic_employee_id": 12,
"borrowed_object_reference": "",
"total_repair_time_minutes": 30,
"delivery_method_id": 0,
"order_items": [
{
"item_id": 1,
"item_type_id": 4,
"special_type_id": 0,
"quantity": 1,
"barcode": "102",
"pos_group_id": 2,
"description": "In- en uitbouwen electromotor in- en uitbouwen accu",
"unit_price_in_vat_cents": 9000,
"unit_discount_amount_in_vat_cents": 0,
"price_in_vat_cents": 9000,
"discount_percentage": 0,
"vat_code": 1,
"vat_percentage": 9,
"vat_amount_cents": 743,
"item_status_id": 0,
"item_status_text": "Geen status",
"unit_work_time_minutes": 0
},
{
"item_id": 2,
"item_type_id": 1,
"special_type_id": 0,
"quantity": 1,
"barcode": "102",
"pos_group_id": 2,
"description": "In- en uitbouwen electromotor in- en uitbouwen accu",
"unit_price_in_vat_cents": 9000,
"unit_discount_amount_in_vat_cents": 0,
"price_in_vat_cents": 9000,
"discount_percentage": 0,
"vat_code": 1,
"vat_percentage": 9,
"vat_amount_cents": 743,
"item_status_id": 0,
"item_status_text": "Geen status",
"unit_work_time_minutes": 0
}
]
}
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 2237
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"workshop_order_id": 397876,
"sales_order_id": 397876,
"customer_id": 24,
"store_id": 1,
"repair_object_id": 1105,
"is_active": true,
"reference_text": "work_number",
"datetime_scheduled_start": "2020-03-13 18:15:45",
"datetime_scheduled_finished": "2020-03-13 18:45:45",
"datetime_created": "2020-03-13 18:15:44",
"datetime_modified": "2023-03-07 16:48:43",
"mechanic_employee_id": 12,
"created_by_employee_id": 1,
"last_update_employee_id": 1,
"phone_number_id": "tel",
"repair_description": "64075cdc1db73",
"status_id": 7,
"status_text": "Reparatie voltooid",
"invoice_number": 0,
"borrowed_object_reference": "",
"total_repair_time_minutes": 30,
"custom_repair_time_minutes": 30,
"delivery_method_id": 0,
"workshop_order_type_id": 1,
"order_items": [
{
"item_id": 1,
"item_type_id": 4,
"special_type_id": 0,
"quantity": 1,
"barcode": "102",
"pos_group_id": 2,
"description": "In- en uitbouwen electromotor in- en uitbouwen accu",
"unit_price_in_vat_cents": 9000,
"unit_discount_amount_in_vat_cents": 0,
"price_in_vat_cents": 9000,
"discount_percentage": 0,
"vat_code": 1,
"vat_percentage": 9,
"vat_amount_cents": 743,
"item_status_id": 0,
"item_status_text": "Geen status",
"unit_work_time_minutes": 0
},
{
"item_id": 2,
"item_type_id": 1,
"special_type_id": 0,
"quantity": 1,
"barcode": "102",
"pos_group_id": 2,
"description": "In- en uitbouwen electromotor in- en uitbouwen accu",
"unit_price_in_vat_cents": 9000,
"unit_discount_amount_in_vat_cents": 0,
"price_in_vat_cents": 9000,
"discount_percentage": 0,
"vat_code": 1,
"vat_percentage": 9,
"vat_amount_cents": 743,
"item_status_id": 0,
"item_status_text": "Geen status",
"unit_work_time_minutes": 0
}
]
}
Vouchers
Read vouchers
Scope(s)
resources
Voucher (object)
| Property | Type | Description |
|---|---|---|
error |
boolean |
true if an error occurred. |
error_message |
?string |
Error message if occurred. |
data.code |
string |
Voucher code e.g. 5455-7407-8042-8985 |
data.type_id |
integer |
Voucher type ID e.g. 1 (see voucher_types in common enum API) |
data.type_description |
string |
Voucher type description Waardebon |
data.is_active |
boolean |
false if the voucher is not useable |
data.amount_initial_cents |
integer |
The amount in cents when the voucher was issued 2000 |
data.amount_spent_cents |
integer |
The amount in cents spent for the voucher 1500 |
data.amount_balance_cents |
integer |
The amount which can be used in cents e.g. 500 |
Voucher info
Get voucher by code
GET
/api/v1/vouchers/:code.json
| URI parameter | Type | Description |
|---|---|---|
code |
string |
The voucher code ID e.g. 1000-2000-3000-4000 |
HTTP request
GET /api/v1/vouchers/1000-2000-3000-4000.json HTTP/1.1
Host: api.cyclesoftware.nl
Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=
Accept-encoding: gzip
Accept: application/json
HTTP Response
HTTP/1.1 200
Content-type: application/json; charset=utf-8
Content-length: 309
X-RateLimit-Minutely-Limit: 360
X-RateLimit-Minutely-Remaining: 59
X-RateLimit-Daily-Limit: 15000
X-RateLimit-Daily-Remaining: 14999
X-RateLimit-Daily-Reset: 1678230000
{
"error": false,
"error_message": null,
"data": {
"code": "1000-2000-3000-4000",
"type_id": 1,
"type_description": "Waardebon",
"is_active": true,
"amount_initial_cents": 2000,
"amount_spent_cents": 1500,
"amount_balance_cents": 500
}
}
Webhooks
Receive updates from CycleSoftware for specific entities.
Webhook request
The payload is a raw POST of a JSON string to your server. Several headers are included:
| Header | Description |
|---|---|
X-CycleSoftware-Delivery |
Unique UUID of the webhook message. Same value JSON id property |
X-CycleSoftware-Event |
Event name. Same value as JSON event_name property |
X-CycleSoftware-Signature |
HMAC of the payload using your hash secret |
Payload structure
Every JSON payload has the same structure. The payload object is different per event.
| Property | Type | Description |
|---|---|---|
id |
uuid |
Unique webhook UUID 20c5d026-68b3-11ec-90d6-0242ac120003 |
account_id |
integer |
Account ID CycleSoftware 1 |
event_name |
string |
The event-name e.g. sales_order.created |
event_timestamp |
float |
Timestamp when the message was created. 1640787926.323 |
payload |
object |
The actual payload of the event |
Payload structure
{
"id": "20c5d026-68b3-11ec-90d6-0242ac120003",
"account_id": 1,
"event_name": "event.sub_name",
"event_timestamp": 1640787926.323,
"payload": {}
}
Customers
| Event name | Description |
|---|---|
customer.created |
Fired when the customer is created |
customer.updated |
Fired when the customer is updated |
Properties
| Property | Type | Description |
|---|---|---|
customer.customer_barcode |
string |
(deprecated) Reference of the customer e.g. REF1212 |
customer.prefix |
string |
(deprecated) Name prefix e.g. Dhr./Mevr. |
customer.country |
string |
(deprecated) Country (deprecated) see country_code_iso_3166 e.g. NL |
customer.name_prefix |
?string |
(deprecated) |
customer.iban |
string |
IBAN bank account |
customer.customer_id |
integer |
Customer ID e.g. 6667 |
customer.customer_type_name |
string |
Customer type see common enum e.g. Klant |
customer.customer_reference |
string |
Customer reference e.g. REF1212 |
customer.postcode |
string |
Postal code e.g. 1000AA |
customer.house_number |
string |
Housenumber e.g. 2522 |
customer.house_number_postfix |
string |
Housenumber postfix e.g. B |
customer.attn |
string |
Attention of e.g. Name of person |
customer.title |
string |
Title of customer e.g. Dhr./Mevr. |
customer.first_name |
string |
Initials e.g. Adri |
customer.initials |
string |
Initials e.g. C.G. |
customer.insertion |
string |
Name insertion e.g. van |
customer.name |
string |
(Sur)name e.g. Wijk |
customer.street |
string |
Street name e.g. Aalsburg |
customer.city |
string |
City name e.g. Amsterdam |
customer.country_code_iso_3166 |
string |
Country code e.g. NL |
customer.email |
string |
Customer E-mail e.g. test@test.nl |
customer.discount_percentage |
integer |
Default discount percentage e.g. 0 |
customer.datetime_created |
?string |
datetime created if known (null if unknown) |
customer.phone_numbers |
object[] |
array of phone numbers |
customer.phone_numbers[].phone_number_id |
string |
ID mob, tel or stringed ID e.g. 10589 |
customer.phone_numbers[].customer_id |
integer |
Customer ID 6667 |
customer.phone_numbers[].phone_number |
string |
Phone number 06-12345678 |
customer.phone_numbers[].name |
string |
Name associated with the phone number e.g. Sjaak |
Payload structure
{
"id": "5e2435ef-bd25-4399-9332-2a8d3c9e5830",
"account_id": 1,
"event_name": "customer.updated",
"event_timestamp": 1677599374.04,
"payload": {
"customer": {
"customer_id": 20,
"customer_type_name": "Lease-rijder",
"customer_reference": "600008000011700",
"postcode": "9999AA",
"house_number": "132",
"house_number_postfix": "a",
"attn": "",
"title": "Dhr.",
"initials": "P",
"insertion": "van",
"first_name": "Peter",
"name": "Wijk",
"street": "Hoogheem",
"city": "Boxtel",
"country_code_iso_3166": "AF",
"email": "email20@example.nl",
"discount_percentage": 0,
"datetime_created": "2023-02-12 12:30:44",
"phone_numbers": [
{
"phone_number_id": "mob",
"customer_id": 20,
"phone_number": "",
"name": "Peter van Wijk"
},
{
"phone_number_id": "tel",
"customer_id": 20,
"phone_number": "09-10000020",
"name": "Peter van Wijk"
},
{
"phone_number_id": "75189",
"customer_id": 20,
"phone_number": "09-10075189",
"name": "Peter van Wijk alternatief"
}
],
"customer_barcode": "600008000011700",
"prefix": "Dhr.",
"country": "AF",
"name_prefix": null,
"iban": "NL00BANK1000000020",
"date_of_birth": "1992-11-22"
}
}
}
Sales orders
| Event name | Description |
|---|---|
sales_order.created |
Fired when the sales order is created |
sales_order.updated |
Fired when the sales order is updated |
sales_order.deleted |
Fired when the sales order is marked as deleted |
sales_order.invoiced |
Fired when the sales order is invoiced (sales transaction created) |
Properties
| Property | Type | Description | |
|---|---|---|---|
sales_order_id |
integer |
Sales Order ID e.g. 1442 |
|
store_id |
integer |
Store ID within account e.g. 1 |
|
sales_employee_id |
integer |
Employee ID see common employees e.g. 1619 |
|
last_update_employee_id |
?integer |
Last update by employee ID e.g. 1619 |
|
customer_id |
integer |
Customer ID e.g. 6667 |
|
order_type_id |
integer |
Order type ID, see common enum e.g. 3 |
|
order_type_text |
string |
Order type text, see common enum Order |
|
order_reference_id |
string |
Order reference ID 12212 |
|
order_reference_text |
string |
Order reference text REF12212 |
|
datetime_created |
datetime |
Created at e.g. 2013-09-05 12:00:00 |
|
datetime_modified |
datetime |
Modified at e.g. 2022-04-20 12:29:23 |
|
datetime_preferred_delivery |
?date |
Date of preferred delivery e.g. 2022-04-20 or null |
|
datetime_preferred_pickup |
?date |
Date of preferred pickup e.g. 2022-04-20 or null |
|
status_id |
integer |
Sales order status id see common enum e.g. 2 |
|
status_text |
string |
Sales order status text see common enum e.g. In behandeling |
|
cancellation_type_id |
integer |
Cancellation type id see common enum e.g. 0 |
|
cancellation_description |
?string |
Cancellation type description see common enum | |
remarks |
string |
Order remarks Omschrijving 1 |
|
has_invoice |
boolean |
True if invoice is associcated with order e.g. false |
|
invoice_number |
integer |
Invoice number if present 0 |
|
ship_to_customer |
boolean |
True if should ship to customer false (deprecated) |
|
delivery_method_id |
integer |
Delivery method ID see common enum e.g. 0 |
|
delivery_method_description |
string |
Delivery method description see common enum e.g. Afhalen in winkel |
|
shipment_method_description |
string |
Free description of shipment e.g. VERZENDEN |
|
payment_method_description |
string |
Free description of shipment e.g. IDEAL |
|
order_items |
object[] |
List of order items | |
order_items[].item_id |
integer |
ID of item within the order e.g. 2 |
|
order_items[].item_type_id |
integer |
Item type ID see common enum e.g. 1 |
|
order_items[].special_type_id |
integer |
ID if associated object if present e.g. 0 |
|
order_items[].quantity |
integer |
Quantity e.g. 1 |
|
order_items[].barcode |
string |
Barcode of item e.g. 4008496261628 |
|
order_items[].pos_group_id |
integer |
POS group see common enum e.g. 11 |
|
order_items[].description |
string |
Description of item e.g. VARTA BATTERIE 12V38MAH V23GA |
|
order_items[].unit_price_in_vat_cents |
integer |
Gross unit price in cents 225 |
|
order_items[].unit_discount_amount_in_vat_cents |
integer |
Unit discount in cents e.g. 0 |
|
order_items[].price_in_vat_cents |
integer |
Line price in cents e.g. 225 |
|
order_items[].discount_percentage |
integer |
Discount percentage e.g. 0 |
|
order_items[].vat_code |
integer |
VAT code see common enum e.g. 2 |
|
order_items[].vat_percentage |
integer |
VAT percentage e.g. 21 |
|
order_items[].vat_amount_cents |
integer |
VAT amount in cents e.g. 39 |
|
order_items[].item_status_id |
integer |
Item status ID see common enum e.g. 0 |
|
order_items[].item_status_text |
string |
Item status text see common enum e.g. Geen status |
|
order_items[].unit_work_time_minutes |
integer |
Work time for item in minutes e.g. 0 |
|
order_items[].assigned_to_customer_id |
integer |
The customer ID which will be invoiced e.g. 1006 (also see order_item_invoice_customer_id in SaveOrder) |
|
order_items[].invoice_number |
?integer |
The invoice number if invoiced e.g. 2993 not present if no invoice exists |
|
cancelled_order_items |
?object[] |
List of cancelled / non-deleted order items (same structure as order_items |
|
deleted_order_items |
?object[] |
List of deleted order items (same structure as order_items, only present once in webhook |
|
customer |
object |
See customers webhook definition | |
delivery_address |
?object |
Delivery address if specified, null if not specified |
|
delivery_address.delivery_address_id |
integer |
Delivery address ID e.g. 91953 |
|
delivery_address.customer_id |
integer |
Customer ID e.g. 6667 |
|
delivery_address.is_business |
boolean |
If business address true |
|
delivery_address.company_name |
string |
Company name if specified | |
delivery_address.name |
string |
Name of customer Name 91953 |
|
delivery_address.street |
string |
Street name e.g. Slangenburg |
|
delivery_address.housenumber |
string |
House number e.g. 314 |
|
delivery_address.housenumber_postfix |
string |
House number postfix B |
|
delivery_address.postcode |
string |
Postcode e.g. 8888ZZ |
|
delivery_address.city |
string |
City Deventer |
|
delivery_address.country |
string |
Deprecated, filled with country code NL |
|
delivery_address.country_code_iso_3166 |
string |
ISO 3166 Country code e.g. NL |
|
delivery_address.phone_number |
string |
Phone number associated with address 06 12345678 |
|
delivery_address.email |
string |
E-mail associated with address email91953@example.nl |
|
delivery_address.remarks |
string |
Remarks for address Some text |
|
labels[] |
string[] |
Label associated with the sales order e.g. ["label1"] |
Payload structure
{
"id": "2f4de380-f2be-4143-bbdf-1174c5d47991",
"account_id": 1,
"event_name": "sales_order.updated",
"event_timestamp": 1650450563.309,
"payload": {
"sales_order_id": 1442,
"store_id": 1,
"sales_employee_id": 1323,
"last_update_employee_id": 1323,
"customer_id": 6667,
"order_type_id": 3,
"order_type_text": "Order",
"order_reference_id": "",
"order_reference_text": "",
"datetime_created": "2013-09-05 12:00:00",
"datetime_modified": "2022-04-20 12:29:23",
"datetime_preferred_delivery": null,
"datetime_preferred_pickup": null,
"status_id": 2,
"status_text": "In behandeling",
"cancellation_type_id": 0,
"cancellation_description": null,
"remarks": "Omschrijving 1",
"has_invoice": false,
"invoice_number": 0,
"ship_to_customer": false,
"delivery_method_id": 0,
"delivery_method_description": "Afhalen in winkel",
"shipment_method_description": "",
"payment_method_description": "",
"order_items": [
{
"item_id": 1,
"item_type_id": 1,
"special_type_id": 0,
"quantity": 1,
"barcode": "8715434065984",
"pos_group_id": 11,
"description": "BOBAG BOBIKE ROZE MOTIEF PRETTY PEONI (BLAUW)",
"unit_price_in_vat_cents": 5995,
"unit_discount_amount_in_vat_cents": 0,
"price_in_vat_cents": 5995,
"discount_percentage": 0,
"vat_code": 2,
"vat_percentage": 21,
"vat_amount_cents": 1040,
"item_status_id": 0,
"item_status_text": "Geen status",
"unit_work_time_minutes": 0,
"assigned_to_customer_id": 6667
},
{
"item_id": 2,
"item_type_id": 1,
"special_type_id": 0,
"quantity": 1,
"barcode": "4008496261628",
"pos_group_id": 11,
"description": "VARTA BATTERIE 12V38MAH V23GA",
"unit_price_in_vat_cents": 225,
"unit_discount_amount_in_vat_cents": 0,
"price_in_vat_cents": 225,
"discount_percentage": 0,
"vat_code": 2,
"vat_percentage": 21,
"vat_amount_cents": 39,
"item_status_id": 0,
"item_status_text": "Geen status",
"unit_work_time_minutes": 0,
"assigned_to_customer_id": 6667
}
],
"customer": {
"customer_barcode": "",
"prefix": "Dhr./Mevr. ",
"country": "",
"name_prefix": null,
"iban": "",
"customer_id": 6667,
"customer_type_name": "Klant",
"customer_reference": "",
"postcode": "1000AA",
"house_number": "2522",
"house_number_postfix": "",
"attn": "",
"title": "Dhr./Mevr. ",
"first_name": "Carlo",
"initials": "C.G.",
"insertion": "van",
"name": "Wijk",
"street": "Aalsburg",
"city": "Amsterdam",
"country_code_iso_3166": "",
"email": "test@test.nl",
"discount_percentage": 0,
"datetime_created": null,
"phone_numbers": [
{
"phone_number_id": "mob",
"customer_id": 6667,
"phone_number": "",
"name": "Dhr./Mevr. C.G. van Wijk"
},
{
"phone_number_id": "tel",
"customer_id": 6667,
"phone_number": "000-1231231",
"name": "Dhr./Mevr. C.G. van Wijk"
},
{
"phone_number_id": "10589",
"customer_id": 6667,
"phone_number": "06-12345678",
"name": "Sjaak"
}
]
},
"delivery_address": {
"delivery_address_id": 91953,
"customer_id": 6667,
"is_business": false,
"company_name": "",
"name": "Name 91953",
"street": "Slangenburg",
"housenumber": "314",
"housenumber_postfix": "B",
"postcode": "8888ZZ",
"city": "Deventer",
"country": "NL",
"country_code_iso_3166": "NL",
"phone_number": "06 12345678",
"email": "email91953@example.nl",
"remarks": "Some text"
},
"labels": [
"label1"
]
}
}
Workshop orders
| Event name | Description |
|---|---|
workshop_order.created |
Fired when the workshop order / repair is created |
workshop_order.updated |
Fired when the workshop order / repair is updated |
workshop_order.deleted |
Fired when the workshop order / repair is marked as deleted |
Properties
| Property | Type | Description |
|---|---|---|
workshop_order_id |
integer |
Workshop order ID e.g. 50032 |
repair_object_id |
integer |
Repair object ID e.g. 22534 |
reference_text |
string |
Reference of order RefText |
datetime_scheduled_start |
datetime |
Scheduled start 2019-06-07 14:30:00 |
datetime_scheduled_finished |
datetime |
Scheduled finished 2019-06-07 16:10:00 |
mechanic_employee_id |
integer |
Assigned to mechanic see common employees 40899 |
repair_description |
string |
Description of workshop order Band plakken |
status_id |
integer |
Workshop order status ID see common enum e.g. 7 |
status_text |
string |
Workshop order status see common enum e.g. Reparatie voltooid |
borrowed_object_reference |
string |
Reference to borrowed object BORROWEDBIKE1 |
total_repair_time_minutes |
integer |
Total time of repair in minutes e.g. 100 (Custom time + items) |
custom_repair_time_minutes |
integer |
Custom time of repair in minutes e.g. 0 |
sales_order |
object |
See structure of sales order webhook ` |
Payload example
{
"id": "34a9759f-3da7-424c-8bd8-1ce3eb22fce8",
"account_id": 1,
"event_name": "workshop_order.updated",
"event_timestamp": 1649336612.447,
"payload": {
"workshop_order_id": 50032,
"repair_object_id": 22534,
"reference_text": "RefText",
"datetime_scheduled_start": "2019-06-07 14:30:00",
"datetime_scheduled_finished": "2019-06-07 16:10:00",
"mechanic_employee_id": 40899,
"repair_description": "Band plakken",
"status_id": 7,
"status_text": "Reparatie voltooid",
"borrowed_object_reference": "",
"total_repair_time_minutes": 100,
"custom_repair_time_minutes": 0,
"sales_order": {
"sales_order_id": 50032,
"store_id": 1,
"sales_employee_id": 1001,
"last_update_employee_id": 1001,
"customer_id": 6776,
"order_type_id": 6,
"order_type_text": "Reparatie",
"order_reference_id": "12122",
"order_reference_text": "RefText",
"datetime_created": "2019-05-22 13:45:37",
"datetime_modified": "2020-08-12 15:51:57",
"datetime_preferred_delivery": null,
"datetime_preferred_pickup": null,
"status_id": 9,
"status_text": "Afgerond",
"cancellation_type_id": 0,
"cancellation_description": null,
"remarks": "Opmerking",
"has_invoice": true,
"invoice_number": 20173328,
"ship_to_customer": false,
"delivery_method_id": 0,
"delivery_method_description": "Afhalen in winkel",
"shipment_method_description": "",
"payment_method_description": "",
"order_items": [],
"customer": {
"customer_barcode": "",
"prefix": "",
"country": "NL",
"name_prefix": null,
"iban": "",
"customer_id": 6776,
"customer_type_name": "Klant",
"customer_reference": "",
"postcode": "1000AA",
"house_number": "1",
"house_number_postfix": "B",
"attn": "",
"title": "",
"first_name": "Jan",
"initials": "",
"insertion": "Van",
"name": "Wijk",
"street": "",
"city": "",
"country_code_iso_3166": "NL",
"email": "test@cyclesoftware.nl",
"discount_percentage": 0,
"datetime_created": null,
"phone_numbers": [
{
"phone_number_id": "mob",
"customer_id": 6776,
"phone_number": "0612345678",
"name": "Van Wijk"
},
{
"phone_number_id": "226441",
"customer_id": 6776,
"phone_number": "0612345679",
"name": "Extra Richard"
}
]
},
"delivery_address": null,
"labels": [
"label1"
]
}
}
}
Sales transactions / invoices
| Event name | Description |
|---|---|
sales_transaction.created |
Fired when the sales transaction / invoice is created |
sales_transaction.updated |
Fired when the sales transaction / invoice is updated |
Properties
| Property | Type | Description |
|---|---|---|
invoice_number |
integer |
Sales transaction number / invoice number e.g. 20210048 |
credit_invoice_number |
?integer |
If this transaction is credited the credit invoice number e.g. 20210049 |
debit_invoice_number |
?integer |
If this transaction is a credit the original invoice number e.g. 20210047 |
is_final |
boolean |
True if the transaciton is booked false |
customer_id |
integer |
Customer ID e.g. 1006 for anonymous 0 |
store_id |
integer |
Store ID within account 1 |
sales_employee_id |
integer |
Employee ID e.g. 1001 see common employees |
sales_order_id |
?integer |
Sales Order ID |
workshop_order_id |
?integer |
Workshop Order ID |
total_amount_cents |
integer |
Total amount in cents e.g. 278820 |
unpayed_amount_cents |
integer |
Unpayed amount in cents. 278820 |
invoice_date |
date |
(pro-forma) date of the invoice 2022-04-29 |
book_date |
?date |
Book date of invoice. null if not booked |
sales_items |
object[] |
Array of sales items |
sales_items[].sales_item_id |
integer |
Item identifier 115350527 |
sales_items[].item_type_id |
integer |
Item type, see common enum .e.g. 1 |
sales_items[].special_type_id |
integer |
If associated with a stock item this is the stock item id 0 |
sales_items[].quantity |
integer |
Quantity sold e.g. 1 |
sales_items[].barcode |
string |
Barcode of the article |
sales_items[].pos_group_id |
integer |
POS group id see common enum e.g. 11 |
sales_items[].description |
string |
Line description Diversen |
sales_items[].unit_price_in_vat_cents |
integer |
Gross unit price in cents 9900 |
sales_items[].unit_discount_amount_in_vat_cents |
integer |
Unit discount amount in cents 990 |
sales_items[].price_in_vat_cents |
integer |
Line price in cents e.g. 8910 |
sales_items[].discount_percentage |
integer |
Discount percentage 10 |
sales_items[].vat_code |
integer |
VAT code, see common enum 2 |
sales_items[].vat_percentage |
integer |
VAT percentage 21 |
sales_items[].vat_amount_cents |
integer |
Line vat amount in cents. 1546 |
sales_items[].identification |
?object |
Object with serial numbers if associated |
sales_items[].identification.stock_object_id |
integer |
Object associated with the item 24406 |
sales_items[].identification.frame_number |
string |
Frame number e.g. FR0000010 |
sales_items[].identification.key_number |
string |
Key number e.g. SL10000 |
sales_items[].identification.lock_number |
string |
Lock number e.g. K1212 |
sales_items[].identification.battery_number |
string |
Battery number e.g. B12122112 |
sales_items[].identification.engine_number |
string |
Engine number e.g. E3322323 |
sales_items[].identification.serial_number |
string |
Serial number e.g. S320934 |
sales_items[].identification.license_plate_number |
string |
License plate number e.g. xx-yy-zz |
Payload example
{
"id": "f65ee643-1010-4ecb-a67e-da50dbe1ed90",
"account_id": 1,
"event_name": "sales_transaction.created",
"event_timestamp": 1651242527.212,
"payload": {
"invoice_number": 20210047,
"is_final": true,
"customer_id": 0,
"store_id": 1,
"sales_employee_id": 1001,
"sales_order_id": null,
"workshop_order_id": null,
"total_amount_cents": 200,
"unpayed_amount_cents": 0,
"invoice_date": "2022-04-29",
"book_date": "2022-04-29",
"sales_items": [
{
"sales_item_id": 115350525,
"item_type_id": 1,
"special_type_id": 0,
"quantity": 1,
"barcode": "",
"pos_group_id": 8,
"description": "Kleding",
"unit_price_in_vat_cents": 200,
"unit_discount_amount_in_vat_cents": 0,
"price_in_vat_cents": 200,
"discount_percentage": 0,
"vat_code": 2,
"vat_percentage": 21,
"vat_amount_cents": 35,
"identification": null
}
]
}
}
Internal deliveries / store orders
| Event name | Description |
|---|---|
store_order.created |
Will be delivered when store order is created |
store_order.updated |
Will be delivered when store order is updated |
Payload properties
| Property | Type | Description |
|---|---|---|
store_order_id |
integer |
internal delivery / store order id e.g. 45287 |
store_id_from |
integer |
destination store id |
dealer_id_from |
integer |
source dealer_id |
store_id_to |
integer |
destination store_id |
dealer_id_to |
integer |
destination dealer_id |
store_order_type |
string |
regulier or via warehouse |
store_order_type_id |
integer |
0: regular, 1: via warehouse, 2: regular via warehouse |
status_id |
integer |
0: open, 1: processed, 2: cancelled, 3: invoiced, 5: locked |
status |
string |
e.g. Verwerkt |
remarks |
string |
e.g. Filiaal naar filiaal levering #2341 |
processed_at |
?datetime |
e.g. 2012-05-25 15:17:00 |
related_to_sales_order_ids |
integer[] |
List of sales order ids related to delivery |
related_to_supplier_order_ids |
integer[] |
List of supplier order ids related to delivery |
items |
object[] |
list of items within store order |
items[].store_order_item_id |
integer |
e.g. 2 |
items[].barcode |
string |
e.g. F.1000 |
items[].quantity |
integer |
e.g. 1 |
items[].item_type_id |
integer |
1: article, 2:object |
items[].object_id |
?integer |
e.g. 1000 or null |
items[].description |
string |
e.g. Fiets |
Payload
{
"id": "20c5d026-68b3-11ec-90d6-0242ac120003",
"account_id": 1,
"event_name": "store_order.created",
"event_timestamp": 1640787926.323,
"payload": {
"store_order_id": 45287,
"store_id_from": 1,
"dealer_id_from": 1,
"store_id_to": 2,
"dealer_id_to": 131073,
"store_order_type": "regulier",
"store_order_type_id": 0,
"status_id": 1,
"status": "Verwerkt",
"remarks": "Filiaal naar filiaal levering #2341",
"processed_at": "2012-05-25 15:17:00",
"related_to_sales_order_ids": [
123223
],
"related_to_supplier_order_ids": [
2443
],
"items": [
{
"store_order_item_id": 2,
"barcode": "1000",
"quantity": 1,
"item_type_id": 1,
"object_id": null,
"description": "Artikel"
},
{
"store_order_item_id": 2,
"barcode": "F.1000",
"quantity": 1,
"item_type_id": 2,
"object_id": 1000,
"description": "Fiets"
}
]
}
}
Payments created
| Event name | Description |
|---|---|
payments.created |
Will be delivered when payments were registered for a sales order or invoice |
Payload properties
| Property | Type | Description |
|---|---|---|
entity_type_id |
integer |
Entity type (sales transaction 5 or sales order 7) |
entity_id |
integer |
Sales transaction number or sales order ID e.g. 54876 (depending on entity_type_id |
payments |
object[] |
array of payment objects |
payments[].payment_method_id |
integer |
Payment method ID 2 (see common api payment_methods) |
payments[].payment_method_name |
string |
Payment method description e.g. Contant |
payments[].book_date |
datetime |
Book date of the payment 2022-11-02 14:12:57 |
payments[].amount_cents |
integer |
Payment amount in cents 4400 for 44.00 in payments[].currency |
payments[].currency |
string |
Payment currency e.g. EUR |
Payload
{
"id": "19b4b578-79bb-4577-9b2c-c86b5fb77004",
"account_id": 1,
"event_name": "payments.created",
"event_timestamp": 1667394777.764,
"payload": {
"entity_type_id": 7,
"entity_id": 54876,
"payments": [
{
"payment_method_id": 2,
"payment_method_name": "Contant",
"book_date": "2022-11-02 14:12:57",
"amount_cents": 4400,
"currency": "EUR"
},
{
"payment_method_id": 1,
"payment_method_name": "PIN",
"book_date": "2022-11-02 14:12:57",
"amount_cents": 10000,
"currency": "EUR"
}
]
}
}