Pleaxy

Raise purchase orders, approve and pay invoices, and set up your workspace.

API reference

Settlement

When purchase orders and invoices can skip manual approval, and the workspace's plan.

More about this resource

Autonomy settings control when POs and invoices skip manual approval; the plan controls what the workspace is entitled to. The plan itself is read-only over the API - Stripe is the system of record for Pleaxy subscriptions, and the entitlement is written only from Stripe's signed webhooks.

Endpoints

Get autonomy settings

Returns the workspace's auto-approval settings.

GET/v1/workspaces/{regionId}/settlement/autonomy

Returns

200 OK with the object shown in the response.

More details

Returns the workspace's autonomous-settlement settings, defaulting to { enabled: false, maxAutoApproveAmount: 300, approvalThreshold: 25000 } if never configured.

Response fields

  • maxAutoApproveAmountnumber

    With autonomy on, a PO or invoice at or below this amount (in the region's currency) is approved as Pleaxy Autonomy with nobody acting, unless a conditional or high-value step applies, a PO went over a spend limit, or the invoice can't be auto-approved (only an invoice matched against an issued AWS invoice can be, never one a buyer entered or one in another currency). For an invoice over the 3% match tolerance, it caps the difference instead.

  • approvalThresholdnumber

    The high-value threshold: approval steps marked highValueOnly run only for amounts above it, and autonomy never approves a document such a step applies to. Applies whether or not autonomy is on.

Errors

  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
GET /v1/workspaces/{regionId}/settlement/autonomy
Request
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/settlement/autonomy" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
{
   "enabled": boolean,
   "maxAutoApproveAmount": number,
   "approvalThreshold": number
}

Update autonomy settings

Updates the workspace's auto-approval settings.

PATCH/v1/workspaces/{regionId}/settlement/autonomy

Body

  • enabledboolean

    Turn autonomous approval on or off.

  • maxAutoApproveAmountnumber

    New auto-approve ceiling.

  • approvalThresholdnumber

    New high-value threshold.

Returns

200 OK with the object shown in the response.

More details

Updates one or more autonomy settings. Enabling autonomy requires the workspace's plan to be Autonomous or Enterprise.

Signed-in session only: autonomy decides whether a person approves at all, so an API key gets 403 whatever its procurement role. Reading the settings accepts a buyer API key.

Errors

  • 400 Bad Request - enabled: true was sent, but the region's plan is Free or Managed (autonomy requires Autonomous or higher).
  • 403 Forbidden - The caller isn't a signed-in person (for example, an API key): "This action requires a logged-in user session, not an API key". Nothing is saved.
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
PATCH /v1/workspaces/{regionId}/settlement/autonomy
Request
curl -X PATCH "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/settlement/autonomy" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{
   "enabled": boolean,
   "maxAutoApproveAmount": number,
   "approvalThreshold": number
}
Response · 200 OK
{
   "enabled": boolean,
   "maxAutoApproveAmount": number,
   "approvalThreshold": number
}

Get billing

Returns the workspace's plan and subscription.

GET/v1/workspaces/{regionId}/settlement/billing

Returns

200 OK with the object shown in the response.

More details

Returns the workspace's plan and the state of its Pleaxy subscription. The plan is an entitlement cache written only from signed Stripe webhooks (or, for enterprise agreements, by Pleaxy operations) - there is no API for changing it, and no Pleaxy API ever accepts a plan from a caller. Self-serve changes go through Stripe-hosted Checkout and the Stripe Customer Portal, whose URLs are issued by the two session endpoints on this path; both require a human session, so API keys cannot start or change a subscription. Stripe identifiers are deliberately not part of this response.

Response fields

  • billingEnabledboolean

    false when the environment has no Stripe configuration; the session endpoints then return 503.

  • planstring

    The entitlement plan limits are enforced against.

  • managedBystring

    "platform" for an enterprise agreement assigned by Pleaxy operations - no self-serve changes; otherwise "self-serve".

  • hasBillingAccountboolean

    A Stripe Customer exists for this workspace, so the Customer Portal is available.

  • subscriptionStatusstring

    Stripe's subscription status, copied verbatim. Absent when the workspace has never subscribed.

  • currentPeriodEndstring

    ISO 8601 renewal date, or the end-of-access date when cancelAtPeriodEnd is true.

  • cancelAtPeriodEndboolean

    The subscription is set to end at currentPeriodEnd rather than renew.

  • pastDueSincestring

    ISO 8601 timestamp of the failed payment. The paid plan is kept for the duration of Stripe's dunning window.

  • availablePlansarray

    The purchasable plans with their current prices, read from Stripe: the first region's monthly price, the yearly price when one is configured, and each further region's price tier. Empty when billing is disabled or Stripe pricing is temporarily unavailable.

  • *PriceLabel, *Pricestring, object

    Each price twice: an English label (such as a monthly price followed by "/mo") and the same price as figures - { amount, currency, interval }, amount in the currency's minor unit (cents) and currency lowercase, as Stripe gives them - to format in your own language. additionalRegionPrices has one { fromRegion, toRegion, price } per label (toRegion null: and every region after).

  • currentPrice, currentTotalobject

    The current subscription's first-region price and what the company pays per interval for all its buyer regions (buyerRegionCount), with their labels. Only when billing is enabled and a price is on file.

Errors

  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
GET /v1/workspaces/{regionId}/settlement/billing
Request
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/settlement/billing" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
{
   "billingEnabled": boolean,
   "plan": "assisted" | "managed" | "autonomous" | "enterprise",
   "managedBy": "self-serve" | "platform",
   "hasBillingAccount": boolean,
   "subscriptionStatus": "trialing" | "active" | "past_due" | "unpaid" | "canceled" | "incomplete" | "incomplete_expired" | "paused",
   "currentPeriodEnd": "string",
   "cancelAtPeriodEnd": boolean,
   "pastDueSince": "string",
   "buyerRegionCount": number,
   "interval": "month" | "year",
   "availablePlans": [
      {
         "plan": "managed" | "autonomous",
         "monthlyPriceLabel": "string",
         "monthlyPrice": { "amount": number, "currency": "string", "interval": "month" },
         "yearlyPriceLabel": "string",
         "yearlyPrice": { "amount": number, "currency": "string", "interval": "year" },
         "additionalRegionPriceLabels": [ "string" ],
         "additionalRegionPrices": [ { "fromRegion": number, "toRegion": number | null, "price": { "amount": number, "currency": "string", "interval": "month" | "year" } } ]
      }
   ],
   "currentPriceLabel": "string",
   "currentPrice": { "amount": number, "currency": "string", "interval": "month" | "year" },
   "currentTotalLabel": "string",
   "currentTotal": { "amount": number, "currency": "string", "interval": "month" | "year" }
}
Talk to us