Class: AdvancedBilling::InvoicesController

#create_invoice(subscription_id, body: nil) ⇒ `InvoiceResponse`

Creates an ad hoc invoice.

Basic Behavior

You can create a basic invoice by sending an array of line items to this endpoint. Each line item, at a minimum, must include a title, a quantity and a unit price. Example:

{
  "invoice": {
    "line_items": [
      {
        "title": "A Product",
        "quantity": 12,
        "unit_price": "150.00"
      }
    ]
  }
}

Catalog items

Instead of creating custom products like in above example, You can pass existing items like products, components.

{
  "invoice": {
    "line_items": [
      {
        "product_id": "handle:gold-product",
        "quantity": 2,
      }
    ]
  }
}

The price for each line item will be calculated as well as a total due amount for the invoice. Multiple line items can be sent.

Line item types

When defining a line item, You can choose one of 3 types for a line item:

Custom item

As shown in the basic behavior example, You can pass title and unit_price for custom item.

Product id

Product handle (with handle: prefix) or id from the scope of current subscription's site can be provided with product_id. By default unit_price is taken from product's default price point, but can be overwritten by passing unit_price or product_price_point_id. If product_id is used, following fields cannot be used: title, component_id.

Component id

Component handle (with handle: prefix) or id from the scope of current subscription's site can be provided with component_id. If component_id is used, following fields cannot be used: title, product_id. By default unit_price is taken from product's default price point, but can be overwritten by passing unit_price or price_point_id. At this moment price points are supported only for quantity based, on/off and metered components. For prepaid and event based billing components unit_price is required.

Coupons

When creating ad hoc invoice, new discounts can be applied in following way:

{
  "invoice": {
    "line_items": [
      {
        "product_id": "handle:gold-product",
        "quantity": 1
      }
    ],
    "coupons": [
      {
        "code": "COUPONCODE",
        "percentage": 50.0
      }
    ]
  }
}

If You want to use existing coupon for discount creation, only code and optional product_family_id is needed

...
 "coupons": [
      {
        "code": "FREESETUP",
        "product_family_id": 1
      }
  ]
...

Using Coupon Subcodes

You can also use coupon subcodes to apply existing coupons with specific subcodes:

...
 "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:

...
 "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. Coupon code can only contain uppercase letters, numbers, and allowed special characters. 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 ignored if code is used to select an existing coupon from the catalog.

Amount

Coupon amount takes number value. It cannot be used with percentage. Used only when not matching existing coupon by code.

Description

Optional description will be displayed with coupon code. Used only when not matching existing coupon by code.

Product Family id

Optional product_family_id handle (with handle: prefix) or id is used to match existing coupon within site, when codes are not unique.

Compounding Strategy

Optional compounding_strategy for percentage coupons, can take values compound or full-price. For amount coupons, discounts will be always calculated against the original item price, before other discounts are applied. compound strategy: Percentage-based discounts will be calculated against the remaining price, after prior discounts have been calculated. It is set by default. full-price strategy: Percentage-based discounts will always be calculated against the original item price, before other discounts are applied.

Line Item Options

Period Date Range

A custom period date range can be defined for each line item with the period_range_start and period_range_end parameters. Dates must be sent in the YYYY-MM-DD format. period_range_end must be greater or equal period_range_start.

Taxes

The taxable parameter can be sent as true if taxes should be calculated for a specific line item. For this to work, the site should be configured to use and calculate taxes. Further, if the site uses Avalara for tax calculations, a tax_code parameter should also be sent. For existing catalog items: products/components taxes cannot be overwritten.

Price Point

Price point handle (with handle: prefix) or id from the scope of current subscription's site can be provided with price_point_id for components with component_id or product_price_point_id for products with product_id parameter. If price point is passed unit_price cannot be used. It can be used only with catalog items products and components.

Description

Optional description parameter, it will overwrite default generated description for line item.

Invoice Options

Issue Date

By default, invoices will be created with a issue date set to today in your site's time zone. The issue_date parameter can be sent to alter the default. Only today or dates in the past are accepted. This date is interpreted and validated in your site's time zone. The format for issue_date is YYYY-MM-DD.

Net Terms

By default, invoices will be created with a due date matching the date of invoice creation. If a different due date is desired, the net_terms parameter can be sent indicating the number of days in advance the due date should be.

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. 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 payment_instructions parameter.

Status

