/** * AdvancedBilling * * This file was automatically generated for Maxio by APIMATIC v3.0 ( https://www.apimatic.io ). */ import { ApiResponse, RequestOptions } from '../core'; import { BasicDateField } from '../models/basicDateField'; import { CreateMetadataRequest } from '../models/createMetadataRequest'; import { CreateMetafieldsRequest } from '../models/createMetafieldsRequest'; import { ListMetafieldsResponse } from '../models/listMetafieldsResponse'; import { Metadata } from '../models/metadata'; import { Metafield } from '../models/metafield'; import { PaginatedMetadata } from '../models/paginatedMetadata'; import { ResourceType } from '../models/resourceType'; import { SortingDirection } from '../models/sortingDirection'; import { UpdateMetadataRequest } from '../models/updateMetadataRequest'; import { UpdateMetafieldsRequest } from '../models/updateMetafieldsRequest'; import { BaseController } from './baseController'; export declare class CustomFieldsController extends BaseController { /** * ## Custom Fields: Metafield Intro * * **Advanced Billing refers to Custom Fields in the API documentation as metafields and metadata.** * Within the Advanced Billing UI, metadata and metafields are grouped together under the umbrella of * "Custom Fields." All of our UI-based documentation that references custom fields will not cite the * terminology metafields or metadata. * * + **Metafield is the custom field** * + **Metadata is the data populating the custom field.** * * Advanced Billing Metafields are used to add meaningful attributes to subscription and customer * resources. Full documentation on how to create Custom Fields in the Advanced Billing UI can be * located [here](https://maxio.zendesk.com/hc/en-us/sections/24266118312589-Custom-Fields). For * additional documentation on how to record data within custom fields, please see our subscription- * based documentation [here](https://maxio.zendesk.com/hc/en-us/articles/24251701302925-Subscription- * Summary-Custom-Fields-Tab). * * Metafield are the place where you will set up your resource to accept additional data. It is scoped * to the site instead of a specific customer or subscription. Think of it as the key, and Metadata as * the value on every record. * * ## Create Metafields * * Use this endpoint to create metafields for your Site. Metafields can be populated with metadata * after the fact. * * Each site is limited to 100 unique Metafields (i.e. keys, or names) per resource. This means you can * have 100 Metafields for Subscription and another 100 for Customer. * * ### Metafields "On-the-Fly" * * It is possible to create Metafields “on the fly” when you create your Metadata – if a non-existant * name is passed when creating Metadata, a Metafield for that key will be automatically created. The * Metafield API, however, gives you more control over your “keys”. * * ### Metafield Scope Warning * * If configuring metafields in the Admin UI or via the API, be careful sending updates to metafields * with the scope attribute – **if a partial update is sent it will overwrite the current * configuration**. * * @param resourceType the resource type to which the metafields belong * @param body * @return Response from the API call */ createMetafields(resourceType: ResourceType, body?: CreateMetafieldsRequest, requestOptions?: RequestOptions): Promise>; /** * This endpoint lists metafields associated with a site. The metafield description and usage is * contained in the response. * * @param resourceType the resource type to which the metafields belong * @param name filter by the name of the metafield * @param page Result records are organized in pages. By default, the first page of * results is displayed. The page parameter specifies a page number of * results to fetch. You can start navigating through the pages to consume * the results. You do this by passing in a page parameter. Retrieve the * next page by adding ?page=2 to the query string. If there are no results * to return, then an empty result set will be returned. Use in query * `page=1`. * @param perPage This parameter indicates how many records to fetch in each request. * Default value is 20. The maximum allowed values is 200; any per_page * value over 200 will be changed to 200. Use in query `per_page=200`. * @param direction Controls the order in which results are returned. Use in query * `direction=asc`. * @return Response from the API call */ listMetafields({ resourceType, name, page, perPage, direction, }: { resourceType: ResourceType; name?: string; page?: number; perPage?: number; direction?: SortingDirection; }, requestOptions?: RequestOptions): Promise>; /** * Use the following method to update metafields for your Site. Metafields can be populated with * metadata after the fact. * * @param resourceType the resource type to which the metafields belong * @param body * @return Response from the API call */ updateMetafield(resourceType: ResourceType, body?: UpdateMetafieldsRequest, requestOptions?: RequestOptions): Promise>; /** * Use the following method to delete a metafield. This will remove the metafield from the Site. * * Additionally, this will remove the metafield and associated metadata with all Subscriptions on the * Site. * * @param resourceType the resource type to which the metafields belong * @param name The name of the metafield to be deleted * @return Response from the API call */ deleteMetafield(resourceType: ResourceType, name?: string, requestOptions?: RequestOptions): Promise>; /** * ## Custom Fields: Metadata Intro * * **Advanced Billing refers to Custom Fields in the API documentation as metafields and metadata.** * Within the Advanced Billing UI, metadata and metafields are grouped together under the umbrella of * "Custom Fields." All of our UI-based documentation that references custom fields will not cite the * terminology metafields or metadata. * * + **Metafield is the custom field** * + **Metadata is the data populating the custom field.** * * Advanced Billing Metafields are used to add meaningful attributes to subscription and customer * resources. Full documentation on how to create Custom Fields in the Advanced Billing UI can be * located [here](https://maxio.zendesk.com/hc/en-us/articles/24266164865677-Custom-Fields-Overview). * For additional documentation on how to record data within custom fields, please see our subscription- * based documentation [here.](https://maxio.zendesk.com/hc/en-us/articles/24251701302925-Subscription- * Summary-Custom-Fields-Tab) * * Metadata is associated to a customer or subscription, and corresponds to a Metafield. When creating * a new metadata object for a given record, **if the metafield is not present it will be created**. * * ## Metadata limits * * Metadata values are limited to 2kB in size. Additonally, there are limits on the number of unique * metafields available per resource. * * ## Create Metadata * * This method will create a metafield for the site on the fly if it does not already exist, and * populate the metadata value. * * ### Subscription or Customer Resource * * Please pay special attention to the resource you use when creating metadata. * * @param resourceType the resource type to which the metafields belong * @param resourceId The Advanced Billing id of the customer or the subscription * for which the metadata applies * @param body * @return Response from the API call */ createMetadata(resourceType: ResourceType, resourceId: number, body?: CreateMetadataRequest, requestOptions?: RequestOptions): Promise>; /** * This request will list all of the metadata belonging to a particular resource (ie. subscription, * customer) that is specified. * * ## Metadata Data * * This endpoint will also display the current stats of your metadata to use as a tool for pagination. * * @param resourceType the resource type to which the metafields belong * @param resourceId The Advanced Billing id of the customer or the subscription for which the * metadata applies * @param page Result records are organized in pages. By default, the first page of results * is displayed. The page parameter specifies a page number of results to fetch. * You can start navigating through the pages to consume the results. You do * this by passing in a page parameter. Retrieve the next page by adding ?page=2 * to the query string. If there are no results to return, then an empty result * set will be returned. Use in query `page=1`. * @param perPage This parameter indicates how many records to fetch in each request. Default * value is 20. The maximum allowed values is 200; any per_page value over 200 * will be changed to 200. Use in query `per_page=200`. * @return Response from the API call */ listMetadata({ resourceType, resourceId, page, perPage, }: { resourceType: ResourceType; resourceId: number; page?: number; perPage?: number; }, requestOptions?: RequestOptions): Promise>; /** * This method allows you to update the existing metadata associated with a subscription or customer. * * @param resourceType the resource type to which the metafields belong * @param resourceId The Advanced Billing id of the customer or the subscription * for which the metadata applies * @param body * @return Response from the API call */ updateMetadata(resourceType: ResourceType, resourceId: number, body?: UpdateMetadataRequest, requestOptions?: RequestOptions): Promise>; /** * This method removes the metadata from the subscriber/customer cited. * * ## Query String Usage * * For instance if you wanted to delete the metadata for customer 99 named weight you would request: * * ``` * https://acme.chargify.com/customers/99/metadata.json?name=weight * ``` * * If you want to delete multiple metadata fields for a customer 99 named: `weight` and `age` you * wrould request: * ``` * https://acme.chargify.com/customers/99/metadata.json?names[]=weight&names[]=age * ``` * * ## Successful Response * * For a success, there will be a code `200` and the plain text response `true`. * * ## Unsuccessful Response * * When a failed response is encountered, you will receive a `404` response and the plain text response * of `true`. * * @param resourceType the resource type to which the metafields belong * @param resourceId The Advanced Billing id of the customer or the subscription for which the * metadata applies * @param name Name of field to be removed. * @param names Names of fields to be removed. Use in query: `names[]=field1&names[]=my- * field&names[]=another-field`. * @return Response from the API call */ deleteMetadata(resourceType: ResourceType, resourceId: number, name?: string, names?: string[], requestOptions?: RequestOptions): Promise>; /** * This method will provide you information on usage of metadata across your selected resource (ie. * subscriptions, customers) * * ## Metadata Data * * This endpoint will also display the current stats of your metadata to use as a tool for pagination. * * ### Metadata for multiple records * * `https://acme.chargify.com/subscriptions/metadata.json?resource_ids[]=1&resource_ids[]=2` * * ## Read Metadata for a Site * * This endpoint will list the number of pages of metadata information that are contained within a site. * * @param resourceType the resource type to which the metafields belong * @param page Result records are organized in pages. By default, the first page of * results is displayed. The page parameter specifies a page number of * results to fetch. You can start navigating through the pages to consume * the results. You do this by passing in a page parameter. Retrieve the * next page by adding ?page=2 to the query string. If there are no results * to return, then an empty result set will be returned. Use in query * `page=1`. * @param perPage This parameter indicates how many records to fetch in each request. * Default value is 20. The maximum allowed values is 200; any per_page * value over 200 will be changed to 200. Use in query `per_page=200`. * @param dateField The type of filter you would like to apply to your search. * @param startDate The start date (format YYYY-MM-DD) with which to filter the date_field. * Returns metadata with a timestamp at or after midnight (12:00:00 AM) in * your site’s time zone on the date specified. * @param endDate The end date (format YYYY-MM-DD) with which to filter the date_field. * Returns metadata with a timestamp up to and including 11:59:59PM in your * site’s time zone on the date specified. * @param startDatetime The start date and time (format YYYY-MM-DD HH:MM:SS) with which to * filter the date_field. Returns metadata with a timestamp at or after * exact time provided in query. You can specify timezone in query - * otherwise your site's time zone will be used. If provided, this * parameter will be used instead of start_date. * @param endDatetime The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter * the date_field. Returns metadata with a timestamp at or before exact * time provided in query. You can specify timezone in query - otherwise * your site's time zone will be used. If provided, this parameter will be * used instead of end_date. * @param withDeleted Allow to fetch deleted metadata. * @param resourceIds Allow to fetch metadata for multiple records based on provided ids. Use * in query: `resource_ids[]=122&resource_ids[]=123&resource_ids[]=124`. * @param direction Controls the order in which results are returned. Use in query * `direction=asc`. * @return Response from the API call */ listMetadataForResourceType({ resourceType, page, perPage, dateField, startDate, endDate, startDatetime, endDatetime, withDeleted, resourceIds, direction, }: { resourceType: ResourceType; page?: number; perPage?: number; dateField?: BasicDateField; startDate?: string; endDate?: string; startDatetime?: string; endDatetime?: string; withDeleted?: boolean; resourceIds?: number[]; direction?: SortingDirection; }, requestOptions?: RequestOptions): Promise>; }