Delete Draft Ad Hoc 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: ```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`.