By default, invoices will be created with open status. Possible alternative is draft. the subscription. description here

Parameters:

subscription_id (Integer) —
Required parameter: The Chargify id of
body (CreateInvoiceRequest) (defaults to: nil) —
Optional parameter: TODO: type

Returns:

(InvoiceResponse) —
Response from the API call.

# File 'lib/advanced_billing/controllers/invoices_controller.rb', line 761

def create_invoice(subscription_id,
                   body: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/invoices.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .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
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(InvoiceResponse.method(:from_hash))
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorArrayMapResponseException))
    .execute
end

#delete_invoice(subscription_id, uid) ⇒ `void`

This method returns an undefined value.

Deletes an ad hoc invoice while it is in the draft state. Important: only invoices with the adhoc role and draft status can be deleted. Any other invoice — issued, or with a different role (e.g. renewal, signup) — cannot be deleted through this endpoint and the request returns a 422 error. Issued invoices should be voided instead. If the invoice does not belong to the provided subscription, a 404 error is returned. A successful deletion returns a 204 No Content response and the invoice is permanently removed. the subscription. invoice, this does not refer to the public facing invoice number.

Parameters:

subscription_id (Integer) —
Required parameter: The Chargify id of
uid (String) —
Required parameter: The unique identifier for the

# File 'lib/advanced_billing/controllers/invoices_controller.rb', line 881

def delete_invoice(subscription_id,
                   uid)
  @api_call
    .request(new_request_builder(HttpMethodEnum::DELETE,
                                 '/subscriptions/{subscription_id}/invoices/{uid}.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .template_param(new_parameter(uid, key: 'uid')
                                .is_required(true)
                                .should_encode(true))
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .is_response_void(true)
                .local_error_template('404',
                                      'Not Found:\'{$response.body}\'',
                                      ErrorListResponseException)
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorListResponseException))
    .execute
end

#issue_invoice(uid, body: nil) ⇒ `Invoice`

Issues an invoice that is in "pending" or "draft" status. For example, you can issue an invoice that was created when allocating new quantity on a component and using "accrue charges" option. You cannot issue a pending child invoice that was created for a member subscription in a group. For Remittance subscriptions, the invoice will go into "open" status and payment won't be attempted. The value for on_failed_payment would be rejected if sent. Any prepayments or service credits that exist on the subscription will be automatically applied. Additionally, if the setting is enabled, an email will be sent for the issued invoice. For Automatic subscriptions, prepayments and service credits will apply to the invoice before payment is attempted. On successful payment, the invoice will go into "paid" status and email will be sent to the customer (if setting applies). When payment fails, the next event depends on the on_failed_payment value:

leave_open_invoice - prepayments and credits applied to invoice; invoice status set to "open"; email sent to the customer for the issued invoice (if setting applies); payment failure recorded in the invoice history. This is the default option.
rollback_to_pending - prepayments and credits not applied; invoice remains in "pending" status; no email sent to the customer; payment failure recorded in the invoice history.
initiate_dunning - prepayments and credits applied to the invoice; invoice status set to "open"; email sent to the customer for the issued invoice (if setting applies); payment failure recorded in the invoice history; subscription will most likely go into "past_due" or "canceled" state (depending upon net terms and dunning settings). invoice, this does not refer to the public facing invoice number. description here

Parameters:

uid (String) —
Required parameter: The unique identifier for the
body (IssueInvoiceRequest) (defaults to: nil) —
Optional parameter: TODO: type

Returns:

(Invoice) —
Response from the API call.

# File 'lib/advanced_billing/controllers/invoices_controller.rb', line 1046

def issue_invoice(uid,
                  body: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/invoices/{uid}/issue.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(uid, key: 'uid')
                                .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
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(Invoice.method(:from_hash))
                .local_error_template('404',
                                      'Not Found:\'{$response.body}\'',
                                      APIException)
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorListResponseException))
    .execute
end

#list_consolidated_invoice_segments(options = {}) ⇒ `ConsolidatedInvoice`

Lists segments for a consolidated invoice. Invoice segments returned on the index will only include totals, not detailed breakdowns for line_items, discounts, taxes, credits, payments, or custom_fields. the consolidated invoice 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. returned segments.

Parameters:

invoice_uid (String) —
Required parameter: The unique identifier of
page (Integer) —
Optional parameter: Result records are organized in
per_page (Integer) —
Optional parameter: This parameter indicates how
direction (Direction) —
Optional parameter: Sort direction of the

