# List fulfillments

Retrieve a list of fulfillments based on various filter criteria. You can filter by shipment details,
tracking information, dates, and more to find the specific fulfillments you need.

Endpoint: GET /v2/fulfillments
Version: 2.0.0
Security: api_keys

## Query parameters:

  - `ship_to_name` (string)
    Filter by recipient name

  - `ship_to_country_code` (string)
    Filter by ship-to country code (2-letter ISO country code)
    Example: "US"

  - `shipment_number` (string)
    Filter by shipment number (order number)

  - `shipment_id` (string)
    Filter by specific shipment id
    Example: "se-12345678"

  - `fulfillment_id` (string)
    Filter by specific fulfillment id
    Example: "se-12345678"

  - `batch_id` (string)
    Filter by batch id
    Example: "se-12345678"

  - `order_source_id` (string)
    Filter by order source id (store id)
    Example: "se-12345678"

  - `fulfillment_provider_code` (string)
    Filter by fulfillment provider code

  - `tracking_number` (string)
    Filter by tracking number

  - `ship_date_start` (string)
    Filter by ship date start (inclusive)
    Example: "2024-01-01T00:00:00Z"

  - `ship_date_end` (string)
    Filter by ship date end (inclusive)
    Example: "2024-01-31T23:59:59Z"

  - `create_date_start` (string)
    Filter by creation date start (inclusive)
    Example: "2024-01-01T00:00:00Z"

  - `create_date_end` (string)
    Filter by creation date end (inclusive)
    Example: "2024-01-31T23:59:59Z"

  - `page` (integer)
    Page number for pagination

  - `page_size` (integer)
    Number of results per page

  - `sort_dir` (string)
    Sort direction
    Enum: "asc", "desc"

  - `sort_by` (string)
    Sort field
    Enum: "created_at", "modified_at", "shipped_at"

## Response 200 fields (application/json):

  - `fulfillments` (array)

  - `fulfillments.fulfillment_id` (string)
    Unique identifier for the fulfillment
    Example: "se-12345678"

  - `fulfillments.shipment_id` (string)
    The associated shipment id
    Example: "se-12345678"

  - `fulfillments.shipment_number` (string)
    The shipment number (order number)
    Example: "ORDER-001"

  - `fulfillments.user_id` (string)
    The user id that created this fulfillment
    Example: "00000000-0000-0000-0000-000000000000"

  - `fulfillments.tracking_number` (string)
    Tracking number for the shipment
    Example: "1Z12345E1234567890"

  - `fulfillments.created_at` (string)
    Date and time when the fulfillment was created
    Example: "2024-01-15T10:30:00Z"

  - `fulfillments.ship_date` (string)
    Date when the shipment was shipped
    Example: "2024-01-15T00:00:00Z"

  - `fulfillments.voided_at` (string,null)
    Date and time when the fulfillment was voided
    Example: "2024-01-15T00:00:00Z"

  - `fulfillments.delivered_at` (string,null)
    Date and time when the shipment was delivered
    Example: "2024-01-18T14:22:00Z"

  - `fulfillments.fulfillment_carrier_friendly_name` (string)
    Friendly name of the carrier
    Example: "UPS"

  - `fulfillments.fulfillment_provider_id` (string,null)
    Fulfillment provider ID
    Example: "se-12345678"

  - `fulfillments.fulfillment_provider_friendly_name` (string,null)
    Friendly name of the fulfillment provider
    Example: "ShipStation Fulfillment"

  - `fulfillments.fulfillment_provider_code` (string,null)
    Code of the fulfillment provider
    Example: "shipstation_fulfillment"

  - `fulfillments.fulfillment_service_code` (string,null)
    Service code used for fulfillment
    Example: "ups_ground"

  - `fulfillments.fulfillment_fee` (object)
    Fee charged for the fulfillment

  - `fulfillments.fulfillment_fee.amount` (number)
    Fee amount
    Example: 12.5

  - `fulfillments.fulfillment_fee.currency` (string)
    Currency code
    Example: "usd"

  - `fulfillments.void_requested` (boolean)
    Whether a void has been requested for this fulfillment

  - `fulfillments.voided` (boolean)
    Whether this fulfillment has been voided

  - `fulfillments.order_source_notified` (boolean)
    Whether the order source has been notified
    Example: true

  - `fulfillments.notification_error_message` (string,null)
    Error message if notification failed

  - `fulfillments.ship_to` (object)
    Shipping address information

  - `fulfillments.ship_to.name` (string)
    Recipient name
    Example: "Jane Doe"

  - `fulfillments.ship_to.company_name` (string,null)
    Company name
    Example: "Example Corp"

  - `fulfillments.ship_to.email` (string,null)
    Email address
    Example: "jane@example.com"

  - `fulfillments.ship_to.phone` (string,null)
    Phone number
    Example: "555-555-5555"

  - `fulfillments.ship_to.address_line1` (string)
    Street address line 1
    Example: "525 S Winchester Blvd"

  - `fulfillments.ship_to.address_line2` (string,null)
    Street address line 2

  - `fulfillments.ship_to.address_line3` (string,null)
    Street address line 3

  - `fulfillments.ship_to.city_locality` (string)
    City or locality
    Example: "San Jose"

  - `fulfillments.ship_to.state_province` (string)
    State or province
    Example: "CA"

  - `fulfillments.ship_to.postal_code` (string)
    Postal or ZIP code
    Example: "95128"

  - `fulfillments.ship_to.country_code` (string)
    ISO country code
    Example: "US"

  - `page` (integer)
    Current page number
    Example: 1

  - `pages` (integer)
    Total number of pages
    Example: 10

  - `total` (integer)
    Total number of fulfillments
    Example: 100

  - `links` (object)

  - `links.first` (object)

  - `links.first.href` (string)
    Example: "https://api.shipstation.com/v2/fulfillments?page=1&page_size=100"

  - `links.last` (object)

  - `links.prev` (object)

  - `links.next` (object)

