OMS Endpoints

These endpoints can be enabled in the admin interface by adding @EnableFrameworkRestControllers to your admin configuration class. Please see the Full Framework Controller Documentation for more information.

Retrieve Fulfillment Orders

You can return all the FulfillmentOrders for the specified order

OMSEndpoint.getFulfillmentOrders, url: GET /order/{orderNumber}/fulfillmentOrders

Request parameters

Parameter	Type	Description
orderNumber	Required path variable	The Order Number of the order you wish to retrieve the fulfillment orders for

Response

Field	Description
orderNumber	The order number of the associated order
status	Status of the fulfillment order
fulfillmentOrderNumber	The fulfillment order number of the fulfillment order
fulfillmentGroupId	The id of the associated fulfillment group
fulfillmentOrderNotes	A list of the notes on the fulfillment order
items	A list of the items and quantities in the fulfillment order
shipmentDetails	A list of the shipments associated with the fulfillment order
acknowledged	A flag indicating whether the fulfillment order has been read and acknowledged
parentOrderAttributes	attributes from the associated order
customerId	id of the associated customer
customerFirstName	first name of the associated customer
customerLastName	last name of the associated customer
customerEmailAddress	email address of the associated customer

Ship Items

You can ship/fulfill specific items. If a fulfillment order number is provided, then broadleaf will attempt to fulfill the requested items on that fulfillment order. If a fulfillment order is not provided then broadleaf will determine the best fulfillment order capable of completing the request. When processing the request, if a fulfillment order is capable of fulfilling the request but the requested items do not account for all of the items on the fulfillment order, then the fulfillment order will be split into 2 fulfillment orders, one containing the fulfilled items with a status of FULFILLED and one containing the remaining unfulfilled items with the original status.

OMSEndpoint.shipItems, url: POST /order/{orderNumber}/fulfillmentOrders

Request parameters

Parameter	Type	Description
orderNumber	Required path parameter	The order number of the order you want to ship items for
fulfillmentOrderNumber	optional request parameter	The fulfillment order number for the fulfillment order. Required if fulfilling items from a specific Fulfillment Order, otherwise Broadleaf will determine the best Fulfillment Order capable of completing the request
items (skuId, quantity)	required request parameter	A list of the items and quantities you wish to fulfill
shipmentDetails (shipperType, trackingNumber, serviceCode)	optional request parameter	An optional set of information about the shipment. shipperType is type of shipper, i.e. UPS, FEDEX, etc. trackingNumber is the shipper's tracking number. serviceCode is the shipper's service code i.e. 17, 01, 14, etc.
fulfillmentOrderNotes	optional request parameter	Any optional notes you like to add to the fulfillment order that is going to be fulfilled

Example request payload:

{
  "items" : [
    {
      "skuId" : 1,
      "quantity" : 5
    },
    {
      "skuId" : 78,
      "quantity" : 2
    }
  ],

  "shipmentDetails" : [
    {
      "shipperType" : "UPS",
      "trackingNumber" : "1Z204E380338943508",
      "serviceCode" : "01"
    }
  ],

  "fulfillmentOrderNotes" : [
    "Bob packaged and shipped these items"
  ]
}

Retrieve Order Notes

You can retrieve a list of the notes for a specified order

OMSEndpoint.getNotes, url: GET /order/{orderNumber}/notes

Request parameters

Parameter	Type	Description
orderNumber	Required path parameter	The order number of the order you want to retrieve notes for

Response

Field	Description
orderNote	A string containing the contents of the note

Example response:

[
  {
    "orderNote" : "The customer asked for a discount on this order"
  },
  {
    "orderNote" : "Gave the customer a 10% discount"
  }
]

Add Order Notes

You can add an order note to an order.

OMSEndpoint.addNote, url: /order/{orderNumber}/notes: POST

Request parameters

Parameter	Type	Description
orderNumber	Required path parameter	The order number of the order you want to add a note to
orderNote	Required request parameter	The contents of the note that wish to add to the order

Example payload:

{
  "orderNote" : "The customer wants to change their payment method"
}

Cancel Order

You can cancel an Order by order number

OMSEndpoint.cancelOrder, url: /order/{orderNumber}/cancel: POST

Request parameters

