Integration Walkthroughs

These walkthroughs stitch multiple services together into copy/paste flows. They use the public contract only and show where auth and tenancy fields belong.

Conventions

Replace placeholders like ORGCODE, SESSION_GUID, and ORG_GUID with real values.
GET: parameters go in the query string. POST: parameters go in JSON body. See /common/http-methods.html.
Use custom domains: https://api.g3nretailstack.com/<service>/....

Downloadable collections for the minimum viable flow:

Postman: /common/collections/g3nretailstack-minimum-viable-flow.postman_collection.json
Insomnia: /common/collections/g3nretailstack-minimum-viable-flow.insomnia_collection.json SDK snippet set (Node.js + Python):
/common/sdk-snippets.html Client shim + ops guidance:
/common/client-shim.html
/common/rate-limit-timeouts.html SDK integration checklist:
/common/sdk-integration-checklist.html

Walkthrough 1: User onboarding -> session -> org -> facilities/zones -> invite member

Prerequisites (operator-only steps)

A verified user exists (email verified + passcode set). The user record provides user_guid. See User Provisioning for the full operator setup flow.
You have a valid invitation_code for org creation (invites are operator-only direct Lambdas). See User Provisioning step 5.

1) Create a session (USM)

curl -sS -X POST https://api.g3nretailstack.com/usm/session/create \
  -H "content-type: application/json" \
  -d '{
    "email": "owner@example.com",
    "passcode": "Abcd!234",
    "caption": "owner-session",
    "session_label": "owner-web",
    "reason": "login"
  }'

Save: SESSION_GUID, USER_GUID (from the UAS user record).

Auth placement note: USM session routes use JSON body auth (session_guid in body). Downstream services use header auth (x-session-guid).

Common failures

401 invalid-passcode: incorrect credentials or unknown email.
403 user-not-verified / email-not-verified: user must be verified before creating a session.

2) Create org (OFM)

curl -sS -X POST https://api.g3nretailstack.com/ofm/org/create \
  -H "content-type: application/json" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{
    "orgcode": "ACME",
    "invitation_code": "INV123",
    "user_guid": "USER_GUID",
    "caption": "Acme HQ"
  }'

Save: ORG_GUID, CC_GUID.

Common failures

409 invitation-expired / invitation-consumed: request a fresh invite.
409 code-generation-exhausted / uniqueness-conflict: pick a different orgcode.

3) Verify org before writes (operator-only)

If the org is not verified, writes will fail with 403 org-write-blocked. Verify the org via the operator-only flow before continuing.

4) Create facilities (OFM)

Physical facility:

curl -sS -X POST https://api.g3nretailstack.com/ofm/facility/physical/create \
  -H "content-type: application/json" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{
    "org_guid": "ORG_GUID",
    "code": "HQ",
    "caption": "Headquarters",
    "address": { "street": "1 Main St", "city": "Austin", "region": "TX", "country": "US" }
  }'

Legal facility:

curl -sS -X POST https://api.g3nretailstack.com/ofm/facility/legal/create \
  -H "content-type: application/json" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{
    "org_guid": "ORG_GUID",
    "code": "ACME-INC",
    "caption": "Acme Incorporated"
  }'

Logical facility:

curl -sS -X POST https://api.g3nretailstack.com/ofm/facility/logical/create \
  -H "content-type: application/json" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{
    "org_guid": "ORG_GUID",
    "physical_guid": "PHYSICAL_GUID",
    "legal_guid": "LEGAL_GUID",
    "code": "DC-01",
    "caption": "Distribution Center"
  }'

Save: LOGICAL_GUID.

5) Create a zone (OFM)

Fetch the ROOT zone for the logical facility, then create a child zone.

curl -sS -X POST https://api.g3nretailstack.com/ofm/zone/list \
  -H "content-type: application/json" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{ "org_guid": "ORG_GUID", "logical_guid": "LOGICAL_GUID", "limit": 8 }'

