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. 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_integration_instance_id (nullable, integer, must exist in integration_instances AND be a SHIPPING_PROVIDER instance) — per-FO shipping-provider override; null = use 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).

Returns the updated fulfillment order object (which includes next_fulfillment_sequence and is_pickup).

Request​

Responses​

OK

Response Headers
    Content-Type