NAV
Code

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.

Inbound orders

Access inbound deliveries and inbound backlog data

Authentication mechanism

Inbound back-log

Get a list of goods to be delivered.

GET parameter Type Description
supplier_id integer If supplied only the data for the specified supplier is given
See common api for supplier-ids
is_assigned integer if 1 only assigned items are returned
offset integer Pagination offset. optional

HTTP request examples

GET
/api/v1/warehouse/inbound/backlog.json
GET
/api/v1/warehouse/inbound/backlog.json?supplier_id=:supplier_id&is_assigned=1&offset=:offset

Properties

Property Type Description
error boolean true when an error occured
error_message ?string Error message if known
data object[] Array of backlog items
data[].id integer Unique item id 412855
data[].supplier_id integer Supplier ID 2403
data[].is_sold_to_customer boolean Marked as sold to customer false
data[].in_transit boolean Marked as in transit false
data[].article_id string Article ID LV106
data[].barcode string Barcode of article 8719812004299
data[].supplier_reference string Reference of supplier 7171999
data[].supplier_reference_2 string Reference of supplier 2 7171999
data[].delivery_date date Expected delivery-date 2022-12-26
data[].original_delivery_date date Original expected delivery-date 2023-01-02
data[].external_remarks string Remarks from supplier
data[].internal_remarks ?string Internal remarks
data[].created_at datetime Date-time created
data[].modified_at datetime Date-time modified
data[].assignment ?object If not null the item is assigned
data[].assignment.assigned_to_entity_type_id integer Entity type assignment 20 (see common api)
data[].assignment.assigned_to_entity_id integer Entity ID of assignment 564840
data[].assignment.outbound_order_id integer Assigned outbound order id 440452
data[].assignment.reference string Reference of outbound-order fvs_138443
pagination.next_offset ?integer If specified use offset in GET parameter for extra data

HTTP request

GET /api/v1/warehouse/inbound/backlog.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: 1330

{
  "error": false,
  "error_message": null,
  "data": [
    {
      "id": 412805,
      "supplier_id": 2403,
      "is_sold_to_customer": false,
      "in_transit": false,
      "article_id": "LV105",
      "barcode": "8719812004282",
      "supplier_reference": "7171648",
      "supplier_reference_2": "7171648",
      "delivery_date": "2022-11-07",
      "original_delivery_date": "2022-11-14",
      "external_remarks": "",
      "internal_remarks": "some text",
      "created_at": "2022-04-21 12:15:56",
      "modified_at": "2022-04-21 12:18:53",
      "assignment": null
    },
    {
      "id": 412843,
      "supplier_id": 2403,
      "is_sold_to_customer": false,
      "in_transit": false,
      "article_id": "LV106",
      "barcode": "8719812004299",
      "supplier_reference": "7171984",
      "supplier_reference_2": "7171984",
      "delivery_date": "2022-10-24",
      "original_delivery_date": "2022-10-31",
      "external_remarks": "BL-412843",
      "internal_remarks": null,
      "created_at": "2022-04-21 12:15:56",
      "modified_at": "2022-04-21 12:18:53",
      "assignment": {
        "assigned_to_entity_type_id": 20,
        "assigned_to_entity_id": 564840,
        "outbound_order_id": 440452,
        "reference": "yourref_138443"
      }
    }
  ],
  "pagination": {
    "next_offset": 2
  }
}

Inbound delivered items

Get a list of delivered inbound goods

GET parameter Type Description
start_date date Start date interval (yyyy-mm-dd) required
end_date date Start date interval (yyyy-mm-dd) required
offset integer Pagination offset. optional

HTTP request examples

GET
/api/v1/warehouse/inbound/delivered-items.json?start_date=:start_date&end_date=:end_date
GET
/api/v1/warehouse/inbound/delivered-items.json?start_date=:start_date&end_date=:end_date&offset=:offset

Response