Parameter	Type	Description
orderNumber	Required path parameter	The order number of the order you want to cancel
reason	Optional request parameter	The reason the order is being cancelled, i.e. CUSTOMER_REJECT, FRAUD, etc., not required
comment	Optional request parameter	An optional message that will added to the order as a note

Example payload:

{
  "reason" : "FRAUD",
  "comment" : "the credit card was flagged as fraudulent"
}

Cancel Items

You can cancel specific items on an order. If a fulfillment order number is provided, then broadleaf will attempt to cancel the requested items on that fulfillment order. If a fulfillment order is not provided then broadleaf will determine the best fulfillment order capable of completing the request. When processing the request, if a fulfillment order is capable of completing the request but the requested items do not account for all of the items on the fulfillment order, then the fulfillment order will be split into 2 fulfillment orders, one containing the cancelled items with a status of CANCELLED and one containing the remaining items with the original status.

OMSEndpoint.cancelItems, url: /order/{orderNumber}/cancelItems: POST

Request parameters

Parameter	Type	Description
orderNumber	Required path parameter	The order number of the order you want cancel items on
fulfillmentOrderNumber	Optional request parameter	The fulfillment order number for the fulfillment order. Required if cancelling items from a specific Fulfillment Order, otherwise Broadleaf will determine the best Fulfillment Order capable of completing the request
items (skuId, quantity)	Required request parameter	A list of the items and quantities you wish to cancel

Example payload:

{
  "items" : [
    {
      "skuId" : 101,
      "quantity" : 1
    },
    {
      "skuId" : 23,
      "quantity" : 7
    }
  ]
}

Cancel Single Item

You can cancel a single item on a fulfillment order. Much like partially cancelling a fulfillment order, if the quantity to cancel does not account for the total quantity on the fulfillment order, the fulfillment order will be split into 2 fulfillment orders, one with the cancelled item and quantity on it, and one with the remaining items/quantity.

OMSEndpoint.cancelSingleItem, url: /order/{orderNumber}/fulfillment/{fulfillmentOrderId}/item/{skuId}/cancel: POST

Request parameters

Parameter	Type	Description
orderNumber	Required path parameter	The order number of the order you want cancel the item on
fulfillmentOrderId	Required path parameter	The id of the fulfillment order you want cancel the item on
skuId	Required path parameter	The id of the sku on the fulfillment item you want cancel
quantity	Required request parameter	The quantity of the single item to cancel

Example payload:

{
  "quantity" : 3
}

Block Order

You can execute the blocking workflow on an order and block the order

OMSEndpoint.blockOrder, url: /order/{orderNumber}/block: POST

Request parameters

Parameter	Type	Description
orderNumber	Required path parameter	The order number of the order you want to run the blocking workflow on

Update Fulfillment Group Address

You can update the address that is used for shipping by updating a fulfillment group's address

OMSEndpoint.updateFulfillmentGroupAddress, url: /order/{orderNumber}/fulfillment/group/{fulfillmentGroupId}: PUT

Request parameters

Parameter	Type	Description
orderNumber	Required path parameter	The order number of the order with the fulfillment group address you want to update
fulfillmentGroupId	Required path parameter	The id of the fulfillment group you want to update
address	Required request parameter	The address information you want to set on the fulfillment group

Example payload:

{
  "address" : {
    "firstName" : "billy",
    "lastName" : "bob",
    "addressLine1" : "42 Wallaby Way",
    "addressLine2" : "Building 2",
    "addressLine3" : "Suite 401",
    "city" : "Austin",
    "isoCountrySubdivision" : "US",
    "isoCountryAlpha2" : "US",
    "stateProvinceRegion" : "TX",
    "postalCode" : "78701",
    "phonePrimary" : {
      "id" : 10,
      "phoneNumber" : "555-555-5555",
      "isActive" : true,
      "isDefault" : true
    }
  }
}

Retrieve Fulfillment Groups

You can retrieve a list of FulfillmentGroups for a specific order

OMSEndpoint.showFulfillmentGroups, url: /order/{orderNumber}/fulfillment/showGroups: GET

Request parameters

Parameter	Type	Description
orderNumber	Required path parameter	The order number of the order you want to retrieve fulfillment groups for

Response

