maxio-advanced-billing-sdk 7.0.1 → 8.0.0

data/lib/advanced_billing/controllers/custom_fields_controller.rb

@@ -6,43 +6,31 @@
 module AdvancedBilling
   # CustomFieldsController
   class CustomFieldsController < 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-F
-    # ields). 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-Subscrip
-    # tion-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-existent 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] resource_type Required parameter: the resource type
-    # to which the metafields belong
+    # Creates metafields on a Site for either the Subscriptions or Customers
+    # resource.
+    # Metafields and their metadata are created in the Custom Fields
+    # configuration page on your Site. Metafields can be populated with metadata
+    # when you create them or later with the [Update
+    # Metafield]($e/Custom%20Fields/updateMetafield), [Create
+    # Metadata]($e/Custom%20Fields/createMetadata), or [Update
+    # Metadata]($e/Custom%20Fields/updateMetadata) endpoints. The Create
+    # Metadata and Update Metadata endpoints allow you to add metafields and
+    # metadata values to a specific subscription or customer.
+    # Each site is limited to 100 unique metafields per resource. This means you
+    # can have 100 metafields for Subscriptions and another 100 for Customers.
+    # > Note: After creating a metafield, the resource type cannot be modified.
+    # In the UI and product documentation, metafields and metadata are called
+    # Custom Fields.
+    # - Metafield is the custom field
+    # - Metadata is the data populating the custom field.
+    # See [Custom Fields
+    # Reference](https://docs.maxio.com/hc/en-us/articles/24266140850573-Custom-
+    # Fields-Reference) and [Custom Fields
+    # Tab](https://maxio.zendesk.com/hc/en-us/articles/24251701302925-Subscripti
+    # on-Summary-Custom-Fields-Tab) for information on using Custom Fields in
+    # the Advanced Billing UI.
+    # @param [ResourceType] resource_type Required parameter: The resource type
+    # to which the metafields belong.
     # @param [CreateMetafieldsRequest] body Optional parameter: TODO: type
     # description here
     # @return [Array[Metafield]] Response from the API call.
@@ -71,12 +59,12 @@ module AdvancedBilling
         .execute
     end
 
-    # This endpoint lists metafields associated with a site. The metafield
-    # description and usage is contained in the response.
-    # @param [ResourceType] resource_type Required parameter: the resource type
-    # to which the metafields belong
-    # @param [String] name Optional parameter: filter by the name of the
-    # metafield
+    # Lists the metafields and their associated details for a Site and resource
+    # type. You can filter the request to a specific metafield.
+    # @param [ResourceType] resource_type Required parameter: The resource type
+    # to which the metafields belong.
+    # @param [String] name Optional parameter: Filter by the name of the
+    # metafield.
     # @param [Integer] page Optional parameter: 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
@@ -111,10 +99,38 @@ module AdvancedBilling
         .execute
     end
 
-    # Use the following method to update metafields for your Site. Metafields
-    # can be populated with metadata after the fact.
-    # @param [ResourceType] resource_type Required parameter: the resource type
-    # to which the metafields belong
+    # Updates metafields on your Site for a resource type.  Depending on the
+    # request structure, you can update or add metafields and metadata to the
+    # Subscriptions or Customers resource.
+    # With this endpoint, you can:
+    # - Add metafields. If the metafield specified in current_name does not
+    # exist, a new metafield is added.
+    #   >Note: Each site is limited to 100 unique metafields per resource. This
+    # means you can have 100 metafields for Subscriptions and another 100 for
+    # Customers.
+    # - Change the name of a metafield.
+    #   >Note: To keep the metafield name the same and only update the metadata
+    # for the metafield, you must use the current metafield name in both the
+    # `current_name` and `name` parameters.
+    # - Change the input type for the metafield. For example, you can change a
+    # metafield input type from text to a dropdown. If you change the input type
+    # from text to a dropdown or radio, you must update the specific
+    # subscriptions or customers where the metafield was used to reflect the
+    # updated metafield and metadata.
+    # - Add metadata values to the existing metadata for a dropdown or radio
+    # metafield.
+    #   >Note: Updates to metadata overwrite. To add one or more values, you
+    # must specify all metadata values including the new value you want to add.
+    # - Add new metadata to a dropdown or radio for a metafield that was created
+    # without metadata.
+    # - Remove  metadata for a dropdown or radio for a metafield.
+    #   >Note: Updates to metadata overwrite existing values. To remove one or
+    # more values, specify all metadata values except those you want to remove.
+    # - Add or update scope settings for a metafield.
+    #   >Note: Scope changes overwrite existing settings. You must specify the
+    # complete scope, including the changes you want to make.
+    # @param [ResourceType] resource_type Required parameter: The resource type
+    # to which the metafields belong.
     # @param [UpdateMetafieldsRequest] body Optional parameter: TODO: type
     # description here
     # @return [Array[Metafield]] Response from the API call.
