Migration Guide

delivery api migration there have been notable changes to the delivery api to support multiple couriers per delivery and a new requirement for specifying the delivery provider source this guide outlines how to handle these changes deadline january 5th, 2026 to meet the january 5th, 2026 deadline, your integration must be updated to use the new courier schema reference docid 7gv344rnwmuoknj9u4rw7 and courier schema reference docid 7gv344rnwmuoknj9u4rw7 arguments when assigning a courier through courier schema reference docid 7gv344rnwmuoknj9u4rw7 , courier schema reference docid 7gv344rnwmuoknj9u4rw7 , courier schema reference docid 7gv344rnwmuoknj9u4rw7 , and courier schema reference docid 7gv344rnwmuoknj9u4rw7 migrating to use courierid for mutations courier schema reference docid 7gv344rnwmuoknj9u4rw7 , courier schema reference docid 7gv344rnwmuoknj9u4rw7 , courier schema reference docid 7gv344rnwmuoknj9u4rw7 , and courier schema reference docid 7gv344rnwmuoknj9u4rw7 is not required for this deadline but is highly recommended as the next step in your integration upgrade action required by deadline the deliveryserviceprovider argument on courier schema reference docid 7gv344rnwmuoknj9u4rw7 is now deprecated it has been replaced by two new fields that must be provided within the courier object itself courier schema reference docid 7gv344rnwmuoknj9u4rw7 a required enum ( in house or third party ) that specifies who is fulfilling the delivery courier schema reference docid 7gv344rnwmuoknj9u4rw7 the name of the service provider this is only necessary/required if providersource is third party (e g , "doordash", "uber direct") you must send these new arguments when using courier schema reference docid 7gv344rnwmuoknj9u4rw7 , courier schema reference docid 7gv344rnwmuoknj9u4rw7 , courier schema reference docid 7gv344rnwmuoknj9u4rw7 , and courier schema reference docid 7gv344rnwmuoknj9u4rw7 a note on changes to assist with the january 5th, 2026 deadline, the new providersource and providername arguments have also been added to the courier schema reference docid 7gv344rnwmuoknj9u4rw7 object this was done to support integrations that have not yet migrated away from the deprecated inline courier assignment (i e , you are still passing the courier object to courier schema reference docid 7gv344rnwmuoknj9u4rw7 , courier schema reference docid 7gv344rnwmuoknj9u4rw7 , courier schema reference docid 7gv344rnwmuoknj9u4rw7 , and courier schema reference docid 7gv344rnwmuoknj9u4rw7 this change allows you to pass the new required providersource and providername arguments through the deprecated courier argument , enabling you to meet the deadline without immediately refactoring for the migration guide /#recommended next steps examples migrating a courierassign call this example shows the specific change required to meet the deadline before { "input" { "courier" { "id" "your courier id", "firstname" "jane", "lastname" "doe", "phone" "+16175551234" }, "deliveryid" "ezcater delivery id", "deliveryserviceprovider" "doordash" } } after { "input" { "courier" { "id" "your courier id", "firstname" "jane", "lastname" "doe", "phone" "+16175551234", "providername" "doordash", "providersource" "third party", }, "deliveryid" "ezcater delivery id" } } note deliverysericeprovider is removed and providername and providersource is added inside the courier object meeting the deadline with couriereventcreate (deprecated flow) { "input" { "courier" { "id" "your courier id", "firstname" "jane", "lastname" "doe", "phone" "+16175551234", "providersource" "in house" }, "deliveryid" "ezcater delivery id", "eventtype" "picked up", "occurredat" "2025 11 01t22 03 03z" } } while this path provides a bridge to compliance, we strongly recommend prioritizing the migration to the two step process (only assigning couriers through courierassign or couriersassign ) as outlined in the migration guide /#recommended next steps recommended next steps migrating to courierid this migration is not required for the january 5th, 2026 deadline but is the next step to fully modernize your integration passing the courier object to mutations courier schema reference docid 7gv344rnwmuoknj9u4rw7 , courier schema reference docid 7gv344rnwmuoknj9u4rw7 , courier schema reference docid 7gv344rnwmuoknj9u4rw7 , and courier schema reference docid 7gv344rnwmuoknj9u4rw7 will not be allowed in the near future this means a courier must be created and assigned to a delivery before you can reference them in other operations new two step process your integration must eventually be updated to follow this two step process assign courier(s) use courierassign or couriersassign to create/update and assign the courier(s) to the delivery perform action use the courierid from the prior step to call other mutations all courier creation, updates, and assignments are being centralized to courierassign and couriersassign couriersassign (the new standard) the new couriersassign mutation is the standard for managing assignments behavior it accepts a list of courierassignmentinput objects use case use this to set or overwrite the complete list of couriers to remove all couriers, pass an empty list assigning two couriers with couriersassign { "input" { "couriers" \[ { "id" "courier id 1", "firstname" "jane", "lastname" "doe", "phone" "+16175551234", "providersource" "in house" }, { "id" "courier id 2", "firstname" "john", "lastname" "smith", "phone" "+16175555678", "providersource" "third party", "providername" "doordash" } ], "deliveryid" "ezcater delivery id" } } courierassign (transition mutation) the existing courierassign mutation is being phased out but has been updated to help you transition we've added a new optional boolean argument, allowmultiplecouriers this is an opt in flag for new behavior legacy behavior (omitted or false ) the mutation replaces all existing couriers with the single courier provided new behavior ( true ) the mutation adds the provided courier to the delivery's existing list of assignments without removing others once your application is ready to support multiple couriers, you should always pass true for allowmultiplecouriers handling new error responses migrating to the courierid argument introduces stricter validation and new potential errors these errors will only happen when using the new courierid argument error cases courier does not exist if the courier for the provided courierid does not exist, the mutation will fail { "errors" \[ { "message" "courier not found", "path" \[ "couriereventcreate" ], "extensions" { "type" "request", "statuscode" 404, "servicename" "delivery public", "code" "downstream service error", "exception" { "message" "courier not found", "locations" \[ { "line" 1, "column" 72 } ], "path" \[ "couriereventcreate" ] } } } ], "data" { "couriereventcreate" null } } courier is not assigned if the courier exists but has not been assigned to the specified deliveryid , the mutation will fail { "errors" \[ { "message" "courier assignment not found", "path" \[ "couriereventcreate" ], "extensions" { "type" "request", "statuscode" 404, "servicename" "delivery public", "code" "downstream service error", "exception" { "message" "courier assignment not found", "locations" \[ { "line" 1, "column" 72 } ], "path" \[ "couriereventcreate" ] } } } ], "data" { "couriereventcreate" null } }