Use the zone_guid where code="ROOT" as ROOT_ZONE_GUID.

curl -sS -X POST https://api.g3nretailstack.com/ofm/zone/create \
  -H "content-type: application/json" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{
    "org_guid": "ORG_GUID",
    "logical_guid": "LOGICAL_GUID",
    "parent_zone_guid": "ROOT_ZONE_GUID",
    "code": "A1",
    "caption": "Aisle A1"
  }'

6) Invite a member (OFM)

Owner creates invite:

curl -sS -X POST https://api.g3nretailstack.com/ofm/member/invite/create \
  -H "content-type: application/json" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{
    "org_guid": "ORG_GUID",
    "invitee_user_guid": "INVITEE_USER_GUID",
    "caption": "Inventory staff",
    "role_profile_id": "pvv"
  }'

Invitee accepts using their own session:

curl -sS -X POST https://api.g3nretailstack.com/ofm/member/invite/accept \
  -H "content-type: application/json" \
  -H "x-session-guid: $INVITEE_SESSION_GUID" \
  -d '{ "code": "INVITE_CODE" }'

Common failures

404 not-found on accept: invitee session must match invitee_user_guid (bound invites).
403 not-owner: invite creation requires owner privileges.

Walkthrough 2: PVM product model -> PMC publish profile -> publish run

Prerequisites

Org is verified (writes otherwise fail with 403 org-write-blocked).
A sales channel exists in OFM with a known channel_code (used by PMC publish profiles).
A taxonomy category exists (category_id) for style creation.
Caller has pma (PVM) and pmc_publish (PMC) permissions.

1) Create suppliers (PVM)

Vendor + manufacturer:

curl -sS -X POST https://api.g3nretailstack.com/pvm/vendor \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{ "code": "VEND1", "caption": "Vendor One" }'

curl -sS -X POST https://api.g3nretailstack.com/pvm/manufacturer \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{ "code": "MFG1", "caption": "Maker One" }'

Set both to verified (required for style creation):

curl -sS -X POST https://api.g3nretailstack.com/pvm/vendor/status \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{ "vendor_id": "VENDOR_ID", "status": "verified" }'

curl -sS -X POST https://api.g3nretailstack.com/pvm/manufacturer/status \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{ "manufacturer_id": "MANUFACTURER_ID", "status": "verified" }'

2) Create option group, option, and OGM (PVM)

curl -sS -X POST https://api.g3nretailstack.com/pvm/option_group \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{ "code": "COLOR", "caption": "Color" }'

curl -sS -X POST https://api.g3nretailstack.com/pvm/option \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{ "group_code": "COLOR", "code": "RED", "caption": "Red" }'

curl -sS -X POST https://api.g3nretailstack.com/pvm/ogm \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{ "code": "APPAREL", "groups": [{ "group_code": "COLOR", "priority": 1 }] }'

Save: OGM_ID and OGM_REV.

3) Create a style and a variant (PVM)

curl -sS -X POST https://api.g3nretailstack.com/pvm/style \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{
    "code": "TEE",
    "category_id": "CATEGORY_ID",
    "vendor_ids": ["VENDOR_ID"],
    "manufacturer_ids": ["MANUFACTURER_ID"],
    "primary_vendor_id": "VENDOR_ID",
    "primary_manufacturer_id": "MANUFACTURER_ID",
    "ogm_id": "OGM_ID",
    "ogm_rev": 1
  }'

curl -sS -X POST https://api.g3nretailstack.com/pvm/variant \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{
    "style_id": "STYLE_ID",
    "selections": [{ "group_code": "COLOR", "option_code": "RED" }]
  }'

Save: STYLE_ID, VARIANT_ID, and the returned revision (for updates). If the create response does not include revision, call GET /pvm/variant/get with variant_id + style_id to fetch it.

4) Add SKU, identifiers, and barcodes (PVM)