@@ -143,12 +159,10 @@ module AdvancedBilling
         .execute
     end
 
-    # 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] resource_type Required parameter: the resource type
-    # to which the metafields belong
+    # Deletes a metafield from your Site. Removes the metafield and associated
+    # metadata from all Subscriptions or Customers resources on the Site.
+    # @param [ResourceType] resource_type Required parameter: The resource type
+    # to which the metafields belong.
     # @param [String] name Optional parameter: The name of the metafield to be
     # deleted
     # @return [void] Response from the API call.
@@ -171,36 +185,19 @@ module AdvancedBilling
         .execute
     end
 
-    # ## 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-F
-    # ields-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-Subscri
-    # ption-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] resource_type Required parameter: the resource type
-    # to which the metafields belong
+    # Creates metadata and metafields for a specific subscription or customer,
+    # or updates metadata values of existing metafields for a subscription or
+    # customer. Metadata values are limited to 2 KB in size.
+    # If you create metadata on a subscription or customer with a metafield that
+    # does not already exist, the metafield is created with the metadata you
+    # specify and it is always added as a text field. You can update the
+    # input_type for the metafield with the [Update
+    # Metafield]($e/Custom%20Fields/updateMetafield) endpoint.
+    # >Note: Each site is limited to 100 unique metafields per resource. This
+    # means you can have 100 metafields for Subscriptions and another 100 for
+    # Customers.
+    # @param [ResourceType] resource_type Required parameter: The resource type
+    # to which the metafields belong.
     # @param [Integer] resource_id Required parameter: The Advanced Billing id
     # of the customer or the subscription for which the metadata applies
     # @param [CreateMetadataRequest] body Optional parameter: TODO: type
@@ -235,13 +232,9 @@ module AdvancedBilling
         .execute
     end
 
-    # 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] resource_type Required parameter: the resource type
-    # to which the metafields belong
+    # Lists metadata and metafields for a specific customer or subscription.
+    # @param [ResourceType] resource_type Required parameter: The resource type
+    # to which the metafields belong.
     # @param [Integer] resource_id Required parameter: The Advanced Billing id
     # of the customer or the subscription for which the metadata applies
     # @param [Integer] page Optional parameter: Result records are organized in
@@ -277,10 +270,18 @@ module AdvancedBilling
         .execute
     end
 
-    # This method allows you to update the existing metadata associated with a
-    # subscription or customer.
-    # @param [ResourceType] resource_type Required parameter: the resource type
-    # to which the metafields belong
+    # Updates metadata and metafields on the Site and the customer or
+    # subscription specified, and updates the metadata value on a subscription
+    # or customer.
+    # If you update metadata on a subscription or customer with a metafield that
+    # does not already exist, the metafield is created with the metadata you
+    # specify and it is always added as a text field to the Site and to the
+    # subscription or customer you specify. You can update the input_type for
+    # the metafield with the Update Metafield endpoint.
+    # Each site is limited to 100 unique metafields per resource. This means you
+    # can have 100 metafields for Subscription and another 100 for Customer.
+    # @param [ResourceType] resource_type Required parameter: The resource type
+    # to which the metafields belong.
     # @param [Integer] resource_id Required parameter: The Advanced Billing id
     # of the customer or the subscription for which the metadata applies
     # @param [UpdateMetadataRequest] body Optional parameter: TODO: type
@@ -315,27 +316,10 @@ module AdvancedBilling
         .execute
     end
 
-    # 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] resource_type Required parameter: the resource type
-    # to which the metafields belong
+    # Deletes one or more metafields (and associated metadata) from the
+    # specified subscription or customer.
+    # @param [ResourceType] resource_type Required parameter: The resource type
+    # to which the metafields belong.
     # @param [Integer] resource_id Required parameter: The Advanced Billing id
     # of the customer or the subscription for which the metadata applies
     # @param [String] name Optional parameter: Name of field to be removed.
@@ -369,19 +353,9 @@ module AdvancedBilling
         .execute
     end
 
-    # 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&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.
-    # @param [ResourceType] resource_type Required parameter: the resource type
-    # to which the metafields belong
+    # Lists  metadata for a specified array of subscriptions or customers.
+    # @param [ResourceType] resource_type Required parameter: The resource type
+    # to which the metafields belong.
     # @param [Integer] page Optional parameter: 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

data/lib/advanced_billing/controllers/customers_controller.rb

@@ -22,8 +22,8 @@ module AdvancedBilling
     # ## Required Country Format
     # Advanced Billing requires that you use the ISO Standard Country codes when
     # formatting country attribute of the customer.
-    # Countries should be formatted as 2 characters. For more information,
-    # please see the following wikipedia article on
+    # Countries should be formatted as 2 characters. For more information, see
+    # the following wikipedia article on
     # [ISO_3166-1.](http://en.wikipedia.org/wiki/ISO_3166-1#Current_codes)
     # ## Required State Format
     # Advanced Billing requires that you use the ISO Standard State codes when
