Content

Add an overview of the Admin - Content API here. This block is preserved across regenerations.

Endpoints

`GET /api/v1/business-rules`

List business rules

get

/business-rules

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Query parameters

limitinteger · min: 1 · max: 100Optional

Max items to return (1–100, default 20)

Default: 20

offsetintegerOptional

Number of items to skip (default 0)

Default: 0

directionstringOptional

Filter by direction (upgrade, downgrade, cancellation, add_on, remove_add_on, retention_discount)

isActivebooleanOptional

Filter by enforcement state

Responses

200

Paginated business rules

No content

get/business-rules

GET /api/v1/business-rules HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

200

Paginated business rules

No content

Notes, examples, or caveats for GET /business-rules go here.

`POST /api/v1/business-rules`

Create a business rule

post

/business-rules

isActive is REQUIRED — a business rule has no draft state, so an active rule is enforced from the moment it is written and there is no safe default to choose on the caller's behalf. isPlatformDefault cannot be set: it is cleared on every boot, so writing it would look applied and silently revert.

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Body

namestringRequired

descriptionstringOptional

directionstring · enumRequiredPossible values:

changeTimingstring · enumRequiredPossible values:

timingValueintegerOptional

timingUnitstring · enumOptionalPossible values:

prorationTypestring · enumOptionalPossible values:

subscriptionStatestring · enumOptionalPossible values:

appliesToSurfacestring · enumOptionalPossible values:

blocksChangebooleanOptional

isActivebooleanRequired

Required. True = enforced immediately.

Responses

201

Rule created; the response enforcement field states whether it is being enforced

No content

400

Validation error

application/json

post/business-rules

POST /api/v1/business-rules HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 231

{
  "name": "text",
  "description": "text",
  "direction": "upgrade",
  "changeTiming": "immediate",
  "timingValue": 1,
  "timingUnit": "days",
  "prorationType": "full",
  "subscriptionState": "any",
  "appliesToSurface": "any",
  "blocksChange": true,
  "isActive": true
}

No content

A business rule is policy, not content. It decides whether a plan change is permitted at all (blocksChange), when it takes effect, how it prorates, and which subscription state and actor surface it governs.

isActive is required. Unlike journeys, pages and product sets, a rule has no draft state — no version to publish, no status to stage. Set it true and the rule is enforced from the moment it is written; set it false and it is authored but dormant. Neither is a safe default to pick on your behalf, so the API makes you say which you mean. The response carries an enforcement line restating what just happened.

isPlatformDefault cannot be set. Platform-default rules were retired; clearPlatformDefaultFlags() demotes any such row on every boot. Writing the flag would look applied and then silently revert at the next restart.

custom_delay and grace_period require both timingValue and timingUnit — without them the rule has no defined timing when the policy engine evaluates it.

`DELETE /api/v1/business-rules/{id}`

Delete a business rule

delete

/business-rules/{id}

Deleting a rule REMOVES a policy. When the rule was an active hard block, that removes a guardrail — the audit entry records the rule's direction, enforcement state, blocking flag and attached journeys, since after deletion that is the only remaining evidence.

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Responses

204

Deleted

No content

404

Not found

application/json

delete/business-rules/{id}

DELETE /api/v1/business-rules/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Deleting a rule removes a policy. When the rule was an active hard block (blocksChange: true), that is the removal of a guardrail, not just a tidy-up.

Because the row is gone afterwards, the audit entry records what the rule was doing — its direction, whether it was active, whether it was blocking, the subscription state it governed, and the journeys it was attached to. Check GET /business-rules/{id}/journeys first to see the blast radius.

`GET /api/v1/business-rules/{id}`

Get a business rule

get

/business-rules/{id}

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Responses

200

Business rule

No content

404

Not found

application/json

get/business-rules/{id}

GET /api/v1/business-rules/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for GET /business-rules/{id} go here.

`PATCH /api/v1/business-rules/{id}`

Update a business rule

patch

/business-rules/{id}

The timing rule is checked against the MERGED result: patching changeTiming to custom_delay or grace_period without supplying a value and unit is refused, because the rule would otherwise have no defined timing when it is evaluated.

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Body

namestringOptional

changeTimingstringOptional

timingValueintegerOptional

timingUnitstringOptional

blocksChangebooleanOptional

isActivebooleanOptional

Responses

200

Rule updated

No content

400

Validation error

application/json

404

Not found

application/json

patch/business-rules/{id}

PATCH /api/v1/business-rules/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 109

{
  "name": "text",
  "changeTiming": "text",
  "timingValue": 1,
  "timingUnit": "text",
  "blocksChange": true,
  "isActive": true
}

No content

The timing rule is validated against the merged result, not just the fields you send. Patching changeTiming to custom_delay or grace_period without also supplying a value and unit is refused, because the stored rule would otherwise be left with undefined timing.

Flipping isActive changes enforcement immediately in both directions — there is no publish step.

`GET /api/v1/business-rules/{id}/journeys`

List the journeys a business rule is attached to

get

/business-rules/{id}/journeys

The blast radius of a rule — read this before changing or deleting one.

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Responses

200

Journeys using this rule

No content

404

Not found

application/json

get/business-rules/{id}/journeys

GET /api/v1/business-rules/{id}/journeys HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for GET /business-rules/{id}/journeys go here.

`GET /api/v1/context/host-routes`

List host routes — which hostname reaches which journey, step or page

get

/context/host-routes

Entry-point routing. Filterable by journeyId or pageId to answer "where do customers actually reach this?". The internal Cloudflare custom-hostname id is deliberately omitted.

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Query parameters

limitinteger · min: 1 · max: 100Optional

Max items to return (1–100, default 20)

Default: 20

offsetintegerOptional

Number of items to skip (default 0)

Default: 0

journeyIdstringOptional

Only routes targeting this journey

pageIdstringOptional

Only routes targeting this page

Responses

200

Paginated host routes

No content

get/context/host-routes

GET /api/v1/context/host-routes HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

200

Paginated host routes

No content

The entry points — which hostname reaches which journey, step or page.

Filter by journeyId or pageId to answer "where do customers actually reach this?" after publishing something.

failureReason is included, because a route that is not serving is exactly the kind of thing an agent should be able to report back. The internal Cloudflare custom-hostname id is omitted; it is infrastructure plumbing with no authoring use.

`GET /api/v1/context/integrations`

List integrations (identity and health only)

get

/context/integrations

Returns ONLY id, type, name, isActive and catalog-sync health. Credentials are never returned — not masked, not their key names — and config is not returned at all. This is an allowlist, so a column added to the integrations table in future stays invisible here until it is deliberately added.

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Query parameters

