Prerequisites
You should have
- a valid api channel-token enabled for api access & order management access
- an api-client
- at least one product-record stored in the Hublify PIM
Creating a new order
Some quick infos what happens usually inside Hublify whenever you create (aka inject) an order via the channel-api.
- Hublify creates an order-record ...
- with a Hublify internal (channel-specific) order-id
- with all the other data you provide
- Hublify creates a person-record. And assigns the order to this person.
Attention: The mandatory and available optional fields can vary depending on the targeted Hublify's system and channel-specific configuration!
... minimum data needed
The very minimum of data necessary to inject an order is basically
- buying customer address (invoice-address equals delivery-address, if applicable)
- one ordered product
Request URL
https://{your hublify url}/api/channel_10/order_createRequest parameter
{
"fields": {
"order": {
// Customer data
"invoice_company": "",
"invoice_gender": "male", // "male|female|diverse|company"
"invoice_firstname": "Max",
"invoice_lastname": "Muster",
"invoice_addrextra": "",
"invoice_street": "Sample Street",
"invoice_housenr": "1b",
"invoice_zip": "22222",
"invoice_town": "Hamburg",
"invoice_country": "DE",
"orderitems": [ // Array of all order items.
{
"oi_pcode": "EK00001", // Product-Code. Product must be available in Hublify PIM.
"oi_quantity": 1, // (optional, default: 1)
}
]
}
}
}Response
If your request was successful, you receive the current status and the hublify ids for this order and person.
{
"status": true,
"data": {
"personid": "KCHN-00012345", // Hublify internal customer-id created / assigned to.
"orderid": "ACHN-00123456", // Hublify internal order-id created.
"o_orderid_external": null, // NULL / empty, because no external order-id was provided in request.Response - Error
If your request failed, you receive a message detailing the error that occurred.
{
"status": false,
"msg": [
{
"type": "ERROR",
"text": "Missing mandatory field 'orderitems'"
}
]
}
... recommended data needed
Adding extra data, especially for later follow-up api-calls, callbacks and enhancing process stability is always a good idea!
Consider providing data, especially such as
- your external system's:
- customer-id
- order-id
Hublify then can detect and avoid unwanted erroneous order injections.
Your own order-id ("o_orderid_external") can be used to avoid accidental double-injects. We highly recommend providing one.
Your own customer-id ("p_personid_external") can be used to recognize a recurring customer that is already known in Hublify.
This could also be used to update a customers information within Hublify.
Request URL
https://{your hublify url}/api/channel_10/order_createRequest parameter
{
"fields": {
"person": {
"p_personid_external": "ABC000012", // Provide your own unique customer-id here
// (alphanumeric, max-length: 127 characters).
"bday": "1973-01-22",
"telephone": "+4940123456",
"telephone_mobile": "+491601234567",
"email": "max@muster.de",
},
"order": {
"o_orderid_external": "CH00012345", // Provide your own unique order-id for this order here.
"invoice_company": "",
"invoice_gender": "male",
"invoice_firstname": "Max",
"invoice_lastname": "Muster",
"invoice_addrextra": "",
"invoice_street": "Sample Street",
"invoice_housenr": "1b",
"invoice_zip": "22222",
"invoice_town": "Hamburg",
"invoice_country": "DE",
"deliver_company": null,
"deliver_gender": "female",
"deliver_firstname": "Maxi",
"deliver_lastname": "Muster",
"deliver_addrextra": null,
"deliver_street": "Second Street",
"deliver_housenr": "2a",
"deliver_zip": "11111",
"deliver_town": "Berlin",
"deliver_country": "DE",
"orderitems": [
{
"oi_pcode": "EK00001",
"oi_name": "Example Product 1",
"oi_type": "product",
"oi_quantity": 1,
"oi_price_single_brutto": 14.56, // Single price including vat, per unit sold
"oi_vat_pct": 19 // vat percentage-value
},
{
"oi_pcode": "PC0001",
"oi_name": "Example Product 2",
"oi_type": "product",
"oi_quantity": 2,
"oi_price_single_brutto": 12.34,
"oi_vat_pct": 19,
}
]
}
}
}If your request failed, you receive a message detailing the error that occured.
{
"status": false,
"msg": [
{
"type": "ERROR",
"text": "Missing mandatory field 'orderitems'"
}
]
}
If you sent the same order twice (based on the unique identifier you provided in o_orderid_external),
the second request will fail with a warning, but we will provide the data again.
(Updating already created orders will be possible in future! But that also depends on configured permission and order states.)
{
"status": false,
"data": {
"personid": "KCHN-00012345",
"orderid": "ACHN-00123456",
"o_orderid_external": "CH00012345
},
"msg": [
{
"type": "WARNING",
"text": "Order \"CH00012345\" was already injected and will be skipped."
}
]
}... with Packstation
To request delivery to a German "Packstation" or "Postfiliale" (post office),
you have to provide some special delivery fields.
- Fill field 'deliver_street' with "packstation" or "postfiliale"
- Fill field 'deliver_housenr' with the number of the packstation or post office
- Fill field 'deliver_addrextra' with the DHL customer number of your customer (called "Postnummer" in german)
Request URL
https://{your hublify url}/api/channel_10/order_createRequest parameter
{
"fields": {
"person": {
"p_personid_external": "ABC000012", // Provide your own unique customer-id here.
"bday": "1973-01-22",
"telephone": "+4940123456",
"telephone_mobile": "+491601234567",
"email": "max@muster.de",
},
"order": {
"o_orderid_external": "CH00012345", // Provide your own unique order-id for this order here.
"invoice_company": "",
"invoice_gender": "male",
"invoice_firstname": "Max",
"invoice_lastname": "Muster",
"invoice_addrextra": "",
"invoice_street": "Sample Street",
"invoice_housenr": "1b",
"invoice_zip": "22222",
"invoice_town": "Hamburg",
"invoice_country": "DE",
"deliver_company": null,
"deliver_gender": "male",
"deliver_firstname": "Paul",
"deliver_lastname": "Packed",
"deliver_addrextra": "987654321", // Customer "Postnummer"
"deliver_street": "packstation", // Packstation
"deliver_housenr": "123", // Number of the packstation
"deliver_zip": "11111",
"deliver_town": "Berlin",
"deliver_country": "DE",
"orderitems": [
{
"oi_pcode": "EK00001",
"oi_name": "Example Product 1",
"oi_type": "product",
"oi_quantity": 1,
"oi_price_single_brutto": 14.56, // Single price including vat, per unit sold
"oi_vat_pct": 19 // vat percentage-value
},
{
"oi_pcode": "PC0001",
"oi_name": "Example Product 2",
"oi_type": "product",
"oi_quantity": 2,
"oi_price_single_brutto": 12.34,
"oi_vat_pct": 19,
}
]
}
}
}... full data provided
Following an example with more possible data provided.
Request URL
https://{your hublify url}/api/channel_10/order_createRequest parameter
{
"fields": {
"person": {
"bday": "1973-01-22",
"telephone": "+4940123456",
"telephone_mobile": "+491601234567",
"email": "max@muster.de",
"p_personid_external": "ABC000012", "deliver_company": null,
"deliver_gender": "female",
"deliver_firstname": "Maxi",
"deliver_lastname": "Muster",
"deliver_addrextra": null,
"deliver_street": "Second Street",
"deliver_housenr": "2a",
"deliver_zip": "11111",
"deliver_town": "Berlin",
"deliver_country": "DE",
"orderitems": [
{
"oi_pcode": "EK00001",
"oi_name": "Example Product 1",
"oi_type": "product",
"oi_quantity": 1,
"oi_price_single_brutto": 14.56,
"oi_vat_pct": 19,
"oi_code": "SKUEXT01" // (optional), external SKU
},
{
"pcode_external": "YourOwnProductCode002", // If your ProductIds are known in Hublify,
// you can use them instead of oi_pcode
// Check with the operator of the respective Hublify system first
"oi_name": "Example Product 2",
"oi_type": "product",
"oi_quantity": 2,
"oi_price_single_brutto": 12.34,
"oi_vat_pct": 19,
"oi_code": "SKUEXT02"
}
]
},
"payment": { // Details about Payments - only provide this, if the operator of
"pys_method": "Remittance" // the Hublify-System requested this info
}
}
}Response
See in examples above the possible responses.
Updating an order
If an order hasn't been processed yet, it can be possible to adjust some details, e.g. correct a spelling mistake in an address. It depends on the configuration for your channel, which fields might be available for this. You need either your own or the Hublify-internal orderid for this. You provide the fields the same way you would on create, but you only need to add the fields, that you want to change.
Request URL
https://{your hublify url}/api/channel_10/order_updateRequest parameter
{
"filter": {
"orderid": "ACHN-00123456", // the Hublify internal orderid or...
"o_orderid_external": "CH00012345" // your own unique order-id as an alternative
},
"fields": {
"order": {
"deliver_street": "ThirdStreet",
"deliver_housenr": "3c",
"not_allowed_field": "change it"
}
}
}Response
You receive details about the success of your update
{
"status": true,
"msg": [
{
"type": "OK",
"text": "The following order-fields have been updated: deliver_street, deliver_housenr"
},
{
"type": "WARNING",
"text": "The following order-fields are not available for update: not_allowed_field"
}
]
}or
{
"status": false,
"msg": [
{
"type": "ERROR",
"text": "Changes to this order are no longer possible."
}
]
}Getting order details
To retrieve details like the current status of your order, you need either the Hublify internal orderid as received in the response for order_create or the external orderid you provided yourself.
Request URL
https://{your hublify url}/api/channel_10/order_getRequest parameter
{
"filter": {
"orderid": "ACHN-00123456", // the Hublify internal orderid
}
}If you provided your own unique orderid on order_create, you can use that as a filter instead.
{
"filter": {
"o_orderid_external": "CH00012345", // your own unique order-id
}
}Basic response
If your request was successful, you receive at least the current status and the hublify ids for this order and person.
Depending on the hublify-system you might also be able to retrieve additional data.
{
"status": true,
"data": {
"personid": "KCHN-00012345", // Hublify internal customer-id
"orderid": "ACHN-00123456", // Hublify internal order-id
"o_orderid_external": null, // NULL / empty, if no external order-id was provided in order_create_request.Response with shipping details
If your order was already shipped, the result could also include details about the shipments.
Please note that there could be multiple shipments for one order.
{
"status": true,
"data": {
"personid": "KCHN-00012345", // Hublify internal customer-id
"orderid": "ACHN-00123456", // Hublify internal order-id
"o_orderid_external": "CH00012345"ACHN-00123456",
"personid": "KCHN-00012345"
}
]
}
}
Response - Error
If your request failed, you receive a message detailing the error that occurred.
{
"status": false,
"msg": [
{
"type": "ERROR",
"text": "Order not found."
}
]
}List of orders
You can also retrieve details for multiple orders at once. For that you can add your own filters and fields. Additional pre-configured filters (e.g. only order from the last 6 months) and field-restrictions could apply depending on how your access was configured.
Request URL
https://{your hublify url}/api/channel_10/order_getListRequest parameter
{
"filter": {
"order_state_code": "shipped", // optional (recommanded),
// example to filter only orders that have been shipped
"order_state_transtime": { // optional (recommanded),
"search": "> -3days" // example to filter only orders that changed the status in the last 3 days
}
}
}Response
You receive a list of orders matching the provided filters.
{
"status": true,
"data": [
{
"personid": "KCHN-00012345", // Hublify internal customer-id
"orderid": "ACHN-00123456", // Hublify internal order-id
"o_orderid_external": "CH00012345", // Your own External order-id if provided
"order_state_code": "shipped", // Current Hublify internal order-state code.
"delivery_list": [
{
"shp_c_label": "dhl",
"shp_c_name": "Deutsche Post DHL",
"dv_extcode": "12345678901234567C",
"drvd_dv_trace_url": "http:\/\/nolp.dhl.de\/nextt-online-public\/set_identcodes.do?lang=de&idc=12345678901234567C",
"dv_time_sent": "2023-03-21 12:34:56",
"orderid": "ACHN-00123456",
"personid": "KCHN-00012345"
}
]
},
{
"personid": "KCHN-00012345", // Hublify internal customer-id
"orderid": "ACHN-00123478", // Hublify internal order-id
"o_orderid_external": "CH00012367", // Your own External order-id if provided
"order_state_code": "shipped", // Current Hublify internal order-state code.
"delivery_list": [
{
"shp_c_label": "dhl",
"shp_c_name": "Deutsche Post DHL",
"dv_extcode": "12345678903456789C",
"drvd_dv_trace_url": "http:\/\/nolp.dhl.de\/nextt-online-public\/set_identcodes.do?lang=de&idc=12345678903456789C",
"dv_time_sent": "2023-03-21 12:34:56",
"orderid": "ACHN-00123478",
"personid": "KCHN-00012345"
}
]
}
]
}Webhook
It is possible to send the data described in the response examples to a webhook on your system and inform you directly about changes to your order.
Please check with the operator of the respective Hublify system if you wish to set up automated outbound calls to a Webhook.