Get Plans
This endpoint will return a list of billing plans and packs that are available for the selected group. Details of each plan and pack will be returned also.
Plans vs Packs: Plans are recurring billing subscriptions (monthly/annual) that provide a base allocation of documents. Packs are one-time purchases that add additional document capacity to your existing plan.
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 you wish to get the usage details for. If not submitted then the group of the API key will be used. | |
plan_id | {integer} | Get information about a specific plan id | |
pack_id | {integer} | Get information about a specific pack id | |
is_parent | {integer} | Filter plans based on parent/child group relationships |
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' \ --header 'Accept: application/json' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'api_key=<API_KEY>'
Sample Request
POST https://api-app.xtracta.com/v1/billings HTTP/1.1 api_key=123
Sample Response
<?xml version="1.0" encoding="UTF-8"?>
<billings_response>
<status>200</status>
<message>The request has been successfully processed</message>
<plan>
<id>1</id>
<plan_name>Plan A</plan_name>
<plan_type>Monthly</plan_type>
<allowed_documents>250</allowed_documents>
<group_id>481</group_id>
<price>155</price>
<currency>NZD</currency>
<wholesale_price>15</wholesale_price>
</plan>
<plan>
<id>2</id>
<plan_name>Plan B</plan_name>
<plan_type>Monthly</plan_type>
<allowed_documents>500</allowed_documents>
<group_id>481</group_id>
<price>195</price>
<currency>NZD</currency>
<wholesale_price>30</wholesale_price>
</plan>
<plan>
<id>3</id>
<plan_name>Plan C</plan_name>
<plan_type>Monthly</plan_type>
<allowed_documents>1000</allowed_documents>
<group_id>481</group_id>
<price>250</price>
<currency>NZD</currency>
<wholesale_price>50</wholesale_price>
</plan>
<plan>
<id>4</id>
<plan_name>Plan D</plan_name>
<plan_type>Monthly</plan_type>
<allowed_documents>5000</allowed_documents>
<group_id>481</group_id>
<price>450</price>
<currency>NZD</currency>
<wholesale_price>100</wholesale_price>
</plan>
<pack>
<id>1</id>
<pack_name>Booster 100</pack_name>
<allowed_documents>100</allowed_documents>
<group_id>481</group_id>
<price>195</price>
<wholesale_price>30</wholesale_price>
</pack>
</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 |
<plan> | Container for billing plan information (can appear multiple times) |
<plan>→<id> | The unique ID of the billing plan |
<plan>→<plan_name> | The name of the billing plan |
<plan>→<plan_type> | The type of plan (e.g., Monthly, Annual) |
<plan>→<allowed_documents> | The number of documents allowed in this plan |
<plan>→<group_id> | The ID of the group this plan is associated with |
<plan>→<price> | The retail price of the plan |
<plan>→<wholesale_price> | The wholesale price of the plan (for resellers) |
<pack> | Container for booster pack information (can appear multiple times) |
<pack>→<id> | The unique ID of the booster pack |
<pack>→<pack_name> | The name of the booster pack |
<pack>→<allowed_documents> | The number of additional documents provided by this pack |
<pack>→<group_id> | The ID of the group this pack is associated with |
<pack>→<price> | The retail price of the pack |
<pack>→<wholesale_price> | The wholesale price of the pack (for resellers) |
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
<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="group_id" type="xs:positiveInteger" minOccurs="0"/>
<xs:element name="price" type="xs:decimal"/>
<xs:element name="currency" type="xs:string"/>
<xs:element name="status" type="xs:string" minOccurs="0"/>
<xs:element name="wholesale_price" type="xs:decimal" minOccurs="0"/>
<xs:element name="credit_amount" type="xs:decimal" minOccurs="0"/>
<xs:element name="nett_total" type="xs:decimal" minOccurs="0"/>
<xs:element name="gst_total" type="xs:decimal" minOccurs="0"/>
<xs:element name="gross_total" type="xs:decimal" minOccurs="0"/>
<xs:element name="action" type="xs:string" minOccurs="0"/>
<xs:element name="expiry_date" type="xs:string" minOccurs="0"/>
<xs:element name="plan_period" type="xs:string" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="PackType">
<xs:sequence>
<xs:element name="id" type="xs:positiveInteger"/>
<xs:choice>
<xs:element name="pack_name" type="xs:string"/>
<xs:element name="plan_name" type="xs:string"/>
</xs:choice>
<xs:element name="expiry_period" type="xs:string" minOccurs="0"/>
<xs:element name="allowed_documents" type="xs:nonNegativeInteger"/>
<xs:element name="group_id" type="xs:positiveInteger" minOccurs="0"/>
<xs:element name="price" type="xs:decimal"/>
<xs:element name="wholesale_price" type="xs:decimal" minOccurs="0"/>
</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="plan" type="PlanType" minOccurs="0" maxOccurs="unbounded"/>
<xs:element name="pack" type="PackType" minOccurs="0" maxOccurs="unbounded"/>
</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, plan_id, and pack_id must use positive integer values. |
400 | is_parent must be '0' or '1' | Use 0 or 1. |
400 | No Group Id or Plan Id or Pack Id is provided | Supply a group, plan, or pack selector when the API key has no default group. |
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.