limitinteger · min: 1 · max: 100Optional

Max items to return (1–100, default 20)

Default: 20

offsetintegerOptional

Number of items to skip (default 0)

Default: 0

Responses

200

Paginated integrations

No content

get/context/integrations

GET /api/v1/context/integrations HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

200

Paginated integrations

No content

Returns only an integration's identity and health: id, type, name, isActive, lastCatalogSyncAt, lastCatalogSyncStatus.

Credentials are never returned — not masked, not their key names. Neither is config.

This is an allowlist, and the distinction matters. The admin UI masks credentials by taking the whole row and overwriting one field; that approach exposes anything added to the table later, silently, the day it lands. Here nothing is returned unless it is named, so a new column stays invisible until someone deliberately exposes it.

What you get is what an authoring agent actually needs: enough to know which system a commerce action calls and whether it is usable.

`GET /api/v1/context/integrations/{id}`

Get an integration (identity and health only)

get

/context/integrations/{id}

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Responses

200

Integration

No content

404

Not found

application/json

get/context/integrations/{id}

GET /api/v1/context/integrations/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for GET /context/integrations/{id} go here.

`GET /api/v1/context/personas`

List persona configurations

get

/context/personas

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Query parameters

limitinteger · min: 1 · max: 100Optional

Max items to return (1–100, default 20)

Default: 20

offsetintegerOptional

Number of items to skip (default 0)

Default: 0

Responses

200

Paginated persona configurations

No content

get/context/personas

GET /api/v1/context/personas HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

200

Paginated persona configurations

No content

Persona configurations describe the audiences a journey or page renders for, and their capabilities.

Read-only, like everything under /context. The context scope has exactly one verb and always will — an agent has to resolve what a journey references, and must never mutate it.

`GET /api/v1/context/personas/{id}`

Get a persona configuration

get

/context/personas/{id}

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Responses

200

Persona configuration

No content

404

Not found

application/json

get/context/personas/{id}

GET /api/v1/context/personas/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for GET /context/personas/{id} go here.

`GET /api/v1/custom-components`

List all custom components for the tenant

get

/custom-components

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Query parameters

limitinteger · min: 1 · max: 100Optional

Max items to return (1–100, default 20)

Default: 20

offsetintegerOptional

Number of items to skip (default 0)

Default: 0

contextstringOptional

Filter by editor context (payment, customer, portal, storefront, checkout, csr)

Responses

200

Paginated list of custom components

application/json

A custom UI component (code or template type) for the Puck editor

idstring · uuidOptional

namestringOptional

displayNamestring · nullableOptional

descriptionstring · nullableOptional

componentTypestring · enumOptionalPossible values:

categorystring · nullableOptional

editorContextsstring[]Optional

audienceRolesstring[]Optional

isActivebooleanOptional

createdAtstring · date-timeOptional

get/custom-components

GET /api/v1/custom-components HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

200

Paginated list of custom components

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "displayName": "text",
  "description": "text",
  "componentType": "code",
  "category": "text",
  "editorContexts": [
    "text"
  ],
  "audienceRoles": [
    "text"
  ],
  "isActive": true,
  "createdAt": "2026-01-01T00:00:00.000Z"
}

Notes, examples, or caveats for GET /custom-components go here.

`POST /api/v1/custom-components`

Create a custom component

post

/custom-components

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Body

namestringRequired

displayNamestringOptional

componentTypestring · enumRequiredPossible values:

codestringOptional

categorystringOptional

editorContextsstring[]Optional

Responses

201

Component created

application/json

A custom UI component (code or template type) for the Puck editor

idstring · uuidOptional

namestringOptional

displayNamestring · nullableOptional

descriptionstring · nullableOptional

componentTypestring · enumOptionalPossible values:

categorystring · nullableOptional

editorContextsstring[]Optional

audienceRolesstring[]Optional

isActivebooleanOptional

createdAtstring · date-timeOptional

400

Validation error

application/json

post/custom-components

POST /api/v1/custom-components HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 117

{
  "name": "text",
  "displayName": "text",
  "componentType": "code",
  "code": "text",
  "category": "text",
  "editorContexts": [
    "text"
  ]
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "displayName": "text",
  "description": "text",
  "componentType": "code",
  "category": "text",
  "editorContexts": [
    "text"
  ],
  "audienceRoles": [
    "text"
  ],
  "isActive": true,
  "createdAt": "2026-01-01T00:00:00.000Z"
}

Notes, examples, or caveats for POST /custom-components go here.

`DELETE /api/v1/custom-components/{id}`

Delete a custom component

delete

/custom-components/{id}

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Responses

204

Component deleted

No content

404

Not found

application/json

delete/custom-components/{id}

DELETE /api/v1/custom-components/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for DELETE /custom-components/{id} go here.

`GET /api/v1/custom-components/{id}`

Get custom component details

get

/custom-components/{id}

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Responses

200

Component details

application/json

A custom UI component (code or template type) for the Puck editor

idstring · uuidOptional

namestringOptional

displayNamestring · nullableOptional

descriptionstring · nullableOptional

componentTypestring · enumOptionalPossible values:

categorystring · nullableOptional

editorContextsstring[]Optional

audienceRolesstring[]Optional

isActivebooleanOptional

createdAtstring · date-timeOptional

404

Not found

application/json

get/custom-components/{id}

GET /api/v1/custom-components/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "displayName": "text",
  "description": "text",
  "componentType": "code",
  "category": "text",
  "editorContexts": [
    "text"
  ],
  "audienceRoles": [
    "text"
  ],
  "isActive": true,
  "createdAt": "2026-01-01T00:00:00.000Z"
}

Notes, examples, or caveats for GET /custom-components/{id} go here.

`PATCH /api/v1/custom-components/{id}`

Update a custom component

patch

/custom-components/{id}

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Body

namestringOptional

displayNamestringOptional

codestringOptional

isActivebooleanOptional

Responses

200

Component updated

application/json

A custom UI component (code or template type) for the Puck editor

idstring · uuidOptional

namestringOptional

displayNamestring · nullableOptional

descriptionstring · nullableOptional

componentTypestring · enumOptionalPossible values:

categorystring · nullableOptional

editorContextsstring[]Optional

audienceRolesstring[]Optional

isActivebooleanOptional

createdAtstring · date-timeOptional

404

Not found

application/json

patch/custom-components/{id}

PATCH /api/v1/custom-components/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 66

