Set referral reward rules

PUT /v1/admin/catalog/referral-rules

• Operation ID: setCatalogReferralRules
• Tags: Catalog: referral rules
• Base URL: http://localhost:8787

Merges referral_reward_credits into the credits settings draft and publishes it immediately, so any other pending draft keys in that section are published too. note becomes the publish note (default referral rules). The database function additionally enforces billing.write and audits.

Workflow: Integration guide.

Authentication: staff Bearer JWT with permission billing.write.

Authentication

• Auth: staff Bearer JWT (Authorization: Bearer <access_token>) with the permissions below.
• Required permissions: billing.write

Request body

Required: yes.

Content type: application/json

Schema: object

Field	Type	Required	Description
referral_reward_credits	integer	yes	Min: 0. Max: 1000000
note	string	no	Max length: 500

Responses

200

Published.

• Header x-request-id: Request identifier; quote it when reporting an error. Content type: application/json

Schema: object

Field	Type	Required	Description
referral_reward_credits	integer	yes	-
published_version	integer	yes	-

Errors

400

Request validation failed.

• Header x-request-id: Request identifier; quote it when reporting an error. Content type: application/json

Schema: object (ValidationErrorBody)

Field	Type	Required	Description
success	boolean	yes	One of: false
error	object	yes	-
error.name	string	yes	One of: "ZodError"
error.issues	object[]	yes	-
error.issues[].code	string	yes	-
error.issues[].path	(string | number)[]	yes	-
error.issues[].message	string	yes	-

Request validation

{
  "success": false,
  "error": {
    "name": "ZodError",
    "issues": [
      {
        "code": "custom",
        "path": [
          "field"
        ],
        "message": "Invalid value"
      }
    ]
  }
}

401

Missing, malformed, expired or wrong-audience Bearer token (missing_token, invalid_token, invalid_audience).

• Header x-request-id: Request identifier; quote it when reporting an error. Content type: application/json

Schema: object (ErrorBody)

Field	Type	Required	Description
error	string	yes	Stable machine-readable error code, e.g. forbidden, not_found.
details	any	no	Optional structured context. For 403 it is { perm }.

Error response

{
  "error": "missing_token"
}

403

Authenticated but lacking the required permission. details.perm lists the accepted permission keys.

• Header x-request-id: Request identifier; quote it when reporting an error. Content type: application/json

Schema: object (ErrorBody), fields as described above.

Error response

{
  "error": "forbidden",
  "details": {
    "perm": "billing.write"
  }
}

500

Unexpected server error (internal). No details are returned.

• Header x-request-id: Request identifier; quote it when reporting an error. Content type: application/json

Schema: object (ErrorBody), fields as described above.

Error response

{
  "error": "internal"
}

Examples

curl

curl -X PUT 'http://localhost:8787/v1/admin/catalog/referral-rules' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"referral_reward_credits":1,"note":"example"}'

TypeScript

const accessToken = process.env.ACCESS_TOKEN; // user JWT from your sign-in flow

const response = await fetch("http://localhost:8787/v1/admin/catalog/referral-rules", {
  method: "PUT",
  headers: {
    "Authorization": `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "referral_reward_credits": 1,
    "note": "example"
  }),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const data = response.status === 204 || response.status === 205
  ? undefined
  : response.headers.get("content-type")?.includes("json")
    ? await response.json()
    : await response.text();