Update a product's Stripe object

PATCH /v1/admin/plans/products/{id}/stripe

• Operation ID: updatePlanStripeProduct
• Tags: Plans and pricing
• Base URL: http://localhost:8787

Updates name, description, images, metadata or active flag on the linked Stripe product. Creates or changes the object in Stripe first (source of truth), then audits the change. Audited as plans.product.stripe_update.

Workflow: Integration guide.

Authentication: staff Bearer JWT with permission plans.write.

Authentication

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

Parameters

Name	In	Type	Required	Description
id	path	string<uuid>	yes	-

Request body

Required: yes.

Content type: application/json

Schema: object

Field	Type	Required	Description
name	string	no	Min length: 1. Max length: 200
description	string	no	Max length: 1000
images	string<uri>[]	no	Max items: 8
metadata	object	no	-
active	boolean	no	-

Responses

200

Stripe product updated.

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

Schema: object

Field	Type	Required	Description
id	string<uuid>	yes	-
stripeProductId	string	yes	-
active	boolean	yes	-

Errors

400

Request validation failed. validation_failed: the product is not linked to a Stripe product.

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

Schema: object (ValidationErrorBody) | object (ErrorBody)

Field	Type	Required	Description
(variant 1).success	boolean	yes	One of: false
(variant 1).error	object	yes	-
(variant 1).error.name	string	yes	One of: "ZodError"
(variant 1).error.issues	object[]	yes	-
(variant 1).error.issues[].code	string	yes	-
(variant 1).error.issues[].path	(string | number)[]	yes	-
(variant 1).error.issues[].message	string	yes	-
(variant 2).error	string	yes	Stable machine-readable error code, e.g. forbidden, not_found.
(variant 2).details	any	no	Optional structured context. For 403 it is { perm }.

Request validation

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

Application error

{
  "error": "validation_failed"
}

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": "plans.write"
  }
}

404

product: no product with this id.

• 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": "product"
}

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 PATCH 'http://localhost:8787/v1/admin/plans/products/3f6c2a1e-8b4d-4e7a-9c1f-2d5b6a7e8f90/stripe' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"name":"example","description":"example","images":["https://example.com/resource"],"metadata":{},"active":false}'

TypeScript

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

const response = await fetch("http://localhost:8787/v1/admin/plans/products/3f6c2a1e-8b4d-4e7a-9c1f-2d5b6a7e8f90/stripe", {
  method: "PATCH",
  headers: {
    "Authorization": `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "example",
    "description": "example",
    "images": [
      "https://example.com/resource"
    ],
    "metadata": {},
    "active": false
  }),
});
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();