The BHN Fulfillment Management Services "FMS" API enables you (the Digital Distribution Partner, a.k.a., DDP) to fulfill Fulfillment Orders using BHN inventory (primarily) in BHN's fulfillment network. You can place (create) Fulfillment Orders that return status (order/item), account-level details, etc. You can place order for any products (physical/egift; open-loop/closed-loop; etc.) that is present in your catalog.

Please consult with your account manager (or implementation manager) the various options that can be on-boarded for your program(s) that will control the user-experience, including but not limited to:

  • Call-backs and payload constraints
  • Kitting (bill of material) setup, enrichment and packaging
  • Fee-based value-added services (bundling, activation, risk, backorder, etc.)
  • Fee-based shipping and handling (e.g., expedited fulfillment)
  • Etc.

You may also get real-time fulfillment status of your Fulfillment Orders (regardless is you created the order via the Fulfillment Management Services API or the Fulfillment Dropship Interface).

The following operations (a.k.a. resources) are included in the FMS API:

The following operations are included in this documentation:

Category

Operation

Description

Version

When and Why should I use this?

Best Practices

Create

CreateOrder

Request that BHN ship items from BHN's Inventory in BHN's fulfillment network to a destination address, e.g., physical product to a physical ship-to address, eGifts to a ship-to email address, etc

As a DDP Developer,

I want to submit an 'aggregate' order

so that I can request the order be fulfilled within the contracted SLA and agreements.

The response will include a fulfillmentOrderID (GUID). It is recommended you persist this value for future the READ API's

This is an asynchronous API call. You must leverage the callback and/or query for order status to determine if order was accepted or rejected.

Read - Order

ListAllFulfillmentOrders

Returns a list of ALL fulfillment order for the given Tenant/MID within a specific order creation date range

Returns a list of fulfillment orders for the given Tenant/MID within a specific order creation date range AND filtered by specific criteria (creation date, fulfillment status, etc.)

As a DDP Developer,

I want to retrieve the list of all orders and order lineitems for my Tenant/MID

so that I can update the order and Order LineItem information in my system and keep track of order status (creation date, fulfillment status, etc)

Read - Order Details

GetFulfillmentOrderDetailsbyFulfillmentOrderID

Returns order details (fulfillment status, errors, error message, etc.) of a specific fulfillment orders.

As a DDP Developer,

I want to retrieve the detail of one order with list of order lineitems for my Tenant/MID by FulfillmentOrderID which is provided in CreateOrder Response

so that I can update the order and Order LineItem information in my system and keep track of order status (creation date, fulfillment status, etc)

If not subscribed for Callback, then use this API to check the status of the order by fulfillmentOrderId (response of CreateOrder API). Also, check the the status of order before cancelling the order.

  • Order Confirmation - check after 60 mins of CreateOrder Request was submitted
    
  • Sent to Printer for Fulfillment - check after 24 hrs of CreateOrder Request was submitted
    
  • Shipped - check after 3 business days of CreateOrder Request was submitted
    

For exact SLA please contact Account Manager

Read - Order Line Items

ListAllOrderLineItemsbyFulfillmentOrderId

Returns all order line items for a specified fulfillment order, identified using the BHN Order ID (vs. Partner Order Number)

Note: Query by Partner Order Number is not allowed as this may return multiple orders (rejection/cancellation scenario).

As a DDP Developer,

I want to retrieve the detail of all lineitems of one order for my Tenant/MID

so that I can update the Order LineItem information in my system and keep track of order status (creation date, fulfillment status, shipping info etc)

If not subscribed for Callback, then use this API to check the status of the order by fulfillmentOrderId (response of CreateOrder API).Also, check the the status of order before cancelling the order.

  • Order Confirmation - check after 60 mins of CreateOrder Request was submitted
    
  • Sent to Printer for Fulfillment - check after 24 hrs of CreateOrder Request was submitted
    
  • Shipped - check after 3 business days of CreateOrder Request was submitted
    

For exact SLA please contact Account Manager

Read - Items Details

ListCardsByFulfillmentOrderID

Returns all the items/cards details (activation status, cardID (a.k.a. accountID), proxy card number, etc.) of all the cards associated with the order

As a DDP Developer,

I want to retrieve the card/item detail of all cards associated to one order for my Tenant/MID

so that I can service my members via a Customer Support Portal.

Read - Items Details

ListCardsBybhnOrderNumber

Returns all the items/cards details (activation status, cardID (a.k.a. accountID), proxy card number, etc.) of all the cards associated with the order

As a DDP Developer,

I want to retrieve the card/item detail of all cards associated to one order for my Tenant/MID

so that I can service my members via a Customer Support Portal.

Read - Items Details

ListAllEgiftsByOrderLineItem

Returns all the items/eGiftID url for all the egifts associated with the order Lineitem

As a DDP Developer,

I want to retrieve the egifts/item detail of all egifts associated to one order Lineitem for my Tenant/MID

so that I can service my members via a Customer Support Portal.

Optional

Update Order Notification (a.k.a., Callback)

Notifies you when an order fulfillment status has changed to ACCEPTED, REJECTED, CANCELLED and SHIPPED.

As a DDP Developer,

I want to be systematically notified when an fulfillment order status has changed

so that I can efficiently pull order details (vs. periodic polling)

🚧

We reserve the right to make changes to the FMS API that are backward compatible. This implies

a) Request Headers and/or Request Parameter can be added that are considered optional

b) Response Headers and/or Response Parameters elements can be added that are considered optional

You must ensure your consumption of these API's are resilient to to support these changes without notice.

In the event a non-backward compatible change is required, a new version of the API will be released.

You are expected to throttle your request as needed to handle timeouts scenario. Please plan on a average of 10 TPS.


Did this page help you?