Returns:

(ConsolidatedInvoice) —
Response from the API call.

# File 'lib/advanced_billing/controllers/invoices_controller.rb', line 534

def list_consolidated_invoice_segments(options = {})
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/invoices/{invoice_uid}/segments.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(options['invoice_uid'], key: 'invoice_uid')
                                .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['direction'], key: 'direction'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(ConsolidatedInvoice.method(:from_hash)))
    .execute
end

#list_credit_notes(options = {}) ⇒ `ListCreditNotesResponse`

Lists credit notes for a site. Credit Notes are like inverse invoices. They reduce the amount a customer owes. By default, the credit notes returned by this endpoint will exclude the arrays of line_items, discounts, taxes, applications, or refunds. To include these arrays, pass the specific field as a key in the query with a value set to true. Advanced Billing id 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. line items data. discounts data. data. refunds data. applications data.

Parameters:

subscription_id (Integer) —
Optional parameter: The subscription's
page (Integer) —
Optional parameter: Result records are organized in
per_page (Integer) —
Optional parameter: This parameter indicates how
line_items (TrueClass | FalseClass) —
Optional parameter: Include
discounts (TrueClass | FalseClass) —
Optional parameter: Include
taxes (TrueClass | FalseClass) —
Optional parameter: Include taxes
refunds (TrueClass | FalseClass) —
Optional parameter: Include
applications (TrueClass | FalseClass) —
Optional parameter: Include

Returns:

(ListCreditNotesResponse) —
Response from the API call.

# File 'lib/advanced_billing/controllers/invoices_controller.rb', line 358

def list_credit_notes(options = {})
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/credit_notes.json',
                                 Server::PRODUCTION)
               .query_param(new_parameter(options['subscription_id'], key: 'subscription_id'))
               .query_param(new_parameter(options['page'], key: 'page'))
               .query_param(new_parameter(options['per_page'], key: 'per_page'))
               .query_param(new_parameter(options['line_items'], key: 'line_items'))
               .query_param(new_parameter(options['discounts'], key: 'discounts'))
               .query_param(new_parameter(options['taxes'], key: 'taxes'))
               .query_param(new_parameter(options['refunds'], key: 'refunds'))
               .query_param(new_parameter(options['applications'], key: 'applications'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(ListCreditNotesResponse.method(:from_hash)))
    .execute
end

#list_invoice_events(options = {}) ⇒ `ListInvoiceEventsResponse`

Lists invoice events for a site. Each event contains event "data" (such as an applied payment) as well as a snapshot of the invoice at the time of event completion. Exposed event types are:

issue_invoice
apply_credit_note
apply_payment
refund_invoice
void_invoice
void_remainder
backport_invoice
change_invoice_status
change_invoice_collection_method
remove_payment
failed_payment
apply_debit_note
create_debit_note
change_chargeback_status Invoice events are returned in ascending order. If both a since_date and since_id are provided in request parameters, the since_date will be used. Note - invoice events that occurred prior to 09/05/2018 will not contain an invoice snapshot. YYYY-MM-DD T HH:MM:SS Z, or YYYY-MM-DD(in this case, it returns data from the beginning of the day). of the event from which you want to start the search. All the events before the since_date timestamp are not returned in the response. which you want to start the search(ID is not included. e.g. if ID is set to 2, then all events with ID 3 and more will be shown) This parameter is not used if since_date is defined. 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 100. The maximum allowed values is 200; any per_page value over 200 will be changed to

allows for scoping of the invoice events to a single invoice or credit note. parameter if you want to fetch also invoice events with change_invoice_status type. results by event_type. Supply a comma separated list of event types (listed above). Use in query: event_types=void_invoice,void_remainder.

Parameters:

since_date (String) —
Optional parameter: The timestamp in a format
since_id (Integer) —
Optional parameter: The ID of the event from
page (Integer) —
Optional parameter: Result records are organized in
per_page (Integer) —
Optional parameter: This parameter indicates how
invoice_uid (String) —
Optional parameter: Providing an invoice_uid
with_change_invoice_status (String) —
Optional parameter: Use this
event_types (Array[InvoiceEventType]) —
Optional parameter: Filter

Returns:

(ListInvoiceEventsResponse) —
Response from the API call.

# File 'lib/advanced_billing/controllers/invoices_controller.rb', line 246

def list_invoice_events(options = {})
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/invoices/events.json',
                                 Server::PRODUCTION)
               .query_param(new_parameter(options['since_date'], key: 'since_date'))
               .query_param(new_parameter(options['since_id'], key: 'since_id'))
               .query_param(new_parameter(options['page'], key: 'page'))
               .query_param(new_parameter(options['per_page'], key: 'per_page'))
               .query_param(new_parameter(options['invoice_uid'], key: 'invoice_uid'))
               .query_param(new_parameter(options['with_change_invoice_status'], key: 'with_change_invoice_status'))
               .query_param(new_parameter(options['event_types'], key: 'event_types'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth'))
               .array_serialization_format(ArraySerializationFormat::CSV))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(ListInvoiceEventsResponse.method(:from_hash)))
    .execute
