Use REST API to Update and Split Order Lines

Use the Sales Orders for Order Hub REST API to update or split order lines across sales orders without having to revise them.

You can update scheduling attributes, substitute items, or remove order lines from a shipment set. Oracle Order Management will then send your changes and split lines to downstream fulfillment systems.

Assume only some of the item's quantity on the order line is available on the requested date in the warehouse. The remaining quantity is available on a different date or in another warehouse, or a substitute item is available. You have different ways to reduce the delay when shipping the item to your customer. For example, you can:

  • Split the line into lines x and y, ship the available quantity on the requested date on line x, and then ship the remaining quantity on the next available date on line y.
  • Split the line into lines x and y, ship the available quantity from the warehouse on line x, and then ship the remaining quantity from another warehouse on the requested date on line y.
  • Ship a substitute item.

You can use the UpdateSchedulingAttributeRequest operation in the Sales Orders for Order Hub REST API to update order lines across sales orders, and you can use the SplitFulfillmentLineRequest operation to split order lines across sales orders.

If you split or update scheduling attributes on the lines, then Order Management will compensate the fulfillment tasks, and then send the updated and split lines to your downstream fulfillment system.

Update

You can use UpdateSchedulingAttributeRequest to update these attributes on the order line:

  • Scheduled Ship Date
  • Scheduled Arrival date
  • Warehouse
  • Supplier
  • Supplier Site
  • Shipping Method, including carrier, mode of transport, and service level
  • Demand Class
  • Item
  • Shipment Set

Try It

Assume you have these order lines.

Sales Order Order Line Split Line Item Original Item Quantity Warehouse Requested Ship Date Scheduled Ship Date Shipment Set Status Override Schedule
530866 1 1-1 AS54888 10 M1 7/17/23 7/31/23 Awaiting Shipping No
530866 2 2-1 OM-RT-Standard-Item1 12 M1 7/17/23 7/31/23 SS1 Awaiting Shipping No
530866 3 3-1 OM-RT-Standard-Item4 16 M1 7/17/23 7/31/23 SS1 Awaiting Shipping No
530868 1 1-1 AS92888 11 M1 7/17/23 7/31/23 Awaiting Shipping No

Note:

  • All order lines have a Requested Ship Date of 7/17/23 but the Scheduled Ship Date is 7/31/23, so all lines are behind schedule. The Status is Awaiting Shipping.
  • Sales order 530866 has three lines and order 530868 has one line.
  • Lines 2-1 and 3-1 are part of a shipment set.
  • All lines ship from the M1 warehouse.

To keep your customers happy, you want to:

  • Substitute the AS54888 with another item that you know is ready to ship from the M1 warehouse, which is the SCH_STD_02 item.
  • Remove the item on order line 2-1 from the shipment set so you can ship the item on order line 3-1 separately. Update the schedule dates of order line 3-1 to ship on the requested date.
  • Change the warehouse from M1 to M2 for the AS92888 because M2's inventory is ready to ship.

Here's a payload that you can use to do this:

Here's a payload that you can use to do this:

Notes

  1. Use the updateSchedulingAttributeRequest operation to specify your changes. You can specify this operation anywhere in the Order entity in your payload.
  2. Set FulfillLineID to the original order line that contains the AS54888.
  3. Set ProductNumber to the SCH_STD_02 substitute item on the original order line, then set ScheduleArrivalDateTime and ScheduleShipDateTime to the requested date.
  4. Set FulfillLineID to the original order line that contains the AS29888.
  5. Set FulfillmentOrganizationCode to M2 and set ScheduleArrivalDateTime and ScheduleShipDateTime to the requested date.
  6. Set FulfillLineID to the original order line that contains the OM-RT-Standard-Item1 item.
  7. Set ShipSetName to null to indicate that you want to remove the OM-RT-Standard-Item1 from the ship set.
  8. Update ScheduleArrivalDateTime and ScheduleShipDateTime on order line 3-1 to ship the OM-RT-Standard-Item4 item on the requested date.
  9. Import your payload, then verify that you receive a Success status in the REST API response.

    The orchestration process on the order line uses the attribute that you updated to identify change for a fulfillment task, compensates the fulfillment task, and then sends the updated attribute values on the order lines to the fulfillment system. For example, if you change a scheduled date, substitute the item, or remove an order line from a shipment set, then Order Management compensates the Schedule, Reservation, and Shipping tasks, and then sends the changes to Oracle Global Order Promising and Oracle Inventory Management.

    Next, go to the Order Management work area, open the sales order, then verify your changes.

    The sales order's status is Processing. You know you didn't create a sales order revision because there's no revision number. You only updated the existing version.

  10. The Item attribute on order line 1 contains the substitute SCH_STD_02 item, the Original Item attribute contains the AS54888 item, and the Scheduled Ship Date contains the updated requested date.
  11. Line 1 for sales order 530868 has the M2 warehouse for your AS92888 item with the revised schedule date.
  12. Line 3 for sales order 530866 has the revised dates that you set for the OM-RT-Standard-Item4.
  13. The Shipment Set attribute is empty on line 2. This means you successfully removed OM-RT-Standard-Item1 from the shipment set.
  14. The Status attribute contains Awaiting Shipping. All items except the item on line 2-1 are ready to ship on the requested ship date instead of after the requested ship date.
  15. The Override Schedule attribute contains Yes. You can use this attribute to quickly determine whether you have overridden the original values from the order line.

Click here to see a nifty demonstration of this set up.

For details about REST API, go to REST API for Oracle Supply Chain Management Cloud, then expand Order Management > Sales Orders for Order Hub.

Guidelines for Updating

  • You must include the order lines and an updated value for at least one of the scheduling attributes on each line.
  • As an option, you can include a reason when you update a scheduling attribute or substitute an item.
  • If the item has a coverage, and if you want to substitute the covered item, then the substitute item’s Enable Coverage Contract attribute in the Product Information Management work area must equal Yes.

Configured Items, Kits, and Shipment Sets

  • You must include all of the items that are part of a configured item, kit, or shipment set, and you must use the same values in the scheduling attributes on each line that's part of the configured item, kit, or shipment set.
  • If you want to remove an order line from a shipment set, then include an empty value such as " ", or include the value null in the ShipSetName attribute in the order line entity.
  • You don’t need to unschedule an order line to remove it from a shipment set. For example, you can remove a line that’s in the Awaiting Shipping status from a shipment set. However, if you use the Remove Shipment Set action in the Order Management work area, then you must continue to unschedule the order line before you remove it from the shipment set.
  • You can't change the shipment set on an order line to another value. You can only change it to an empty value.
  • You can update scheduling attributes when you remove an order line from a shipment set. For example, you can update the scheduled ship date, scheduled arrival date, warehouse, shipping method, and so on.

Substitutions

  • If you want to substitute an item on the line, then specify the substitute item in one of these attributes: InventoryItemID, ProductNumber, or ProductDescription.
  • You can update scheduling attributes when you substitute an item. For example, you can update the scheduled ship date, scheduled arrival date, warehouse, shipping method, and so on.
  • You can substitute only a standard item. You can't substitute a configured item, kit, or the child item of a configured item or kit.
  • If the line is in a shipment set, then you can't substitute the item on the order line. Instead, you can remove the order line from the shipment set, and then substitute the item.

Split

You can also use REST API to split an order line. Realize these benefits when you split a line:

  • Provide more flexibility in how you split an order line or update scheduling attributes on the line.
  • Improve efficiency and performance when you split an order line or update scheduling attributes on the line.
  • Improve usability and efficiency when you need to split or update order lines in more than one sales order.
  • Avoid revising sales orders.

Assume you have these order lines.

Sales Order Order Line Split Line Item Original Item Quantity Warehouse Requested Ship Date Scheduled Ship Date Shipment Set Status Override Schedule
530883 1 1-1 OM-RT-Standard-Item3 15 M1 7/17/23 7/31/23 Awaiting Shipping No
530885 2 1-1 OM-RT-Standard-Item6 18 M1 7/17/23 7/31/23 Awaiting Shipping No