## Response 400 fields (application/json):

  - `request_id` (string, required)
    A UUID that uniquely identifies the request id.
This can be given to the support team to help debug non-trivial issues that may occur
    Example: "aa3d8e8e-462b-4476-9618-72db7f7b7009"

  - `errors` (array, required)
    The errors associated with the failed API call

  - `errors.error_source` (string, required)
    The source of the error, as indicated by the name this informs us if the API call failed because of the
carrier, the order source, or the ShipStation API itself.
    Enum: "carrier", "order_source", "ShipStation"

  - `errors.error_type` (string, required)
    The type of error
    Enum: "account_status", "business_rules", "validation", "security", "system", "integrations"

  - `errors.error_code` (string, required)
    The error code specified for the failed API Call
    Enum: "auto_fund_not_supported", "batch_cannot_be_modified", "carrier_conflict", "carrier_disconnected", "carrier_not_connected", "carrier_not_supported", "confirmation_not_supported", "default_warehouse_cannot_be_deleted", "field_conflict", "field_value_required", "forbidden", "identifier_conflict", "identifiers_must_match", "insufficient_funds", "invalid_address", "invalid_billing_plan", "invalid_field_value", "invalid_identifier", "invalid_status", "invalid_string_length", "label_images_not_supported", "meter_failure", "order_source_not_active", "rate_limit_exceeded", "refresh_not_supported", "request_body_required", "return_label_not_supported", "settings_not_supported", "subscription_inactive", "terms_not_accepted", "tracking_not_supported", "trial_expired", "unauthorized", "unknown", "unspecified", "verification_failure", "warehouse_conflict", "webhook_event_type_conflict", "customs_items_required", "incompatible_paired_labels", "invalid_charge_event", "invalid_object", "no_rates_returned"

  - `errors.message` (string, required)
    An error message associated with the failed API call
    Example: "Body of request cannot be null."

  - `errors.field_name` (string)
    The name of the field that caused the error (only present for validation errors)
    Example: "inventory_warehouse_id"

  - `errors.field_value` (string)
    The invalid value that was provided for the field (only present for validation errors)
    Example: "invalid-id"

## Response 404 fields (application/json):

  - `request_id` (string, required)
    A UUID that uniquely identifies the request id.
This can be given to the support team to help debug non-trivial issues that may occur
    Example: "aa3d8e8e-462b-4476-9618-72db7f7b7009"

  - `errors` (array, required)
    The errors associated with the failed API call

  - `errors.error_source` (string, required)
    The source of the error, as indicated by the name this informs us if the API call failed because of the
carrier, the order source, or the ShipStation API itself.
    Enum: "carrier", "order_source", "ShipStation"

  - `errors.error_type` (string, required)
    The type of error
    Enum: "account_status", "business_rules", "validation", "security", "system", "integrations"

  - `errors.error_code` (string, required)
    The error code specified for the failed API Call
    Enum: "auto_fund_not_supported", "batch_cannot_be_modified", "carrier_conflict", "carrier_disconnected", "carrier_not_connected", "carrier_not_supported", "confirmation_not_supported", "default_warehouse_cannot_be_deleted", "field_conflict", "field_value_required", "forbidden", "identifier_conflict", "identifiers_must_match", "insufficient_funds", "invalid_address", "invalid_billing_plan", "invalid_field_value", "invalid_identifier", "invalid_status", "invalid_string_length", "label_images_not_supported", "meter_failure", "order_source_not_active", "rate_limit_exceeded", "refresh_not_supported", "request_body_required", "return_label_not_supported", "settings_not_supported", "subscription_inactive", "terms_not_accepted", "tracking_not_supported", "trial_expired", "unauthorized", "unknown", "unspecified", "verification_failure", "warehouse_conflict", "webhook_event_type_conflict", "customs_items_required", "incompatible_paired_labels", "invalid_charge_event", "invalid_object", "no_rates_returned"

  - `errors.message` (string, required)
    An error message associated with the failed API call
    Example: "Body of request cannot be null."

  - `errors.field_name` (string)
    The name of the field that caused the error (only present for validation errors)
    Example: "inventory_warehouse_id"

  - `errors.field_value` (string)
    The invalid value that was provided for the field (only present for validation errors)
    Example: "invalid-id"