Prerequisites
You should have
- an user-account enabled for api access & order management access
- an api-client
Creating a new order
Some quick infos what happens usually inside Hublify whenever you create (aka inject) an order.
- Hublify creates an order-record ...
- with a Hublify internal 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.
.... 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 item
Request URL
https://{your hublify url}/api/eos_10/order_injectRequest parameter
{
"fields": {
"order": {
// Customer data
"invoice_company": "",
"invoice_gender": "male", // Options: "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. If the Product is available in Hublify PIM, the other item-details can be filled from there.
"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": {
"persid": "12345", // Hublify internal primary id for the customer
"personid": "K00012345", // Hublify internal customer-id created / assigned to.
"oid": "123456", // Hublify internal primary id for the order
"orderid": "A00123456", // Hublify internal order-id created.
"o_orderid_external": null, // NULL / empty, because no external order-id was provided in request.
"order_state_code": "received", // Hublify internal order-state code after order injection.
}
}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
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
- customer-id or external customer-id
- order-id or external order-id
- to inject backdated orders, provide the date and time of the original order
Hublify then can detect and avoid unwanted erroneous order injections.
Request URL
https://{your hublify url}/api/eos_10/order_injectRequest parameter
{ "fields": { "person": { "personid": "KABC0000123", // Provide your own unique customer-id here instead of letting one be autocreated "p_personid_external": "ABC000012", // Provide an external unique customer-id here. "bday": "1973-01-22", "telephone": "+4940123456", "telephone_mobile": "+491601234567", "email": "max@muster.de" }, "order": { "orderid": "ABC0000123", // Provide your own unique order-id here instead of letting one be autocreated "o_orderid_external": "EXT12345", // Provide your own unique external order-id here. "o_time_ordered": "2021-01-23 14:56:00", // Provide the original date and time of the order (current time will be used if not set) "invoice_company": "", "invoice_gender": "male",// Options: "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", "deliver_company": null, "deliver_gender": "female","invoice_title": "", // e.g. "Prof.","Dr."..// Options: "male|female|diverse|company""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 } ] }"deliver_title": "", // e.g. "Prof.","Dr."..} }
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 either orderid or o_orderid_external), the second request will fail with a warning, but we will provide the data again.
{
"status": false,
"data": {
"persid": "12345", // Hublify internal primary id for the customer
"personid": "KABC0000123", // Hublify internal customer-id created / assigned to.
"oid": "123456", // Hublify internal primary id for the order
"orderid": "ABC0000123", // Hublify internal order-id created.
"o_orderid_external": "EXT12345", // external order-id if it was provided in request.
"order_state_code": "received", // Hublify internal order-state code after order injection.
},
"msg": [
{
"type": "WARNING",
"text": "Order \"ABC0000123\" was already injected and will be skipped."
}
]
}
... full data provided
In Parameter "autolearn" you can list data that should be learned from the injected orders.
This way you can use the injected order to fill other data in the hublify system like products and campaigns.
Following an example with more possible data provided.
Request URL
https://{your hublify url}/api/eos_10/order_injectRequest parameter
{
"autolearn": [
"campaign", // creates a campaign based on "camp_campaign" if it doesn't exist yet
"shippingtype", // creates a shippingtype based on "st_label" if it doesn't exist yet
"product" // creates a product based on "oi_pcode" if it doesn't exist yet
],
"fields": {
"person": {
"personid": "KABC0000123", // Provide your own unique customer-id here instead of letting one be autocreated
"p_personid_external": "ABC000012", // Provide an external unique customer-id here.
"bday": "1973-01-22",
"telephone": "+4940123456",
"telephone_mobile": "+491601234567",
"email": "max@muster.de",
},
"order": {
"orderid": "ABC0000123", // Provide your own unique order-id here instead of letting one be autocreated
"o_orderid_external": "EXT12345", // Provide your own unique external order-id here.
"o_time_ordered": "2021-03-21 14:15:00",
"o_comment": "A Comment about order ABC0000123",
"camp_campaign": "MyNewCampaign", // With "campaign" listed in "autolearn" this can be automatically created
"st_label": "MyNewShippingtype", // With "shippingtype" listed in "autolearn" this can be automatically created
"invoice_company": "",
"invoice_gender": "male", // Options: "male|female|diverse|company" "invoice_title": "", // e.g. "Prof.","Dr.".. // Options: "male|female|diverse|company"
"deliver_title": "", // e.g. "Prof.","Dr.".. "oi_name": "My New Product",
"oi_quantity": 1,
"oi_type": "product", // this product will be created with "product" in "autolearn" if it doesn't exist yet
"oi_price_single_brutto": 123.45,
"oi_vat_pct": 19
},
{
"oi_pcode": "HFYSHP0001",
"oi_name": "Shipping Cost",
"oi_quantity": 1,
"oi_type": "shipping", // marked a additional shipping cost this will not be created as a product
"oi_price_single_brutto": 1.23,
"oi_vat_pct": 19
}
]
},
"payment": { // Details about Payments
"pys_method": "Remittance"
}
}
}Response
See in examples above the possible responses.