{
  "name": "text",
  "displayName": "text",
  "code": "text",
  "isActive": true
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "displayName": "text",
  "description": "text",
  "componentType": "code",
  "category": "text",
  "editorContexts": [
    "text"
  ],
  "audienceRoles": [
    "text"
  ],
  "isActive": true,
  "createdAt": "2026-01-01T00:00:00.000Z"
}

Notes, examples, or caveats for PATCH /custom-components/{id} go here.

`GET /api/v1/journeys`

List journeys for the tenant

get

/journeys

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Query parameters

limitinteger · min: 1 · max: 100Optional

Max items to return (1–100, default 20)

Default: 20

offsetintegerOptional

Number of items to skip (default 0)

Default: 0

statusstringOptional

Filter by status (draft, active, archived)

typestringOptional

Filter by journey type

Responses

200

Paginated list of journeys

No content

get/journeys

GET /api/v1/journeys HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

200

Paginated list of journeys

No content

Supports ?status= (draft, active, archived) and ?type= filters. An unrecognised status is a 400 rather than an empty list, so a typo cannot look like "no journeys".

`POST /api/v1/journeys`

Create a journey

post

/journeys

A journey is always created as a draft. Publish it with POST /journeys/{id}/publish.

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Body

namestringRequired

typestringRequired

descriptionstringOptional

purposestringOptional

audiencestringOptional

Responses

201

Journey created (status draft)

No content

400

Validation error

application/json

post/journeys

POST /api/v1/journeys HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 85

{
  "name": "text",
  "type": "text",
  "description": "text",
  "purpose": "text",
  "audience": "text"
}

No content

A journey is always created as a draft. Passing status: "active" is rejected rather than silently downgraded, because creating a live journey would bypass every publish gate.

Create the journey, add its steps, then publish it.

`DELETE /api/v1/journeys/{id}`

Delete a journey

delete

/journeys/{id}

Deleting an ACTIVE journey takes it off the air and additionally requires journeys:publish.

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Responses

204

Journey deleted

No content

403

Insufficient scope

application/json

404

Not found

application/json

delete/journeys/{id}

DELETE /api/v1/journeys/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Deleting a draft or archived journey needs journeys:delete.

Deleting an active journey takes it off the air, so it additionally requires journeys:publish. Archive it first if your key only holds delete authority.

`GET /api/v1/journeys/{id}`

Get journey details

get

/journeys/{id}

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Responses

200

Journey details

No content

404

Not found

application/json

get/journeys/{id}

GET /api/v1/journeys/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for GET /journeys/{id} go here.

`PATCH /api/v1/journeys/{id}`

Update a journey

patch

/journeys/{id}

Changing status changes what is live and additionally requires journeys:publish — in either direction, since taking a live journey down matters as much as putting one up. A transition to active runs the publish gates and records a version.

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Body

namestringOptional

descriptionstringOptional

statusstring · enumOptional

Requires journeys:publish.

Possible values:

Responses

200

Journey updated

No content

403

Insufficient scope

application/json

404

Not found

application/json

patch/journeys/{id}

PATCH /api/v1/journeys/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 53

{
  "name": "text",
  "description": "text",
  "status": "draft"
}

No content

Editing a journey's name, description or audience needs journeys:write.

Changing status is different. A journey's status is its live state, so a status transition additionally requires journeys:publish — in either direction. Deactivating a live journey is gated as tightly as activating one, because taking a journey off the air affects customers just as much as putting it up.

Re-sending the journey's current status is not a transition, so a client that submits the whole object on every save can keep editing a live journey with only journeys:write.

A transition to active runs the full publish validation and records a journey version — it behaves exactly like POST /journeys/{id}/publish, including its error responses.

`POST /api/v1/journeys/{id}/publish`

Publish a journey

post

/journeys/{id}/publish

Runs the publish-time validation gates and records a journey version. A rejection returns the gate's own code — BROKEN_BRANCHING_TARGETS or UNSATISFIABLE_REQUIRED_ACTIONS — with its detail, so the problem can be fixed. Republishing an unchanged journey returns unchanged: true and mints no new version.

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Responses

200

Journey published (or unchanged)

No content

400

Graph validation failed

application/json

404

Not found

application/json

422

A publish gate rejected the journey

application/json

post/journeys/{id}/publish

POST /api/v1/journeys/{id}/publish HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Publishes the journey through the platform's publish-time validation. Four gates run, and a failure returns the gate's own error code so you can fix the specific problem:

Code

Meaning

BROKEN_BRANCHING_TARGETS (422)

A step branches to a target that no longer exists. The response lists brokenTargets.

UNSATISFIABLE_REQUIRED_ACTIONS (422)

A required commerce action has a hard-required field that nothing maps. The response lists errors.

graph validation (400)

The draft introduces a new cycle or unreachable step versus what is already published. Pre-existing issues do not block a republish.

Republishing a journey with no changes returns 200 with unchanged: true and does not mint a new version — check that flag rather than assuming a new version exists.

Non-blocking findings come back in warnings alongside a successful publish.

`GET /api/v1/journeys/{id}/steps`

List a journey's steps

get

/journeys/{id}/steps

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Query parameters

limitinteger · min: 1 · max: 100Optional

Max items to return (1–100, default 20)

Default: 20

offsetintegerOptional

Number of items to skip (default 0)

Default: 0

Responses

200

Paginated list of steps

No content

404

Not found

application/json

get/journeys/{id}/steps

GET /api/v1/journeys/{id}/steps HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for GET /journeys/{id}/steps go here.

`POST /api/v1/journeys/{id}/steps`

Add a step to a journey

post

/journeys/{id}/steps

Draft-side: needs only journeys:write, and is invisible to live sessions until the journey is published. stepOrder is optional and appends when omitted.

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Body

pageIdstringRequired

A page in the same tenant.

labelstringOptional

stepOrderintegerOptional

branchingConfigobjectOptional

Responses

201

Step created

No content

400

Validation error

application/json

404

Not found

application/json

post/journeys/{id}/steps

POST /api/v1/journeys/{id}/steps HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 67

{
  "pageId": "text",
  "label": "text",
  "stepOrder": 1,
  "branchingConfig": {}
}

No content

Adding, editing and removing steps is draft-side and needs only journeys:write.

That is deliberate, not a gap. For a published journey the runtime serves the version snapshot frozen at publish time, so a step edit is invisible to live sessions until you publish again. journeys:delete means deleting the journey, not a step.

stepOrder is optional — omit it and the step is appended.

pageId must reference a page in the same tenant.