end

#list_invoices(options = {}) ⇒ `ListInvoicesResponse`

Lists invoices for a site. By default, invoices returned on the index will only include totals, not detailed breakdowns for line_items, discounts, taxes, credits, payments, custom_fields, or refunds. To include breakdowns, pass the specific field as a key in the query with a value set to true. YYYY-MM-DD) with which to filter the date_field. Returns invoices 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 invoices with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. the invoice. Allowed Values: draft, open, paid, pending, voided ID. subscription group you want to fetch consolidated invoices for. This will return a paginated list of consolidated invoices for the specified group. level of the invoice. Allowed Values: none, parent, child or comma-separated lists of thereof, e.g. none,parent. 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. returned invoices. line items data. discounts data. data. credits data. payments data. custom fields data. refunds data. filter you would like to apply to your search. Use in query date_field=issue_date. (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns invoices 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. Allowed to be used only along with date_field set to created_at or updated_at. (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns invoices 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. Allowed to be used only along with date_field set to created_at or updated_at. invoices with matching customer id based on provided values. Use in query customer_ids=1,2,3. with matching invoice number based on provided values. Use in query number=1234,1235. invoices with matching line items product ids based on provided values. Use in query product_ids=23,34. the order of the returned list. Use in query sort=total_amount.

Parameters:

start_date (String) —
Optional parameter: The start date (format
end_date (String) —
Optional parameter: The end date (format
status (InvoiceStatus) —
Optional parameter: The current status of
subscription_id (Integer) —
Optional parameter: The subscription's
subscription_group_uid (String) —
Optional parameter: The UID of the
consolidation_level (String) —
Optional parameter: The consolidation
page (Integer) —
Optional parameter: Result records are organized in
per_page (Integer) —
Optional parameter: This parameter indicates how
direction (Direction) —
Optional parameter: The sort direction of the
line_items (TrueClass | FalseClass) —
Optional parameter: Include
discounts (TrueClass | FalseClass) —
Optional parameter: Include
taxes (TrueClass | FalseClass) —
Optional parameter: Include taxes
credits (TrueClass | FalseClass) —
Optional parameter: Include
payments (TrueClass | FalseClass) —
Optional parameter: Include
custom_fields (TrueClass | FalseClass) —
Optional parameter: Include
refunds (TrueClass | FalseClass) —
Optional parameter: Include
date_field (InvoiceDateField) —
Optional parameter: The type of
start_datetime (String) —
Optional parameter: The start date and time
end_datetime (String) —
Optional parameter: The end date and time
customer_ids (Array[Integer]) —
Optional parameter: Allows fetching
number (Array[String]) —
Optional parameter: Allows fetching invoices
product_ids (Array[Integer]) —
Optional parameter: Allows fetching
sort (InvoiceSortField) —
Optional parameter: Allows specification of

Returns:

(ListInvoicesResponse) —
Response from the API call.

# File 'lib/advanced_billing/controllers/invoices_controller.rb', line 125

def list_invoices(options = {})
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/invoices.json',
                                 Server::PRODUCTION)
               .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['status'], key: 'status'))
               .query_param(new_parameter(options['subscription_id'], key: 'subscription_id'))
               .query_param(new_parameter(options['subscription_group_uid'], key: 'subscription_group_uid'))
               .query_param(new_parameter(options['consolidation_level'], key: 'consolidation_level'))
               .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'))
               .query_param(new_parameter(options['line_items'], key: 'line_items'))
               .query_param(new_parameter(options['discounts'], key: 'discounts'))
               .query_param(new_parameter(options['taxes'], key: 'taxes'))
               .query_param(new_parameter(options['credits'], key: 'credits'))
               .query_param(new_parameter(options['payments'], key: 'payments'))
               .query_param(new_parameter(options['custom_fields'], key: 'custom_fields'))
               .query_param(new_parameter(options['refunds'], key: 'refunds'))
               .query_param(new_parameter(options['date_field'], key: 'date_field'))
               .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['customer_ids'], key: 'customer_ids'))
               .query_param(new_parameter(options['number'], key: 'number'))
               .query_param(new_parameter(options['product_ids'], key: 'product_ids'))
               .query_param(new_parameter(options['sort'], key: 'sort'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth'))
               .array_serialization_format(ArraySerializationFormat::CSV))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(ListInvoicesResponse.method(:from_hash)))
    .execute