curl -sS -X POST https://api.g3nretailstack.com/pvm/variant/update \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{
    "style_id": "STYLE_ID",
    "variant_id": "VARIANT_ID",
    "expected_revision": "VARIANT_REV",
    "sku": "SKU-123"
  }'

curl -sS -X POST https://api.g3nretailstack.com/pvm/identifier/add \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{
    "style_id": "STYLE_ID",
    "variant_id": "VARIANT_ID",
    "type": "sku",
    "value": "SKU-123"
  }'

curl -sS -X POST https://api.g3nretailstack.com/pvm/barcode/add \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{
    "style_id": "STYLE_ID",
    "variant_id": "VARIANT_ID",
    "value": "012345678905",
    "scheme": "gtin",
    "packaging_level": "each"
  }'

5) Set publish profile (PMC)

curl -sS -X POST https://api.g3nretailstack.com/pmc/publish-profile/set \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{
    "channel_code": "WEB",
    "required_sku": true,
    "required_identifier_types": ["sku"]
  }'

6) Start a publish run (PMC)

curl -sS -X POST https://api.g3nretailstack.com/pmc/publish/run/start \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{
    "reason": "initial publish",
    "style_id": "STYLE_ID",
    "channel_code": "WEB"
  }'

Save: RUN_ID and RUN_REVISION (from the response).

7) Step the run (PMC)

curl -sS -X POST https://api.g3nretailstack.com/pmc/publish/run/step \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{ "run_id": "RUN_ID", "expected_revision": "RUN_REVISION", "limit": 8 }'

Conflict handling

428 expected-revision-required: fetch the run via GET /publish/run/get and retry with the latest revision.
409 conflict: same as above; re-read and retry.

8) Verify the published product

curl -sS -G "https://api.g3nretailstack.com/pmc/product/list" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  --data-urlencode "variant_id=VARIANT_ID" \
  --data-urlencode "online_state=online"

Walkthrough 3: Presigned config upload (OFM) -> downstream reference

This flow shows a presigned upload for sales-channel config, then uses the channel in PMC.

1) Create a sales channel (OFM)

curl -sS -X POST https://api.g3nretailstack.com/ofm/sales-channel/create \
  -H "content-type: application/json" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{
    "org_guid": "ORG_GUID",
    "logical_guid": "LOGICAL_GUID",
    "channel_code": "WEB",
    "market_code": "US",
    "locale_codes": ["en-US"],
    "default_locale_code": "en-US",
    "caption": "US Web"
  }'

Save: CHANNEL_GUID and the latest revision (from the create or get response).

2) Presign the config upload (OFM)

curl -sS -X POST https://api.g3nretailstack.com/ofm/sales-channel/config/presign \
  -H "content-type: application/json" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{
    "org_guid": "ORG_GUID",
    "channel_guid": "CHANNEL_GUID",
    "expected_revision": "CHANNEL_REVISION"
  }'

Save: UPLOAD_URL, UPLOAD_HEADERS[], CONFIG_S3_KEY, and the latest revision (from the presign response or a fresh get).

3) Upload the config to S3 (presigned)

curl -sS -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/json" \
  -H "${UPLOAD_HEADERS_1}" \
  -H "${UPLOAD_HEADERS_2}" \
  --data-binary @channel-config.json

4) Complete the upload (OFM)

curl -sS -X POST https://api.g3nretailstack.com/ofm/sales-channel/config/complete \
  -H "content-type: application/json" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{
    "org_guid": "ORG_GUID",
    "channel_guid": "CHANNEL_GUID",
    "expected_revision": "LATEST_CHANNEL_REVISION",
    "config_s3_key": "CONFIG_S3_KEY",
    "reason": "initial config"
  }'

5) Confirm the config pointer (OFM)

curl -sS -X POST https://api.g3nretailstack.com/ofm/sales-channel/get \
  -H "content-type: application/json" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{ "org_guid": "ORG_GUID", "channel_guid": "CHANNEL_GUID" }'

