Create Order and Create Return: Receiving-System Integration

Before you begin: complete General webhook requirements for connection security, shared fields, responses and duplicate prevention.

1. Read the order and return data

Both actions use schema version 1. action.type identifies the submission. The shared technical guide defines the common fields; the table below explains the order and return details.

Missing customer details: customer and channel values can be null. Anonymous Web Messaging may provide no customer identity.

Order example

{
  "schemaVersion": 1,
  "eventId": "9c4f2a7e-5b3d-4e8f-9a1b-2c3d4e5f6a7b",
  "action": {
    "type": "CREATE_ORDER",
    "actionId": "act_8f3a1c2e",
    "label": "Order - Dairy"
  },
  "organizationId": "your-genesys-org-guid",
  "conversationId": "c0ffee00-1111-2222-3333-444455556666",
  "metadata": {
    "agent": {
      "id": "agent-user-guid",
      "name": "Dana Levi",
      "email": "dana.levi@example.com"
    },
    "agentModifiedFields": [
      "items[0].quantity"
    ],
    "submittedAt": "2026-08-29T11:20:33.000Z",
    "source": "mediabriz-agent"
  },
  "customer": {
    "externalContactId": "b1e2c3d4-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
    "name": "David Cohen",
    "channelType": "whatsapp",
    "channelAddress": "15551234567",
    "customerReference": "ERP-CUST-1188"
  },
  "items": [
    {
      "sku": "DAIRY-0042",
      "productName": "Cottage Cheese 5%",
      "quantity": 3,
      "unit": "CASE",
      "originalDescription": "three cases of the blue cottage cheese"
    }
  ],
  "queue": {
    "id": "q-guid",
    "name": "Orders"
  },
  "requestedDeliveryDate": "2026-09-01",
  "customFields": { "requested_outcome": "credit", "sales_rep": "R-42" }
}

In this example, requested_outcome is a Dropdown field. Its value, credit, is the selected option key.

2. Handle return-specific information

Returns use the same shared fields, security and response rules as orders, with these additional fields:

Return example

{
  "schemaVersion": 1,
  "eventId": "2b7e1c90-4d5a-4f3b-8e6c-1a2b3c4d5e6f",
  "action": {
    "type": "CREATE_RETURN",
    "actionId": "act_5d2c9b1f",
    "label": "Return - Dairy"
  },
  "organizationId": "your-genesys-org-guid",
  "conversationId": "c0ffee00-1111-2222-3333-444455556666",
  "metadata": {
    "agent": { "id": "agent-user-guid", "name": "Dana Levi", "email": "dana.levi@example.com" },
    "agentModifiedFields": [],
    "submittedAt": "2026-09-13T11:20:33.000Z",
    "source": "mediabriz-agent"
  },
  "customer": {
    "externalContactId": null,
    "name": "David Cohen",
    "channelType": "whatsapp",
    "channelAddress": "15551234567",
    "customerReference": "ERP-CUST-1188"
  },
  "items": [
    {
      "sku": "DAIRY-0001",
      "productName": "Milk 3%",
      "quantity": 2,
      "unit": "CASE",
      "originalDescription": "2 cases of milk 3%",
      "reason": "damaged",
      "reasonText": "packages torn, milk leaked"
    }
  ],
  "queue": null,
  "requestedDeliveryDate": null,
  "reference": "45812",
  "pickupDate": null
}

Return outcomes: your system decides whether to provide credit, replacement or collection. There is no built-in resolution field. Requested replacement goods are not added as returned items and do not generate an order submission.

3. Apply your business rules

• Products: every SKU is checked against the action’s catalog. Each configured action needs its own catalog.
• Business processing: pricing, inventory, promotions and commercial calculations stay in your system.
• Extra information: notes, PO numbers and requested return outcomes use custom fields, not dedicated top-level fields. Read their configured keys, such as customFields.po_number.
• Retries: an unchanged retry keeps its eventId. Changes to products, customer or date fields, or custom-field values create a new ID.

4. Next: configure and test the action

Continue to Create Order and Create Return: Setup in Mediabriz to configure each action, upload its catalog, test the complete connection and make it available to agents.