end

#preview_customer_information_changes(uid) ⇒ `CustomerChangesPreviewResponse`

Previews the effect of customer information changes on an open invoice. Customer information may change after an invoice is issued, which may lead to a mismatch between customer information that is present on an open invoice and actual customer information. This endpoint allows you to preview these differences, if any. The endpoint doesn't accept a request body. Customer information differences are calculated on the application side. invoice, this does not refer to the public facing invoice number.

Parameters:

uid (String) —
Required parameter: The unique identifier for the

Returns:

(CustomerChangesPreviewResponse) —
Response from the API call.

# File 'lib/advanced_billing/controllers/invoices_controller.rb', line 960

def preview_customer_information_changes(uid)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/invoices/{uid}/customer_information/preview.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(uid, key: 'uid')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(CustomerChangesPreviewResponse.method(:from_hash))
                .local_error_template('404',
                                      'Not Found:\'{$response.body}\'',
                                      ErrorListResponseException)
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorListResponseException))
    .execute
end

#read_credit_note(uid) ⇒ `CreditNote`

Returns the details for a credit note. credit note

Parameters:

uid (String) —
Required parameter: The unique identifier of the

Returns:

(CreditNote) —
Response from the API call.

# File 'lib/advanced_billing/controllers/invoices_controller.rb', line 383

def read_credit_note(uid)
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/credit_notes/{uid}.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(uid, key: 'uid')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(CreditNote.method(:from_hash)))
    .execute
end

#read_invoice(uid) ⇒ `Invoice`

Returns the details for an invoice.

PDF Invoice retrieval

Individual PDF Invoices can be retrieved by using the "Accept" header application/pdf or appending .pdf as the format portion of the URL:

Accept:application/pdf -H
https://acme.chargify.com/invoices/inv_8gd8tdhtd3hgr.pdf > output_file.pdf
URL: `https://<subdomain>.chargify.com/invoices/<uid>.<format>`
Method: GET
Required parameters: `uid`
Response: A single Invoice.

invoice, this does not refer to the public facing invoice number.

Parameters:

uid (String) —
Required parameter: The unique identifier for the

Returns:

(Invoice) —
Response from the API call.

# File 'lib/advanced_billing/controllers/invoices_controller.rb', line 177

def read_invoice(uid)
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/invoices/{uid}.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(uid, key: 'uid')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(Invoice.method(:from_hash)))
    .execute
end

#record_payment_for_invoice(uid, body: nil) ⇒ `Invoice`

Applies a payment of a given type against a specific invoice. If you would like to apply a payment across multiple invoices, you can use the Record Payment for Multiple Invoices endpoint. invoice, this does not refer to the public facing invoice number. description here

Parameters:

uid (String) —
Required parameter: The unique identifier for the
body (CreateInvoicePaymentRequest) (defaults to: nil) —
Optional parameter: TODO: type

Returns:

(Invoice) —
Response from the API call.

# File 'lib/advanced_billing/controllers/invoices_controller.rb', line 276

def record_payment_for_invoice(uid,
                               body: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/invoices/{uid}/payments.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(uid, key: 'uid')
                                .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
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(Invoice.method(:from_hash))
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorListResponseException))
    .execute
end

#record_payment_for_multiple_invoices(body: nil) ⇒ `MultiInvoicePaymentResponse`

Records an external payment against multiple invoices. To apply a payment to multiple invoices, at minimum, specify the amount and applications (i.e., invoice_uid and amount) details. Note that the invoice payment amounts must be greater than 0. Total amount must be greater or equal to invoices payment amount sum. type description here

