Class: AdvancedBilling::CustomFieldsController

Inherits:
BaseController show all
Defined in:
lib/advanced_billing/controllers/custom_fields_controller.rb

Overview

CustomFieldsController

Constant Summary

Constants inherited from BaseController

BaseController::GLOBAL_ERRORS

Instance Attribute Summary

Attributes inherited from BaseController

#config, #http_call_back

Instance Method Summary collapse

Methods inherited from BaseController

#initialize, #new_api_call_builder, #new_parameter, #new_request_builder, #new_response_handler, user_agent, user_agent_parameters

Constructor Details

This class inherits a constructor from AdvancedBilling::BaseController

Instance Method Details

#create_metadata(resource_type, resource_id, value: nil, body: nil) ⇒ Array[Metadata]

## Custom Fields: Metadata Intro **Chargify refers to Custom Fields in the API documentation as metafields and metadata.** Within the Chargify 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.** Chargify Metafields are used to add meaningful attributes to subscription and customer resources. Full documentation on how to create Custom Fields in the Chargify UI can be located [here](chargify.zendesk.com/hc/en-us/articles/4407659856411). For additional documentation on how to record data within custom fields, please see our subscription-based documentation [here.](chargify.zendesk.com/hc/en-us/articles/4407884887835#custo m-fields) 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. to which the metafields belong customer or the subscription for which the metadata applies of metadata

Parameters:

  • resource_type (ResourceType) —

    Required parameter: the resource type

  • resource_id (String) —

    Required parameter: The Chargify id of the

  • value (String) (defaults to: nil) —

    Optional parameter: Can be a single item or a list

  • body (CreateMetadataRequest) (defaults to: nil) —

    Optional parameter: Example:

Returns:

  • (Array[Metadata]) —

    response from the API call.



215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
 
# File 'lib/advanced_billing/controllers/custom_fields_controller.rb', line 215

def create_metadata(resource_type,
                    resource_id,
                    value: nil,
                    body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/{resource_type}/{resource_id}/metadata.json',
                                 Server::DEFAULT)
               .template_param(new_parameter(resource_type, key: 'resource_type')
                                .is_required(true)
                                .should_encode(true))
               .template_param(new_parameter(resource_id, key: 'resource_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .query_param(new_parameter(value, key: 'value'))
               .body_param(new_parameter(body))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(Metadata.method(:from_hash))
                .is_response_array(true))
    .execute
end

#create_metafields(resource_type, body: nil) ⇒ Array[Metafield]

## Custom Fields: Metafield Intro **Chargify refers to Custom Fields in the API documentation as metafields and metadata.** Within the Chargify 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.** Chargify Metafields are used to add meaningful attributes to subscription and customer resources. Full documentation on how to create Custom Fields in the Chargify UI can be located [here](maxio-chargify.zendesk.com/hc/en-us/articles/5405332553613- Custom-Fields-Reference). For additional documentation on how to record data within custom fields, please see our subscription-based documentation [here.](maxio-chargify.zendesk.com/hc/en-us/articles/5404434903181 -Subscription-Summary#custom-fields) 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**. to which the metafields belong

Parameters:

Returns:

  • (Array[Metafield]) —

    response from the API call.



48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/advanced_billing/controllers/custom_fields_controller.rb', line 48

def create_metafields(resource_type,
                      body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/{resource_type}/metafields.json',
                                 Server::DEFAULT)
               .template_param(new_parameter(resource_type, key: 'resource_type')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(Metafield.method(:from_hash))
                .is_response_array(true))
    .execute
end

#delete_metadata(resource_type, resource_id, name: nil, names: nil) ⇒ void

This method returns an undefined value.

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: “‘ 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: “` 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`. to which the metafields belong customer or the subscription for which the metadata applies removed. Use in query: `names[]=field1&names=my-field&names[]=another-field`.

Parameters:

  • resource_type (ResourceType) —

    Required parameter: the resource type

  • resource_id (String) —

    Required parameter: The Chargify id of the

  • name (String) (defaults to: nil) —

    Optional parameter: Name of field to be removed.

  • names (Array[String]) (defaults to: nil) —

    Optional parameter: Names of fields to be



309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
 
# File 'lib/advanced_billing/controllers/custom_fields_controller.rb', line 309

def delete_metadata(resource_type,
                    resource_id,
                    name: nil,
                    names: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::DELETE,
                                 '/{resource_type}/{resource_id}/metadata.json',
                                 Server::DEFAULT)
               .template_param(new_parameter(resource_type, key: 'resource_type')
                                .is_required(true)
                                .should_encode(true))
               .template_param(new_parameter(resource_id, key: 'resource_id')
                                .is_required(true)
                                .should_encode(true))
               .query_param(new_parameter(name, key: 'name'))
               .query_param(new_parameter(names, key: 'names[]'))
               .auth(Single.new('BasicAuth'))
               .array_serialization_format(ArraySerializationFormat::UN_INDEXED))
    .response(new_response_handler
                .is_nullify404(true)
                .is_response_void(true)
                .local_error('404',
                             'Not Found',
                             APIException))
    .execute
