> ## Documentation Index > Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt > Use this file to discover all available pages before exploring further. # Fulfill (ship) a parcel > Marks the parcel shipped. This is the same workflow the marketplace operator runs, so the customer's dispatch email, the label purchase and any extension hooks happen exactly as they would had the operator shipped it. `items` narrows the dispatch to part of what the fulfillment holds; the remainder splits onto a new one. Omit it to ship the lot. ## OpenAPI ````yaml /api-reference/seller.yaml patch /api/v3/seller/orders/{order_id}/fulfillments/{id}/fulfill openapi: 3.0.3 info: title: Seller API contact: name: Spree Commerce url: https://spreecommerce.org email: hello@spreecommerce.org description: | Spree Seller API v3 - the marketplace seller panel, where a seller runs their own shop inside someone else's marketplace. This is a branch of its own, not a narrowing of the Admin API. Every endpoint is scoped server-side to the seller the request acts as, which is what makes cross-seller access impossible by construction rather than by rule. Sellers never call the Admin API. ## Authentication Sign in at `POST /api/v3/seller/auth/login` and send the returned JWT as `Authorization: Bearer `. The token carries a `seller_api` audience — a token minted for the storefront or the back office is not accepted here, and vice versa. There is deliberately **no secret API key** for this branch: a credential that could act as a seller without a seller signing in is exactly what the separate audience exists to prevent. ### Choosing a seller A user may run more than one seller. Login returns the list; send the chosen seller's ID in the `X-Spree-Seller-Id` header on every authenticated request. The store is derived from the seller — never sent — so no header can widen what a seller reaches. A request that names no seller the caller belongs to is rejected with `403`. ## Response Format All responses are JSON. List endpoints return paginated responses with `data` and `meta` keys. ## Error Handling Errors return a consistent format: ```json { "error": { "code": "validation_error", "message": "Validation failed", "details": { "name": ["can't be blank"] } } } ``` version: v3 servers: - url: http://{defaultHost} variables: defaultHost: default: localhost:3000 security: [] tags: - name: Authentication description: Seller sign-in, token refresh, logout, and invitation acceptance - name: Account description: The signed-in user, the sellers they may act for, and what they may do - name: Countries description: Country and state reference data for the panel's address forms - name: Delivery Methods description: >- The seller's own ways to ship, and the marketplace methods shared with them - name: Delivery Profiles description: >- The marketplace's delivery vocabulary — what kind of goods a product is, which decides how it ships - name: Delivery Zones description: >- The marketplace's destinations, for narrowing where a seller's own method ships - name: Onboarding description: >- The marketplace checklist a seller completes before admission, and what they submit against it - name: Policies description: The seller's own legal documents, as the marketplace asks them to publish - name: Product Types description: The types a seller may list a product against, and what each adds - name: Products description: The seller's own catalog - name: Profile description: >- The seller's own record — presentation, contact details, addresses, and tax registration - name: Stock Locations description: Where the seller keeps stock, and so where their returns are sent - name: Team description: Who runs this seller, and the invitations nobody has accepted yet - name: Files description: Uploading the files a profile, a submission or an import uses paths: /api/v3/seller/orders/{order_id}/fulfillments/{id}/fulfill: parameters: - name: order_id in: path description: Prefixed order ID required: true schema: type: string - name: id in: path description: Prefixed fulfillment ID required: true schema: type: string patch: tags: - Fulfillments summary: Fulfill (ship) a parcel description: | Marks the parcel shipped. This is the same workflow the marketplace operator runs, so the customer's dispatch email, the label purchase and any extension hooks happen exactly as they would had the operator shipped it. `items` narrows the dispatch to part of what the fulfillment holds; the remainder splits onto a new one. Omit it to ship the lot. parameters: - name: X-Spree-Seller-Id in: header required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/FulfillmentFulfillParams' responses: '200': description: parcel shipped content: application/json: example: id: ful_UkLWZg9DAJ number: R1001-F1 status: fulfilled tracking: TRACK-1 tracking_url: null fulfilled_at: '2026-01-15T12:00:00.000Z' delivered_at: null created_at: '2026-01-15T12:00:00.000Z' updated_at: '2026-01-15T12:00:00.000Z' fulfillment_type: shipping delivery_method_name: UPS Ground 130 stock_location_name: Mirta Herman stock_location_id: sloc_UkLWZg9DAJ fulfillment_items: - id: fi_UkLWZg9DAJ quantity: 1 line_item_id: li_UkLWZg9DAJ variant_id: variant_UkLWZg9DAJ name: Product 253961 sku: SKU-339 options_text: '' selected_delivery_rate_id: dr_gbHJdmfrXB delivery_rates: - id: dr_gbHJdmfrXB name: UPS Ground 130 selected: true cost: '10.00' total: '10.00' carrier: null service_level: null estimated_delivery_date: null unpriced: false deliveries: - id: dlv_UkLWZg9DAJ tracking_number: TRACK-1 carrier: null carrier_name: null service: null status: pending tracking_url: null estimated_delivery_at: null delivered_at: null created_at: '2026-01-15T12:00:00.000Z' updated_at: '2026-01-15T12:00:00.000Z' shipping_label_id: null labels: [] schema: $ref: '#/components/schemas/Fulfillment' security: - bearer_auth: [] x-codeSamples: - lang: javascript label: Spree Seller SDK source: >- import { createSellerClient } from '@spree/seller-sdk' const client = createSellerClient({ baseUrl: 'https://your-store.com', jwtToken: 'eyJhbGciOi...', sellerId: 'sel_UkLWZg9DAJ', }) const fulfillment = await client.orders.fulfillments.fulfill('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ', { tracking: '1Z879E930346834440', tracking_carrier: 'ups', notify_customer: true, }) components: schemas: FulfillmentFulfillParams: type: object properties: tracking: type: string description: Carrier tracking number. tracking_carrier: type: string description: Carrier name. notify_customer: type: boolean description: Send the dispatch email (default true). items: type: array items: type: object properties: item_id: type: string description: Prefixed line item ID. quantity: type: integer required: - item_id - quantity description: Ship only these lines; the rest split onto a new fulfillment. Fulfillment: type: object properties: id: type: string number: type: string status: anyOf: - type: string enum: - unfulfilled - fulfilled - delivered - canceled - type: string description: The values listed are the built-in ones; extensions may add more. tracking: type: string nullable: true tracking_url: type: string nullable: true fulfilled_at: type: string nullable: true delivered_at: type: string nullable: true created_at: type: string updated_at: type: string fulfillment_type: type: string nullable: true delivery_method_name: type: string nullable: true stock_location_name: type: string nullable: true stock_location_id: type: string nullable: true fulfillment_items: type: array items: $ref: '#/components/schemas/FulfillmentItem' selected_delivery_rate_id: type: string nullable: true delivery_rates: type: array items: $ref: '#/components/schemas/DeliveryRate' deliveries: type: array items: $ref: '#/components/schemas/Delivery' labels: type: array items: $ref: '#/components/schemas/ShippingLabel' required: - id - number - status - tracking - tracking_url - fulfilled_at - delivered_at - created_at - updated_at - fulfillment_type - delivery_method_name - stock_location_name - stock_location_id - fulfillment_items - selected_delivery_rate_id - delivery_rates - deliveries - labels x-typelizer: true FulfillmentItem: type: object properties: id: type: string quantity: type: number line_item_id: type: string nullable: true variant_id: type: string nullable: true name: type: string nullable: true sku: type: string nullable: true options_text: type: string nullable: true required: - id - quantity - line_item_id - variant_id - name - sku - options_text x-typelizer: true DeliveryRate: type: object properties: id: type: string name: type: string selected: type: boolean cost: type: string total: type: string carrier: type: string nullable: true service_level: type: string nullable: true estimated_delivery_date: type: string nullable: true unpriced: type: boolean required: - id - name - selected - cost - total - carrier - service_level - estimated_delivery_date - unpriced x-typelizer: true Delivery: type: object properties: id: type: string tracking_number: type: string carrier: type: string nullable: true carrier_name: type: string nullable: true service: type: string nullable: true status: type: string enum: - pending - pre_transit - in_transit - out_for_delivery - available_for_pickup - delivered - return_to_sender - failure - unknown tracking_url: type: string nullable: true estimated_delivery_at: type: string nullable: true delivered_at: type: string nullable: true created_at: type: string updated_at: type: string shipping_label_id: type: string nullable: true required: - id - tracking_number - carrier - carrier_name - service - status - tracking_url - estimated_delivery_at - delivered_at - created_at - updated_at - shipping_label_id x-typelizer: true ShippingLabel: type: object properties: id: type: string source: type: string enum: - purchased - uploaded status: anyOf: - type: string enum: - purchased - refund_requested - refunded - type: string description: The values listed are the built-in ones; extensions may add more. carrier: type: string nullable: true carrier_name: type: string nullable: true service: type: string nullable: true tracking_number: type: string nullable: true currency: type: string nullable: true enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BRL - BSD - BTN - BWP - BYN - BYR - BZD - CAD - CDF - CHF - CLF - CLP - CNY - COP - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EEK - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LTL - LVL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MRU - MTL - MUR - MVR - MWK - MXN - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SKK - SLE - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMM - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - UYI - UYU - UYW - UZS - VED - VEF - VES - VND - VUV - WST - XAF - XCD - XCG - XOF - XPF - YER - ZAR - ZMK - ZMW - ZWD - ZWG - ZWL - ZWN - ZWR format: type: string nullable: true enum: - pdf - png - zpl external_id: type: string nullable: true metadata: type: object refunded_at: type: string nullable: true created_at: type: string updated_at: type: string owner_id: type: string owner_type: type: string enum: - fulfillment - return cost: type: string integration_id: type: string nullable: true file_pending: type: boolean download_url: type: string nullable: true required: - id - source - status - carrier - carrier_name - service - tracking_number - currency - format - external_id - metadata - refunded_at - created_at - updated_at - owner_id - owner_type - cost - integration_id - file_pending - download_url x-typelizer: true securitySchemes: bearer_auth: type: http scheme: bearer bearerFormat: JWT description: JWT token for an authenticated seller session (`seller_api` audience) ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.