Parameters:

body (CreateMultiInvoicePaymentRequest) (defaults to: nil) —
Optional parameter: TODO:

Returns:

(MultiInvoicePaymentResponse) —
Response from the API call.

# File 'lib/advanced_billing/controllers/invoices_controller.rb', line 308

def record_payment_for_multiple_invoices(body: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/invoices/payments.json',
                                 Server::PRODUCTION)
               .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
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(MultiInvoicePaymentResponse.method(:from_hash))
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorListResponseException))
    .execute
end

#record_payment_for_subscription(subscription_id, body: nil) ⇒ `RecordPaymentResponse`

Records an external payment made against a subscription that will pay partially or in full one or more invoices. Payment will be applied starting with the oldest open invoice and then next oldest, and so on until the amount of the payment is fully consumed. Excess payment will result in the creation of a prepayment on the Invoice Account. Only ungrouped or primary subscriptions may be paid using the "bulk" payment request. the subscription. description here

Parameters:

subscription_id (Integer) —
Required parameter: The Chargify id of
body (RecordPaymentRequest) (defaults to: nil) —
Optional parameter: TODO: type

Returns:

(RecordPaymentResponse) —
Response from the API call.

# File 'lib/advanced_billing/controllers/invoices_controller.rb', line 412

def record_payment_for_subscription(subscription_id,
                                    body: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/payments.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .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
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(RecordPaymentResponse.method(:from_hash))
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorListResponseException))
    .execute
end

#refund_invoice(uid, body: nil) ⇒ `Invoice`

Refunds an invoice, segment, or consolidated invoice.

Partial Refund for Consolidated Invoice

A refund less than the total of a consolidated invoice will be split across its segments. For a $50.00 refund on a $100.00 consolidated invoice with one $60.00 segment and one $40.00 segment, the refunded amount will be applied as 50% of each ($30.00 and $20.00, respectively). invoice, this does not refer to the public facing invoice number. description here

Parameters:

uid (String) —
Required parameter: The unique identifier for the
body (RefundInvoiceRequest) (defaults to: nil) —
Optional parameter: TODO: type

Returns:

(Invoice) —
Response from the API call.

# File 'lib/advanced_billing/controllers/invoices_controller.rb', line 21

def refund_invoice(uid,
                   body: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/invoices/{uid}/refunds.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(uid, key: 'uid')
                                .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
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(Invoice.method(:from_hash))
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorListResponseException))
    .execute
end

#reopen_invoice(uid) ⇒ `Invoice`

Reopens any invoice with the "canceled" status. Invoices enter "canceled" status if they were open at the time the subscription was canceled (whether through dunning or an intentional cancellation). Invoices with "canceled" status are no longer considered to be due. Once reopened, they are considered due for payment. Payment may then be captured in one of the following ways:

Reactivating the subscription, which will capture all open invoices (See note below about automatic reopening of invoices.)
Recording a payment directly against the invoice A note about reactivations: any canceled invoices from the most recent active period are automatically opened as a part of the reactivation process. Reactivating via this endpoint prior to reactivation is only necessary when you wish to capture older invoices from previous periods during the reactivation.

Reopening Consolidated Invoices

When reopening a consolidated invoice, all of its canceled segments will also be reopened. invoice, this does not refer to the public facing invoice number.

Parameters:

uid (String) —
Required parameter: The unique identifier for the

Returns:

(Invoice) —
Response from the API call.

# File 'lib/advanced_billing/controllers/invoices_controller.rb', line 456

def reopen_invoice(uid)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/invoices/{uid}/reopen.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(uid, key: 'uid')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(Invoice.method(:from_hash))
                .local_error_template('404',
                                      'Not Found:\'{$response.body}\'',
                                      APIException)
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorListResponseException))
    .execute
end

#send_invoice(uid, body: nil) ⇒ `void`

This method returns an undefined value.

Sends an invoice to the customer via email. This endpoint supports the delivery of both ad-hoc and automatically generated invoices. Additionally, this endpoint supports email delivery to direct recipients, carbon-copy (cc) recipients, and blind carbon-copy (bcc) recipients. File Attachments: You can attach files to invoice emails using attachment_urls[] parameter by providing URLs to the files you want to attach. When using attachments, the request must use multipart/form-data content type. Max 10 files, 10MB per file. 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. invoice, this does not refer to the public facing invoice number. description here