`DELETE /api/v1/journeys/{id}/steps/{stepId}`

Delete a journey step

delete

/journeys/{id}/steps/{stepId}

Draft-side, so journeys:write — journeys:delete is for deleting the journey itself.

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

stepIdstringRequired

Responses

204

Step deleted

No content

404

Not found

application/json

delete/journeys/{id}/steps/{stepId}

DELETE /api/v1/journeys/{id}/steps/{stepId} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for DELETE /journeys/{id}/steps/{stepId} go here.

`GET /api/v1/journeys/{id}/steps/{stepId}`

Get one journey step

get

/journeys/{id}/steps/{stepId}

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

stepIdstringRequired

Responses

200

Step

No content

404

Not found

application/json

get/journeys/{id}/steps/{stepId}

GET /api/v1/journeys/{id}/steps/{stepId} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for GET /journeys/{id}/steps/{stepId} go here.

`PATCH /api/v1/journeys/{id}/steps/{stepId}`

Update a journey step

patch

/journeys/{id}/steps/{stepId}

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

stepIdstringRequired

Body

labelstringOptional

pageIdstringOptional

branchingConfigobjectOptional

disabledbooleanOptional

Responses

200

Step updated

No content

404

Not found

application/json

patch/journeys/{id}/steps/{stepId}

PATCH /api/v1/journeys/{id}/steps/{stepId} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 69

{
  "label": "text",
  "pageId": "text",
  "branchingConfig": {},
  "disabled": true
}

No content

Notes, examples, or caveats for PATCH /journeys/{id}/steps/{stepId} go here.

`GET /api/v1/journeys/{id}/steps/{stepId}/actions`

List a step's commerce actions

get

/journeys/{id}/steps/{stepId}/actions

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

stepIdstringRequired

Responses

200

Commerce actions in execution order

No content

404

Not found

application/json

get/journeys/{id}/steps/{stepId}/actions

GET /api/v1/journeys/{id}/steps/{stepId}/actions HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for GET /journeys/{id}/steps/{stepId}/actions go here.

`POST /api/v1/journeys/{id}/steps/{stepId}/actions`

Add a commerce action to a step

post

/journeys/{id}/steps/{stepId}/actions

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

stepIdstringRequired

Body

operationTypestringRequired

executionModestring · enumOptionalPossible values:

integrationIdstringOptional

fieldMappingobject[]Optional

Responses

201

Action created

No content

400

Validation error

application/json

404

Not found

application/json

post/journeys/{id}/steps/{stepId}/actions

POST /api/v1/journeys/{id}/steps/{stepId}/actions HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 94

{
  "operationType": "text",
  "executionMode": "blocking",
  "integrationId": "text",
  "fieldMapping": [
    {}
  ]
}

No content

Notes, examples, or caveats for POST /journeys/{id}/steps/{stepId}/actions go here.

`DELETE /api/v1/journeys/{id}/steps/{stepId}/actions/{actionId}`

Delete a commerce action

delete

/journeys/{id}/steps/{stepId}/actions/{actionId}

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

stepIdstringRequired

actionIdstringRequired

Responses

204

Action deleted

No content

404

Not found

application/json

delete/journeys/{id}/steps/{stepId}/actions/{actionId}

DELETE /api/v1/journeys/{id}/steps/{stepId}/actions/{actionId} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for DELETE /journeys/{id}/steps/{stepId}/actions/{actionId} go here.

`PATCH /api/v1/journeys/{id}/steps/{stepId}/actions/{actionId}`

Update a commerce action

patch

/journeys/{id}/steps/{stepId}/actions/{actionId}

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

stepIdstringRequired

actionIdstringRequired

Body

executionModestringOptional

integrationIdstringOptional

fieldMappingobject[]Optional

Responses

200

Action updated

No content

404

Not found

application/json

patch/journeys/{id}/steps/{stepId}/actions/{actionId}

PATCH /api/v1/journeys/{id}/steps/{stepId}/actions/{actionId} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 67

{
  "executionMode": "text",
  "integrationId": "text",
  "fieldMapping": [
    {}
  ]
}

No content

Notes, examples, or caveats for PATCH /journeys/{id}/steps/{stepId}/actions/{actionId} go here.

`POST /api/v1/journeys/{id}/steps/{stepId}/actions/reorder`

Reorder a step's commerce actions

post

/journeys/{id}/steps/{stepId}/actions/reorder

Action order IS execution order, so the list must name every action on the step exactly once.

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

stepIdstringRequired

Body

actionIdsstring[]Required

Responses

200

Actions reordered

No content

400

Invalid list

application/json

404

Not found

application/json

post/journeys/{id}/steps/{stepId}/actions/reorder

POST /api/v1/journeys/{id}/steps/{stepId}/actions/reorder HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 22

{
  "actionIds": [
    "text"
  ]
}

No content

A step's action order is its execution order, so actionIds must name every action on the step exactly once. A partial list is refused — silently accepting one would change which action runs first.

`POST /api/v1/journeys/{id}/steps/reorder`

Reorder a journey's steps

post

/journeys/{id}/steps/reorder

Must list every step exactly once. Rejected if the new order introduces a cycle or strands a step — non-retroactively, so a journey that already had a graph problem can still be rearranged toward a fix.

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Body

stepIdsstring[]Required

Responses

200

Steps reordered

No content

400

Invalid list or graph would break

application/json

404

Not found

application/json

post/journeys/{id}/steps/reorder

POST /api/v1/journeys/{id}/steps/reorder HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 20

{
  "stepIds": [
    "text"
  ]
}

No content

Supply stepIds naming every step of the journey exactly once. A partial or stale list is rejected rather than reordered into something you did not ask for.

The reorder is refused with journey_graph_invalid if the new order introduces a cycle or leaves a step unreachable. The check is non-retroactive: only problems the reorder itself introduces block it, so a journey that already had a graph issue can still be rearranged toward a fix. The response carries graphIssues with the offending step orders.

`GET /api/v1/journeys/{id}/versions`

List a journey's versions

get

/journeys/{id}/versions

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Query parameters

limitinteger · min: 1 · max: 100Optional

Max items to return (1–100, default 20)

Default: 20

offsetintegerOptional

Number of items to skip (default 0)

Default: 0

Responses

200

Paginated list of journey versions

No content

404

Not found

application/json

get/journeys/{id}/versions

GET /api/v1/journeys/{id}/versions HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for GET /journeys/{id}/versions go here.

`GET /api/v1/journeys/{id}/versions/{versionId}`

Get one journey version, including its snapshot

get