@@ -31,7 +31,7 @@ module AdvancedBilling
     # + US States (2 characters):
     # [ISO_3166-2](https://en.wikipedia.org/wiki/ISO_3166-2:US)
     # + States Outside the US (2-3 characters): To find the correct state codes
-    # outside of the US, please go to
+    # outside of the US, go to
     # [ISO_3166-1](http://en.wikipedia.org/wiki/ISO_3166-1#Current_codes) and
     # click on the link in the “ISO 3166-2 codes” column next to country you
     # wish to populate.
@@ -74,7 +74,7 @@ module AdvancedBilling
     # + Search by an organization
     # + Search by a reference value from your application
     # + Search by a first or last name
-    # To retrieve a single, exact match by reference, please use the [lookup
+    # To retrieve a single, exact match by reference, use the [lookup
     # endpoint](https://developers.chargify.com/docs/api-docs/b710d8fbef104-read
     # -customer-by-reference).
     # @param [SortingDirection] direction Optional parameter: Direction to sort

data/lib/advanced_billing/controllers/invoices_controller.rb

@@ -658,6 +658,38 @@ module AdvancedBilling
     #   ]
     # ...
     # ```
+    # #### Using Coupon Subcodes
+    # You can also use coupon subcodes to apply existing coupons with specific
+    # subcodes:
+    # ```json
+    # ...
+    #  "coupons": [
+    #       {
+    #         "subcode": "SUB1",
+    #         "product_family_id": 1
+    #       }
+    #   ]
+    # ...
+    # ```
+    # **Important:** You cannot specify both `code` and `subcode` for the same
+    # coupon. Use either:
+    # - `code` to apply a main coupon
+    # - `subcode` to apply a specific coupon subcode
+    # The API response will include both the main coupon code and the subcode
+    # used:
+    # ```json
+    # ...
+    #  "coupons": [
+    #       {
+    #         "code": "MAIN123",
+    #         "subcode": "SUB1",
+    #         "product_family_id": 1,
+    #         "percentage": 10,
+    #         "description": "Special discount"
+    #       }
+    #   ]
+    # ...
+    # ```
     # ### Coupon options
     # #### Code
     # Coupon `code` will be displayed on invoice discount section.
@@ -666,6 +698,11 @@ module AdvancedBilling
     # Lowercase letters will be converted to uppercase. It can be used to select
     # an existing coupon from the catalog, or as an ad hoc coupon when passed
     # with `percentage` or `amount`.
+    # #### Subcode
+    # Coupon `subcode` allows you to apply existing coupons using their
+    # subcodes. When a subcode is used, the API response will include both the
+    # main coupon code and the specific subcode that was applied. Subcodes are
+    # case-insensitive and will be converted to uppercase automatically.
     # #### Percentage
     # Coupon `percentage` can take values from 0 to 100 and up to 4 decimal
     # places. It cannot be used with `amount`. Only for ad hoc coupons, will be
@@ -724,8 +761,8 @@ module AdvancedBilling
     # #### Addresses
     # The seller, shipping and billing addresses can be sent to override the
     # site's defaults. Each address requires to send a `first_name` at a minimum
-    # in order to work. Please see below for the details on which parameters can
-    # be sent for each address object.
+    # in order to work. See below for the details on which parameters can be
+    # sent for each address object.
     # #### Memo and Payment Instructions
     # A custom memo can be sent with the `memo` parameter to override the site's
     # default. Likewise, custom payment instructions can be sent with the
@@ -767,15 +804,15 @@ module AdvancedBilling
     # automatically generated invoices. Additionally, this endpoint supports
     # email delivery to direct recipients, carbon-copy (cc) recipients, and
     # blind carbon-copy (bcc) recipients.
-    # Please note that if no recipient email addresses are specified in the
-    # request, then the subscription's default email configuration will be used.
-    # For example, if `recipient_emails` is left blank, then the invoice will be
-    # delivered to the subscription's customer email address.
-    # On success, a 204 no-content response will be returned. Please note that
-    # this does not indicate that email(s) have been delivered, but instead
-    # indicates that emails have been successfully queued for delivery. If _any_
-    # invalid or malformed email address is found in the request body, the
-    # entire request will be rejected and a 422 response will be returned.
+    # If no recipient email addresses are specified in the request, then the
+    # subscription's default email configuration will be used. For example, if
+    # `recipient_emails` is left blank, then the invoice will be delivered to
+    # the subscription's customer email address.
+    # On success, a 204 no-content response will be returned. The response does
+    # not indicate that email(s) have been delivered, but instead indicates that
+    # emails have been successfully queued for delivery. If _any_ invalid or
+    # malformed email address is found in the request body, the entire request
+    # will be rejected and a 422 response will be returned.
     # @param [String] uid Required parameter: The unique identifier for the
     # invoice, this does not refer to the public facing invoice number.
     # @param [SendInvoiceRequest] body Optional parameter: TODO: type