Parameters:

uid (String) —
Required parameter: The unique identifier for the
body (SendInvoiceRequest) (defaults to: nil) —
Optional parameter: TODO: type

# File 'lib/advanced_billing/controllers/invoices_controller.rb', line 928

def send_invoice(uid,
                 body: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/invoices/{uid}/deliveries.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(uid, key: 'uid')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .is_response_void(true)
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorListResponseException))
    .execute
end

#update_customer_information(uid) ⇒ `Invoice`

Updates customer information on an open invoice and returns the updated invoice. If you would like to preview changes that will be applied, use the /invoices/{uid}/customer_information/preview.json endpoint first. The endpoint doesn't accept a request body. Customer information differences are calculated on the application side. invoice, this does not refer to the public facing invoice number.

Parameters:

uid (String) —
Required parameter: The unique identifier for the

Returns:

(Invoice) —
Response from the API call.

# File 'lib/advanced_billing/controllers/invoices_controller.rb', line 991

def update_customer_information(uid)
  @api_call
    .request(new_request_builder(HttpMethodEnum::PUT,
                                 '/invoices/{uid}/customer_information.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(uid, key: 'uid')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(Invoice.method(:from_hash))
                .local_error_template('404',
                                      'Not Found:\'{$response.body}\'',
                                      ErrorListResponseException)
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorListResponseException))
    .execute
end

#update_invoice(subscription_id, uid, body: nil) ⇒ `InvoiceResponse`

Updates an ad hoc invoice while it is in the draft state. Important: only invoices with the adhoc role and draft status can be updated. Any other invoice — issued, or with a different role (e.g. renewal, signup) — cannot be updated through this endpoint and the request returns a 422 error. If the invoice does not belong to the provided subscription, a 404 error is returned. Only the attributes submitted in the request are changed — omitted attributes keep their current values.

Line Items

The line_items array describes changes to the invoice's line items. Line items not referenced in the array remain unchanged.

Adding a line item

A line item without a uid is added to the invoice. The same line item types and options as on invoice creation are supported (custom items, product_id, component_id, price points, period date ranges, taxes).

Updating a line item

A line item with the uid of an existing line item updates that line item with the submitted attributes. Amounts and taxes are recalculated.

Removing a line item

A line item with a uid and "_destroy": true is removed from the invoice. Other line items remain unchanged. Referencing a uid which does not exist on the invoice returns a 422 error.

Coupons

When the coupons key is present, the submitted coupons replace all discounts currently applied to the invoice. Send an empty array to remove all discounts. Coupon options are the same as on invoice creation.

Invoice Options

Issue Date and Net Terms

The issue_date parameter can be sent to change the invoice's issue date. Only today or dates in the past are accepted. The date is interpreted and validated in your site's time zone, using the YYYY-MM-DD format. The net_terms parameter indicates the number of days after the issue date on which the invoice is due. The due date is recalculated whenever the issue date or net terms change.

Addresses

The seller, shipping and billing addresses can be sent to replace the addresses on the invoice. Each address requires to send a first_name at a minimum in order to work. Taxes are recalculated after an address change.

Memo and Payment Instructions

A custom memo can be sent with the memo parameter. Likewise, custom payment instructions can be sent with the payment_instructions parameter. the subscription. invoice, this does not refer to the public facing invoice number. description here

Parameters:

subscription_id (Integer) —
Required parameter: The Chargify id of
uid (String) —
Required parameter: The unique identifier for the
body (UpdateInvoiceRequest) (defaults to: nil) —
Optional parameter: TODO: type

Returns:

(InvoiceResponse) —
Response from the API call.

# File 'lib/advanced_billing/controllers/invoices_controller.rb', line 836

def update_invoice(subscription_id,
                   uid,
                   body: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::PUT,
                                 '/subscriptions/{subscription_id}/invoices/{uid}.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .template_param(new_parameter(uid, key: 'uid')
                                .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
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(InvoiceResponse.method(:from_hash))
                .local_error_template('404',
                                      'Not Found:\'{$response.body}\'',
                                      ErrorListResponseException)
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorArrayMapResponseException))
    .execute
end

#void_invoice(uid, body: nil) ⇒ `Invoice`

Voids any invoice with the "open" or "canceled" status. It will also allow voiding of an invoice with the "pending" status if it is not a consolidated invoice. invoice, this does not refer to the public facing invoice number. description here