The response includes config_s3_bucket, config_s3_key, config_s3_version_id, and config_etag (content stays opaque).

6) Reference the channel downstream (PMC)

curl -sS -X POST https://api.g3nretailstack.com/pmc/publish-profile/set \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{
    "channel_code": "WEB",
    "required_sku": true,
    "required_identifier_types": ["sku"]
  }'

PMC uses channel_code/channel_guid from OFM when selecting publish targets. The channel config pointer remains in OFM and is not emitted inline in PMC responses.

Walkthrough 4: Stock update + read (ICS)

1) Record an adjustment (ICS)

curl -sS -X POST https://api.g3nretailstack.com/ics/adjustment/create \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{
    "logical_guid": "LOGICAL_GUID",
    "variant_id": "VARIANT_ID",
    "qty_delta": 5,
    "reason": "initial stock",
    "source_refs": [{ "kind": "bootstrap", "id": "seed-1" }]
  }'

2) Read stock (ICS)

curl -sS -X POST https://api.g3nretailstack.com/ics/stock/get \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{ "logical_guid": "LOGICAL_GUID", "variant_id": "VARIANT_ID" }'

Walkthrough 5: Order lifecycle (SCM)

1) Place an order

curl -sS -X POST https://api.g3nretailstack.com/scm/order/create \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{
    "logical_guid": "LOGICAL_GUID",
    "channel_code": "WEB",
    "items": [{ "variant_id": "VARIANT_ID", "qty": 1 }],
    "reason": "checkout",
    "source_refs": [{ "kind": "cart", "id": "cart-123" }]
  }'

Then place/commit:

curl -sS -X POST https://api.g3nretailstack.com/scm/order/place \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{ "order_id": "ORDER_ID", "expected_revision": "ORDER_REV", "reason": "checkout" }'

Walkthrough 6: Procurement receipt (PCM)

1) Record a receipt

curl -sS -X POST https://api.g3nretailstack.com/pcm/receipt/record \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{
    "receipt": {
      "po_id": "PO_ID",
      "logical_guid": "LOGICAL_GUID",
      "lines": [{ "variant_id": "VARIANT_ID", "qty": 10 }]
    },
    "reason": "receiving",
    "source_refs": [{ "kind": "po", "id": "PO_ID" }]
  }'

Walkthrough 7: Price resolve (PPM)

curl -sS -X POST https://api.g3nretailstack.com/ppm/price/resolve \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{
    "logical_guid": "LOGICAL_GUID",
    "channel_code": "WEB",
    "items": [{ "variant_id": "VARIANT_ID", "qty": 1 }],
    "reason": "cart"
  }'

Walkthrough 8: Loyalty earn + redeem (CRM)

Earn:

curl -sS -X POST https://api.g3nretailstack.com/crm/loyalty/earn \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{
    "customer_id": "CUSTOMER_ID",
    "points": 100,
    "reason": "purchase",
    "source_refs": [{ "kind": "order", "id": "ORDER_ID" }]
  }'

Redeem:

curl -sS -X POST https://api.g3nretailstack.com/crm/loyalty/redeem \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{
    "customer_id": "CUSTOMER_ID",
    "points": 50,
    "reason": "reward",
    "source_refs": [{ "kind": "order", "id": "ORDER_ID" }]
  }'

Walkthrough 9: Export batch (Accounting)

curl -sS -X POST https://api.g3nretailstack.com/accounting/export/create \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{
    "export_kind": "financial_events",
    "reason": "erp-sync",
    "source_refs": [{ "kind": "job", "id": "sync-001" }]
  }'

Then fetch status:

curl -sS -X POST https://api.g3nretailstack.com/accounting/export/get \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{ "export_id": "EXPORT_ID" }'

Walkthrough 10: Event subscription (RBS)

1) Register a subscription

