Read and lower an accepted usage plan
Read a customer’s accepted ShareAI application plan and request a permitted decrease with revision checks and an idempotency key.
On this page
Use the application agreement API when your backend needs to read the current accepted plan or apply a decrease allowed by that agreement. Authenticate as the application client that owns the customer’s subject.
https://auth.shareai.now/oauth/agreements/{subject}Read the accepted grant and current plan.
- Base URL
https://auth.shareai.now- Authentication
- HTTP Basic: client ID and client secret
cURL
curl --fail-with-body "https://auth.shareai.now/oauth/agreements/$SHAREAI_SUBJECT" \
-u "$SHAREAI_CLIENT_ID:$SHAREAI_CLIENT_SECRET"
The response includes grant_id, revision, plan_id, status and acceptance information. Keep the current grant and revision when preparing a change.
https://auth.shareai.now/oauth/agreements/{subject}Apply a permitted decrease within the accepted contract.
- Base URL
https://auth.shareai.now- Authentication
- HTTP Basic: client ID and client secret
cURL
curl --fail-with-body "https://auth.shareai.now/oauth/agreements/$SHAREAI_SUBJECT" \
-u "$SHAREAI_CLIENT_ID:$SHAREAI_CLIENT_SECRET" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $UNIQUE_CHANGE_KEY" \
--data '{"grant_id":"CURRENT_GRANT_ID","revision":1,"plan_id":"growth"}'
| Field | Rule |
|---|---|
subject | Use this client’s opaque account subject. |
grant_id | Use the grant returned by the latest read. |
revision | Use the current revision; refresh state after a conflict. |
plan_id | Choose a permitted lower plan in the accepted contract. |
Idempotency-Key | 16–128 letters, digits, underscores or hyphens. Reuse only for an identical retry. |
A higher fee needs new consent#
Publishing new prices does not silently increase existing customer agreements. A higher fee requires interactive consent. An application cannot use this endpoint to replace the customer’s accepted terms with a more expensive contract.
Handle concurrent updates#
If the revision or grant has changed, read the current agreement and reconsider the operation. Do not blindly increment revision. An idempotency key reused for a different plan is an error.
Learn the Console workflow#
Last updated September 15, 2026