distributions:upsert

Description: Create a distribution or update a single distribution by ID.

You can create a distribution in two ways:

• From template: Use a predefined template_id (retrieved via distribution_templates:query) to leverage default values and structure.
• Manual: Manually specify all required attributes (not yet documented).

---

From template

Using a template simplifies creation by applying standard defaults and composition rules. For example, if a template defines 2 variant lines with a quantity of 1 each, and you submit a quantity of 10, each line’s quantity will scale to 10.

Request Schema

{
  "payload": {
    "id": 1, // When set, update existing record, else create new record
    "type": "distributions:upsert",
    "template_id": 1, // Required for creation
    "procured_on": "2026-01-29", // Required for creation
    "quantity": 1, // Required for creation
    "weight_value": 1.25,
    "weight_unit": "kg",
    "buyer": {
      ... , // See payload specs for the appropriate buyer type: people:upsert, households:upsert
      "forms": [
      	{ "id": 1, "data": { "key1": "value1", ... } } // See form:fill, `subject` key not required
      ],
      "people": [
        {
          "type": "people:upsert", // See people:upsert
          "first_name": "John",
          "last_name": "Doe",
          "dob": "1970-12-30",
          "forms": [
		    { "id": 2, "data": { "key1": "value1", ... } } // See form:fill, `subject` key not required
    	  ],
          "collaboration": {
            "title": "Father",
            "main": false
          }
        }, // New record
        {
          "id": 1, // When set, update existing record, else create new record
          "type": "people:upsert", // See people:upsert
          "first_name": "Jane",
          "last_name": "Doe",
          "dob": "1974-07-12",
          "collaboration": {
            "title": "Mother",
            "main": true
          }
        } // Existing record        
      ]
    }
  },
  "signature": "payload_ed25519_hex_signature",
  "source_public_key": "your_client_public_key"
}

Request Attributes

• See global request attributes
• payload.id - Integer - The distribution’s ID in the remote Arkipel community - when not set, a record will be created
• payload.template_id - Integer - The distribution’s template - Compulsory for creation
• payload.procured_on - Date ("%Y-%m-%d") - The distribution’s date - Compulsory for creation
• payload.quantity - Integer - The distribution’s quantity - Compulsory for creation
• payload.buyer - Object - The distribution’s buyer, please check people:upsert or households:upsert - Compulsory for creation

Additional values

• payload.weight_value - Decimal - The distribution’s weight value
• payload.weight_unit - Enum (kg, lb) - The distribution’s weight unit
• payload.buyer.forms - Array - The distribution’s buyer additional custom forms values, please check forms:query for the form’s inputs you need to fill out

Manual

TODO

Response Schema

{
  "source_public_key": "community_public_key",
  "source_site": {
    "protocol": "http",
    "fqdn": "arkipel.localhost:3000"
  },
  "created_at": "2025-11-13T20:52:49Z",
  "signature": "8b6392d5550605bd6ccddf9c21ebec470de4b44e4b4deb746076e37ab61c5346e07e7c7c7cebb5bbee41cdd92a476bcd3f02373d146ec165b31c31fc31c9ce0d",
  "payload": {
    "message_id": "6916452112f746b2b4cf48c1",
    "type": "distributions:upsert"
  }
}