{
  "error": false,
  "error_message": null,
  "data": [
    {
      "article_id": "ART1",
      "barcode": "1000001",
      "datetime_delivered": "2021-01-01 12:00:33",
      "inbound_delivery_id": 10000,
      "inbound_delivery_item_id": 100001,
      "packinglist_number": "PB11",
      "purchase_price_cents": 10099,
      "quantity_missing": 0,
      "quantity_packinglist": 1,
      "quantity_scanned": 0,
      "quantity_stocked": 1,
      "supplier_id": 2113
    },
    {
      "article_id": "ART2",
      "barcode": "1000002",
      "datetime_delivered": "2021-01-01 12:00:33",
      "inbound_delivery_id": 10000,
      "inbound_delivery_item_id": 100002,
      "packinglist_number": "PB11",
      "purchase_price_cents": 10099,
      "quantity_missing": 0,
      "quantity_packinglist": 1,
      "quantity_scanned": 0,
      "quantity_stocked": 0,
      "supplier_id": 2113
    }
  ],
  "pagination": {
    "next_offset": null
  }
}

Workshop

Access workshop data

Authentication mechanism

Workshop assemblies

Get a list of stock items released for shipment

GET parameter Type Description
start_date date Start date interval (yyyy-mm-dd) required
end_date date Start date interval (yyyy-mm-dd) required
offset integer Pagination offset. optional

Properties

Property Type Description
error boolean e.g. false
error_message ?string The error message if an error occurred
data[].stock_item_id integer Stock item ID e.g. 20000
data[].is_assembled boolean true if object is assembled
data[].released_by string The user who released/assembled the item e.g. Name 12
data[].scheduled_for_release_at date Scheduled date for release/assembly e.g. 2021-10-10
data[].released_for_shipment_at date Date of release/assembly e.g. 2021-10-11
data[].claimed_by_dealer_id integer Dealer-id who claimed the stock item 5393
data[].outbound_order_id integer The Outbound Order ID e.g. 20001
data[].outbound_order_item_id integer The Outbound Order Item ID e.g. 20002
data[].outbound_shipment_id integer The Outbound Shipment ID e.g. 20003
data[].outbound_shipment_item_id integer The Outbound Shipment Item ID e.g. 20004
data[].is_sold_to_customer boolean Boolean whether the item is sold
pagination.next_offset ?integer If not null use in next paginated request in offset GET parameter

HTTP request examples

GET
/api/v1/warehouse/workshop/assemblies.json?start_date=:start_date&end_date=:end_date
GET
/api/v1/warehouse/workshop/assemblies.json?start_date=:start_date&end_date=:end_date&offset=:offset

Response

{
  "error": false,
  "error_message": null,
  "data": [
    {
      "stock_item_id": 10000,
      "is_assembled": true,
      "released_by": "Name 11",
      "scheduled_for_release_at": "2021-10-10",
      "released_for_shipment_at": "2021-10-11",
      "claimed_by_dealer_id": 5393,
      "outbound_order_id": 10001,
      "outbound_order_item_id": 10002,
      "outbound_shipment_id": 10003,
      "outbound_shipment_item_id": 10004,
      "is_sold_to_customer": true
    },
    {
      "stock_item_id": 20000,
      "is_assembled": false,
      "released_by": "Name 12",
      "scheduled_for_release_at": "2021-10-10",
      "released_for_shipment_at": "2021-10-11",
      "claimed_by_dealer_id": 5393,
      "outbound_order_id": 20001,
      "outbound_order_item_id": 20002,
      "outbound_shipment_id": 20003,
      "outbound_shipment_item_id": 20004,
      "is_sold_to_customer": false
    }
  ],
  "pagination": {
    "next_offset": null
  }
}

Stock

Access stock info for warehouse

Authentication mechanism

Stock-info

Get a list of stock items released for shipment

GET parameter Type Description
stock_items integer if set to 1 details about the stock items is provided optional
no_remote_supplier_check integer if set to 1 no remote supplier checks are included optional
only_supplier_stock integer if set to 1 only remote supplier stock is checked, store and warehouse stock is ignored optional
only_supplier_id integer if a supplier_id is given only this supplier will be included for supplier stock checks optional
remote_supplier_check_if_not_in_warehouse integer if set to 1 supplier check will always be checked there is no stock in warehouse optional
always_remote_supplier_check integer if set to 1 supplier check will always be checked optional
POST parameter Type Description
barcodes string[] array of barcodes

Properties

