OMS Bulk Endpoints
The Broadleaf OMS module provides endpoints for reading Orders and Fulfillment Order in large amounts and acknowledging that they have been received and read. This provides an easy way for external services to integrate with the Broadleaf OMS module and retrieve order and fulfillment information.
Retrieving Orders
The Broadleaf OMS module provides 2 endpoints for retrieving Orders, one for retrieval and one for acknowledging that Orders have been read.
OMSBulkEndpoint.listOrders, url: GET /bulk-order/orders:
Request parameters
| Parameter | Type | Description |
|---|---|---|
| token | Optional request parameter | a token indicating the submit date and the id of the last Order returned, in the format {epocTimeInMilliseconds}-{orderId} |
| maxRecords | Optional request parameter | the max number of Order records to return, defaults to 10 |
| status | Optional request parameter | the status of the Order's you want to retrieve, defaults to SUBMITTED |
| includeBlockedOrders | Optional request parameter | boolean indicating whether to return orders that are blocked or not, defaults to false |
| acknowledged | Optional request parameter | boolean indicating whether to return orders that have been acknowledged or not, defaults to false |
| beginDate | Optional request parameter | the beginning submit date for the range of Orders to be returned, in ISO date time format yyyy-MM-dd'T'HH:mm:ss.SSSZ, defaults to January 1, 1970 |
| endDate | Optional request parameter | the end submit date for the range of Orders to be returned, in ISO data time format yyyy-MM-dd'T'HH:mm:ss.SSSZ, defaults to 24 hours in the future |
The response from this endpoint will return a list of Orders and a token in the same format described above in the parameters. This allows you to pass this token on subsequent requests in order to get the next set of orders easily without having to change very much about your requests.
Example request:
.../bulk-order/orders
Example response:
{
"bulkToken": "1489174139000-1",
"items": [
{
"id": 1,
"orderNumber": "201703101328591711",
"status": "SUBMITTED",
"totalTax": {
"amount": "0.00",
"currency": "USD"
},
"totalShipping": {
"amount": "5.00",
"currency": "USD"
},
"subTotal": {
"amount": "9.99",
"currency": "USD"
},
"total": {
"amount": "14.99",
"currency": "USD"
},
"itemCount": 1,
"customer": {
"id": 100,
"firstName": null,
"lastName": null,
"emailAddress": null,
"customerAttribute": null
},
"orderItem": [
{
"id": 1,
"name": "Green Ghost",
"quantity": 1,
"retailPrice": {
"amount": "11.99",
"currency": "USD"
},
"salePrice": {
"amount": "9.99",
"currency": "USD"
},
"orderId": 1,
"categoryId": 2002,
"skuId": 7,
"productId": 7,
"isBundle": false,
"parentOrderItemId": null,
"isDiscountingAllowed": true,
"orderItemAttribute": null,
"orderItemPriceDetails": [
{
"id": 1,
"totalAdjustmentValue": {
"amount": "0.00",
"currency": "USD"
},
"totalAdjustedPrice": {
"amount": "9.99",
"currency": "USD"
},
"quantity": 1,
"adjustment": []
}
],
"bundleItem": null,
"childOrderItems": [],
"qualifier": null
}
],
"fulfillmentGroup": [
{
"id": 1,
"orderId": 1,
"fulfillmentType": null,
"fulfillmentOption": {
"id": 1,
"name": "Standard",
"description": "5 - 7 Days",
"fulfillmentType": {
"friendlyName": "Physical Ship",
"type": "PHYSICAL_SHIP"
}
},
"total": {
"amount": "14.99",
"currency": "USD"
},
"fulfillmentPrice": {
"amount": "5.00",
"currency": "USD"
},
"address": {
"id": 2,
"firstName": null,
"lastName": null,
"addressLine1": "807 Brazos Street",
"addressLine2": null,
"addressLine3": null,
"city": "Austin",
"state": null,
"country": null,
"isoCountrySubdivision": "US-TX",
"stateProvinceRegion": "TX",
"isoCountryAlpha2": {
"name": "United States",
"alpha2": "US"
},
"postalCode": "55555",
"phonePrimary": {
"id": 2,
"phoneNumber": "5555555555",
"isActive": true,
"isDefault": false
},
"phoneSecondary": null,
"phoneFax": null,
"companyName": null,
"isBusiness": false,
"isDefault": false
},
"phone": null,
"fulfillmentGroupAdjustment": null,
"fulfillmentGroupItem": [
{
"id": 1,
"fulfillmentGroupId": 1,
"orderItemId": 1,
"orderItem": {
"id": 1,
"name": "Green Ghost",
"quantity": 1,
"retailPrice": {
"amount": "11.99",
"currency": "USD"
},
"salePrice": {
"amount": "9.99",
"currency": "USD"
},
"orderId": 1,
"categoryId": 2002,
"skuId": 7,
"productId": 7,
"isBundle": false,
"parentOrderItemId": null,
"isDiscountingAllowed": true,
"orderItemAttribute": null,
"orderItemPriceDetails": [
{
"id": 1,
"totalAdjustmentValue": {
"amount": "0.00",
"currency": "USD"
},
"totalAdjustedPrice": {
"amount": "9.99",
"currency": "USD"
},
"quantity": 1,
"adjustment": []
}
],
"bundleItem": null,
"childOrderItems": [],
"qualifier": null
},
"totalTax": {
"amount": "0.00",
"currency": "USD"
},
"quantity": 1,
"totalItemAmount": {
"amount": "9.99",
"currency": "USD"
},
"taxDetail": null
}
],
"taxDetail": null
}
],
"payment": [
{
"id": 2,
"orderId": 1,
"type": "CREDIT_CARD",
"billingAddress": {
"id": 3,
"firstName": "bob",
"lastName": "",
"addressLine1": "807 Brazos Street",
"addressLine2": "",
"addressLine3": null,
"city": "Austin",
"state": {
"name": "TEXAS",
"abbreviation": "TX"
},
"country": {
"name": "United States",
"abbreviation": "US"
},
"isoCountrySubdivision": "US-TX",
"stateProvinceRegion": "TX",
"isoCountryAlpha2": {
"name": "United States",
"alpha2": "US"
},
"postalCode": "55555",
"phonePrimary": null,
"phoneSecondary": null,
"phoneFax": null,
"companyName": null,
"isBusiness": false,
"isDefault": false
},
"amount": "14.99",
"currency": "USD",
"referenceNumber": null,
"gatewayType": "NULL_GATEWAY",
"isActive": true,
"transactions": [
{
"id": 1,
"orderPaymentId": 2,
"parentTransactionId": null,
"type": "AUTHORIZE_AND_CAPTURE",
"customerIpAddress": null,
"rawResponse": "{\"attributes\": {\"org.springframework.web.servlet.HandlerMapping.bestMatchingPattern\":\"/sample-checkout/return\",\"blSandboxDisplayDateTimeDate\":\"03/10/2017\",\"javax.servlet.request.ssl_session_id\":\"58c2fe3547c60e833f74f38e6a1cdd3096144a34e870fa89b347c39b4d727505\",\"blSandboxDisplayDateTimeMinutes\":\"28\",\"org.springframework.web.servlet.HandlerMapping.pathWithinHandlerMapping\":\"/sample-checkout/return\",\"javax.servlet.request.ssl_session\":\"58c2fe3547c60e833f74f38e6a1cdd3096144a34e870fa89b347c39b4d727505\",\"javax.servlet.request.cipher_suite\":\"TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256\",\"blSandboxDisplayDateTimeHours\":\"1\"},\"parameters\": {\"TRANSACTION_AMT\":\"14.99\",\"ORDER_ID\":\"1\",\"GATEWAY_TRANSACTION_ID\":\"bf9a72a0-0bf4-4dd2-bdd2-7d8541e7618d\",\"MESSAGE\":\"Success!\",\"SUCCESS\":\"true\",\"NULL_BILLING_FIRST_NAME\":\"bob\",\"NULL_BILLING_LAST_NAME\":\"\",\"NULL_BILLING_ADDRESS_LINE1\":\"807 Brazos Street\",\"NULL_BILLING_ADDRESS_LINE2\":\"\",\"NULL_BILLING_CITY\":\"Austin\",\"NULL_BILLING_STATE\":\"TX\",\"NULL_BILLING_ZIP\":\"55555\",\"NULL_BILLING_COUNTRY\":\"US\",\"NULL_SHIPPING_FIRST_NAME\":\"bob\",\"NULL_SHIPPING_LAST_NAME\":\"\",\"NULL_SHIPPING_ADDRESS_LINE1\":\"807 Brazos Street\",\"NULL_SHIPPING_ADDRESS_LINE2\":\"\",\"NULL_SHIPPING_CITY\":\"Austin\",\"NULL_SHIPPING_STATE\":\"TX\",\"NULL_SHIPPING_ZIP\":\"55555\",\"NULL_SHIPPING_COUNTRY\":\"US\",\"CREDIT_CARD_NAME\":\"Hotsauce Connoisseur\",\"CREDIT_CARD_LAST_FOUR\":\"1111\",\"CREDIT_CARD_TYPE\":\"VISA\",\"CREDIT_CARD_EXP_DATE\":\"01/99\"}}",
"success": true,
"amount": "14.99",
"currency": "USD",
"additionalField": [
{
"key": "MESSAGE",
"value": "Success!"
},
{
"key": "EXP_DATE",
"value": "01/99"
},
{
"key": "NAME_ON_CARD",
"value": "Hotsauce Connoisseur"
},
{
"key": "CARD_TYPE",
"value": "VISA"
},
{
"key": "GATEWAY_TRANSACTION_ID",
"value": "bf9a72a0-0bf4-4dd2-bdd2-7d8541e7618d"
},
{
"key": "LAST_FOUR",
"value": "1111"
}
]
}
]
}
],
"orderAdjustment": null,
"orderAttribute": null,
"cartMessages": null
}
]
}
When the end of the set of Orders has been reached, the endpoint will return an empty set of items and a null bulk token, example:
{
"bulkToken": null,
"items": []
}
Acknowledging Orders
You can send a list of order acknowledgements to acknowledge that the orders have been read.
OMSEndpoint.acknowledgeOrder, url: PATCH /order/acknowledgeOrder:
Request parameters
| Parameter | Type | Description |
|---|---|---|
| orderId | Required request parameter | The id of the order you want to acknowledge |
| acknowledged | Required request parameter | a flag indicating if the order is acknowledged or not |
| inFulfillment | Optional request parameter | a flag indicating if the order is in fulfillment in another system and the status of the order should be updated to IN_FULFILLMENT, defaults to true |
| externalOrderId | Optional request parameter | if it is provided the external id will be set on the Order while the acknowledgement flag is being set. This provides an easy way to tell the Broadleaf OMS module that an order has been read and a record with another id has been created in another system. |
Example payload:
[
{
"orderId" : 1,
"acknowledged" : true,
"inFulfillment" : true,
"externalOrderId" : "external-order-1"
},
{
"orderId" : 2,
"acknowledged" : true,
"inFulfillment" : true,
"externalOrderId" : "external-order-2"
},
{
"orderId" : 3,
"acknowledged" : true,
"inFulfillment" : false,
"externalOrderId" : "external-order-3"
}
]
Retrieving Fulfillment Orders
Just like Orders, the Broadleaf OMS module provides 2 endpoints for retrieving Fulfillment Orders, one for retrieval and one for acknowledging that Fulfillment Orders have been read.
OMSBulkEndpoint.listFulfillmentOrders, url: GET /bulk-order/fulfillmentOrders/
Request parameters
| Parameter | Type | Description |
|---|---|---|
| token | Optional request parameter | a token indicating the submit date of the associated Order and the id of the last Fulfillment Order returned, in the format {epocTimeInMilliseconds}-{fulfillmentOrderId} |
| maxRecords | Optional request parameter | the max number of Fulfillment Order records to return, defaults to 10 |
| status | Optional request parameter | the status of the Fulfillment Order's you want to retrieve, defaults to NEW |
| includeBlockedOrders | Optional request parameter | boolean indicating whether to return fulfillment orders that are associated with blocked orders or not, defaults to false |
| acknowledged | Optional request parameter | boolean indicating whether to return fulfillment orders that have been acknowledged or not, defaults to false |
| beginDate | Optional request parameter | the beginning submit date for the range of Fulfillment Orders to be returned, in ISO date time format yyyy-MM-dd'T'HH:mm:ss.SSSZ, defaults to January 1, 1970 |
| endDate | Optional request parameter | the end submit date for the range of Fulfillment Orders to be returned, in ISO date time format yyyy-MM-dd'T'HH:mm:ss.SSSZ, defaults to 24 hours in the future |
Just like the bulk Order endpoint, the response from this endpoint will return a list of Fulfillment Orders and a token in the same format described above in the parameters. This allows you to pass this token on subsequent requests in order to get the next set of Fulfillment Orders easily without having to change very much about your requests.
Example request:
.../bulk-order/fulfillmentOrders
Example response:
{
"bulkToken": "1489174298000-2",
"items": [
{
"orderNumber": "201703101328591711",
"status": "New",
"fulfillmentOrderNumber": "1-1-1",
"fulfillmentGroupId": 1,
"fulfillmentOrderNotes": null,
"items": [
{
"skuId": 7,
"quantity": 1
}
],
"shipmentDetails": [],
"acknowledged": null,
"parentOrderAttributes": [],
"customerId": 100,
"customerFirstName": null,
"customerLastName": null,
"customerEmailAddress": null
},
{
"orderNumber": "201703101331375222",
"status": "New",
"fulfillmentOrderNumber": "2-2-1",
"fulfillmentGroupId": 2,
"fulfillmentOrderNotes": null,
"items": [
{
"skuId": 8,
"quantity": 1
}
],
"shipmentDetails": [],
"acknowledged": null,
"parentOrderAttributes": [],
"customerId": 101,
"customerFirstName": null,
"customerLastName": null,
"customerEmailAddress": null
}
]
}
When the end of the set of Fulfillment Orders has been reached, the endpoint will return an empty set of items and a null bulk token, example:
{
"bulkToken": null,
"items": []
}
Acknowledging Fulfillment Orders
You can send a list of fulfillment order acknowledgements to acknowledge that the fulfillment orders have been read.
OMSEndpoint.acknowledgeFulfillmentOrder, url: PATCH /order/acknowledgeFulfillmentOrder
Request parameters
| Parameter | Type | Description |
|---|---|---|
| fulfillmentOrderId | Required request parameter | The id of the fulfillment order you want to acknowledge |
| acknowledged | Required request parameter | a flag indicating if the fulfillment order is acknowledged or not |
| inFulfillment | Optional request parameter | a flag indicating if the fulfillment order is in fulfillment in another system and the status of the fulfillment order should be updated to PROCESSING, defaults to true |
| externalFulfillmentOrderId | Optional request parameter | if it is provided the external id will be set on the fulfillment order while the acknowledgement flag is being set. This provides an easy way to tell the Broadleaf OMS module that a fulfillment order has been read and a record with another id has been created in another system. |
[
{
"fulfillmentOrderId" : 1,
"externalFulfillmentOrderId" : "external-fulfillment-order-1",
"acknowledged" : true
"inFulfillment" : true,
},
{
"fulfillmentOrderId" : 2,
"externalFulfillmentOrderId" : "external-fulfillment-order-2",
"acknowledged" : true
"inFulfillment" : true,
},
{
"fulfillmentOrderId" : 3,
"externalFulfillmentOrderId" : "external-fulfillment-order-3",
"acknowledged" : true
"inFulfillment" : false,
}
]