Renew/Upgrade/Downgrade Plan

This endpoint adds/renews/upgrades/downgrades the billing plans associated with a group. All documents processed in that group will count towards the selected billing plan regardless of the number of workflows being used.

Document Processing Impact: When upgrading/downgrading plans, use the purge parameter to decide what happens to documents that were on hold due to processing limits. Choose process to release them or delete to remove them permanently.

POST Parameters

Parameter	Required	Value	Description
`api_key`	✅	`{key}`	An API key that has access to the resource you want to query for
`group_id`		`{integer}`	The group that the billing plan is to be applied to. Required if applying the plan to a sub-group.
`plan_id`	✅	`{integer}`	The plan to be applied to the group.
`purge`	⚠️	`- delete - process`	Decide what to do with the documents placed on hold due to the processing limit being met as they can be released as part of renewal/upgrade.

Code Examples

The cURL, PHP, Python, Node.js, and C# examples call Xtracta from a trusted server. The React example calls an application-defined backend proxy so the API key is never exposed in browser code.

Store XTRACTA_API_KEY as a server-side environment variable. Never embed it in browser-delivered code.

curl --request POST 'https://api-app.xtracta.com/v1/billings/update' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'api_key=<API_KEY>' \
  --data-urlencode 'group_id=<GROUP_ID>' \
  --data-urlencode 'plan_id=<PLAN_ID>'

Sample Request

POST https://api-app.xtracta.com/v1/billings/update HTTP/1.1
api_key=123&group_id=123&plan_id=111

Sample Response

<?xml version="1.0" encoding="UTF-8"?>
<billings_response>
	<status>200</status>
	<message>The new billing plan is assigned successfully</message>
	<plan>
		<id>1111</id>
		<plan_name>Test Plan</plan_name>
		<plan_type>Monthly</plan_type>
		<allowed_documents>1000</allowed_documents>
		<used_documents>0</used_documents>
		<price>500</price>
		<start_date>2018-03-27T01:11:18+00:00</start_date>
		<expiry_date>2018-04-27T02:11:17+00:00</expiry_date>
	</plan>
</billings_response>

Schema Definition

Response Elements

Element	Description
`<status>`	An integer (200) as to whether the operation succeeded.
`<message>`	Additional information about the operation. If the `<result>` was false this will provide brief information about the `<error_code>` as well as additional supplemental information about the specific query.
`<id>`	Plan id used.
`<plan_name>`
`<plan_type>`	Monthly or annual.
`<allowed_documents>`	The maximum number of documents allowed to be processed during the “plan_type”.
`<used_documents>`	The number of documents used at the time of the request.
`<price>`
`<start_date>`
`<expiry_date>`

Example

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">

  <xs:simpleType name="ConfidenceType">
    <xs:union>
      <xs:simpleType>
        <xs:restriction base="xs:integer">
          <xs:minInclusive value="0"/>
          <xs:maxInclusive value="100"/>
        </xs:restriction>
      </xs:simpleType>
      <xs:simpleType>
        <xs:restriction base="xs:string">
          <xs:enumeration value=""/>
        </xs:restriction>
      </xs:simpleType>
    </xs:union>
  </xs:simpleType>

  <xs:complexType name="PlanType">
    <xs:sequence>
      <xs:element name="id" type="xs:positiveInteger"/>
      <xs:element name="plan_name" type="xs:string"/>
      <xs:element name="plan_type" type="xs:string"/>
      <xs:element name="allowed_documents" type="xs:nonNegativeInteger"/>
      <xs:element name="used_documents" type="xs:nonNegativeInteger"/>
      <xs:element name="price" type="xs:decimal"/>
      <xs:element name="start_date" type="xs:string"/>
      <xs:element name="expiry_date" type="xs:string"/>
    </xs:sequence>
  </xs:complexType>

  <xs:element name="billings_response">
    <xs:complexType>
      <xs:sequence>
      <xs:element name="status" type="xs:positiveInteger" minOccurs="0"/>
      <xs:element name="message" type="xs:string"/>
      <xs:element name="plan" type="PlanType" minOccurs="0"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

</xs:schema>

Error Responses

For JSON and XML responses generated by this endpoint, the response is wrapped in billings_response and includes the HTTP status code and a message.

Status	Message	Description
`400`	plan_id must be natural number / group_id must be natural number	Use positive integer plan and group IDs.
`400`	timezone must be one of the values of [...]	Use a supported IANA timezone identifier.
`400`	purge is required	Billing-pending documents exist; choose how they should be handled.
`400`	purge must be one of the values of [delete,process]	Set `purge` to `delete` or `process`.
`500`	Could not update the database	The billing-plan update did not return an updated plan. Contact support if retrying fails.
`500`	Internal server error occurred. Please try again later or contact support@xtracta.com	Retry and contact support with the request parameters and timestamp if it persists.

Authentication, permission, IP-access-control, and rate-limit failures can be returned before this endpoint processes the request. Confirm the API key and caller access first.