/journeys/{id}/versions/{versionId}

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

versionIdstringRequired

Responses

200

Journey version

No content

404

Not found

application/json

get/journeys/{id}/versions/{versionId}

GET /api/v1/journeys/{id}/versions/{versionId} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for GET /journeys/{id}/versions/{versionId} go here.

`GET /api/v1/journeys/{journeyId}/business-rules`

List the business rules attached to a journey

get

/journeys/{journeyId}/business-rules

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

journeyIdstringRequired

Responses

200

Attached rules

No content

404

Not found

application/json

get/journeys/{journeyId}/business-rules

GET /api/v1/journeys/{journeyId}/business-rules HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for GET /journeys/{journeyId}/business-rules go here.

`POST /api/v1/journeys/{journeyId}/business-rules`

Attach a business rule to a journey

post

/journeys/{journeyId}/business-rules

Scoped as a rules:* operation — the rule is what is being applied. Both the journey and the rule must belong to the caller's tenant. A duplicate attachment returns 409 already_linked.

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

journeyIdstringRequired

Body

businessRuleIdstringRequired

Responses

201

Attached

No content

400

Validation error

application/json

409

Already attached

application/json

post/journeys/{journeyId}/business-rules

POST /api/v1/journeys/{journeyId}/business-rules HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 25

{
  "businessRuleId": "text"
}

No content

Attaching a rule to a journey changes that journey's policy. It is scoped as a rules:* operation because the rule is what is being applied; the journey is still verified to belong to your tenant.

Both ends are re-checked under the tenant — a rule id from another tenant is refused rather than silently attaching a foreign policy. Attaching a rule that is already on the journey returns 409 already_linked rather than a raw database error.

`DELETE /api/v1/journeys/{journeyId}/business-rules/{linkId}`

Detach a business rule from a journey

delete

/journeys/{journeyId}/business-rules/{linkId}

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

journeyIdstringRequired

linkIdstringRequired

Responses

204

Detached

No content

404

Not found

application/json

delete/journeys/{journeyId}/business-rules/{linkId}

DELETE /api/v1/journeys/{journeyId}/business-rules/{linkId} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for DELETE /journeys/{journeyId}/business-rules/{linkId} go here.

`GET /api/v1/pages`

List all pages (portal, payment, storefront, checkout) for the tenant

get

/pages

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Query parameters

limitinteger · min: 1 · max: 100Optional

Max items to return (1–100, default 20)

Default: 20

offsetintegerOptional

Number of items to skip (default 0)

Default: 0

typestringOptional

Filter by page type

Responses

200

Paginated list of pages

application/json

A portal page, payment page, storefront page, or checkout page

idstring · uuidOptional

namestringOptional

slugstringOptional

typestringOptional

isActivebooleanOptional

createdAtstring · date-timeOptional

get/pages

GET /api/v1/pages HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

200

Paginated list of pages

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "slug": "text",
  "type": "text",
  "isActive": true,
  "createdAt": "2026-01-01T00:00:00.000Z"
}

Notes, examples, or caveats for GET /pages go here.

`POST /api/v1/pages`

Create a new page

post

/pages

Setting pageContent publishes the page live and additionally requires the pages:publish scope; write draftPageContent and use POST /pages/{id}/publish instead.

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Body

namestringRequired

typestringRequired

slugstringOptional

draftPageContentobjectOptional

Working draft. Safe to write with pages:write.

pageContentobjectOptional

LIVE content. Requires pages:publish.

Responses

201

Page created

application/json

A portal page, payment page, storefront page, or checkout page

idstring · uuidOptional

namestringOptional

slugstringOptional

typestringOptional

isActivebooleanOptional

createdAtstring · date-timeOptional

400

Validation error

application/json

post/pages

POST /api/v1/pages HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 82

{
  "name": "text",
  "type": "text",
  "slug": "text",
  "draftPageContent": {},
  "pageContent": {}
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "slug": "text",
  "type": "text",
  "isActive": true,
  "createdAt": "2026-01-01T00:00:00.000Z"
}

Notes, examples, or caveats for POST /pages go here.

`DELETE /api/v1/pages/{id}`

Delete a page

delete

/pages/{id}

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Responses

204

Page deleted

No content

404

Not found

application/json

delete/pages/{id}

DELETE /api/v1/pages/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for DELETE /pages/{id} go here.

`GET /api/v1/pages/{id}`

Get page details

get

/pages/{id}

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Responses

200

Page details

application/json

A portal page, payment page, storefront page, or checkout page

idstring · uuidOptional

namestringOptional

slugstringOptional

typestringOptional

isActivebooleanOptional

createdAtstring · date-timeOptional

404

Not found

application/json

get/pages/{id}

GET /api/v1/pages/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "slug": "text",
  "type": "text",
  "isActive": true,
  "createdAt": "2026-01-01T00:00:00.000Z"
}

Notes, examples, or caveats for GET /pages/{id} go here.

`PATCH /api/v1/pages/{id}`

Update a page

patch

/pages/{id}

Setting pageContent publishes the page live and additionally requires the pages:publish scope; write draftPageContent and use POST /pages/{id}/publish instead.

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Body

namestringOptional

slugstringOptional

draftPageContentobjectOptional

Working draft. Safe to write with pages:write.

pageContentobjectOptional

LIVE content. Requires pages:publish.

Responses

200

Page updated

application/json

A portal page, payment page, storefront page, or checkout page

idstring · uuidOptional

namestringOptional

slugstringOptional

typestringOptional

isActivebooleanOptional

createdAtstring · date-timeOptional

404

Not found

application/json

patch/pages/{id}

PATCH /api/v1/pages/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 68

{
  "name": "text",
  "slug": "text",
  "draftPageContent": {},
  "pageContent": {}
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "slug": "text",
  "type": "text",
  "isActive": true,
  "createdAt": "2026-01-01T00:00:00.000Z"
}

Notes, examples, or caveats for PATCH /pages/{id} go here.

`GET /api/v1/pages/{id}/manifest`

Get a page's commerce manifest

get

/pages/{id}/manifest

What this page sells — product set, persona config and resolved commerce manifest. Read-only context for an agent editing the page.

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Responses

200

Page commerce manifest

No content

404

Not found

application/json

get/pages/{id}/manifest

GET /api/v1/pages/{id}/manifest HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for GET /pages/{id}/manifest go here.

`POST /api/v1/pages/{id}/publish`

Publish a page — promote its draft content to live

post

/pages/{id}/publish

Copies draftPageContent onto pageContent and records a published version. The explicit form of what setting pageContent used to do implicitly.

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Responses

