Maxio Advanced Billing
HomeSDKsAPI ReferenceContext Plugin
Invoices

Issue Invoice

POST
/invoices/{uid}/issue.json

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).

Authorization

BasicAuth
AuthorizationBasic <token>

The username is a Maxio Chargify API key. The password is x.

In: header

Path Parameters

uid*string

The unique identifier for the invoice, this does not refer to the public facing invoice number.

Request Body

application/json

on_failed_payment?Failed Payment Action

Action taken when payment for an invoice fails:

  • 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).
Default"leave_open_invoice"

Value in

  • "leave_open_invoice"
  • "rollback_to_pending"
  • "initiate_dunning"

Response Body

application/json

application/json

curl -X POST "https://example.com/invoices/string/issue.json" \  -H "Content-Type: application/json" \  -d '{}'
{  "id": 0,  "uid": "string",  "site_id": 0,  "customer_id": 0,  "subscription_id": 0,  "number": "string",  "sequence_number": 0,  "transaction_time": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z",  "issue_date": "2019-08-24",  "due_date": "2019-08-24",  "paid_date": "2019-08-24",  "status": "draft",  "role": "unset",  "parent_invoice_id": 0,  "collection_method": "automatic",  "payment_instructions": "string",  "currency": "string",  "consolidation_level": "none",  "parent_invoice_uid": null,  "subscription_group_id": 0,  "parent_invoice_number": null,  "group_primary_subscription_id": null,  "product_name": "string",  "product_family_name": "string",  "seller": {    "name": "string",    "address": {      "street": null,      "line2": null,      "city": null,      "state": null,      "zip": null,      "country": null    },    "phone": "string",    "logo_url": "string"  },  "customer": {    "chargify_id": 0,    "first_name": "string",    "last_name": "string",    "organization": null,    "email": "string",    "vat_number": "string",    "reference": "string"  },  "payer": {    "chargify_id": 0,    "first_name": "string",    "last_name": "string",    "organization": null,    "email": "string",    "vat_number": "string"  },  "recipient_emails": [    "string"  ],  "net_terms": 0,  "memo": "string",  "billing_address": {    "street": null,    "line2": null,    "city": null,    "state": null,    "zip": null,    "country": null  },  "shipping_address": {    "street": null,    "line2": null,    "city": null,    "state": null,    "zip": null,    "country": null  },  "subtotal_amount": "string",  "discount_amount": "string",  "tax_amount": "string",  "total_amount": "string",  "credit_amount": "string",  "debit_amount": "string",  "refund_amount": "string",  "paid_amount": "string",  "due_amount": "string",  "line_items": [    {      "uid": "string",      "title": "string",      "description": "string",      "quantity": "string",      "unit_price": "string",      "subtotal_amount": "string",      "discount_amount": "string",      "tax_amount": "string",      "tax_included": true,      "total_amount": "string",      "tiered_unit_price": true,      "period_range_start": "2019-08-24",      "period_range_end": "2019-08-24",      "transaction_id": 0,      "product_id": 0,      "product_version": 0,      "component_id": 0,      "price_point_id": 0,      "billing_schedule_item_id": 0,      "hide": true,      "component_cost_data": null,      "product_price_point_id": null,      "custom_item": true,      "kind": "string",      "prepaid_allocation_expires_at": "2019-08-24"    }  ],  "discounts": [    {      "uid": "string",      "title": "string",      "description": "string",      "code": "string",      "source_type": "Coupon",      "source_id": 0,      "discount_type": "percentage",      "percentage": "string",      "eligible_amount": "string",      "discount_amount": "string",      "transaction_id": 0,      "line_item_breakouts": [        {          "uid": "string",          "eligible_amount": "string",          "discount_amount": "string"        }      ]    }  ],  "taxes": [    {      "uid": "string",      "title": "string",      "description": "string",      "source_type": "Tax",      "source_id": 0,      "percentage": "string",      "taxable_amount": "string",      "tax_amount": "string",      "transaction_id": 0,      "line_item_breakouts": [        {          "uid": "string",          "taxable_amount": "string",          "tax_amount": "string",          "tax_exempt_amount": "string"        }      ],      "tax_component_breakouts": [        {          "tax_rule_id": 0,          "percentage": "string",          "country_code": "string",          "subdivision_code": "string",          "tax_amount": "string",          "taxable_amount": "string",          "tax_exempt_amount": "string",          "non_taxable_amount": "string",          "tax_name": "string",          "tax_type": "string",          "rate_type": "string",          "tax_authority_type": 0,          "state_assigned_no": "string",          "tax_sub_type": "string"        }      ],      "eu_vat": true,      "type": "string",      "tax_exempt_amount": "string"    }  ],  "credits": [    {      "uid": "string",      "credit_note_number": "string",      "credit_note_uid": "string",      "transaction_time": "2019-08-24T14:15:22Z",      "memo": "string",      "original_amount": "string",      "applied_amount": "string"    }  ],  "debits": [    {      "uid": "string",      "debit_note_number": "string",      "debit_note_uid": "string",      "role": "chargeback",      "transaction_time": "2019-08-24T14:15:22Z",      "memo": "string",      "original_amount": "string",      "applied_amount": "string"    }  ],  "refunds": [    {      "transaction_id": 0,      "payment_id": 0,      "memo": "string",      "original_amount": "string",      "applied_amount": "string",      "gateway_transaction_id": "string",      "gateway_used": "string",      "gateway_handle": "string",      "ach_late_reject": true    }  ],  "payments": [    {      "transaction_time": "2019-08-24T14:15:22Z",      "memo": "string",      "original_amount": "string",      "applied_amount": "string",      "payment_method": {        "details": "string",        "kind": "string",        "memo": "string",        "type": "string",        "card_brand": "string",        "card_expiration": "string",        "last_four": "string",        "masked_card_number": "string"      },      "transaction_id": 0,      "prepayment": true,      "gateway_handle": "string",      "gateway_used": "string",      "gateway_transaction_id": "string",      "received_on": "2019-08-24",      "uid": "string"    }  ],  "custom_fields": [    {      "owner_id": 0,      "owner_type": "Customer",      "name": "string",      "value": "string",      "metadatum_id": 0    }  ],  "display_settings": {    "hide_zero_subtotal_lines": true,    "include_discounts_on_lines": true  },  "avatax_details": {    "id": 0,    "status": "string",    "document_code": "string",    "commit_date": "2019-08-24T14:15:22Z",    "modify_date": "2019-08-24T14:15:22Z"  },  "public_url": "string",  "previous_balance_data": {    "captured_at": "2019-08-24T14:15:22Z",    "invoices": [      {        "uid": "string",        "number": "string",        "outstanding_amount": "string"      }    ]  },  "public_url_expires_on": "2019-08-24",  "branding_theme_id": 0}

Update Customer Information PUT

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.

Read Account Balances GET

Returns the `balance_in_cents` of the Subscription's Pending Discount, Service Credit, and Prepayment accounts, as well as the sum of the Subscription's open, payable invoices.