Property Type Description
error boolean true if errors occurred
error_message ?string Error message if occurred
data.status boolean true if no errors occurred
data.result_items object[] Result per requested barcode
data.result_items[].barcode string Article barcode
data.result_items[].stock_available boolean Overall status whether stock is available
data.result_items[].delivery_date ?date expected delivery date from supplier
data.result_items[].delivery_date_supplier ?date expected delivery date from supplier
data.result_items[].delivery_date_backlog ?date expected delivery date from registered backlog orders supplier
data.result_items[].stock_supplier ?boolean true if stock available at supplier, null if not checked
data.result_items[].stock_quantity integer available quantity within stores+warehouse (new+demo+used+rental)
data.result_items[].stock_quantity_stores integer available quantity within stores
data.result_items[].stock_quantity_warehouse integer available quantity within warehouse
data.result_items[].stock_stores object[] array with stock info per store
data.result_items[].stock_stores[].dealer_id integer dealer-id of store
data.result_items[].stock_stores[].store_name string name of store
data.result_items[].stock_stores[].store_phone string phone number of store
data.result_items[].stock_stores[].quantity integer quantity including demo, used, rental models available
data.result_items[].stock_stores[].quantity_demo integer quantity of demo models available
data.result_items[].stock_stores[].quantity_used integer quantity of used models available
data.result_items[].stock_stores[].quantity_rental integer quantity of rental models available
data.result_items[].supplier_id ?string used supplier_id in request
data.result_items[].article_id string used "barcode" in request e.g. 8719461035781

HTTP request examples

GET
/app/api/whm/stockinfo/:barcode1/:barcode2/../../
GET
/app/api/whm/stockinfo/:barcode1/:barcode2/../../?stock_items={0,1}
GET
/app/api/whm/stockinfo/:barcode1/:barcode2/../../?no_remote_supplier_check={0,1}
GET
/app/api/whm/stockinfo/:barcode1/:barcode2/../../?only_supplier_stock={0,1}
GET
/app/api/whm/stockinfo/:barcode1/:barcode2/../../?only_supplier_id=:supplier_id
POST
/app/api/whm/stockinfo/

Response

{
  "error": false,
  "error_message": "",
  "data": {
    "status": true,
    "result_items": [
      {
        "barcode": "8719461035781",
        "stock_available": true,
        "delivery_date": null,
        "delivery_date_supplier": null,
        "delivery_date_backlog": null,
        "stock_supplier": null,
        "stock_quantity": 1,
        "stock_quantity_stores": 1,
        "stock_quantity_warehouse": 0,
        "stock_stores": [
          {
            "dealer_id": 791825,
            "store_name": "Ridderkerk",
            "store_phone": "010-1234567",
            "quantity": 1,
            "quantity_demo": 1,
            "quantity_used": 0,
            "quantity_rental": 0
          },
          {
            "dealer_id": 857361,
            "store_name": "Breda",
            "store_phone": "010-1234567",
            "quantity": 1,
            "quantity_demo": 1,
            "quantity_used": 0,
            "quantity_rental": 0
          }
        ],
        "supplier_id": null,
        "article_id": "8719461035781"
      },
      {
        "barcode": "8719461035782",
        "stock_available": false,
        "delivery_date": "01-01-2022",
        "delivery_date_supplier": "01-05-2022",
        "delivery_date_backlog": "01-01-2022",
        "stock_supplier": false,
        "stock_quantity": 0,
        "stock_quantity_stores": 0,
        "stock_quantity_warehouse": 0,
        "stock_stores": [],
        "supplier_id": null,
        "article_id": "8719461035782"
      }
    ]
  }
}

Stock list Warehouse

Get a list of objects in warehouse

Properties

Property Type Description
error boolean true if error occurred
error_message ?string Error if occurred
data object[] array of objects
data[].stock_item_id integer Object ID within warehouse 325817
data[].outbound_order_id integer Outbound order ID
data[].supplier string Supplier name
data[].article_id string Article number 735-18460
data[].barcode string Barcode 4063518126705
data[].description string Description of article Ravenna E8F Herenfiets 28" grey 60 cm diamant
data[].frame_id string Framenumber AA01148291
data[].purchase_price_cents integer Purchase price in cents
data[].purchase_price_cents_packinglist integer Purchase price in cents from last packinglist
data[].dealer_rrp_cents integer RRP in cents
data[].claimed_for_account_id ?integer If claimed the account_id
data[].claimed_for_store_id ?integer If claimed the store_id
data[].is_blocked_for_claiming boolean true if blocked for claiming
data[].is_claimed_for_obo boolean true if claimed for outbound order
data[].is_sold_to_customer boolean true if sold to a customer
data[].is_shipped boolean true if shipped
data[].is_deleted boolean true if item was deleted
data[].stocked_at datetime Datetime stocked 2021-10-22 11:33:03
data[].shipped_at ?datetime Datetime shipped
data[].custom_variable_1 string Custom variable from article
data[].custom_variable_2 string Custom variable from article
data[].custom_variable_3 string Custom variable from article
data[].custom_variable_4 string Custom variable from article
data[].custom_variable_5 string Custom variable from article