200

Page published

application/json

A portal page, payment page, storefront page, or checkout page

idstring · uuidOptional

namestringOptional

slugstringOptional

typestringOptional

isActivebooleanOptional

createdAtstring · date-timeOptional

404

Not found

application/json

409

No draft content to publish

application/json

post/pages/{id}/publish

POST /api/v1/pages/{id}/publish HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "slug": "text",
  "type": "text",
  "isActive": true,
  "createdAt": "2026-01-01T00:00:00.000Z"
}

Notes, examples, or caveats for POST /pages/{id}/publish go here.

`GET /api/v1/pages/{id}/versions`

List a page's saved versions

get

/pages/{id}/versions

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Query parameters

limitinteger · min: 1 · max: 100Optional

Max items to return (1–100, default 20)

Default: 20

offsetintegerOptional

Number of items to skip (default 0)

Default: 0

Responses

200

Paginated list of versions

No content

404

Not found

application/json

get/pages/{id}/versions

GET /api/v1/pages/{id}/versions HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for GET /pages/{id}/versions go here.

`GET /api/v1/pages/{id}/versions/{versionId}`

Get one saved version of a page

get

/pages/{id}/versions/{versionId}

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

versionIdstringRequired

Responses

200

Version details

No content

404

Not found

application/json

get/pages/{id}/versions/{versionId}

GET /api/v1/pages/{id}/versions/{versionId} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for GET /pages/{id}/versions/{versionId} go here.

`POST /api/v1/pages/{id}/versions/{versionId}/restore`

Restore a saved version into the page's draft

post

/pages/{id}/versions/{versionId}/restore

Restores into draftPageContent, never directly to live — so rolling back what is published stays a deliberate restore-then-publish. Requires pages:write only.

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

versionIdstringRequired

Responses

200

Draft restored

application/json

A portal page, payment page, storefront page, or checkout page

idstring · uuidOptional

namestringOptional

slugstringOptional

typestringOptional

isActivebooleanOptional

createdAtstring · date-timeOptional

404

Not found

application/json

post/pages/{id}/versions/{versionId}/restore

POST /api/v1/pages/{id}/versions/{versionId}/restore HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "slug": "text",
  "type": "text",
  "isActive": true,
  "createdAt": "2026-01-01T00:00:00.000Z"
}

Notes, examples, or caveats for POST /pages/{id}/versions/{versionId}/restore go here.

`GET /api/v1/product-sets`

List product sets

get

/product-sets

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Query parameters

limitinteger · min: 1 · max: 100Optional

Max items to return (1–100, default 20)

Default: 20

offsetintegerOptional

Number of items to skip (default 0)

Default: 0

statusstringOptional

Filter by status (draft, active, archived)

Responses

200

Paginated product sets

No content

get/product-sets

GET /api/v1/product-sets HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

200

Paginated product sets

No content

Notes, examples, or caveats for GET /product-sets go here.

`POST /api/v1/product-sets`

Create a product set

post

/product-sets

Always created as a draft. Activate it with PATCH once its items are in place — activation runs the timing anchor rule and needs productsets:publish.

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Body

namestringRequired

descriptionstringOptional

carryQuantityOnBaseChangebooleanOptional

Responses

201

Product set created (status draft)

No content

400

Validation error

application/json

post/product-sets

POST /api/v1/product-sets HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 69

{
  "name": "text",
  "description": "text",
  "carryQuantityOnBaseChange": true
}

No content

Product sets are always created as drafts. Passing status: "active" is rejected rather than downgraded, because a set born active would skip the activation timing gate entirely.

The normal shape is: create the set → add its items → PATCH status to active with a key holding productsets:publish.

`DELETE /api/v1/product-sets/{id}`

Delete a product set

delete

/product-sets/{id}

Deleting an ACTIVE set withdraws it from customers and additionally requires productsets:publish.

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Responses

204

Deleted

No content

403

Insufficient scope

application/json

404

Not found

application/json

delete/product-sets/{id}

DELETE /api/v1/product-sets/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for DELETE /product-sets/{id} go here.

`GET /api/v1/product-sets/{id}`

Get a product set

get

/product-sets/{id}

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Responses

200

Product set

No content

404

Not found

application/json

get/product-sets/{id}

GET /api/v1/product-sets/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for GET /product-sets/{id} go here.

`PATCH /api/v1/product-sets/{id}`

Update a product set

patch

/product-sets/{id}

An ACTIVE set resolves for customers and has no version snapshot, so any edit to it — and every status transition in either direction — additionally requires productsets:publish. Activating runs the §1.5 anchor rule and returns product_set_timing_invalid if no line uses same-as-order timing.

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Body

namestringOptional

descriptionstringOptional

statusstring · enumOptional

Requires productsets:publish.

Possible values:

Responses

200

Updated

No content

400

Timing/validation error

application/json

403

Insufficient scope

application/json

404

Not found

application/json

patch/product-sets/{id}

PATCH /api/v1/product-sets/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 53

{
  "name": "text",
  "description": "text",
  "status": "draft"
}

No content

A product set is the strictest surface in the API, for a reason worth understanding.

Unlike a journey or a page, a product set has no version snapshot. A journey freezes its steps at publish time, so editing the draft cannot reach a running session. A product set is resolved straight from its live rows — so if the set is active, an edit is in front of customers immediately.

Accordingly:

The set is…

productsets:write can edit it?

draft

yes

archived

yes

active

no — needs productsets:publish

A status transition needs productsets:publish in either direction, since deactivating a live set withdraws it from customers just as surely as activating one exposes it.

Activating also runs the §1.5 anchor rule: at least one line must use same_as_order timing, so something bills or activates immediately. A set that fails it comes back 400 product_set_timing_invalid with the specific errors in configErrors. Draft edits are allowed to defer this — activation is where it bites.

`GET /api/v1/product-sets/{id}/bundles`

List a product set's bundles

get

/product-sets/{id}/bundles

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Responses

200

Bundles with their members

No content

404

Not found

application/json

get/product-sets/{id}/bundles

GET /api/v1/product-sets/{id}/bundles HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for GET /product-sets/{id}/bundles go here.

`POST /api/v1/product-sets/{id}/bundles`

Create a bundle in a product set

post

/product-sets/{id}/bundles

A bundle is one FACE entry (the card the customer sees) plus one or more MEMBER entries added silently when the face is selected. The face may not be a member of its own bundle, and a bundle must have at least one member.

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Body

namestringRequired

faceItemIdstringRequired