Note:

  • All lines ship from the M1 warehouse.
  • Each line is from a different sales order.
  • M1's Requested Ship Date is 7/17/23 on all lines, but the Scheduled Ship Date is 7/31/23, which is after the requested date.

All lines are behind schedule. M1 only has a quantity of 9 for the OM-RT-Standard-Item3, while M2 has enough inventory to fulfill the remaining quantity. To keep your customers happy, you want to:

  • Split the line that has the OM-RT-Standard-Item3 into two lines. You want to ship one line with a quantity of 9 from M1 and another line with the remaining quantity of 6 from M2.
  • Split the line that has the OM-RT-Standard-Item6 into three lines so you can fulfillment them on different dates.

Here's an example payload that you could use to split the line.

{
  "processRequestOfflineAfter": 240,
  "splitFulfillmentLineRequest": [
    {
      "FulfillLineId": 300100599645013,
      "ProductNumber": "OM-RT-Standard-Item3",
      "OrderedQty": "9",
      "FulfillmentOrganizationCode": "M1",
      "ScheduleArrivalDateTime": "2023-07-19T23:59:59+00:00",
      "ScheduleShipDateTime": "2023-07-17T23:59:59+00:00"
    },
    {
      "SplitFromFlineId": 300100599645013,
      "FulfillInstanceId": 1,
      "ProductNumber": "OM-RT-Standard-Item3",
      "OrderedQty": "6",
      "FulfillmentOrganizationCode": "M2",
      "ScheduleArrivalDateTime": "2023-07-19T23:59:59+00:00",
      "ScheduleShipDateTime": "2023-07-17T23:59:59+00:00"
    },
    {
      "FulfillLineId": 300100599645173,
      "ProductNumber": "OM-RT-Standard-Item6",
      "OrderedQty": "3",
      "FulfillmentOrganizationCode": "M1",
      "ScheduleArrivalDateTime": "2023-07-19T23:59:59+00:00",
      "ScheduleShipDateTime": "2023-07-17T23:59:59+00:00"
    },
    {
      "SplitFromFlineId": 300100599645173,
      "FulfillInstanceId": 1,
      "ProductNumber": "OM-RT-Standard-Item6",
      "OrderedQty": "7",
      "FulfillmentOrganizationCode": "M1",
      "ScheduleArrivalDateTime": "2023-07-26T23:59:59+00:00",
      "ScheduleShipDateTime": "2023-07-24T23:59:59+00:00"
    },
    {
      "SplitFromFlineId": 300100599645173,
      "FulfillInstanceId": 2,
      "ProductNumber": "OM-RT-Standard-Item6",
      "OrderedQty": "8",
      "FulfillmentOrganizationCode": "M1",
      "ScheduleArrivalDateTime": "2023-08-02T23:59:59+00:00",
      "ScheduleShipDateTime": "2023-07-31T23:59:59+00:00"
    }
  ]
}

For details about this example, including the payload and results in the Order Management work area, click here, then go to 3:52 in the demonstration.

Guidelines for Splitting

  • You must include the reduced quantity on the original order line and the remaining quantity on the split lines. The sum of these quantities must equal the original quantity. Assume line x has a quantity of 10 and you split x into line x and line y. The sum of the quantities on x and y must equal 10.
  • You can split an order line into more than two lines. For example, you can split an order line into four lines, then assign a different warehouse on each of those four lines.
  • The values in the scheduling attributes on the split lines don't have to match the values on the original line.
  • You can update the scheduling attributes on the original order line when you split it. For example, you can include updated values for the scheduled date, warehouse, supplier, and so on.
  • If you use the splitFulfillmentLineRequest operation in REST API, then you can split the line even if it isn't on a manual step. For example, you can split a line that’s in the Awaiting Shipping status. However, if you use the Split Line action in the Order Management work area, then you must make sure the order line is on a manual step. If you use the Check Availability action, then you must continue to unschedule the order line before you split it through Check Availability.
  • You can't use a single request to split an order line and substitute an item on the original line at the same time. Instead, send one request that substitutes the item on the original line, then send another request that splits the line.
  • If you create your own task and use a hold service on that task, and if your order line is on your task's wait step, then you can't split the order line.
  • You can’t use splitFulfillmentLineRequest to split an order line that includes an inventory transaction.
  • If you split an order line, and if the fulfillment tolerance on the line isn’t 0, and you ship the split line, then Oracle Shipping won’t consider the cumulative quantity that you already shipped across all of the order line’s order lines. Instead, shipping will consider only the quantity on the split line that Shipping is currently shipping.