end

#delete_metafield(resource_type, name: nil) ⇒ void

This method returns an undefined value.

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. to which the metafields belong deleted

Parameters:

  • resource_type (ResourceType) —

    Required parameter: the resource type

  • name (String) (defaults to: nil) —

    Optional parameter: The name of the metafield to be



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/advanced_billing/controllers/custom_fields_controller.rb', line 79

def delete_metafield(resource_type,
                     name: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::DELETE,
                                 '/{resource_type}/metafields.json',
                                 Server::DEFAULT)
               .template_param(new_parameter(resource_type, key: 'resource_type')
                                .is_required(true)
                                .should_encode(true))
               .query_param(new_parameter(name, key: 'name'))
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .is_nullify404(true)
                .is_response_void(true)
                .local_error('404',
                             'Not Found',
                             APIException))
    .execute
end

#list_metadata(options = {}) ⇒ PaginatedMetadata

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 ‘acme.chargify.com/subscriptions/metadata.json?resource_ids[]=1&re source_ids[]=2` ## Read Metadata for a Site This endpoint will list the number of pages of metadata information that are contained within a site. to which the metafields belong 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`. 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`. you would like to apply to your search. 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. 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. (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. (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. fetch deleted metadata. metadata for multiple records based on provided ids. Use in query: ‘resource_ids[]=122&resource_ids=123&resource_ids[]=124`. order in which results are returned. Use in query `direction=asc`.

Parameters:

  • resource_type (ResourceType) —

    Required parameter: the resource type

  • page (Integer) —

    Optional parameter: Result records are organized in

  • per_page (Integer) —

    Optional parameter: This parameter indicates how

  • date_field (BasicDateField) —

    Optional parameter: The type of filter

  • start_date (String) —

    Optional parameter: The start date (format

  • end_date (String) —

    Optional parameter: The end date (format

  • start_datetime (String) —

    Optional parameter: The start date and time

  • end_datetime (String) —

    Optional parameter: The end date and time

  • with_deleted (TrueClass | FalseClass) —

    Optional parameter: Allow to

  • resource_ids (Array[Integer]) —

    Optional parameter: Allow to fetch

  • direction (SortingDirection | nil) —

    Optional parameter: Controls the

Returns:



388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
 
# File 'lib/advanced_billing/controllers/custom_fields_controller.rb', line 388

def list_metadata(options = {})
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/{resource_type}/metadata.json',
                                 Server::DEFAULT)
               .template_param(new_parameter(options['resource_type'], key: 'resource_type')
                                .is_required(true)
                                .should_encode(true))
               .query_param(new_parameter(options['page'], key: 'page'))
               .query_param(new_parameter(options['per_page'], key: 'per_page'))
               .query_param(new_parameter(options['date_field'], key: 'date_field'))
               .query_param(new_parameter(options['start_date'], key: 'start_date'))
               .query_param(new_parameter(options['end_date'], key: 'end_date'))
               .query_param(new_parameter(options['start_datetime'], key: 'start_datetime'))
               .query_param(new_parameter(options['end_datetime'], key: 'end_datetime'))
               .query_param(new_parameter(options['with_deleted'], key: 'with_deleted'))
               .query_param(new_parameter(options['resource_ids'], key: 'resource_ids[]'))
               .query_param(new_parameter(options['direction'], key: 'direction')
                             .validator(proc do |value|
                               UnionTypeLookUp.get(:ListMetadataInputDirection)
                                              .validate(value)
                             end))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth'))
               .array_serialization_format(ArraySerializationFormat::CSV))
    .response(new_response_handler
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(PaginatedMetadata.method(:from_hash)))
    .execute
end

#list_metafields(options = {}) ⇒ ListMetafieldsResponse

This endpoint lists metafields associated with a site. The metafield description and usage is contained in the response. to which the metafields belong metafield 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`. 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`. order in which results are returned. Use in query `direction=asc`.

Parameters:

  • resource_type (ResourceType) —

    Required parameter: the resource type

  • name (String) —

    Optional parameter: filter by the name of the

  • page (Integer) —

    Optional parameter: Result records are organized in

  • per_page (Integer) —

    Optional parameter: This parameter indicates how

  • direction (SortingDirection | nil) —

    Optional parameter: Controls the