memberItemIdsstring[]Required

Responses

201

Bundle created

No content

400

Validation error

application/json

post/product-sets/{id}/bundles

POST /api/v1/product-sets/{id}/bundles HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 60

{
  "name": "text",
  "faceItemId": "text",
  "memberItemIds": [
    "text"
  ]
}

No content

A bundle is a composition unit inside a set: one face entry (the card the customer actually sees) plus one or more member entries that are added silently to the order when the face is selected.

Two shapes are refused: a face that is also a member of its own bundle, and a bundle with no members at all.

Bundles are distinct from the classification-driven groups in the editor — groups are taxonomy that organize the card list, bundles compose sellable units. An entry keeps its classification while being a bundle member; the two axes are orthogonal.

`DELETE /api/v1/product-sets/{id}/bundles/{bundleId}`

Delete a bundle

delete

/product-sets/{id}/bundles/{bundleId}

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

bundleIdstringRequired

Responses

204

Deleted

No content

404

Not found

application/json

delete/product-sets/{id}/bundles/{bundleId}

DELETE /api/v1/product-sets/{id}/bundles/{bundleId} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for DELETE /product-sets/{id}/bundles/{bundleId} go here.

`PATCH /api/v1/product-sets/{id}/bundles/{bundleId}`

Update a bundle

patch

/product-sets/{id}/bundles/{bundleId}

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

bundleIdstringRequired

Body

namestringOptional

faceItemIdstringOptional

memberItemIdsstring[]Optional

Responses

200

Bundle updated

No content

400

Validation error

application/json

404

Not found

application/json

patch/product-sets/{id}/bundles/{bundleId}

PATCH /api/v1/product-sets/{id}/bundles/{bundleId} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 60

{
  "name": "text",
  "faceItemId": "text",
  "memberItemIds": [
    "text"
  ]
}

No content

Notes, examples, or caveats for PATCH /product-sets/{id}/bundles/{bundleId} go here.

`GET /api/v1/product-sets/{id}/dependencies`

List a product set's dependencies

get

/product-sets/{id}/dependencies

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Responses

200

Dependencies

No content

404

Not found

application/json

get/product-sets/{id}/dependencies

GET /api/v1/product-sets/{id}/dependencies HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for GET /product-sets/{id}/dependencies go here.

`POST /api/v1/product-sets/{id}/dependencies`

Create a dependency between two items in a set

post

/product-sets/{id}/dependencies

Both ends must be items of THIS set, and an item cannot depend on itself.

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Body

sourceItemIdstringRequired

targetItemIdstringRequired

dependencyTypestring · enumRequiredPossible values:

Responses

201

Dependency created

No content

400

Validation error

application/json

post/product-sets/{id}/dependencies

POST /api/v1/product-sets/{id}/dependencies HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 73

{
  "sourceItemId": "text",
  "targetItemId": "text",
  "dependencyType": "requires"
}

No content

Both sourceItemId and targetItemId must be items of this set — a dependency pointing outside it would be unresolvable at runtime — and an item cannot depend on itself.

`DELETE /api/v1/product-sets/{id}/dependencies/{depId}`

Delete a dependency

delete

/product-sets/{id}/dependencies/{depId}

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

depIdstringRequired

Responses

204

Deleted

No content

404

Not found

application/json

delete/product-sets/{id}/dependencies/{depId}

DELETE /api/v1/product-sets/{id}/dependencies/{depId} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for DELETE /product-sets/{id}/dependencies/{depId} go here.

`GET /api/v1/product-sets/{id}/items`

List a product set's items

get

/product-sets/{id}/items

Each item carries a derived orderGroup (default or own), read from metadata.orderGroup with any unrecognised value reported as default, alongside its effectiveDateTiming.

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Query parameters

limitinteger · min: 1 · max: 100Optional

Max items to return (1–100, default 20)

Default: 20

offsetintegerOptional

Number of items to skip (default 0)

Default: 0

Responses

200

Paginated items

No content

404

Not found

application/json

get/product-sets/{id}/items

GET /api/v1/product-sets/{id}/items HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Each item includes its effectiveDateTiming and a derived orderGroup ("default" or "own") — see POST /product-sets/{id}/items for what they do.

`POST /api/v1/product-sets/{id}/items`

Add an item to a product set

post

/product-sets/{id}/items

productId must reference a product in the same tenant. On an ACTIVE set this requires productsets:publish.

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Body

productIdstringRequired

planIdstringOptional

classificationstring · enumOptionalPossible values:

groupNamestringOptional

sortOrderintegerOptional

orderGroupstring · enumOptional

How the line is booked when a journey places the order. own books it as its own order action (an AddProduct) in the same order and subscription; default books it with the other lines. Honored only by journeys whose create_order action has honorOrderGrouping on. Stored in the item's metadata.orderGroup and merged there server-side, so setting it never replaces other metadata keys. Defaults to default.

Possible values:

effectiveDateTimingone ofOptional

When the line starts, counted from the order date. same_as_order (the default) starts it on the order date; set_period starts it value (1–120) unit later. Applied at checkout only when the create_order action has honorActivationOffsets on. On an ACTIVE set at least one line must stay same_as_order (the anchor rule); a write that breaks it returns 400 product_set_timing_invalid.

Responses

201

Item added. Items are returned with a derived orderGroup, and configWarnings when the set's lines resolve to more than two activation dates.

No content

400

Validation error, or product_set_timing_invalid when the write would leave an active set with no same-as-order line

application/json

403

Set is active

application/json

post/product-sets/{id}/items

POST /api/v1/product-sets/{id}/items HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 163

{
  "productId": "text",
  "planId": "text",
  "classification": "base",
  "groupName": "text",
  "sortOrder": 1,
  "orderGroup": "default",
  "effectiveDateTiming": {
    "mode": "same_as_order"
  }
}

No content

productId must reference a product in the same tenant.

If the set is active, adding an item requires productsets:publish — the item is purchasable the moment it lands, since a product set resolves from its live rows with no draft buffer.

How the line is booked. Two optional fields control how this line lands in the order when a journey checks out:

Field

Values

Default

Effect

orderGroup

"default" · "own"

"default"

"own" books the line as its own order action (an Add Product) within the same order and subscription. Takes effect only when the journey's create_order action has honorOrderGrouping on.

effectiveDateTiming

{"mode":"same_as_order"} · {"mode":"set_period","value":1–120,"unit":"days"|"months"|"years"}

same_as_order

When the line starts, counted from the order date. Applied only when the create_order action has honorActivationOffsets on.

