Overview

The Allocate With Custom Filters endpoint allows you to allocate consignments to carrier services while restricting which services can be considered during allocation.

Instead of selecting a carrier service directly, you can apply filters that guide the allocation engine. This allows Ship to continue selecting the best available service while ensuring only services that meet your criteria are considered.

For example, you can restrict allocation to:

  • A specific carrier service
  • A service group (e.g express or economy); or
  • Pickup or collection services

This approach is useful when your application needs to influence allocation behaviour without fully overriding the allocation logic configured in Sorted Ship.

Endpoint 

  PUT /allocation/allocateWithCustomFilters

For more information on this endpoint, please view our API reference.

Request body

Provide a JSON object containing the consignments to allocate and optional filters.

PropertyTypeRequiredDescription
consignmentReferencesstring[]YesThe consignment references to allocate
filtersobjectNoOptional filters used to restrict which services are eligible

Filters

The filters object controls which services are considered during allocation.

PropertyTypeRequiredDescription
serviceReferencestringNoAllocate directly to a specific carrier service
serviceGroupReferencestringNoRestrict allocation to services within a defined group
serviceAttributesobjectNoAdditional attributes used to filter eligible services

You can provide either serviceReference or serviceGroupReference, but not both.

Service attributes

Service attributes allow you to filter services based on their capabilities.

PropertyTypeRequiredDescription
pickupbooleanNoWhen true, only pickup or collection services are considered

Typical use cases for this endpoint

Allocate to a pickup service

Pickup services allow customers to collect package from a designated collection point, such as a shop or locker (PUDO).

To allocate consignments to pickup services, set the pickup attribute to true.

Pickup requirements

To allocate consignments to pickup services:

  1. Set filters.serviceAttributes.pickup to true.
  2. Ensure the destination address includes a shopLocationReference when the consignment was created.
  3. Ensure said shopLocationReference is valid for the targeted carrier.

1. Allocate to any pickup service in a group 

  {
  "consignmentReferences": ["EC-000-05F-MML"],
  "filters": {
    "serviceGroupReference": "pickup-services",
    "serviceAttributes": {
      "pickup": true
    }
  }
}

2. Allocate to a specific pickup service 

  {
  "consignmentReferences": ["EC-000-05F-MML"],
  "filters": {
    "serviceReference": "pickup-service-01",
    "serviceAttributes": {
      "pickup": true
    }
  }
}