HTTP request examples

GET
/api/v1/warehouse/stock/items.json

Response

{
  "error": false,
  "error_message": null,
  "data": [
    {
      "stock_item_id": 109993,
      "outbound_order_id": 315254,
      "supplier": "Leopard",
      "article_id": "593005",
      "barcode": "8717931438117",
      "description": "Leopard Tess 24 inch 2019 M24-39 Zwart Mat",
      "frame_id": "17017456",
      "purchase_price_cents": 40900,
      "purchase_price_cents_packinglist": 40900,
      "dealer_rrp_cents": 41900,
      "claimed_for_account_id": 1000,
      "claimed_for_store_id": 13,
      "is_blocked_for_claiming": false,
      "is_claimed_for_obo": true,
      "is_sold_to_customer": true,
      "is_shipped": true,
      "is_deleted": false,
      "stocked_at": "2018-04-24 08:53:20",
      "shipped_at": "2021-04-13 07:59:29",
      "custom_variable_1": "Custom var 1",
      "custom_variable_2": "Custom var 2",
      "custom_variable_3": "Custom var 3",
      "custom_variable_4": "Custom var 4",
      "custom_variable_5": "Custom var 5"
    },
    {
      "stock_item_id": 203013,
      "outbound_order_id": 376797,
      "supplier": "Gazelle",
      "article_id": "G1539",
      "barcode": "8717231346426",
      "description": "Orange C8 HMB H8",
      "frame_id": "61380279",
      "purchase_price_cents": 279900,
      "purchase_price_cents_packinglist": 279900,
      "dealer_rrp_cents": 289900,
      "claimed_for_account_id": 1000,
      "claimed_for_store_id": 23,
      "is_blocked_for_claiming": false,
      "is_claimed_for_obo": true,
      "is_sold_to_customer": false,
      "is_shipped": true,
      "is_deleted": true,
      "stocked_at": "2020-06-11 10:59:05",
      "shipped_at": "2021-10-15 10:03:09",
      "custom_variable_1": "Custom var 1",
      "custom_variable_2": "Custom var 2",
      "custom_variable_3": "Custom var 3",
      "custom_variable_4": "Custom var 4",
      "custom_variable_5": "Custom var 5"
    }
  ]
}

Stock list POS

Get a list of stocked objects in POS

Properties

Property Type Description
error boolean true if error occurred e.g. false
error_message ?string Error message or null
data[].account_id integer Account ID of store 5393
data[].store_id integer ID of the POS store 2
data[].object_id integer POS Object ID 20648
data[].sales_order_id integer POS order id 1000
data[].supplier string Supplier name Gazelle
data[].article_id string Article number A1935
data[].barcode string Barcode 8717231254776
data[].description string Description Gazelle Eclipse C8 LTD
data[].frame_id string Framenumber 60516151
data[].purchase_price_cents integer Purchase price in cents 50980
data[].purchase_price_cents_packinglist integer Purchase price in cents from last packinglist 50980
data[].dealer_rrp_cents integer RRP in cents 94900
data[].is_sold_to_customer boolean true if sold to customer
data[].is_demo boolean true if marked as demo
data[].has_invoice boolean true if invoiced
data[].stocked_at date Custom variable from article
data[].custom_variable_1 string Custom variable from article
data[].custom_variable_2 string Custom variable from article
data[].custom_variable_3 string Custom variable from article
data[].custom_variable_4 string Custom variable from article
data[].custom_variable_5 string Custom variable from article
data[].is_deleted boolean Item is deleted
data[].is_rental boolean If rental object true
data[].is_used boolean true if not a new object

HTTP request examples

GET
/api/v1/warehouse/stock/pos-items.json

Response