Returns:



440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
 
# File 'lib/advanced_billing/controllers/custom_fields_controller.rb', line 440

def list_metafields(options = {})
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/{resource_type}/metafields.json',
                                 Server::DEFAULT)
               .template_param(new_parameter(options['resource_type'], key: 'resource_type')
                                .is_required(true)
                                .should_encode(true))
               .query_param(new_parameter(options['name'], key: 'name'))
               .query_param(new_parameter(options['page'], key: 'page'))
               .query_param(new_parameter(options['per_page'], key: 'per_page'))
               .query_param(new_parameter(options['direction'], key: 'direction')
                             .validator(proc do |value|
                               UnionTypeLookUp.get(:ListMetafieldsInputDirection)
                                              .validate(value)
                             end))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(ListMetafieldsResponse.method(:from_hash)))
    .execute
end

#read_metadata(options = {}) ⇒ PaginatedMetadata

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. to which the metafields belong customer or the subscription for which the metadata applies 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`. 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`.

Parameters:

  • resource_type (ResourceType) —

    Required parameter: the resource type

  • resource_id (String) —

    Required parameter: The Chargify id of the

  • page (Integer) —

    Optional parameter: Result records are organized in

  • per_page (Integer) —

    Optional parameter: This parameter indicates how

Returns:



120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/advanced_billing/controllers/custom_fields_controller.rb', line 120

def read_metadata(options = {})
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/{resource_type}/{resource_id}/metadata.json',
                                 Server::DEFAULT)
               .template_param(new_parameter(options['resource_type'], key: 'resource_type')
                                .is_required(true)
                                .should_encode(true))
               .template_param(new_parameter(options['resource_id'], key: 'resource_id')
                                .is_required(true)
                                .should_encode(true))
               .query_param(new_parameter(options['page'], key: 'page'))
               .query_param(new_parameter(options['per_page'], key: 'per_page'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(PaginatedMetadata.method(:from_hash)))
    .execute
end

#update_metadata(resource_type, resource_id, value: nil, body: nil) ⇒ Array[Metadata]

This method allows you to update the existing metadata associated with a subscription or customer. to which the metafields belong customer or the subscription for which the metadata applies of metadata

Parameters:

  • resource_type (ResourceType) —

    Required parameter: the resource type

  • resource_id (String) —

    Required parameter: The Chargify id of the

  • value (String) (defaults to: nil) —

    Optional parameter: Can be a single item or a list

  • body (UpdateMetadataRequest) (defaults to: nil) —

    Optional parameter: Example:

Returns:

  • (Array[Metadata]) —

    response from the API call.



253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
 
# File 'lib/advanced_billing/controllers/custom_fields_controller.rb', line 253

def update_metadata(resource_type,
                    resource_id,
                    value: nil,
                    body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::PUT,
                                 '/{resource_type}/{resource_id}/metadata.json',
                                 Server::DEFAULT)
               .template_param(new_parameter(resource_type, key: 'resource_type')
                                .is_required(true)
                                .should_encode(true))
               .template_param(new_parameter(resource_id, key: 'resource_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .query_param(new_parameter(value, key: 'value'))
               .body_param(new_parameter(body))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(Metadata.method(:from_hash))
                .is_response_array(true))
    .execute
end

#update_metafield(resource_type, name, current_name: nil, body: nil) ⇒ Array[Metafield]

Use the following method to update metafields for your Site. Metafields can be populated with metadata after the fact. to which the metafields belong you are updating an existing record and you wish to rename the field. Note you must supply name and current_name to rename the field

Parameters:

  • resource_type (ResourceType) —

    Required parameter: the resource type

  • name (String) —

    Required parameter: Name of the custom field.

  • current_name (String) (defaults to: nil) —

    Optional parameter: This only applies when

  • body (UpdateMetafieldsRequest) (defaults to: nil) —

    Optional parameter: Example:

Returns:

  • (Array[Metafield]) —

    response from the API call.



152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/advanced_billing/controllers/custom_fields_controller.rb', line 152

def update_metafield(resource_type,
                     name,
                     current_name: nil,
                     body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::PUT,
                                 '/{resource_type}/metafields.json',
                                 Server::DEFAULT)
               .template_param(new_parameter(resource_type, key: 'resource_type')
                                .is_required(true)
                                .should_encode(true))
               .query_param(new_parameter(name, key: 'name')
                             .is_required(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .query_param(new_parameter(current_name, key: 'current_name'))
               .body_param(new_parameter(body))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(Metafield.method(:from_hash))
                .is_response_array(true))
    .execute
end