Skip to main content

Edit Fulfillment Order Shipping Details

PATCH 
/api/fulfillment-orders/:fulfillmentOrder/shipping

Edit the requested shipping params on a proforma fulfillment order before it is submitted — the shipping method, requested ship date, and provider-specific metadata (e.g. notes). These travel with the FO into the submission payload.

Required scope: orders:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Mutability gate. Allowed ONLY while the FO is status=open AND request_status is unsubmitted or rejected (i.e. not yet successfully sent). Once submitting/accepted the carrier owns the values, so edits return 409.

Body fields (all optional — sometimes; only the keys present are written):

  • requested_shipping_method_id (nullable, integer, must exist in shipping_methods) — the chosen shipping method.
  • requested_shipping_method (nullable, string, max 255) — free-text method label (used when no method id applies / provider-specific).
  • requested_ship_date (nullable, date) — requested dispatch date.
  • requested_metadata (nullable, object) — free-form, provider-varying values. Merged onto the saved metadata: keys you leave out are kept, a key sent as null is removed, and sending requested_metadata: null clears all of it. So a request that only changes comments keeps an earlier explicit feature_constraints choice (including an empty []). Only the keys the active provider owns are written; on submission they are bridged onto the SalesOrderFulfillment metadata the carrier dispatchers read.
  • requested_metadata.notes (nullable, string, max 2000) — fulfillment notes for the provider.
  • requested_metadata.signature_required (nullable, boolean) — signature on delivery (Starshipit / ShipHero / ShipMyOrders / ShipFusion). Aliased to isSignatureRequired for ShipHero & ShipMyOrders when bridged onto the fulfillment.
  • requested_metadata.veracore_packing_slip_comments (nullable, string, max 500) — Veracore packing-slip comments.
  • requested_metadata.veracore_shipping_comments (nullable, string, max 500) — Veracore shipping comments.
  • requested_metadata.veracore_third_party_type (nullable, integer, in 1,2,3) — Veracore third-party billing type.
  • requested_metadata.veracore_third_party_account_number (nullable, string, max 100) — Veracore third-party account number.
  • requested_metadata.isInsured (nullable, boolean) — ShipMyOrders insured flag.
  • requested_metadata.instructionsForWarehouse (nullable, string, max 500) — ShipMyOrders warehouse instructions.
  • requested_metadata.fulfillment_sequence (nullable, integer, min 1) — backup override for the postfix pushed to the provider as the order number ({sales_order_number}.{sequence}). Omit/null to auto-assign the next sequence at submit. The current default is exposed on the fulfillment order object as next_fulfillment_sequence.
  • requested_metadata.shipping_speed (nullable, string, in: Standard, Expedited, Priority, ScheduledDelivery) — Amazon MCF shipping speed.
  • requested_metadata.comments (nullable, string, max 1000) — Amazon MCF order comment.
  • requested_metadata.feature_constraints (nullable, array of: BLOCK_AMZL, BLANK_BOX, OVERBOX, PACKING_SLIP, SIGNATURE_CONFIRMATION) — Amazon MCF features, each sent as Required. Omit the key to keep the sales channel's defaults (e.g. a channel-level BLANK_BOX default); send an explicit list — including an empty [] — to replace them. BLOCK_AMZL configured for the sales channel is always sent.
  • requested_integration_instance_id (nullable, integer, must exist in integration_instances AND be a shipping-provider instance) — per-FO shipping-provider override; null = no override (the warehouse's routing rule for the shipping method applies, else the warehouse default).
  • requested_fulfillment_type (nullable, string, in: manual) — per-FO "force Manual" override.

Click & Collect (pickup) lock. When the order's effective shipping method is a pickup method (is_pickup), it is collected in person and is never dispatched — so a requested_integration_instance_id (carrier) or requested_fulfillment_type=manual override is rejected with 422. The lock is keyed on the RESULTING method: passing a non-pickup requested_shipping_method_id in the SAME request releases the lock (the resource then reports is_pickup=false).

Clearing an override. Send "requested_integration_instance_id": null and "requested_fulfillment_type": null to remove a per-order provider / Manual override. The order then resolves by the warehouse's shipping-method routing rule when one applies, otherwise the warehouse default. A per-order override always beats a routing rule.

Returns the updated fulfillment order object at the response root (not wrapped in data), including next_fulfillment_sequence, is_pickup and resolved_provider.

resolved_provider (object): which shipping provider this fulfillment order dispatches to, and why — { integration_instance_id, name, fulfillment_type, source, routing_rule_id }. source names the step that decided it, in precedence order: fba / wfs (Amazon FBA / Walmart WFS warehouse), pickup (Click & Collect method), dispatched (the order has been submitted — the provider it was actually sent to wins over any override, routing rule or default configured since), override (per-order provider override), force_manual (per-order Manual override), routing_rule (the warehouse's shipping-method routing rule — routing_rule_id identifies it; see /api/warehouses/{warehouse}/provider-routing-rules), warehouse_default (the warehouse's default provider), or manual_backstop (nothing configured — ships Manually). integration_instance_id is null for Manual, FBA, WFS and pickup. When a routing rule decides the provider, effective_fulfillment_provider and effective_integration_instance_name reflect the rule too.

On an order that mixes shipped and Click & Collect items, switching a fulfillment order between shipping and pickup moves its lines' delivery method with it. It is refused (409) when a line on it is also split across another open fulfillment order.

Required permission: fulfillment_orders.update (Fulfillment Orders → Edit) and fulfillment_orders.index (Fulfillment Orders → View). A token also needs its orders scope; the owner needs these role permissions.

Request​

Responses​

OK

Response Headers
    Content-Type