Create Invoice

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.