Package: maxio-advanced-billing-sdk
Getting Started with Maxio Advanced BillingIntroductionIntroductionAPI IntegrationMaxio Advanced Billing (formerly Chargify API) can be integrated with many environments and programming languages via our REST API. Some of our users have contributed their API wrappers in various programming languages. Check out theAPI Code Overviewdoc for an introduction to the wrappers and available code samples.Testing GuideMaxio Advanced Billing has compiled atesting guidethat covers a list of important factors to consider while in the testing phase. Here's a high-level overiew of what's covered in our testing guide:Test credit card basicsTest site limitsLive mode versus test modeWe strongly suggest reading over the testing guide, as well as the entire set of application-based documentation to aid in your discovery of the product.Engage SupportWe always enjoy (and appreciate) hearing about larger integrations ahead of time. If you’re planning on importing a large amount of data into Maxio via our API, we suggest sending a “heads up” to “support@chargify.com” so we can coordinate with you to ensure your import process goes smoothly.Our API, while considered stable, is continually being improved and polished. Please feel free to contact support if you experience issues when integrating with the Maxio Advanced Billing API.If you have any additional questions regarding our documentation please don't hesitate in reaching out.Support AccessAccess to our Technical Specialist team for API support is currently limited to purchasers of our larger Maxio support plans.But don’t worry! There are quite a few options to help you get the answers you need:Read our documentation for developersExplore the endpoints of our API DocumentationWatch our videos and tutorialsCheck out the Chargify tag on Stack OverflowAPI OverviewThe Chargify API allows you to interact with our system programmatically from your own application. Using the API you interact with Resources such as:ProductsSubscriptionsCustomersetc.The API attempts to conform to theRESTfuldesign principles.
You interact with the resources exposed via the API by accessing resource collection and element URIs using the HTTP verbs (GET, POST, PUT, and DELETE).
Chargify accepts and returns both JSON and XML data via the API.You’ll likely need access to a web developer or programmer (if you’re not one) to get the most use out of the API.Available Formats: JSON and XMLJSON is the primary and recommended format for use with the Chargify API.  XML is also provided as a backwards compatible option for Merchants who require it.AuthenticationAuthentication is implemented as HTTP Basic Authentication over TLS >= 1.2 (HTTPS), as described inAPI AuthenticationURLThe URL for API requests includes the subdomain of the Site you are working with:https://<subdomain>.chargify.com/<resource URI>Response DataResponse data is sent as either XML or JSON, depending on the type of data requested (HTTP Content-Typeheader) or the type specified as being accepted (HTTPAcceptheader).GETs for individual statements & invoices may also be requested as PDF usingapplication/pdfor appending.pdfto the resource URI.Response codes are sent via the normal HTTP Response Code, and are documented separately for each resource.For boolean fields, please note that a value ofnullmay be considered as false. However, this is not true across all cases. Please excercise good judgement here, or contact support with any questions.For example:nullcan define that there's no data available for that attributePaginationWhen an endpoint returns a list of items, it will be paginated.  Usually, 20 items will be returned by default, and you may request up to a maximum of 200 at a time.  Pagination is done with query string parameters, for example:?page=5&per_page=200Response Time ZonesAPI responses from Chargify are sent with the timezone of current Chargify site.Alternately, webhooks sent from Chargify globally utilize EST as the timezone for all content in the body of the payload.Request DataPOST and PUT request data may be formatted as either XML (application/xml) or JSON (application/json). For best results, you should set your HTTPContent-Typerequest header accordingly, although you may also specify your format by appending.xmlor.jsonextensions on to the resource URI.Note that Chargify does not accept PUT or POST data sent as query params or form encoded data – data must be sent as either XML or JSON. If you fail to set yourContent-Typeto eitherapplication/xmlorapplication/json, your request may fail due to triggering of forgery protection mechanisms.About Decimal NumbersIn order to prevent losing precision, we serialize decimal numbers as strings instead of as JSON numbers.We recommend parsing these strings into their decimal equivalent using a decimal number library in your programming language (i.e.BigDecimalin Ruby) instead of relying on floating point values or arithmetic.About Amount FieldsFields holding amount values are given as a string representing a decimal whole currency amount.For example,"1.23"in currency"USD"would equate to$1.23.Not all fields will be rounded to the smallest currency denomination.  Intermediate results, such as those that derive from line-level tax calculations, may hold precision up to 8 decimal places.  However, the top-level totals we provide (e.g.total_amount) will be rounded to the smallest currency denomination.It is up to API consumers to parse the string into a decimal number representation and do any rounding necessary for your application.DebuggingIf you’re having difficulty executing a request via our API, try the simplest thing and attempt your request via the curl command-line tool, as shown in the below example. Add the--verboseflag to your request to receive even more debugging information.Another handy tool isBeeceptor. You can use this to intercept your request to see exactly what is being sent.If you are unable to connect at all, check that you are using TLS 1.2 or better.If you see a "Could not resolve host" error, double check that the url is correct, including your subdomain. For example:mysite.chargify.com.  This error means your DNS server could not find an IP address for the domain you are trying to connect to.Backwards CompatibilityWe consider the following changes to be backwards compatible and may make them without advance notice:Adding new API endpoints, or adding new attributes in the responses of existing endpointsAdding new optional parameters to be sent to existing API endpointsAdding new fields to exported dataChanging the type or length of any of the ID attributesFor example, most IDs are currently integers, but you should not assume that this will always be the case.In addition, you should not depend on the order of attributes within the API response as this may change.Chargify does not provide notifications for additions that are clearly defined as backwards compatible.ExamplesThe following examples use the curl command-line tool to execute API requests.Subscription ListingRequestcurl -u <api_key>:x -H Accept:application/json -H Content-Type:application/jsonhttps://acme.chargify.com/subscriptions.jsonAPI Access LimitationsThere are a few scenarios that may end up in causing an API request to be blocked even with correct credentials.Please note:All relevant API requests will be blocked if any of the below conditions are true. These limitations also apply toChargify Direct.Those scenarios are as follows:Your Chargify subscription is canceled.Your Chargify trial has reached an end.The site you're making a request for is in the process of"clearing site data"Note: any API request for another site that is in a good state will NOT be blockedThe site you're making a request for has been deleted.Note: any API request for another site that is in a good state will NOT be blockedRead more about your Chargify subscriptionhereWhat happens when an API request is blockedThe request will fail with a422http status code. The response will also include a message explaining the reason for the request being blocked. For example:If your Chargify subscription is canceled:{"errors"=>[[0]"Your Chargify account has been canceled. Please contact support@chargify.com to reactivate."]}If your Chargify trial has reached and end and you attempted to make an API request, the response body will look like:{"errors"=>[[0]"Your trial has ended, please contact sales."]}If the site you're making a request for is in the process of"clearing site data":{"errors"=>[[0]"Site data clearing is in progress. Please try later."]}If the site you're making a request for has been deleted:{"errors"=>[[0]"This site has been deleted."]}Secure ApplicationsPlease note that it is NOT possible to make API requests directly from the customer's browser or device.  Doing so would expose your API key on the client side, and anyone who has that key has full access to all of your Chargify data.Instead you will need to take care to tokenize sensitive information by usingChargify.jsor a similar JavaScript library provided by your gateway, and then post the token and other information to your own server, from which you can make the API call to Chargify.TroubleshootingIf you attempt to make a Chargify API request directly from the customer's browser, you may see an error such as:Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource.orOrigin 'https://example.com' is therefore not allowed access.` `The response had HTTP status code 404.This is an error message indicating that Cross-Origin Resource Sharing (CORS) is not enabled on the Chargify server.Relationship InvoicingAPI Compatibility for Relationship InvoicingThis section describes the API for the new,Relationship Invoicingstyle of invoices introduced in January 2018.If you are an existing customer from prior to January 2018 or have not otherwise explicitly opted into this new style of invoices, you are probably looking for the legacy "Invoices" section that describesinvoice-billing legacy-style invoices.These new invoices provide a single representation of all of your Chargify billing, whether you collect automatically or via remittance.About Decimal NumbersIn order to prevent losing precision, we serialize decimal numbers as strings instead of as JSON numbers.We recommend parsing these strings into their decimal equivalent using a decimal number library in your programming language (i.e.BigDecimalin Ruby) instead of relying on floating point values or arithmetic.About Amount FieldsFields holding amount values are given as a string representing a decimal whole currency amount.For example,"1.23"in currency"USD"would equate to$1.23.Not all fields will be rounded to the smallest currency denomination. Intermediate results, such as those that derive from line-level tax calculations, may hold precision up to 8 decimal places.  However, the top-level totals we provide (e.g.total_amount) will be rounded to the smallest currency denomination.It is up to API consumers to parse the string into a decimal number representation and do any rounding necessary for your application.Relationship Invoicing SummaryIf your siteisusing relationship invoicing, you may only use the methods described in this section for working with invoices.If your site isnotusing relationship invoicing, please use the legacy invoice methods:InvoicesInvoices: PaymentsInvoices: ChargesInvoices: CreditsInstall the PackageThe package is compatible with Python versions3 >=3.7, <= 3.11.
Install the package from PyPi using the following pip command:pipinstallmaxio-advanced-billing-sdk==1.0.0You can also view the package at:https://pypi.python.org/pypi/maxio-advanced-billing-sdk/1.0.0Initialize the API ClientNote:Documentation for the client can be foundhere.The following parameters are configurable for the API Client:ParameterTypeDescriptionsubdomainstrThe subdomain for your Chargify site.Default:'subdomain'domainstrThe Chargify server domain.Default:'chargify.com'environmentEnvironmentThe API environment.Default:Environment.PRODUCTIONhttp_client_instanceHttpClientThe Http Client passed from the sdk user for making requestsoverride_http_client_configurationboolThe value which determines to override properties of the passed Http Client from the sdk userhttp_call_backHttpCallBackThe callback value that is invoked before and after an HTTP call is made to an endpointtimeoutfloatThe value to use for connection timeout.Default: 30max_retriesintThe number of times to retry an endpoint call if it fails.Default: 0backoff_factorfloatA backoff factor to apply between attempts after the second try.Default: 2retry_statusesArray of intThe http statuses on which retry is to be done.Default: [408, 413, 429, 500, 502, 503, 504, 521, 522, 524]retry_methodsArray of stringThe http methods on which retry is to be done.Default: ['GET', 'PUT']basic_auth_user_namestrThe username to use with basic authenticationbasic_auth_passwordstrThe password to use with basic authenticationThe API client can be initialized as follows:fromadvancedbilling.advanced_billing_clientimportAdvancedBillingClientfromadvancedbilling.configurationimportEnvironmentclient=AdvancedBillingClient(basic_auth_user_name='BasicAuthUserName',basic_auth_password='BasicAuthPassword')EnvironmentsThe SDK can be configured to use a different environment for making API calls. Available environments are:FieldsNameDescriptionproductionDefaultProduction serverenvironment2Production serverAuthorizationThis API usesBasic Authentication.List of APIsAPI ExportsAdvance InvoiceBilling PortalCustom FieldsEvents-Based Billing SegmentsPayment ProfilesProduct FamiliesProduct Price PointsProforma InvoicesReason CodesReferral CodesSales CommissionsSubscription ComponentsSubscription GroupsSubscription Group Invoice AccountSubscription Group StatusSubscription Invoice AccountSubscription NotesSubscription ProductsSubscription StatusCouponsComponentsCustomersEventsInsightsInvoicesOffersProductsSitesSubscriptionsWebhooksClasses DocumentationUtility ClassesHttpResponseHttpRequest