Fulfillments


About Fulfillments

  • See the Shipments page for more efficient methods of marking orders as shipped - ChannelAdvisor interprets the data provided through the Shipments methods to intelligently create fulfillments as requested.
  • This section outlines direct methods of retrieving and updating Fulfillment-level information. It also provides information on updating a fulfillment previously marked as shipped, and moving an item from one fulfillment to another.
  • Fulfillment(s) are created when an order is created in the system - whether that order originated from the marketplace or via a seller's integration.

Considerations

  • Reference the entity tables below for information about what each field means.
  • In most cases, the fields are not required - it all depends on the seller's goals.
  • DeliveryStatus is the field that controls whether or not the order and items are marked as shipped in the API.
    • Any value other than "NoChange" will result in some action depending on the value set.
    • No validation is completed on the DeliveryStatus - we recommend treating this value as if a shipment was completed, where 'Complete' simply means the item was shipped...not that it is actually delivered.
    • ChannelAdvisor does not link the tracking number to a carrier or class, and no link is made to a carrier's site, and as a result cannot update the DeliveryStatus on the seller's behalf.
  • Some marketplaces require valid Tracking Number information - or it will be rejected when ChannelAdvisor sends it to them.
  • An option exists to fulfill an order from a different DistributionCenterID than what may have been defined in the original order data - this change is not reflected at the marketplace until the next quantity update is sent to the marketplace.
  • Any Carrier and Class values being sent to create or update a Fulfillment must exist in the Account Carrier/Class list.
  • External Fulfillment Center Code will identify the marketplace's defined fulfillment center ID/code in string format. This currently applies to only Amazon FBA (Fulfillment by Amazon) orders, but not Multi-Channel FBA orders.
  • On multi-quantity/multi-item orders, fulfillments may be split by item and/or quantity - it's important to capture the DistributionCenterID in the fulfillment and correlate it to the correct Distribution Center:
    • Item 1 is associated with distribution center 1.
    • Item 2 is associated with distribution center 2.
    • See more about the Distribution Center endpoint to display Distribution Center data.
  • A query string parameter exists to prevent communication of an update to the marketplace.
  • ShippingLabelRequestID can be supplied for two label-specific purchase endpoints noted below. It can only be retrieved from the Fulfillments entity.
  • Fulfillments cannot be canceled/refunded via the /v1/Fulfillments, or /v1/Orders/Ship endpoints.

Process for Partial or Split Fulfillments (Same Steps for Changing the Distribution Center)

Endpoints

All available endpoints for Fulfillments.

All available endpoints for FulfillmentItems.

Query String Parameters

PUT or PATCH /v1/Fulfillments(Fulfillment ID)?PreventMarketplaceCommunication={boolean}Prevent communication of update to the marketplace.

Common Fulfillment Entities for POST / PATCH / PUT

Note: this is not a comprehensive list of all properties available. For a full list of properties, see the Order Entities page and Fulfillment Entity

PropertyType (Max Length)POST RequiredPATCH RequiredDescription
IDinteger (32 bit)Read OnlyRequired in URLUniquely identifies the ChannelAdvisor Fulfillment ID.
ProfileIDinteger (32 bit)Required in BodyOptionalUniquely identifies the ChannelAdvisor account.
OrderID integer (32 bit)Required in Body

Read Only

Uniquely identifies the order within the ChannelAdvisor account.
TypeenumOptionalOptionalIndicates how the items will be fulfilled.
DeliveryStatusenumOptionalOptional

Indicates the progress of the fulfillment.
Requires a value other than 'NoChange' to trigger a "final" (note: can be changed back) status on the item or order.

Important: DeliveryStatus cannot be set to Canceled. To cancel fulfillments, see Refund & Cancel Orders (Item Level) to ensure requests to cancel are sent through to marketplaces.

TrackingNumberstring (50)OptionalOptionalProvided by a shipping carrier to track the progress of a shipment.
ReturnTrackingNumberstring (50)OptionalOptionalProvided by a shipping carrier to track the progress of a return shipment.
ShippingCarrierstring (50)OptionalOptionalIdentifies the shipping carrier or agent of delivery.
ShippingClassstring (50)OptionalOptionalIdentifies the class of shipment or delivery.
DistributionCenterID integer (32 bit)OptionalOptionalIdentifies the distribution center from which the fulfillment will originate. This value is defined by the marketplace, but aligns with the distribution centers internal to the ChannelAdvisor system created by the seller. To change the value, create a new fulfillment and move items to the new fulfillment - see more under the Fulfillments page.
Read more about Distribution Centers and accessing DistributionCenterIDs. 
ExternalFulfillmentCenterCodestringRead OnlyRead OnlyIdentifies the external distribution center from which the fulfillment will originate. This value is defined by the marketplace and does not align with the distribution centers internal to the ChannelAdvisor system created by the seller. This value cannot be changed, and will only apply to FBA orders.
ShippedDateUtcDateTimeOffsetOptionalOptionalTimestamp when the fulfillment was sent.
SellerFulfillmentIDstring (50)OptionalOptionalIdentifier provided by the seller. Amazon only allows integers.
ItemsFulfillmentItem[]RecommendedOptionalThe fulfilled items which comprise the fulfillment. Include this data to add a new fulfillment for partial shipment and/or mark it as shipped within the same request. See fields in FulfillmentItem entity table below.

Common FulfillmentItem Entities for POST / PATCH / PUT

Note: this is not a comprehensive list of all properties available. For a full list of properties, see the Order Entities page and FulfillmentItem Entity

PropertyType (Max Length)POST RequiredPATCH RequiredSOAP EquivalentDescription
OrderItemID integer (32 bit)ConditionalOptionalLineItemIDRequired if ProductID is not provided. The ChannelAdvisor generated unique identifier for the OrderItem.
ProductID integer (32 bit)ConditionalOptionalN/ARequired if OrderItemID is not provided. The ChannelAdvisor generated unique identifier for the Product.
Quantity integer (32 bit)RecommendedOptionalQuantityThe number of units in this fulfillment.

Query String Parameter

PropertyType (Max Length)POST RequiredPATCH RequiredSOAP EquivalentDescription
PreventMarketplaceCommunicationbooleanN/AOptionalN/ADefaults to false. When true, the shipment information passed in the request will not be sent to the marketplace.

Fulfillment Request Examples