{
  "error": false,
  "error_message": null,
  "data": [
    {
      "account_id": 1000,
      "store_id": 6,
      "object_id": 1076,
      "sales_order_id": 0,
      "supplier": "Batavus",
      "article_id": "BE100086",
      "barcode": "8713568256155",
      "description": "Batavus STREAM",
      "frame_id": "BA5169351",
      "purchase_price_cents": 219900,
      "purchase_price_cents_packinglist": 219900,
      "dealer_rrp_cents": 259900,
      "is_sold_to_customer": false,
      "is_demo": true,
      "has_invoice": false,
      "stocked_at": "2015-12-08",
      "custom_variable_1": "Custom var 1",
      "custom_variable_2": "Custom var 2",
      "custom_variable_3": "Custom var 3",
      "custom_variable_4": "Custom var 4",
      "custom_variable_5": "Custom var 5",
      "is_deleted": false,
      "is_used": false,
      "is_rental": false
    },
    {
      "account_id": 1000,
      "store_id": 2,
      "object_id": 4673,
      "sales_order_id": 0,
      "supplier": "Gazelle",
      "article_id": "A0828",
      "barcode": "8717231240205",
      "description": "Gazelle Orange C8 Hm",
      "frame_id": "60467933",
      "purchase_price_cents": 190000,
      "purchase_price_cents_packinglist": 190000,
      "dealer_rrp_cents": 210000,
      "is_sold_to_customer": false,
      "is_demo": true,
      "has_invoice": false,
      "stocked_at": "2016-02-03",
      "custom_variable_1": "Custom var 1",
      "custom_variable_2": "Custom var 2",
      "custom_variable_3": "Custom var 3",
      "custom_variable_4": "Custom var 4",
      "custom_variable_5": "Custom var 5",
      "is_deleted": false,
      "is_used": true,
      "is_rental": true
    }
  ]
}

Outbound orders

Outbound orders related APIs

Authentication mechanism

Open order items

Get a list of open outbound order items: quantity shipped < quantity

GET parameter Type Description
:page integer Pagination page

HTTP request examples

GET
/api/v1/warehouse/outbound/order/open-orders.json?page=:page
Property Type Description
error boolean false if no error occured
error_message ?string Error message if present
data object[] Array of OBO items
data[].dealer_id integer The dealer ID e.g. 99
data[].outbound_order_id integer Outbound order ID e.g. 204915
data[].outbound_order_item_id integer Outbound order item ID e.g. 307229
data[].created_at datetime Date time created 2019-08-15 12:48:10
data[].ecommerce_reference_id string Reference ID
data[].ecommerce_reference_text string Reference Text
data[].barcode string Barcode e.g. 8717231260616
data[].description string Description e.g. Esprit C3 H 59 T3
data[].quantity integer Quantity of item e.g. 1
data[].quantity_claimed integer Quantity claimed e.g. 0
data[].quantity_shipped integer Quantity shipped e.g. 0
data[].reference string Reference to POS order
data[].is_sold_to_customer boolean true if sold to customer
data[].is_blocked_for_claiming boolean true if item is blocked for claiming
data[].is_pooled_within_stores boolean true if item is sourced within stores
pagination.page integer Pagination page 1
pagination.count integer Count result items 262
pagination.has_next_page boolean If true call endpoint again with page=page+1

HTTP Request

GET /api/v1/warehouse/outbound/order/open-orders.json?page=1 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: 1441
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": [
        {
            "dealer_id": 4807,
            "outbound_order_id": 225,
            "outbound_order_item_id": 277,
            "created_at": "2014-01-03 15:05:16",
            "ecommerce_reference_id": "FV_121212",
            "ecommerce_reference_text": "FV_121212",
            "barcode": "8717231228326",
            "description": "Gazelle MS GRACE Dames Black 2014 49",
            "quantity": 1,
            "quantity_claimed": 0,
            "quantity_shipped": 0,
            "reference": "POS12121076",
            "is_sold_to_customer": true,
            "is_blocked_for_claiming": false,
            "is_pooled_within_stores": false
        },
        {
            "dealer_id": 4807,
            "outbound_order_id": 231,
            "outbound_order_item_id": 283,
            "created_at": "2014-01-07 15:49:15",
            "ecommerce_reference_id": "",
            "ecommerce_reference_text": "",
            "barcode": "8713568224574",
            "description": "Batavus",
            "quantity": 1,
            "quantity_claimed": 0,
            "quantity_shipped": 0,
            "reference": "F.1080",
            "is_sold_to_customer": true,
            "is_blocked_for_claiming": false,
            "is_pooled_within_stores": false
        },
    ],
    "pagination": {
        "page": 1,
        "count": 2,
        "has_next_page": false
    }
}

