List Segments for Consolidated Invoice
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.
Authorization
BasicAuth The username is a Maxio Chargify API key. The password is x.
In: header
Path Parameters
The unique identifier of the consolidated invoice
Query Parameters
Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned.
Use in query page=1.
1 <= value1This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200.
Use in query per_page=200.
value <= 20020Sort direction of the returned segments.
"asc"Value in
- "asc"
- "desc"
Response Body
application/json
curl -X GET "https://example.com/invoices/string/segments.json"{ "invoices": [ { "uid": "inv_8htcd29wcq3q6", "site_id": 51288, "customer_id": 20153415, "subscription_id": 23277588, "number": "125", "sequence_number": 125, "issue_date": "2018-09-20", "due_date": "2018-09-20", "paid_date": "2018-09-20", "status": "paid", "collection_method": "automatic", "payment_instructions": "Make checks payable to Acme, Inc.", "currency": "USD", "consolidation_level": "parent", "parent_invoice_uid": null, "parent_invoice_number": null, "group_primary_subscription_id": 23277588, "product_name": "Trial and setup fee", "product_family_name": "Billing Plans", "seller": { "name": "General Goods", "address": { "street": "123 General Goods Way", "line2": "Apt. 10", "city": "Boston", "state": "MA", "zip": "02120", "country": "US" }, "phone": "555-555-1212" }, "customer": { "chargify_id": 20153415, "first_name": "Meg", "last_name": "Example", "organization": "", "email": "meg@example.com" }, "memo": "Payment due within 15 days of receipt.", "billing_address": { "street": "123 I Love Cats Way", "line2": "", "city": "Boston", "state": "MA", "zip": "90210", "country": "US" }, "shipping_address": { "street": "123 I Love Cats Way", "line2": "", "city": "Boston", "state": "MA", "zip": "90210", "country": "US" }, "subtotal_amount": "100.0", "discount_amount": "0.0", "tax_amount": "0.0", "total_amount": "100.0", "credit_amount": "0.0", "paid_amount": "100.0", "refund_amount": "0.0", "due_amount": "0.0", "public_url": "https://www.chargifypay.com/invoice/inv_8htcd29wcq3q6?token=fb6kpjz5rcr2vttyjs4rcv6y" }, { "uid": "inv_8hr3546xp4h8n", "site_id": 51288, "customer_id": 21687686, "subscription_id": 22007644, "number": "124", "sequence_number": 124, "issue_date": "2018-09-18", "due_date": "2018-09-18", "paid_date": null, "status": "open", "collection_method": "remittance", "payment_instructions": "Make checks payable to Acme, Inc.", "currency": "USD", "consolidation_level": "none", "parent_invoice_uid": null, "parent_invoice_number": null, "group_primary_subscription_id": null, "product_name": "Trial and setup fee", "product_family_name": "Billing Plans", "seller": { "name": "General Goods", "address": { "street": "123 General Goods Way", "line2": "Apt. 10", "city": "Boston", "state": "MA", "zip": "02120", "country": "US" }, "phone": "555-555-1212" }, "customer": { "chargify_id": 21687686, "first_name": "Charlene", "last_name": "Tester", "organization": "", "email": "food@example.com" }, "memo": "Payment due within 15 days of receipt.", "billing_address": { "street": "", "line2": "", "city": "", "state": "", "zip": "", "country": "" }, "shipping_address": { "street": "", "line2": "", "city": "", "state": "", "zip": "", "country": "" }, "subtotal_amount": "100.0", "discount_amount": "0.0", "tax_amount": "0.0", "total_amount": "100.0", "credit_amount": "0.0", "paid_amount": "0.0", "refund_amount": "0.0", "due_amount": "100.0", "public_url": "https://www.chargifypay.com/invoice/inv_8hr3546xp4h8n?token=fb6kpjz5rcr2vttyjs4rcv6y" }, { "uid": "inv_8hr3546wdwxkr", "site_id": 51288, "customer_id": 21687670, "subscription_id": 22007627, "number": "123", "sequence_number": 123, "issue_date": "2018-09-18", "due_date": "2018-09-18", "paid_date": "2018-09-18", "status": "paid", "collection_method": "automatic", "payment_instructions": "Make checks payable to Acme, Inc.", "currency": "USD", "consolidation_level": "none", "parent_invoice_uid": null, "parent_invoice_number": null, "group_primary_subscription_id": null, "product_name": "Trial End - Free", "product_family_name": "Billing Plans", "seller": { "name": "General Goods", "address": { "street": "123 General Goods Way", "line2": "Apt. 10", "city": "Boston", "state": "MA", "zip": "02120", "country": "US" }, "phone": "555-555-1212" }, "customer": { "chargify_id": 21687670, "first_name": "Hello", "last_name": "World", "organization": "123", "email": "example@example.com" }, "memo": "Payment due within 15 days of receipt.", "billing_address": { "street": "123 Anywhere Street", "line2": "", "city": "Boston", "state": "MA", "zip": "02120", "country": "US" }, "shipping_address": { "street": "", "line2": "", "city": "Boston", "state": "AL", "zip": "02120", "country": "US" }, "subtotal_amount": "0.0", "discount_amount": "0.0", "tax_amount": "0.0", "total_amount": "0.0", "credit_amount": "0.0", "paid_amount": "0.0", "refund_amount": "0.0", "due_amount": "0.0", "public_url": "https://www.chargifypay.com/invoice/inv_8hr3546wdwxkr?token=fb6kpjz5rcr2vttyjs4rcv6y" }, { "uid": "inv_8hjtk8bz56bbp", "site_id": 51288, "customer_id": 20137757, "subscription_id": 20541100, "number": "122", "sequence_number": 122, "issue_date": "2018-09-10", "due_date": "2018-09-10", "paid_date": "2018-09-10", "status": "paid", "collection_method": "automatic", "payment_instructions": "Make checks payable to Acme, Inc.", "currency": "USD", "consolidation_level": "none", "parent_invoice_uid": null, "parent_invoice_number": null, "group_primary_subscription_id": null, "product_name": "$0 Product", "product_family_name": "Billing Plans", "seller": { "name": "General Goods", "address": { "street": "123 General Goods Way", "line2": "Apt. 10", "city": "Boston", "state": "MA", "zip": "02120", "country": "US" }, "phone": "555-555-1212" }, "customer": { "chargify_id": 20137757, "first_name": "Sasha", "last_name": "Example", "organization": "", "email": "example@example.com" }, "memo": "Payment due within 15 days of receipt.", "billing_address": { "street": "123 I Love Cats Way", "line2": "", "city": "Catville", "state": "MA", "zip": "90210", "country": "US" }, "shipping_address": { "street": "123 I Love Cats Way", "line2": "", "city": "Catville", "state": "AL", "zip": "90210", "country": "US" }, "subtotal_amount": "0.0", "discount_amount": "0.0", "tax_amount": "0.0", "total_amount": "0.0", "credit_amount": "0.0", "paid_amount": "0.0", "refund_amount": "0.0", "due_amount": "0.0", "public_url": "https://www.chargifypay.com/invoice/inv_8jzrw74xq8kxr?token=fb6kpjz5rcr2vttyjs4rcv6y" } ]}Void Invoice POST
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.
Create Invoice POST
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: ```json { "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. ```json { "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: ```json { "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 ```json ... "coupons": [ { "code": "FREESETUP", "product_family_id": 1 } ] ... ``` #### 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. 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`.