NAV
Code PHP

Introduction

Welcome to the CycleSoftware API documentation

Documentation overview

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.

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:

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

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

Articledata

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

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

Customers

Find, create and update customers

Scope(s)

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)

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&#124;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.

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

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

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

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

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

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)

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

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 date
datetime_modified interval as modification dates
factuurdatum 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.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&vert;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
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

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)

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.

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
    }
}

Stock

Access stock data

Authentication mechanism

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.

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.

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

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)

Trading hours (object)

Property Type Description
date date Date e.g. 2023-03-21
capacity_minutes integer Capacity in minutes e.g. 780
scheduled_minutes integer Scheduled workshop orders in minutes e.g. 0
available_minutes integer Available duration in minutes e.g. 780
timestamp_finished_twsc_repairs timestamp Unix timestamp when the scheduled workshop-orders via api are finished (0 if not available)
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

Trading hours

Workshop trading hours for default or specific store

GET
/api/v1/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 array of Trading hours objects.

HTTP request

GET /api/v1/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: 5318
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

[
    {
        "date": "2023-03-08",
        "capacity_minutes": 780,
        "scheduled_minutes": 0,
        "available_minutes": 780,
        "timestamp_finished_twsc_repairs": 0,
        "day_id": 3,
        "week_no": 10,
        "is_closed": false,
        "workshop_trading_hours": [
            {
                "start": "07:00",
                "finish": "19:45",
                "duration_minutes": 780
            }
        ]
    },
    {
        "date": "2023-03-09",
        "capacity_minutes": 780,
        "scheduled_minutes": 0,
        "available_minutes": 780,
        "timestamp_finished_twsc_repairs": 0,
        "day_id": 4,
        "week_no": 10,
        "is_closed": false,
        "workshop_trading_hours": [
            {
                "start": "07:00",
                "finish": "19:45",
                "duration_minutes": 780
            }
        ]
    }
]

Trading hours per store

Get the workshop trading hours per store

GET
/api/v1/workshop/trading-hours-per-store.json?day_count=:day_count
GET parameter Type Description
day_count integer Number of days to retrieve information for e.g. 3

Properties

Property Type Description
[].store_id integer Store ID e.g. 2
[].store_name string Store Name e.g. Store 1
[].trading_hours object[] array of Trading hours objects

HTTP request

GET /api/v1/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: 7150
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

[
    {
        "store_id": 1,
        "store_name": "Store 1",
        "trading_hours": [
            {
                "date": "2023-03-08",
                "capacity_minutes": 780,
                "scheduled_minutes": 0,
                "available_minutes": 780,
                "timestamp_finished_twsc_repairs": 0,
                "day_id": 3,
                "week_no": 10,
                "is_closed": false,
                "workshop_trading_hours": [
                    {
                        "start": "07:00",
                        "finish": "19:45",
                        "duration_minutes": 780
                    }
                ]
            },
            {
                "date": "2023-03-09",
                "capacity_minutes": 780,
                "scheduled_minutes": 0,
                "available_minutes": 780,
                "timestamp_finished_twsc_repairs": 0,
                "day_id": 4,
                "week_no": 10,
                "is_closed": false,
                "workshop_trading_hours": [
                    {
                        "start": "07:00",
                        "finish": "19:45",
                        "duration_minutes": 780
                    }
                ]
            }
        ]
    },
    {
        "store_id": 2,
        "store_name": "Store 2",
        "trading_hours": [
         {
                "date": "2023-03-08",
                "capacity_minutes": 780,
                "scheduled_minutes": 0,
                "available_minutes": 780,
                "timestamp_finished_twsc_repairs": 0,
                "day_id": 3,
                "week_no": 10,
                "is_closed": false,
                "workshop_trading_hours": [
                    {
                        "start": "07:00",
                        "finish": "19:45",
                        "duration_minutes": 780
                    }
                ]
            },
            {
                "date": "2023-03-09",
                "capacity_minutes": 780,
                "scheduled_minutes": 0,
                "available_minutes": 780,
                "timestamp_finished_twsc_repairs": 0,
                "day_id": 4,
                "week_no": 10,
                "is_closed": false,
                "workshop_trading_hours": [
                    {
                        "start": "07:00",
                        "finish": "19:45",
                        "duration_minutes": 780
                    }
                ]
            }
        ]
    }
]

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)

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)

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"
      }
    ]
  }
}
Code PHP