Skip to main content
PUT
/
fulfillment
Upsert fulfillment options
curl --request PUT \
  --url https://api.example.com/fulfillment
{
  "data": {
    "created": 2,
    "updated": 1
  }
}
Creates or updates one or more fulfillment options for the authenticated merchant. Use this endpoint to sync fulfillment names, type codes, and status from your operational stack into Fire spark. Each array element is matched by id. When no fulfillment option exists with that id for the merchant, Fire spark creates it. When one already exists, Fire spark updates the writable fields below. Omitted fields keep their current values on update.
Requires an access token with the fulfillment:write scope. See Authorize to obtain a token.
Fulfillment id values are immutable. You cannot change an existing option’s id through this endpoint — send the same id on every sync.

​
Request

Send a JSON array. Each element represents one fulfillment option. Include id on every element — it is the stable external identifier and the upsert key. It cannot be changed after the option is created. 
curl -X PUT "https://firespark.vercel.app/api/integrations/v1/fulfillment" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "id": "delivery",
      "name": "Delivery",
      "type": "DELIVERY",
      "status": "ACTIVE"
    },
    {
      "id": "pickup",
      "name": "Pickup",
      "type": "PICKUP",
      "status": "ACTIVE"
    },
    {
      "id": "drive-thru",
      "name": "Drive-thru",
      "type": "DRIVE_THRU",
      "status": "ACTIVE"
    }
  ]'

​
Request fields

FieldTypeDescription
idstringRequired. External fulfillment identifier. Alphanumeric characters, _, and - only. 1–64 characters. Unique per merchant. Used as the upsert key. Cannot be changed after the option is created.
namestringDisplay name. 1–100 characters.
typestringRequired on create. Fulfillment type code. 1–100 characters. Unique per merchant among active records. Common values: DELIVERY, PICKUP, DINE_IN. Custom codes such as DRIVE_THRU are supported.
statusstringACTIVE or INACTIVE.
Each merchant can have at most one active fulfillment option per type code. Attempting to create or update a second active record with the same type returns a validation error.

​
Response

{
  "data": {
    "created": 2,
    "updated": 1
  }
}

​
Error responses

StatusDescription
400Request body failed validation. Check field constraints above.
401Missing or invalid access token.
403Token does not include the fulfillment:write scope.
422Business rule violation — for example attempting to change a fulfillment id, or duplicate id, name, or type for the merchant among active records.
Validation error
{
  "error": "validation_error",
  "message": "type: Required"
}