Get Billing History

This endpoint allows you to check a group's billing plan history.

Date Range Required: This endpoint requires both billing_from and billing_to parameters in Unix timestamp format. Use recursive=1 to include billing history for all subgroups.

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 ID of the group you want the billing history for.
`billing_from`	✅	`{TimeStamp}`	The start date you wish to query in unix format.
`billing_to`	✅	`{TimeStamp}`	The end date you wish to query in unix format.
`recursive`	✅	`{integer}`	Provide '1' to get the billing history for all subgroups recursively.

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/history' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'api_key=<API_KEY>' \
  --data-urlencode 'group_id=<GROUP_ID>'

Sample Request

POST https://api-app.xtracta.com/v1/billings/history HTTP/1.1
api_key=123&group_id=456789

Sample Response

<?xml version="1.0" encoding="UTF-8"?>
<billings_response>
   <status>200</status>
   <message>The request has been successfully processed</message>
   <plans>
      <activity>
         <id>0123</id>
         <plan>Xtracta Default Plan - Free - 50 Docs</plan>
         <plan_type>Monthly</plan_type>
         <price>0</price>
         <credit_amount>0</credit_amount>
         <price_currency>NZD</price_currency>
         <allowed_documents>50</allowed_documents>
         <used_documents>8</used_documents>
         <plan_activity>signup</plan_activity>
         <start_date>2017-08-21T02:16:49+00:00</start_date>
         <expiry_date>2017-09-21T02:16:48+00:00</expiry_date>
         <group_name>Bob The Builders</group_name>
         <group_id>123456</group_id>
      </activity>
   </plans>
</billings_response>

Schema Definition

Response Elements

Element	Description
`<status>`	A status code in response to the operation.
`<message>`	Additional information about the operation – human readable.
`<plans>`	List all the plans.
`<id>`
`<plan>`
`<plan_type>`	Monthly or annual.
`<price>`
`<credit_amount>`
`<price_currency>`
`<allowed_documents>`
`<used_documents>`
`<plan_activity>`
`<start_date>`
`<expiry_date>`
`<group_name>`
`<group_id>`

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
  <xs:complexType name="PlanActivityType">
    <xs:sequence>
      <xs:element name="id" type="xs:positiveInteger"/>
      <xs:element name="plan" type="xs:string"/>
      <xs:element name="plan_type" type="xs:string"/>
      <xs:element name="price" type="xs:decimal"/>
      <xs:element name="credit_amount" type="xs:decimal"/>
      <xs:element name="price_currency" type="xs:string"/>
      <xs:element name="allowed_documents" type="xs:nonNegativeInteger"/>
      <xs:element name="used_documents" type="xs:nonNegativeInteger"/>
      <xs:element name="plan_activity" type="xs:string"/>
      <xs:element name="start_date" type="xs:string"/>
      <xs:element name="expiry_date" type="xs:string"/>
      <xs:element name="group_name" type="xs:string"/>
      <xs:element name="group_id" type="xs:positiveInteger"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="PackActivityType">
    <xs:sequence>
      <xs:element name="id" type="xs:positiveInteger"/>
      <xs:element name="pack" type="xs:string"/>
      <xs:element name="price" type="xs:decimal"/>
      <xs:element name="price_currency" type="xs:string"/>
      <xs:element name="allowed_documents" type="xs:nonNegativeInteger"/>
      <xs:element name="used_documents" type="xs:nonNegativeInteger"/>
      <xs:element name="start_date" type="xs:string"/>
      <xs:element name="expiry_date" type="xs:string"/>
      <xs:element name="group_name" type="xs:string"/>
      <xs:element name="group_id" type="xs:positiveInteger"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="PlansType">
    <xs:sequence>
      <xs:element name="activity" type="PlanActivityType" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="PacksType">
    <xs:sequence>
      <xs:element name="activity" type="PackActivityType" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>

  <xs:element name="billings_response">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="status" type="xs:positiveInteger"/>
        <xs:element name="message" type="xs:string"/>
        <xs:element name="plans" type="PlansType" minOccurs="0"/>
        <xs:element name="packs" type="PacksType" 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`	<parameter> must be natural number	`group_id`, `billing_from`, `billing_to`, and `recursive` must use supported integer values.
`400`	timezone must be one of the values of [...]	Use a supported IANA timezone identifier.
`404`	No Billing history found	No accessible billing activity matched the group and time window.
`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.