Field	Description
orderId	the id of the associated order
fulfillmentType	the type of fulfillment used for the fulfillment group, i.e. DIGITAL, PHYSICAL_SHIP
fulfillmentOption	information about the fulfillment group's selected fulfillment option
total	total amount value for the fulfillment group
fulfillmentPrice	the amount charged for fulfillment, such as shipping cost
address	the address information on the fulfillment group, usually the shipping address
phone	the phone information on the fulfillment group

Example response:

[
  {
    "orderId" : 12,
    "fulfillmentType" : "PHYSICAL_SHIP",
    "fulfillmentOption" : {
        "id" : 5,
        "name" : "standard",
        "description" : "5 - 7 Days",
        "fulfillmentType" : "PHYSICAL_SHIP"
    },
    "total" : {
        "amount" : 32.00,
        "currency" : "USD"
    },
    "fulfillmentPrice" : {
        "amount" : 5.00,
        "currency" : "USD"
    },
    "address" : {
        "firstName" : "billy",
        "lastName" : "bob",
        "addressLine1" : "42 Wallaby Way",
        "addressLine2" : "Building 2",
        "addressLine3" : "Suite 401",
        "city" : "Austin",
        "isoCountrySubdivision" : "US",
        "isoCountryAlpha2" : "US",
        "stateProvinceRegion" : "TX",
        "postalCode" : "78701",
        "phonePrimary" : {
          "id" : 7,
          "phoneNumber" : "555-555-5555",
          "isActive" : true,
          "isDefault" : true
        }
    },
    "phone" : {
        "id" : 4,
        "phoneNumber" : "555-555-5555",
        "isActive" : true,
        "isDefault" : false
    }
  }
]

Update Order Payment Address

You can update the billing address on an order payment

OMSEndpoint.updateOrderPaymentAddress, url: /order/{orderNumber}/payment/{paymentId}: PUT

Request parameters

Parameter	Type	Description
orderNumber	Required path parameter	The order number of the order you want to update the order payment addres on
paymentId	Required path parameter	The id of the order payment that you want to update the address on
address	Required request parameter	The address information you want to set on the order payment

Example payload:

{
  "address" : {
    "firstName" : "billy",
    "lastName" : "bob",
    "addressLine1" : "42 Wallaby Way",
    "addressLine2" : "Building 2",
    "addressLine3" : "Suite 401",
    "city" : "Austin",
    "isoCountrySubdivision" : "US",
    "isoCountryAlpha2" : "US",
    "stateProvinceRegion" : "TX",
    "postalCode" : "78701",
    "phonePrimary" : {
      "id" : 10,
      "phoneNumber" : "555-555-5555",
      "isActive" : true,
      "isDefault" : true
    }
  }
}

Retrieve Order Payments

You can retrieve a list of the payments associated with an order

OMSEndpoint.showOrderPayments, url: /order/{orderNumber}/payment/showPayments: GET

Request parameters

Parameter	Type	Description
orderNumber	Required path parameter	The order number of the order you want to retrieve payments for

Response

Example response:

{
    "id" : 3,
    "orderId" : 7,
    "type" : "CREDIT_CARD",
    "billingAddress" : {
        "firstName" : "billy",
        "lastName" : "bob",
        "addressLine1" : "42 Wallaby Way",
        "addressLine2" : "Building 2",
        "addressLine3" : "Suite 401",
        "city" : "Austin",
        "isoCountrySubdivision" : "US",
        "isoCountryAlpha2" : "US",
        "stateProvinceRegion" : "TX",
        "postalCode" : "78701",
        "phonePrimary" : {
            "id" : 10,
            "phoneNumber" : "555-555-5555",
            "isActive" : true,
            "isDefault" : true
        }
    },
    "amount" : 32.00,
    "currency" : "USD",
    "referenceNumber" : "12345",
    "gatewayType" : "Passthrough",
    "isActive" : true,
    "transaction" : {
        "id" : 7,
        "orderPaymentId" : 3,
        "parentTransactionId" : null,
        "type" : "AUTHORIZE_AND_CAPTURE",
        "customerIpAddress" : "192.168.1.1",
        "rawResponse" : "raw string response from the payment gateway",
        "success" : true,
        "amount" : 32.00,
        "currency" : "USD",
        "additionalFields" : [
            {
                "key" : "LAST_FOUR",
                "value" : "4783"
            }
        ]
    }
}