Parameters:

uid (String) —
Required parameter: The unique identifier for the
body (VoidInvoiceRequest) (defaults to: nil) —
Optional parameter: TODO: type

Returns:

(Invoice) —
Response from the API call.

# File 'lib/advanced_billing/controllers/invoices_controller.rb', line 487

def void_invoice(uid,
                 body: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/invoices/{uid}/void.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(uid, key: 'uid')
                                .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
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(Invoice.method(:from_hash))
                .local_error_template('404',
                                      'Not Found:\'{$response.body}\'',
                                      APIException)
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorListResponseException))
    .execute
end

Overview

Constant Summary

Constants inherited from BaseController

Instance Attribute Summary

Attributes inherited from BaseController

Instance Method Summary collapse

Methods inherited from BaseController

Constructor Details

Instance Method Details

#create_invoice(subscription_id, body: nil) ⇒ InvoiceResponse

Basic Behavior

Catalog items

Line item types

Custom item

Product id

Component id

Coupons

Using Coupon Subcodes

Coupon options

Code

Subcode

Percentage

Amount

Description

Product Family id

Compounding Strategy

Line Item Options

Period Date Range

Taxes

Price Point

Description

Invoice Options

Issue Date

Net Terms

Addresses

Memo and Payment Instructions

Status

#delete_invoice(subscription_id, uid) ⇒ void

#issue_invoice(uid, body: nil) ⇒ Invoice

#list_consolidated_invoice_segments(options = {}) ⇒ ConsolidatedInvoice

#list_credit_notes(options = {}) ⇒ ListCreditNotesResponse

#list_invoice_events(options = {}) ⇒ ListInvoiceEventsResponse

#list_invoices(options = {}) ⇒ ListInvoicesResponse

#preview_customer_information_changes(uid) ⇒ CustomerChangesPreviewResponse

#read_credit_note(uid) ⇒ CreditNote

#read_invoice(uid) ⇒ Invoice

PDF Invoice retrieval

#record_payment_for_invoice(uid, body: nil) ⇒ Invoice

#record_payment_for_multiple_invoices(body: nil) ⇒ MultiInvoicePaymentResponse

#record_payment_for_subscription(subscription_id, body: nil) ⇒ RecordPaymentResponse

#refund_invoice(uid, body: nil) ⇒ Invoice

Partial Refund for Consolidated Invoice

#reopen_invoice(uid) ⇒ Invoice

Reopening Consolidated Invoices

#send_invoice(uid, body: nil) ⇒ void

#update_customer_information(uid) ⇒ Invoice

#update_invoice(subscription_id, uid, body: nil) ⇒ InvoiceResponse

Line Items

Adding a line item

Updating a line item

Removing a line item

Coupons

Invoice Options

Issue Date and Net Terms

Addresses

Memo and Payment Instructions

#void_invoice(uid, body: nil) ⇒ Invoice

#create_invoice(subscription_id, body: nil) ⇒ `InvoiceResponse`

#delete_invoice(subscription_id, uid) ⇒ `void`

#issue_invoice(uid, body: nil) ⇒ `Invoice`

#list_consolidated_invoice_segments(options = {}) ⇒ `ConsolidatedInvoice`

#list_credit_notes(options = {}) ⇒ `ListCreditNotesResponse`

#list_invoice_events(options = {}) ⇒ `ListInvoiceEventsResponse`

#list_invoices(options = {}) ⇒ `ListInvoicesResponse`

#preview_customer_information_changes(uid) ⇒ `CustomerChangesPreviewResponse`

#read_credit_note(uid) ⇒ `CreditNote`

#read_invoice(uid) ⇒ `Invoice`

#record_payment_for_invoice(uid, body: nil) ⇒ `Invoice`

#record_payment_for_multiple_invoices(body: nil) ⇒ `MultiInvoicePaymentResponse`

#record_payment_for_subscription(subscription_id, body: nil) ⇒ `RecordPaymentResponse`

#refund_invoice(uid, body: nil) ⇒ `Invoice`

#reopen_invoice(uid) ⇒ `Invoice`

#send_invoice(uid, body: nil) ⇒ `void`

#update_customer_information(uid) ⇒ `Invoice`

#update_invoice(subscription_id, uid, body: nil) ⇒ `InvoiceResponse`

#void_invoice(uid, body: nil) ⇒ `Invoice`