{
  "productId": "5d0c…",
  "planId": "a41e…",
  "classification": "addon",
  "orderGroup": "own",
  "effectiveDateTiming": { "mode": "set_period", "value": 1, "unit": "months" }
}

orderGroup is stored in the item's metadata.orderGroup and merged in on the server, so sending it never replaces other metadata keys such as visibility. Every item response carries the derived orderGroup.
On an active set, at least one line must stay same_as_order. A write that breaks this is refused with 400 product_set_timing_invalid, the same error activation returns. A draft set may pass through that state while you assemble it.
When the set's lines resolve to more than two distinct start dates, the response includes configWarnings.

See Booking a Line as Its Own Order Action for how the order is built from these fields.

`DELETE /api/v1/product-sets/{id}/items/{itemId}`

Remove an item from a product set

delete

/product-sets/{id}/items/{itemId}

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

itemIdstringRequired

Responses

204

Item removed

No content

403

Set is active

application/json

404

Not found

application/json

delete/product-sets/{id}/items/{itemId}

DELETE /api/v1/product-sets/{id}/items/{itemId} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for DELETE /product-sets/{id}/items/{itemId} go here.

`PATCH /api/v1/product-sets/{id}/items/{itemId}`

Update a product set item

patch

/product-sets/{id}/items/{itemId}

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

itemIdstringRequired

Body

classificationstringOptional

groupNamestringOptional

sortOrderintegerOptional

orderGroupstring · enumOptional

Possible values:

effectiveDateTimingone ofOptional

Responses

200

Item updated. Returned with a derived orderGroup, and configWarnings when relevant.

No content

400

Validation error, or product_set_timing_invalid when the change would leave an active set with no same-as-order line

application/json

403

Set is active

application/json

404

Not found

application/json

patch/product-sets/{id}/items/{itemId}

PATCH /api/v1/product-sets/{id}/items/{itemId} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 128

{
  "classification": "text",
  "groupName": "text",
  "sortOrder": 1,
  "orderGroup": "default",
  "effectiveDateTiming": {
    "mode": "same_as_order"
  }
}

No content

Send only the fields you are changing. orderGroup and effectiveDateTiming behave as described under POST /product-sets/{id}/items: orderGroup merges into the stored metadata, and a timing change that would leave an active set with no same_as_order line is refused with 400 product_set_timing_invalid.

{ "orderGroup": "own" }

Editing an item on an active set requires productsets:publish.

`POST /api/v1/product-sets/{id}/items/reorder`

Reorder a product set's items

post

/product-sets/{id}/items/reorder

Sort order drives card order in every consumer, so itemIds must list every item exactly once.

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Body

itemIdsstring[]Required

Responses

200

Reordered

No content

400

Invalid list

application/json

post/product-sets/{id}/items/reorder

POST /api/v1/product-sets/{id}/items/reorder HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 20

{
  "itemIds": [
    "text"
  ]
}

No content

Notes, examples, or caveats for POST /product-sets/{id}/items/reorder go here.

`GET /api/v1/templates`

List page templates

get

/templates

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Query parameters

limitinteger · min: 1 · max: 100Optional

Max items to return (1–100, default 20)

Default: 20

offsetintegerOptional

Number of items to skip (default 0)

Default: 0

pageTypestringOptional

Filter by page type

Responses

200

Paginated list of page templates

application/json

A reusable page template for the editor

idstring · uuidOptional

namestringOptional

descriptionstring · nullableOptional

pageTypestringOptional

thumbnailstring · nullableOptional

createdAtstring · date-timeOptional

get/templates

GET /api/v1/templates HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

200

Paginated list of page templates

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "pageType": "text",
  "thumbnail": "text",
  "createdAt": "2026-01-01T00:00:00.000Z"
}

Notes, examples, or caveats for GET /templates go here.

`POST /api/v1/templates`

Create a page template

post

/templates

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Body

namestringRequired

descriptionstringOptional

pageTypestringOptional

pageContentobjectOptional

Responses

201

Template created

application/json

A reusable page template for the editor

idstring · uuidOptional

namestringOptional

descriptionstring · nullableOptional

pageTypestringOptional

thumbnailstring · nullableOptional

createdAtstring · date-timeOptional

400

Validation error

application/json

post/templates

POST /api/v1/templates HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 71

{
  "name": "text",
  "description": "text",
  "pageType": "text",
  "pageContent": {}
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "pageType": "text",
  "thumbnail": "text",
  "createdAt": "2026-01-01T00:00:00.000Z"
}

Notes, examples, or caveats for POST /templates go here.

`DELETE /api/v1/templates/{id}`

Delete a page template (system templates cannot be deleted)

delete

/templates/{id}

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Responses

204

Template deleted

No content

403

System template — cannot delete

application/json

404

Not found

application/json

delete/templates/{id}

DELETE /api/v1/templates/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for DELETE /templates/{id} go here.

`GET /api/v1/templates/{id}`

Get page template details

get

/templates/{id}

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Responses

200

Template details

application/json

A reusable page template for the editor

idstring · uuidOptional

namestringOptional

descriptionstring · nullableOptional

pageTypestringOptional

thumbnailstring · nullableOptional

createdAtstring · date-timeOptional

404

Not found

application/json

get/templates/{id}

GET /api/v1/templates/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "pageType": "text",
  "thumbnail": "text",
  "createdAt": "2026-01-01T00:00:00.000Z"
}

Notes, examples, or caveats for GET /templates/{id} go here.

`PATCH /api/v1/templates/{id}`

Update a page template (system templates cannot be modified)

patch

/templates/{id}

Required scopes

This endpoint requires the following scopes:

Authorizations

X-API-KeystringRequired

Path parameters

idstringRequired

Body

namestringOptional

descriptionstringOptional

pageContentobjectOptional

isActivebooleanOptional

Responses

200

Template updated

application/json

A reusable page template for the editor

idstring · uuidOptional

namestringOptional

descriptionstring · nullableOptional

pageTypestringOptional

thumbnailstring · nullableOptional

createdAtstring · date-timeOptional

403

System template — cannot modify

application/json

404

Not found

application/json

patch/templates/{id}

PATCH /api/v1/templates/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 69

{
  "name": "text",
  "description": "text",
  "pageContent": {},
  "isActive": true
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "pageType": "text",
  "thumbnail": "text",
  "createdAt": "2026-01-01T00:00:00.000Z"
}

Notes, examples, or caveats for PATCH /templates/{id} go here.

PreviousAudit

NextPartners

Last updated 20 days ago

Was this helpful?