Enter a commitment · Billing API

POST/api/v1/billing/commitment

Agrees to the published commitment terms: a volume of ehu per month for the term the terms set, starting on the first day of next month, billed at the commitment price whether or not it is used. This is a binding agreement; read terms.body from GET /api/v1/billing/commitment first.

accepted must be true, and terms_version must be the version of the terms you read; if the terms have changed since, the request is refused with 409 TERMS_CHANGED.
ehu must be above zero.
With a commitment already running, only a larger ehu is accepted (409 NOT_AN_INCREASE otherwise). The running one then ends without any early-termination charge and the new one starts next month. To commit to less, end the current commitment first.

The acceptance records the terms version, who accepted (the person behind a personal key, or the organization key) and the address the request came from. Answers with the new commitment state.

Requires the billing:commitment:write scope.

Authorization

Any one of:

Request body required

Content type: application/json

Type: object

ehu number required
EHU committed per month.
terms_version integer required
The terms.version you read and agree to.
accepted boolean required
Must be true.

Responses

`200`

The commitment was recorded.

Content type: application/json

Type: object

data CommitmentState
Show CommitmentState properties
- terms CommitmentTerms
  Show CommitmentTerms properties
  - version integer
  - body string
    The full text of the agreement.
  - body_sha256 string
  - term_months integer
  - published_at string (date-time)
- active Commitment
  Show Commitment properties
  - id integer
  - org_id string
  - ehu_per_month number
  - starts_on string (date-time)
    The first day of the first committed month.
  - ends_on string (date-time)
    The first day after the term (exclusive).
  - status string
    One of: active completed terminated
  - terms_version integer
  - terms_sha256 string
    The hash of the agreement text that was accepted.
  - accepted_at string (date-time)
  - accepted_by string
    The person, or the organization key, that accepted.
  - accepted_ip string
  - terminated_at string (date-time)
  - terminated_from string (date-time)
    The first month no longer committed, for an ended commitment.
  - terminated_by string
  - clawback_usd number
    The early-termination charge.
  - clawback_invoice_id string
  - clawback_invoice_url string (uri)
  - clawback_invoice_pdf_url string (uri)
  - clawback_invoiced_at string (date-time)
  - ending_notice_at string (date-time)
    When the organization was told the term is nearly over.
  - created_at string (date-time)
- starts_on string (date-time)
  When a commitment agreed now would start.
- estimated_clawback_usd number
  What ending the active commitment today would cost; 0 without one.
- commitment_usd_per_ehu number
- on_demand_usd_per_ehu number
- history array of Commitment
  The last 24 commitments.
  Show Commitment properties
  - id integer
  - org_id string
  - ehu_per_month number
  - starts_on string (date-time)
    The first day of the first committed month.
  - ends_on string (date-time)
    The first day after the term (exclusive).
  - status string
    One of: active completed terminated
  - terms_version integer
  - terms_sha256 string
    The hash of the agreement text that was accepted.
  - accepted_at string (date-time)
  - accepted_by string
    The person, or the organization key, that accepted.
  - accepted_ip string
  - terminated_at string (date-time)
  - terminated_from string (date-time)
    The first month no longer committed, for an ended commitment.
  - terminated_by string
  - clawback_usd number
    The early-termination charge.
  - clawback_invoice_id string
  - clawback_invoice_url string (uri)
  - clawback_invoice_pdf_url string (uri)
  - clawback_invoiced_at string (date-time)
  - ending_notice_at string (date-time)
    When the organization was told the term is nearly over.
  - created_at string (date-time)

`400`

The body is not JSON (INVALID_BODY), accepted is not true (TERMS_NOT_ACCEPTED), or ehu is not above zero (INVALID_AMOUNT).

Content type: application/json

Type: Error

error object required
- code string required
  Example: STATEMENT_NOT_FOUND
- message string required
  Example: No statement for that period.
- request_id string

`401`

No API key was sent, or it is unknown, revoked or expired (UNAUTHORIZED).

Content type: application/json

Type: Error

error object required
- code string required
  Example: STATEMENT_NOT_FOUND
- message string required
  Example: No statement for that period.
- request_id string

`403`

The key lacks the scope this endpoint needs (FORBIDDEN).

Content type: application/json

Type: Error

error object required
- code string required
  Example: STATEMENT_NOT_FOUND
- message string required
  Example: No statement for that period.
- request_id string

`409`

Commitments are not being offered (TERMS_UNAVAILABLE), the terms changed since the version you sent (TERMS_CHANGED), the new volume is not larger than the running one (NOT_AN_INCREASE), or a commitment is already running (COMMITMENT_EXISTS).

Content type: application/json

Type: Error

error object required
- code string required
  Example: STATEMENT_NOT_FOUND
- message string required
  Example: No statement for that period.
- request_id string

`429`

Too many requests (RATE_LIMITED). Wait for Retry-After seconds.

Headers

Retry-After integer
Seconds to wait before retrying.

Content type: application/json

Type: Error

error object required
- code string required
  Example: STATEMENT_NOT_FOUND
- message string required
  Example: No statement for that period.
- request_id string

`500`

The commitment could not be recorded (COMMITMENT_FAILED). Retry later.

Content type: application/json

Type: Error

error object required
- code string required
  Example: STATEMENT_NOT_FOUND
- message string required
  Example: No statement for that period.
- request_id string

Example request

curl -X POST 'https://evohub.io/api/v1/billing/commitment' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <TOKEN>' \
  -d '{
  "ehu": 5000,
  "accepted": true,
  "terms_version": 1
}'