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",
    "invoice_number": "INV-2026-001",
    "invoice_date": "2026-01-29",
    "buyer": {
      "type": "households:upsert", // See payload specs for the appropriate buyer type: people:upsert, households:upsert
      "name": "Family Doe",
      "import_id": "F0001",
      "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

Field Constraints

Field	Type	Required	Default	Max Length	Constraints
id	Integer	No	null	-	Arkipel ID. When set, updates existing record. When omitted, creates new record.
template_id	Integer	Yes*	null	-	Distribution template ID. Required for creation. See distribution_templates:query
procured_on	Date	Yes*	null	-	Distribution date. Format: YYYY-MM-DD. Required for creation.
quantity	Integer	Yes*	null	-	Distribution quantity. Required for creation.
buyer	Object	Yes*	null	-	Buyer information. Required for creation. See Buyer fields below.
weight_value	Decimal	No	null	-	Weight as decimal number
weight_unit	Enum	No	null	-	Weight unit. Values: kg, lb
location_at	DateTime	No	Current time	-	Location timestamp
invoice_number	String	No	null	-	Invoice number for this distribution
invoice_date	Date	No	null	-	Invoice date for this distribution. Format: YYYY-MM-DD

* Required only when creating new distribution (when id is not set).

Buyer Fields

The buyer object can be a person or household:

Field	Type	Required	Description
type	String	Yes	Buyer type: "people:upsert" or "households:upsert"
id	Integer	No	Arkipel ID for updating existing buyer
import_id	String	Yes	Your external system ID for this buyer
name	String	Conditional	For households: required. See households:upsert
first_name	String	Conditional	For people: required if last_name blank
last_name	String	Conditional	For people: required if first_name blank
forms	Array	No	Form submissions. See forms:query to list available forms, form:query for individual form details
people	Array	No	Nested people for household buyers. See people:upsert

Complete buyer fields: Refer to people:upsert or households:upsert for all available fields.

Real life example

Distribution Creation

{
  "type": "distributions:upsert",
  "template_id": 120884,
  "quantity": 1,
  "weight_value": 12.5,
  "weight_unit": "kg",
  "invoice_number": "INV-2026-001",
  "invoice_date": "2026-01-29",
  "buyer": {
    "type": "households:upsert",
    "name": "Family Doe",
    "import_id": "F0001",
    "locale": "fr",
    "data_consent": "accepted",
    "accepts_marketing": true,
    "forms": [
      {
        "id": 443,
        "data": {
          "vehicules": "aucun",
          "vehicules_detail": "FOOOOOOO"
        }
      }
    ],
    "people": [
      {
        "type": "people:upsert",
        "import_id": "F0001-01",
        "first_name": "John",
        "last_name": "Doe",
        "dob": "1970-12-30",
        "collaboration": {
          "title": "Father",
          "main": false
        }
      },
      {
        "type": "people:upsert",
        "import_id": "F0001-02",
        "first_name": "Jane",
        "last_name": "Doe",
        "dob": "1974-07-12",
        "forms": [
          {
            "id": 435,
            "data": {
              "groupeDage": "adulte",
              "femme": true
            }
          }
        ],
        "collaboration": {
          "title": "Mother",
          "main": true
        }
      }
    ],
    "contact_informations": [
      {
        "label": "Office",
        "type": "PhoneNumber",
        "info": "514 123 1234",
        "main": true
      }
    ],
    "addresses": [
      {
        "name": "Home",
        "street1": "259 Wellington St. W",
        "street2": "Appt 1",
        "city": "Toronto",
        "zip": "M5V 3P9",
        "region_code": "ON",
        "country_code": "CA",
        "main": true
      }
    ]
  }
}

🚧 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"
  }
}