AlmondTill/G3N API

On this page

applyOrderLoyalty

mutation · in the family Selling

What it does

Redeem a customer’s loyalty points against an open order.

Attach a LoyaltyMember to an OPEN SALE. redeemPoints ABSENT = attach-for-EARN-only; PRESENT = the redemption request the position-4 evaluation converts to source=loyalty PRE-TAX LINE entries. Gates in order: member NOT_FOUND/CONSTRUCT → program org-enablement + order⟺program currency → the verdict map (CONFLICT/REF_STATE on a dead program/member/window · CONFLICT/INSUFFICIENT_POINTS naming live figures · VALIDATION/INVALID on zero-value / exceeds-available naming figures — never silently take less). The cart money re-stamps in the SAME revision; PLACE re-validates FRESH (commit truth). Requires the unrestricted capability + the record's CURRENT revision.

What happens

Re-prices with the points value and earmarks the points.

Careful

Points are customer money — the redemption finalizes when the order places.

Who may call it

Capability area: Selling — Ringing sales, serving customers and issuing invoices.

Arguments

NameTypeRequiredNotes
orderIdID ID!yesNo further notes.
revisionID ID!yesThe revision id you read on the record; the change is refused if an edit landed in the meantime.
memberIdID ID!yesNo further notes.
redeemPointsIntnoNo further notes.

Returns

Order Order! — A selling Order — the cart IS the open state (no Cart construct); orderType selects the FSM profile; lines embed with captured prices in integer minor units; the tax slots are pipeline-written at place over the master data; ecom place reserves stock, POS place does not — a layaway place reserves BOTH channels for the term; a special_order place NEVER reserves (goods are not on-hand — arrival reserves the claim).

Example request

mutation ExampleApplyOrderLoyalty($orderId: ID!, $revision: ID!, $memberId: ID!, $redeemPoints: Int) {
  applyOrderLoyalty(orderId: $orderId, revision: $revision, memberId: $memberId, redeemPoints: $redeemPoints) {
    id
    sysId
    type
    caption
    status
    parentId
    rootId
    createdAt
    updatedAt
    revisionNum
    revision
    organizationId
    channel
    orderType
    validUntil
    termEndsAt
    convertedOrderId
    sourceDocumentId
    reorderOfOrderId
    logicalFacilityId
    currency
    exemptionCertificateId
    paymentState
    fulfillmentState
    recognitionState
    taxJurisdictionId
    subtotalMinor
    discountTotalMinor
    taxTotalMinor
    totalMinor
    fulfillmentFeeMinor
    fulfillmentFeeTaxMinor
    tenderedNetMinor
    tipTotalMinor
    paymentIds
    refundIds
    disputeIds
    invoiceIds
    couponIds
    sourcingSagaId
    commissionAgentUserIds
    affiliateId
  }
}

Variables:

{
  "orderId": "01900000-0000-7000-8000-f6d8263a0000",
  "revision": "01900000-0000-7000-8000-b7960e180000",
  "memberId": "01900000-0000-7000-8000-80d971ae0000",
  "redeemPoints": 1
}

Send it with the envelope naming the version: "extensions": {"at": {"version": {"name":"genesis","number":0}}}.

Example response

{
  "data": {
    "applyOrderLoyalty": {
      "id": "01900000-0000-7000-8000-37386ae00000",
      "sysId": "SO-EXMP-0000-000F",
      "type": "Order",
      "caption": "Blue jeans",
      "status": "open",
      "parentId": "01900000-0000-7000-8000-065235280000",
      "rootId": "01900000-0000-7000-8000-a093dd800000",
      "createdAt": "2027-01-31T00:00:00.000Z",
      "updatedAt": "2027-01-31T00:00:00.000Z",
      "revisionNum": 1,
      "revision": "01900000-0000-7000-8000-b7960e180000",
      "organizationId": "01900000-0000-7000-8000-44b781470000",
      "channel": "pos",
      "orderType": "sale",
      "validUntil": "<valid until>",
      "termEndsAt": "2027-01-31T00:00:00.000Z",
      "convertedOrderId": "01900000-0000-7000-8000-b1563ac60000",
      "sourceDocumentId": "01900000-0000-7000-8000-8fd6a7c40000",
      "reorderOfOrderId": "01900000-0000-7000-8000-5533d5a60000",
      "logicalFacilityId": "01900000-0000-7000-8000-8026f71c0000",
      "currency": "USD",
      "exemptionCertificateId": "01900000-0000-7000-8000-6c082e160000",
      "paymentState": "<payment state>",
      "fulfillmentState": "<fulfillment state>",
      "recognitionState": "<recognition state>",
      "taxJurisdictionId": "01900000-0000-7000-8000-3a64e3820000",
      "subtotalMinor": 1,
      "discountTotalMinor": 1,
      "taxTotalMinor": 1,
      "totalMinor": 1,
      "fulfillmentFeeMinor": 1,
      "fulfillmentFeeTaxMinor": 1,
      "tenderedNetMinor": 1,
      "tipTotalMinor": 1,
      "paymentIds": [
        "01900000-0000-7000-8000-f1636a750000"
      ],
      "refundIds": [
        "01900000-0000-7000-8000-a5d2e2d30000"
      ],
      "disputeIds": [
        "01900000-0000-7000-8000-d72df27f0000"
      ],
      "invoiceIds": [
        "01900000-0000-7000-8000-0a4b14ba0000"
      ],
      "couponIds": [
        "01900000-0000-7000-8000-6a9b05ef0000"
      ],
      "sourcingSagaId": "01900000-0000-7000-8000-2dfe37aa0000",
      "commissionAgentUserIds": [
        "01900000-0000-7000-8000-7aaf99300000"
      ],
      "affiliateId": "01900000-0000-7000-8000-ab1bc9b90000"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}

Errors this call can answer

Used in