Configured Items, Kits, and Shipment Sets

  • You must include all of the items that are part of a configured item or kit, and you must use the same values in the scheduling attributes on each line that's part of the configured item or kit.
  • You can’t split an order line that's in a shipment set. Instead, you can remove the order line from the shipment set and then split it.
  • If you split a configured item or a kit, then the split must be in proportion. For details, see How Configure-to-Order Works.

Other Considerations

You can’t use REST API's splitFulfillmentLineRequest or updateSchedulingAttributeRequest on:

  • A return line, coverage, or subscription.
  • An item that you don’t ship.
  • An order line that's already undergoing change or that isn't on an active wait step.
  • An order line that Order Management created while partially fulfilling a drop shipment.
  • A remnant line of a configured item. For more about remnants, see Fulfill Configured Items.
  • A sales order that you submitted before you opted into the Update Attributes on Split Order Lines for Partial Shipments feature.

Notes

  • If the update or split fails for an order line, then Order Management won't update or split the line and instead return an error status. If your request includes more than one order line, then the update or split might be successful for some lines but fail for the other lines. Order Management returns a success status for the successful lines and an error status for the failed lines. If the failed line is part of a configured item, kit, or shipment set, then Order Management won’t update or split any of the items that are part of the configured item, kit, or shipment set, and instead return an error on all the lines.
  • updateSchedulingAttributeRequest sets the Override Schedule attribute to Yes on the order line that you update, and splitFulfillmentLineRequest sets it to Yes on the original order line and on the split lines. Order Management won't create a new revision for the sales order when you use updateSchedulingAttributeRequest or splitFulfillmentLineRequest.
  • You can use the processRequestOfflineAfter operation to manage your REST request to split or update an order line. It works the same when you use REST API to split or update an order line as it does with holds. For details about using it, see Use REST API to Apply and Release Holds.
  • If you use updateSchedulingAttributeRequest on an order line that’s in the Manual Scheduling Required status because you set up scheduling as a manual task in the orchestration process or you unscheduled the line, and if you include a scheduled date and a warehouse attribute, or a scheduled date and a supplier and supplier site attribute in your REST payload, then Order Management will automatically schedule the order line. Order Management applies this same behavior when you use splitFulfillmentLineRequest. For example, if you include these scheduling attributes in your payload, then it will automatically schedule the original line and the split lines.

For more about import, see Overview of Importing Orders Into Order Management.

Other Features

You can also update or split an order line with other Oracle applications:

Privileges

You need these privileges to use updateSchedulingAttributeRequest in the Sales Orders for Order Hub REST API:

  • Create Sales Orders Using REST Services (FOM_SALES_ORDER_REST_POST_PRIV)
  • Modify Orchestration Order Fulfillment Line Attributes (DOO_MODIFY_ORCHESTRATION_ORDER_FULFILLMENT_LINE_ATTRIBUTES_PRIV)

You need these privileges to use splitFulfillmentLineRequest in the Sales Orders for Order Hub REST API:

  • Create Sales Orders Using REST Services (FOM_SALES_ORDER_REST_POST_PRIV)
  • Split Orchestration Order Fulfillment Line (DOO_SPLIT_ORCHESTRATION_ORDER_FULFILLMENT_LINE_PRIV)