Convert pool to regular

Convert a POOL order to a regular order.

URL parameter Type Description
:outbound_order_id integer Outbound order id required

HTTP request examples

POST
/api/v1/warehouse/outbound/order/:outbound_order_id/pool-to-regular.json

HTTP Request

POST /api/v1/warehouse/outbound/order/1013123/pool-to-regular.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: 722
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
}

Cancel order

Cancels an outbound order and will attempt to cancel the related supplier order in POS.

URL parameter Type Description
:outbound_order_id integer Outbound order id required

HTTP request examples

POST
/api/v1/warehouse/outbound/order/:outbound_order_id/cancel.json

HTTP Request

POST /api/v1/warehouse/outbound/order/1013123/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: 265
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": [
        {
            "outbound_order_item_id": 111,
            "unclaimed_stock": 2
        },
        {
            "outbound_order_item_id": 333,
            "unclaimed_stock": 3
        }
    ]
}

Shipments

Access outbound shipment data

Authentication mechanism

Delivery status for object item id

Mark the shipment for a stock item as delivered or not-delivered. not-delivered should be used if the package could not be delivered at the destination.

URL parameter Type Description
:stock_item_id integer Stock item ID in warehouse required

HTTP request examples

POST
/api/v1/warehouse/outbound/item/:stock_item_id/delivered.json
POST
/api/v1/warehouse/outbound/item/:stock_item_id/not-delivered.json

Response

{
  "error": false,
  "error_message": null
}

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": {}
}

Outbound orders

Event name Description
warehouse_outbound_order.created_or_updated Fired when the outbound order is created or updated

Properties

Property Type Description
payload.outbound_order_id integer Outbound order ID e.g. 463681
payload.outbound_order_type_id integer Type of order e.g. 1
payload.outbound_order_status_id integer Status of order e.g. 1
payload.dealer_id integer ID of dealer e.g. 4807
payload.account_id integer ID of account of the order e.g. 4807
payload.store_id integer ID of store of the order e.g. 1
payload.created_at datetime Created datetime e.g. 2022-07-05 11:07:48
payload.datetime_preferred_delivery ?datetime e.g. 2022-07-05 11:07:48 or null
payload.sales_order_id ?integer Sales order ID in POS
payload.order_reference_text string String with e-commerce reference from POS
payload.order_items object[] Array of order items
payload.order_items[].outbound_order_item_id integer ID of the item e.g. 605491
payload.order_items[].item_type_id integer Item type id, see common api e.g. 2
payload.order_items[].is_active boolean if false the item is marked deleted
payload.order_items[].barcode string Barcode of item e.g. 8713568215084
payload.order_items[].quantity integer Quantity ordered 1
payload.order_items[].quantity_claimed integer Quantity claimed stock e.g. 0
payload.order_items[].quantity_shipped integer Quantity shipped e.g. 0
payload.order_items[].is_blocked_for_claiming boolean true if blocked for claiming
payload.order_items[].description string Description of item
payload.order_items[].remark string Remark of order item
payload.order_items[].reference string Reference of order item
payload.order_items[].is_sold_to_customer boolean true if sold to customer
payload.order_items[].is_attached_to_outbound_item_id ?integer If not null the outbound_order_item_id of which the item is attached to
payload.order_items[].is_pooled_within_stores boolean true if pool order

Payload structure

{
  "id": "180c1fd6-04ab-4215-b55a-0d8710961c95",
  "account_id": 4743,
  "event_name": "warehouse_outbound_order.created_or_updated",
  "event_timestamp": 1657012068.444,
  "payload": {
    "outbound_order_id": 463681,
    "outbound_order_type_id": 1,
    "outbound_order_status_id": 1,
    "dealer_id": 4807,
    "account_id": 4807,
    "store_id": 1,
    "created_at": "2022-07-05 11:07:48",
    "datetime_preferred_delivery": null,
    "sales_order_id": null,
    "order_reference_text": "",
    "order_items": [
      {
        "outbound_order_item_id": 605491,
        "item_type_id": 2,
        "is_active": true,
        "barcode": "8713568215084",
        "quantity": 1,
        "quantity_claimed": 0,
        "quantity_shipped": 0,
        "is_blocked_for_claiming": false,
        "description": "",
        "remark": "",
        "reference": "",
        "is_sold_to_customer": false,
        "is_attached_to_outbound_item_id": null,
        "is_pooled_within_stores": false
      }
    ]
  }
}

