# Create an invoice item ## OpenAPI Specification ```yaml openapi: 3.0.1 info: title: '' description: '' version: 1.0.0 paths: /v1/invoiceitems: post: summary: Create an invoice item deprecated: false description: '' tags: - API Reference/Invoice Items parameters: - name: Accept in: header description: '' required: true example: application/json schema: type: string - name: Content-Type in: header description: '' required: true example: application/json schema: type: string requestBody: content: application/json: schema: type: object x-apifox-refs: 01HC72W96QYQJNHVZVESB4KZ3A: &ref_4 $ref: '#/components/schemas/Invoice%20item' x-apifox-overrides: customer: &ref_0 type: string description: >- The ID of the customer who will be billed when this invoice item is billed. id: null object: null period: &ref_1 type: object properties: end: type: string description: >- timestamp.The end of the period, which must be greater than or equal to the start. This value is inclusive. start: type: string description: >- timestamp. The start of the period. This value is inclusive. x-apifox-orders: - end - start description: >- The period this line_item covers. For subscription line items, this is the subscription period. required: - end - start x-apifox-ignore-properties: [] unit_amount_decimal: null discounts: null discountable: null tax_rates: null livemode: null proration: null required: - customer x-apifox-orders: - 01HC72W96QYQJNHVZVESB4KZ3A - price_data - pending_invoice_items_behavior properties: amount: type: integer description: >- Amount (in the currency specified) of the invoice item. This should always be equal to unit_amount * quantity. currency: type: string description: Three-letter ISO currency code customer: *ref_0 description: type: string description: >- An arbitrary string attached to the object. Often useful for displaying to users. metadata: type: object properties: {} description: Set of key-value pairs that you can attach to an object. x-apifox-orders: [] x-apifox-ignore-properties: [] period: *ref_1 price: type: object x-apifox-refs: 01HC6W63CA87BWB46BAWMWWCQC: &ref_2 $ref: '#/components/schemas/Price' x-apifox-overrides: transform_quantity: null tiers_mode: null tax_behavior: null custom_unit_amount: null unit_amount_decimal: null x-apifox-orders: - 01HC6W63CA87BWB46BAWMWWCQC properties: id: type: string description: Unique identifier for the object, like "price_xxxx". object: type: string description: '''price''' active: type: boolean description: Whether the price can be used for new purchases. billing_scheme: type: string description: >- Describes how to compute the price per period. Either per_unit or tiered enum: - per_unit - tiered x-apifox-enum: - value: per_unit name: '' description: only per_unit is supported now. - value: tiered name: '' description: '' created: type: integer description: >- Time at which the object was created. Measured in seconds since the Unix epoch. currency: type: string description: 'Three-letter ISO currency code, in uppercase. ' livemode: type: boolean description: >- Has the value true if the object exists in live mode or the value false if the object exists in test mode. lookup_key: type: string description: >- A lookup key used to retrieve prices dynamically from a static string. This may be up to 200 characters. metadata: type: object properties: {} x-apifox-orders: [] description: >- Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. x-apifox-ignore-properties: [] nickname: type: string description: A brief description of the price, hidden from customers. product: type: string description: The ID of the product this price is associated with. type: type: string description: >- One of one_time or recurring depending on whether the price is for a one-time purchase or a recurring (subscription) purchase. enum: - one_time - recurring x-apifox-enum: - value: one_time name: '' description: only one-time is supported now. - value: recurring name: '' description: '' unit_amount: type: integer description: >- The unit amount in cents to be charged, represented as a whole integer if possible. Only set if billing_scheme=per_unit. recurring: type: object properties: interval: type: string description: >- The frequency at which a subscription is billed. One of day, week, month or year. enum: - day - week - month - year x-apifox-enum: - value: day name: '' description: '' - value: week name: '' description: '' - value: month name: '' description: '' - value: year name: '' description: '' interval_count: type: integer description: >- The number of intervals (specified in the interval attribute) between subscription billings. For example, interval=month and interval_count=3 bills every 3 months. usage_type: type: string description: >- Configures how the quantity per period should be determined. enum: - licensed x-apifox-enum: - value: licensed name: '' description: '' x-apifox-orders: - interval - interval_count - usage_type description: The recurring components of a price required: - interval x-apifox-ignore-properties: [] tiers: &ref_3 type: array items: type: object properties: up_to: type: string description: >- Specifies the upper bound of this tier. The lower bound of a tier is the upper bound of the previous tier adding one. Use inf to define a fallback tier. flat_amount: type: string description: >- The flat billing amount for an entire tier, regardless of the number of units in the tier. unit_amount: type: string description: >- The per unit billing amount for each individual unit for which this tier applies. x-apifox-orders: - up_to - flat_amount - unit_amount x-apifox-ignore-properties: [] description: （未实现） description: The ID of the price object. x-apifox-ignore-properties: - id - object - active - billing_scheme - created - currency - livemode - lookup_key - metadata - nickname - product - type - unit_amount - recurring - tiers date: type: string description: >- Time at which the object was created. Measured in seconds since the Unix epoch. invoice: type: string description: >- The ID of an existing invoice to add this invoice item to. When left blank, the invoice item will be added to the next upcoming scheduled invoice. This is useful when adding invoice items in response to an invoice.created webhook. You can only add invoice items to draft invoices and there is a maximum of 250 items per invoice. quantity: type: integer description: >- The quantity of the subscription, if the line item is a subscription or a proration. subscription: type: string description: >- The ID of a subscription to add this invoice item to. When left blank, the invoice item will be be added to the next upcoming scheduled invoice. When set, scheduled invoices for subscriptions other than the specified subscription will ignore the invoice item. Use this when you want to express that an invoice item has been accrued within the context of a particular subscription. unit_amount: type: integer description: >- The integer unit amount in pence of the charge to be applied to the upcoming invoice. This unit_amount will be multiplied by the quantity to get the full amount. Passing in a negative unit_amount will reduce the amount_due on the invoice. test_clock: type: string description: ID of the test clock this invoice item belongs to. price_data: type: object x-apifox-refs: 01HC7343E86XX9FJB2YQ8P5Q3M: *ref_2 x-apifox-orders: - 01HC7343E86XX9FJB2YQ8P5Q3M properties: currency: type: string description: 'Three-letter ISO currency code, in lowercase. ' product: type: string description: The ID of the product this price is associated with. unit_amount: type: integer description: >- A positive integer in pence (or 0 for a free price) representing how much to charge. tiers: *ref_3 required: - currency - product x-apifox-ignore-properties: - currency - product - unit_amount - tiers pending_invoice_items_behavior: type: string description: >- How to handle pending invoice items on invoice creation. One of include or exclude. include will include any pending invoice items, and will create an empty draft invoice if no pending invoice items exist. exclude will always create an empty invoice draft regardless if there are pending invoice items or not. Defaults to exclude if the parameter is omitted. required: - customer x-apifox-ignore-properties: - amount - currency - customer - description - metadata - period - price - date - invoice - quantity - subscription - unit_amount - test_clock responses: '200': description: '' content: application/json: schema: type: object x-apifox-refs: 01HC749DKRARJEKRK2WSR55NAY: *ref_4 x-apifox-orders: - 01HC749DKRARJEKRK2WSR55NAY properties: id: type: string description: Unique identifier for the object. object: type: string description: '"invoiceitem"' amount: type: integer description: >- Amount (in the currency specified) of the invoice item. This should always be equal to unit_amount * quantity. currency: type: string description: Three-letter ISO currency code customer: type: string description: >- The ID of the customer who will be billed when this invoice item is billed. description: type: string description: >- An arbitrary string attached to the object. Often useful for displaying to users. metadata: type: object properties: {} description: Set of key-value pairs that you can attach to an object. x-apifox-orders: [] x-apifox-ignore-properties: [] period: type: object properties: end: type: string description: >- timestamp.The end of the period, which must be greater than or equal to the start. This value is inclusive. start: type: string description: >- timestamp. The start of the period. This value is inclusive. x-apifox-orders: - end - start description: >- The period associated with this invoice item. When set to different values, the period will be rendered on the invoice. x-apifox-ignore-properties: [] price: type: object x-apifox-refs: 01HC6W63CA87BWB46BAWMWWCQC: x-apifox-overrides: transform_quantity: null tiers_mode: null tax_behavior: null custom_unit_amount: null unit_amount_decimal: null type: object properties: {} x-apifox-orders: - 01HC6W63CA87BWB46BAWMWWCQC properties: id: type: string description: Unique identifier for the object, like "price_xxxx". object: type: string description: '''price''' active: type: boolean description: Whether the price can be used for new purchases. billing_scheme: type: string description: >- Describes how to compute the price per period. Either per_unit or tiered enum: - per_unit - tiered x-apifox-enum: - value: per_unit name: '' description: only per_unit is supported now. - value: tiered name: '' description: '' created: type: integer description: >- Time at which the object was created. Measured in seconds since the Unix epoch. currency: type: string description: 'Three-letter ISO currency code, in uppercase. ' livemode: type: boolean description: >- Has the value true if the object exists in live mode or the value false if the object exists in test mode. lookup_key: type: string description: >- A lookup key used to retrieve prices dynamically from a static string. This may be up to 200 characters. metadata: type: object properties: {} x-apifox-orders: [] description: >- Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. x-apifox-ignore-properties: [] nickname: type: string description: >- A brief description of the price, hidden from customers. product: type: string description: The ID of the product this price is associated with. type: type: string description: >- One of one_time or recurring depending on whether the price is for a one-time purchase or a recurring (subscription) purchase. enum: - one_time - recurring x-apifox-enum: - value: one_time name: '' description: only one-time is supported now. - value: recurring name: '' description: '' unit_amount: type: integer description: >- The unit amount in cents to be charged, represented as a whole integer if possible. Only set if billing_scheme=per_unit. recurring: type: object properties: interval: type: string description: >- The frequency at which a subscription is billed. One of day, week, month or year. enum: - day - week - month - year x-apifox-enum: - value: day name: '' description: '' - value: week name: '' description: '' - value: month name: '' description: '' - value: year name: '' description: '' interval_count: type: integer description: >- The number of intervals (specified in the interval attribute) between subscription billings. For example, interval=month and interval_count=3 bills every 3 months. usage_type: type: string description: >- Configures how the quantity per period should be determined. enum: - licensed x-apifox-enum: - value: licensed name: '' description: '' x-apifox-orders: - interval - interval_count - usage_type description: The recurring components of a price required: - interval x-apifox-ignore-properties: [] tiers: type: array items: type: object properties: up_to: type: string description: >- Specifies the upper bound of this tier. The lower bound of a tier is the upper bound of the previous tier adding one. Use inf to define a fallback tier. flat_amount: type: string description: >- The flat billing amount for an entire tier, regardless of the number of units in the tier. unit_amount: type: string description: >- The per unit billing amount for each individual unit for which this tier applies. x-apifox-orders: - up_to - flat_amount - unit_amount x-apifox-ignore-properties: [] description: （未实现） description: The ID of the price object. x-apifox-ignore-properties: - id - object - active - billing_scheme - created - currency - livemode - lookup_key - metadata - nickname - product - type - unit_amount - recurring - tiers date: type: string description: >- Time at which the object was created. Measured in seconds since the Unix epoch. invoice: type: string description: >- The ID of an existing invoice to add this invoice item to. When left blank, the invoice item will be added to the next upcoming scheduled invoice. This is useful when adding invoice items in response to an invoice.created webhook. You can only add invoice items to draft invoices and there is a maximum of 250 items per invoice. livemode: type: boolean description: >- Has the value true if the object exists in live mode or the value false if the object exists in test mode. quantity: type: integer description: >- The quantity of the subscription, if the line item is a subscription or a proration. subscription: type: string description: >- The ID of a subscription to add this invoice item to. When left blank, the invoice item will be be added to the next upcoming scheduled invoice. When set, scheduled invoices for subscriptions other than the specified subscription will ignore the invoice item. Use this when you want to express that an invoice item has been accrued within the context of a particular subscription. unit_amount: type: integer description: >- The integer unit amount in pence of the charge to be applied to the upcoming invoice. This unit_amount will be multiplied by the quantity to get the full amount. Passing in a negative unit_amount will reduce the amount_due on the invoice. test_clock: type: string description: ID of the test clock this invoice item belongs to. x-apifox-ignore-properties: - id - object - amount - currency - customer - description - metadata - period - price - date - invoice - livemode - quantity - subscription - unit_amount - test_clock headers: {} x-apifox-name: OK security: - basic: [] x-apifox-folder: API Reference/Invoice Items x-apifox-status: developing x-run-in-apifox: https://app.apifox.com/web/project/1296482/apis/api-114858716-run components: schemas: Price: type: object properties: id: &ref_5 type: string description: Unique identifier for the object, like "price_xxxx". object: &ref_6 type: string description: '''price''' active: &ref_7 type: boolean description: Whether the price can be used for new purchases. billing_scheme: type: string description: >- Describes how to compute the price per period. Either per_unit or tiered enum: &ref_8 - per_unit - tiered x-apifox-enum: - value: per_unit name: '' description: only per_unit is supported now. - value: tiered name: '' description: '' created: &ref_9 type: integer description: >- Time at which the object was created. Measured in seconds since the Unix epoch. currency: &ref_10 type: string description: 'Three-letter ISO currency code, in uppercase. ' livemode: &ref_11 type: boolean description: >- Has the value true if the object exists in live mode or the value false if the object exists in test mode. lookup_key: &ref_12 type: string description: >- A lookup key used to retrieve prices dynamically from a static string. This may be up to 200 characters. metadata: type: object properties: {} x-apifox-orders: &ref_13 [] description: >- Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. x-apifox-ignore-properties: [] nickname: &ref_14 type: string description: A brief description of the price, hidden from customers. product: &ref_15 type: string description: The ID of the product this price is associated with. type: type: string description: >- One of one_time or recurring depending on whether the price is for a one-time purchase or a recurring (subscription) purchase. enum: &ref_16 - one_time - recurring x-apifox-enum: - value: one_time name: '' description: only one-time is supported now. - value: recurring name: '' description: '' unit_amount: &ref_17 type: integer description: >- The unit amount in cents to be charged, represented as a whole integer if possible. Only set if billing_scheme=per_unit. custom_unit_amount: type: 'null' description: （未实现） recurring: type: object properties: interval: type: string description: >- The frequency at which a subscription is billed. One of day, week, month or year. enum: &ref_18 - day - week - month - year x-apifox-enum: - value: day name: '' description: '' - value: week name: '' description: '' - value: month name: '' description: '' - value: year name: '' description: '' interval_count: &ref_19 type: integer description: >- The number of intervals (specified in the interval attribute) between subscription billings. For example, interval=month and interval_count=3 bills every 3 months. usage_type: type: string description: Configures how the quantity per period should be determined. enum: &ref_20 - licensed x-apifox-enum: - value: licensed name: '' description: '' x-apifox-orders: &ref_21 - interval - interval_count - usage_type description: The recurring components of a price required: - interval x-apifox-ignore-properties: [] tax_behavior: type: string description: （未实现） tiers_mode: type: 'null' description: （未实现） tiers: type: array items: type: object properties: up_to: &ref_22 type: string description: >- Specifies the upper bound of this tier. The lower bound of a tier is the upper bound of the previous tier adding one. Use inf to define a fallback tier. flat_amount: &ref_23 type: string description: >- The flat billing amount for an entire tier, regardless of the number of units in the tier. unit_amount: &ref_24 type: string description: >- The per unit billing amount for each individual unit for which this tier applies. x-apifox-orders: &ref_25 - up_to - flat_amount - unit_amount x-apifox-ignore-properties: [] description: （未实现） transform_quantity: type: 'null' description: （未实现） unit_amount_decimal: type: string description: （未实现） x-apifox-orders: - id - object - active - billing_scheme - created - currency - livemode - lookup_key - metadata - nickname - product - type - unit_amount - custom_unit_amount - recurring - tax_behavior - tiers_mode - tiers - transform_quantity - unit_amount_decimal x-apifox-ignore-properties: [] x-apifox-folder: '' Invoice item: type: object properties: id: type: string description: Unique identifier for the object. object: type: string description: '"invoiceitem"' amount: type: integer description: >- Amount (in the currency specified) of the invoice item. This should always be equal to unit_amount * quantity. currency: type: string description: Three-letter ISO currency code customer: type: string description: >- The ID of the customer who will be billed when this invoice item is billed. description: type: string description: >- An arbitrary string attached to the object. Often useful for displaying to users. metadata: type: object properties: {} description: Set of key-value pairs that you can attach to an object. x-apifox-orders: [] x-apifox-ignore-properties: [] period: type: object properties: end: type: string description: >- timestamp.The end of the period, which must be greater than or equal to the start. This value is inclusive. start: type: string description: timestamp. The start of the period. This value is inclusive. x-apifox-orders: - end - start description: >- The period associated with this invoice item. When set to different values, the period will be rendered on the invoice. x-apifox-ignore-properties: [] price: type: object x-apifox-refs: 01HC6W63CA87BWB46BAWMWWCQC: *ref_2 x-apifox-orders: - 01HC6W63CA87BWB46BAWMWWCQC properties: id: *ref_5 object: *ref_6 active: *ref_7 billing_scheme: type: string description: >- Describes how to compute the price per period. Either per_unit or tiered enum: *ref_8 x-apifox-enum: - value: per_unit name: '' description: only per_unit is supported now. - value: tiered name: '' description: '' created: *ref_9 currency: *ref_10 livemode: *ref_11 lookup_key: *ref_12 metadata: type: object properties: {} x-apifox-orders: *ref_13 description: >- Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. x-apifox-ignore-properties: [] nickname: *ref_14 product: *ref_15 type: type: string description: >- One of one_time or recurring depending on whether the price is for a one-time purchase or a recurring (subscription) purchase. enum: *ref_16 x-apifox-enum: - value: one_time name: '' description: only one-time is supported now. - value: recurring name: '' description: '' unit_amount: *ref_17 recurring: type: object properties: interval: type: string description: >- The frequency at which a subscription is billed. One of day, week, month or year. enum: *ref_18 x-apifox-enum: - value: day name: '' description: '' - value: week name: '' description: '' - value: month name: '' description: '' - value: year name: '' description: '' interval_count: *ref_19 usage_type: type: string description: Configures how the quantity per period should be determined. enum: *ref_20 x-apifox-enum: - value: licensed name: '' description: '' x-apifox-orders: *ref_21 description: The recurring components of a price required: - interval x-apifox-ignore-properties: [] tiers: type: array items: type: object properties: up_to: *ref_22 flat_amount: *ref_23 unit_amount: *ref_24 x-apifox-orders: *ref_25 x-apifox-ignore-properties: [] description: （未实现） description: The ID of the price object. x-apifox-ignore-properties: - id - object - active - billing_scheme - created - currency - livemode - lookup_key - metadata - nickname - product - type - unit_amount - recurring - tiers date: type: string description: >- Time at which the object was created. Measured in seconds since the Unix epoch. invoice: type: string description: >- The ID of an existing invoice to add this invoice item to. When left blank, the invoice item will be added to the next upcoming scheduled invoice. This is useful when adding invoice items in response to an invoice.created webhook. You can only add invoice items to draft invoices and there is a maximum of 250 items per invoice. livemode: type: boolean description: >- Has the value true if the object exists in live mode or the value false if the object exists in test mode. quantity: type: integer description: >- The quantity of the subscription, if the line item is a subscription or a proration. subscription: type: string description: >- The ID of a subscription to add this invoice item to. When left blank, the invoice item will be be added to the next upcoming scheduled invoice. When set, scheduled invoices for subscriptions other than the specified subscription will ignore the invoice item. Use this when you want to express that an invoice item has been accrued within the context of a particular subscription. unit_amount: type: integer description: >- The integer unit amount in pence of the charge to be applied to the upcoming invoice. This unit_amount will be multiplied by the quantity to get the full amount. Passing in a negative unit_amount will reduce the amount_due on the invoice. test_clock: type: string description: ID of the test clock this invoice item belongs to. proration: type: boolean deprecated: true description: >- Whether the invoice item was created automatically as a proration adjustment when the customer switched plans. tax_rates: type: string description: 未完成 deprecated: true discountable: type: string description: 未完成 deprecated: true discounts: type: string description: 未完成 deprecated: true unit_amount_decimal: type: string description: 未完成 deprecated: true x-apifox-refs: {} x-apifox-orders: - id - object - amount - currency - customer - description - metadata - period - price - date - invoice - livemode - quantity - subscription - unit_amount - test_clock - proration - tax_rates - discountable - discounts - unit_amount_decimal x-apifox-ignore-properties: [] x-apifox-folder: '' securitySchemes: basic: type: http scheme: basic servers: - url: https://apitest.wooshpay.com description: 官网测试 security: - basic: [] ```