curl -sS -X POST https://api.g3nretailstack.com/rbs/subscription/register \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{
    "queue_url": "https://sqs.us-east-1.amazonaws.com/123456789012/g3n-events",
    "queue_region": "us-east-1",
    "filters": [{ "service": "scm", "action_prefix": "order-" }],
    "reason": "integration"
  }'

2) Verify the subscription

curl -sS -X POST https://api.g3nretailstack.com/rbs/subscription/verify \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{ "subscription_id": "SUB_ID", "verification_token": "TOKEN", "reason": "verify" }'

Integration Walkthroughs ​

Walkthrough 1: User onboarding -> session -> org -> facilities/zones -> invite member ​

Prerequisites (operator-only steps) ​

1) Create a session (USM) ​

2) Create org (OFM) ​

3) Verify org before writes (operator-only) ​

4) Create facilities (OFM) ​

5) Create a zone (OFM) ​

6) Invite a member (OFM) ​

Walkthrough 2: PVM product model -> PMC publish profile -> publish run ​

Prerequisites ​

1) Create suppliers (PVM) ​

2) Create option group, option, and OGM (PVM) ​

3) Create a style and a variant (PVM) ​

4) Add SKU, identifiers, and barcodes (PVM) ​

5) Set publish profile (PMC) ​

6) Start a publish run (PMC) ​

7) Step the run (PMC) ​

8) Verify the published product ​

Walkthrough 3: Presigned config upload (OFM) -> downstream reference ​

1) Create a sales channel (OFM) ​

2) Presign the config upload (OFM) ​

3) Upload the config to S3 (presigned) ​

4) Complete the upload (OFM) ​

5) Confirm the config pointer (OFM) ​

6) Reference the channel downstream (PMC) ​

Walkthrough 4: Stock update + read (ICS) ​

1) Record an adjustment (ICS) ​

2) Read stock (ICS) ​

Walkthrough 5: Order lifecycle (SCM) ​

1) Place an order ​

Walkthrough 6: Procurement receipt (PCM) ​

1) Record a receipt ​

Walkthrough 7: Price resolve (PPM) ​

Walkthrough 8: Loyalty earn + redeem (CRM) ​

Walkthrough 9: Export batch (Accounting) ​

Walkthrough 10: Event subscription (RBS) ​

1) Register a subscription ​

2) Verify the subscription ​

Integration Walkthroughs

Walkthrough 1: User onboarding -> session -> org -> facilities/zones -> invite member

Prerequisites (operator-only steps)

1) Create a session (USM)

2) Create org (OFM)

3) Verify org before writes (operator-only)

4) Create facilities (OFM)

5) Create a zone (OFM)

6) Invite a member (OFM)

Walkthrough 2: PVM product model -> PMC publish profile -> publish run

Prerequisites

1) Create suppliers (PVM)

2) Create option group, option, and OGM (PVM)

3) Create a style and a variant (PVM)

4) Add SKU, identifiers, and barcodes (PVM)

5) Set publish profile (PMC)

6) Start a publish run (PMC)

7) Step the run (PMC)

8) Verify the published product

Walkthrough 3: Presigned config upload (OFM) -> downstream reference

1) Create a sales channel (OFM)

2) Presign the config upload (OFM)

3) Upload the config to S3 (presigned)

4) Complete the upload (OFM)

5) Confirm the config pointer (OFM)

6) Reference the channel downstream (PMC)

Walkthrough 4: Stock update + read (ICS)

1) Record an adjustment (ICS)

2) Read stock (ICS)

Walkthrough 5: Order lifecycle (SCM)

1) Place an order

Walkthrough 6: Procurement receipt (PCM)

1) Record a receipt

Walkthrough 7: Price resolve (PPM)

Walkthrough 8: Loyalty earn + redeem (CRM)

Walkthrough 9: Export batch (Accounting)

Walkthrough 10: Event subscription (RBS)

1) Register a subscription

2) Verify the subscription