Warehouse stock item

Event name Description
warehouse_stock_item.updated Fired when the stock item is updated
warehouse_stock_item.released_for_shipment Fired when stock item is released for shipment

Properties

Property Type Description
warehouse_stock_item_id integer Warehouse stock Item ID 285
warehouse_outbound_order_id integer Outbound order ID 121212 (0 if not associated to an order)
warehouse_outbound_order_item_id integer Outbound order Item ID 333233 (0 if not associated to an order)
warehouse_outbound_shipment_id integer Shipment ID 0 if not shipped
warehouse_outbound_shipment_item_id integer Shipment Item ID 0 if not shipped
warehouse_location.location string Location in warehouse e.g. R-1-2
warehouse_location.rack_name string Rack name in warehouse R
supplier_id integer Supplier ID of object e.g. 2113 (see common API suppliers)
article_id string Article number of stock item e.g. 4961
barcode string Barcode of stock item e.g. 2000100281620
battery_id string Battery ID e.g. BAT22222
customer_id integer Customer ID in POS e.g. 1006
customer_order_id integer Sales order ID in POS e.g. 333
employee_first_name string Employee name e.g. First
employee_last_name string Employee last name e.g. Last
frame_id string Frame ID e.g. 3232
is_assembled boolean true if item is assembled
is_shipped boolean true if item is shipped
is_delivered boolean true if item is delivered
key_id string Key ID of object e.g. 2323
lock_id string Lock ID of object e.g. 2323
license_plate_number string License plate of object e.g. xx-yy-zz
order_reference_id string POS/OBO order reference ID fvs12222
order_reference_text string POS/OBO order reference text e.g. REF
labels string[] Labels associated with object e.g. Label 1
sub_order_items object[] Arrey of sub order items associated to item
sub_order_items[].article_id string Article ID e.g. a3223
sub_order_items[].barcode string Article barcode e.g. 883273232332
sub_order_items[].is_active boolean true if order item is active
sub_order_items[].is_included boolean true if item is included with item
sub_order_items[].quantity integer Quantity of sub item e.g. 3
sub_order_items[].quantity_claimed integer Quantity stock claimed e.g. 3
sub_order_items[].reference string Reference of item ref-1
sub_order_items[].remark string Remark of item remark-1

Payload structure

{
  "id": "180c1fd6-04ab-4215-b55a-0d8710961c95",
  "account_id": 4743,
  "event_name": "warehouse_outbound_order.created_or_updated",
  "event_timestamp": 1657012068.444,
  "payload": {
    "warehouse_stock_item_id": 285,
    "warehouse_outbound_order_id": 121212,
    "warehouse_outbound_order_item_id": 333233,
    "warehouse_outbound_shipment_id": 0,
    "warehouse_outbound_shipment_item_id": 0,
    "article_id": "4961",
    "barcode": "2000100281620",
    "battery_id": "BAT22222",
    "customer_id": 1006,
    "customer_order_id": 333,
    "employee_first_name": "First",
    "employee_last_name": "Last",
    "frame_id": "3232",
    "is_assembled": true,
    "is_shipped": false,
    "is_delivered": false,
    "key_id": "2323",
    "lock_id": "2323",
    "license_plate_number": "xx-yy-zz",
    "order_reference_id": "fvs12222",
    "order_reference_text": "REF",
    "sub_order_items": [
      {
        "article_id": "a3223",
        "barcode": "883273232332",
        "is_active": true,
        "is_included": true,
        "quantity": 2,
        "quantity_claimed": 2,
        "reference": "ref-1",
        "remark": "remark-1"
      },
      {
        "article_id": "a3223",
        "barcode": "883273232332",
        "is_active": true,
        "is_included": true,
        "quantity": 3,
        "quantity_claimed": 3,
        "reference": "ref-1",
        "remark": "remark-1"
      }
    ],
    "supplier_id": 2113,
    "warehouse_location": {
      "location": "R-1-2",
      "rack_name": "R"
    },
    "labels": [
      "Label 1"
    ]
  }
}