--- updatedAt: 2026-08-28T04:13:35.000Z agentTools: projectIndex: https://docs.gettrx.com/llms.txt --- # Void an Invoice Voids an invoice by ID only when its status is `open`. Invoices in any other status (draft, paid, voided, uncollectible, etc.) cannot be voided. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "onboarding", "version": "1.0" }, "servers": [ { "url": "https://api-dev.gettrx.com/onboard/v1/" } ], "components": { "securitySchemes": { "sec0": { "type": "apiKey", "in": "header", "name": "secretKey" } } }, "security": [ { "sec0": [] } ], "paths": { "/invoices/{invoiceId}/void": { "post": { "tags": [ "Invoices" ], "summary": "Void an Invoice", "description": "Voids an invoice by ID only when its status is `open`. Invoices in any other status (draft, paid, voided, uncollectible, etc.) cannot be voided. ", "operationId": "postInvoiceVoid", "parameters": [ { "name": "invoiceId", "in": "path", "description": "Invoice ID (e.g. inv_a11YYufWQzNY63zpQ6QSNRQhkUpVph4WRmzW0zWJO2znZKdVujZ0N0S22u). Must be valid, not soft deleted, and belong to the merchant account. ", "required": true, "schema": { "maxLength": 128, "minLength": 10, "type": "string" } }, { "name": "secretKey", "in": "header", "description": "Secret key associated to the partner's account", "required": true, "schema": { "type": "string" } }, { "name": "onBehalfOf", "in": "header", "description": "(Optional) AccountId of the merchant. Only required when secretKey belongs to an \"entity\" account. ", "required": false, "schema": { "type": "string" } }, { "name": "requestId", "in": "header", "description": "Unique Key String refNumber", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK **Response Codes:** - ED999: System error occurred. Please contact the system administrator. - ED101: The value %s of element %s is not valid. - ED109: Merchant Authentication failed, please use valid credentials. - ED138: Merchant not found ", "content": { "application/json": { "schema": { "required": [ "code", "message", "success" ], "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "format": "int32", "example": 200 }, "message": { "type": "string", "example": "Invoice retrieved successfully." }, "errorType": { "type": "string", "description": "Error classification. Present only when pay-invoice fails with a payment error." }, "errorCode": { "type": "string", "description": "Specific error code identifying the failure reason. Present only on payment error." }, "declineCode": { "type": "string", "description": "Decline code from the payment processor. Present only on payment error." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Invoice identifier", "example": "inv_a11YYufWQzNY63zpQ6QSNRQh" }, "accountId": { "type": "string" }, "created": { "type": "integer", "format": "int64", "example": 1679600215 }, "periodStart": { "type": "integer", "format": "int64" }, "periodEnd": { "type": "integer", "format": "int64" }, "invoiceNumber": { "type": "string" }, "status": { "type": "string", "description": "Current status of the invoice", "example": "open" }, "finalizedOn": { "type": "integer", "format": "int64" }, "autoFinalizeAt": { "type": "integer", "format": "int64" }, "autoSendInvoiceAt": { "type": "integer", "format": "int64" }, "autoAdvance": { "type": "boolean" }, "dueDate": { "type": "integer", "format": "int64" }, "isPastDue": { "type": "boolean" }, "paidOn": { "type": "integer", "format": "int64" }, "voidedOn": { "type": "integer", "format": "int64" }, "markedUncollectibleOn": { "type": "integer", "format": "int64" }, "billingReason": { "type": "string", "example": "manual" }, "subscriptionInvoiceType": { "type": "string" }, "subscription": { "type": "string" }, "collectionMethod": { "type": "string" }, "externalReferenceId": { "type": "string" }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } } } }, "hostedInvoiceUrl": { "type": "string" }, "pdfInvoiceUrl": { "type": "string" }, "customer": { "type": "object", "description": "Customer id or full customer details from DynamoDB when `expand` includes `customer` (id when not expanded; full object when expanded — same semantics as `defaultPaymentMethod`). " }, "customerEmail": { "type": "string" }, "customerName": { "type": "string" }, "customerPhone": { "type": "string" }, "customerAddress": { "type": "object", "properties": { "line1": { "type": "string" }, "line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "postalCode": { "type": "string" } } }, "shippingDetails": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "address": { "type": "object", "properties": { "line1": { "type": "string" }, "line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "postalCode": { "type": "string" } } } } }, "amountSubtotal": { "type": "number", "example": 2000 }, "totalAmountToBeCharged": { "type": "object", "properties": { "card": { "type": "object", "properties": { "total": { "type": "number" }, "details": { "type": "object", "properties": { "subtotal": { "type": "number" }, "amountFees": { "type": "number" }, "amountDiscount": { "type": "number" }, "amountShipping": { "type": "number" }, "amountTax": { "type": "number" } } } } }, "usBankAccount": { "type": "object", "properties": { "total": { "type": "number" }, "details": { "type": "object", "properties": { "subtotal": { "type": "number" }, "amountFees": { "type": "number" }, "amountDiscount": { "type": "number" }, "amountShipping": { "type": "number" }, "amountTax": { "type": "number" } } } } } } }, "partialAmountsToBeCharged": { "type": "object" }, "amountDue": { "type": "number", "example": 0 }, "amountPaid": { "type": "number", "example": 0 }, "feesPaid": { "type": "number" }, "discountsApplied": { "type": "number" }, "amountRemaining": { "type": "number" }, "attempted": { "type": "boolean" }, "nextPaymentAttempt": { "type": "integer", "format": "int64" }, "currency": { "type": "string", "example": "usd" }, "paymentMethodTypes": { "type": "array", "items": { "type": "string" } }, "paymentWallets": { "type": "object", "properties": { "applePay": { "type": "string" }, "googlePay": { "type": "string" } } }, "defaultPaymentMethod": { "type": "object", "description": "Payment method id or full payment method details; same semantics as GET subscription `defaultPaymentMethod`. " }, "accountFeeAndDiscountDisplayLayout": { "type": "string" }, "accountFees": { "type": "object", "properties": { "fees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "string" }, "percentage": { "type": "string" }, "appliesTo": { "type": "string" }, "removable": { "type": "string" } } } } } }, "accountDiscounts": { "type": "object", "properties": { "discounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "string" }, "percentage": { "type": "string" }, "appliesTo": { "type": "string" }, "removable": { "type": "string" } } } } } }, "lineItemsGroup": { "type": "object", "properties": { "currency": { "type": "string", "example": "usd" }, "subtotal": { "type": "number" }, "shippingRate": { "type": "number" }, "totalAccountDiscounts": { "type": "array", "items": { "type": "object" } }, "totalAccountFees": { "type": "array", "items": { "type": "object" } }, "dualPricingAmounts": { "type": "object", "properties": { "expectedCardFeeAmountTotal": { "type": "number" }, "expectedCardDiscountAmountTotal": { "type": "number" }, "expectedCardAmountTotal": { "type": "number" }, "expectedACHFeeAmountTotal": { "type": "number" }, "expectedACHDiscountAmountTotal": { "type": "number" }, "expectedACHAmountTotal": { "type": "number" } } }, "invoiceLineItems": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "urlPath": { "type": "string", "description": "Path template for additional line items; replace `{invoiceId}` with the actual invoice id in responses. ", "example": "/invoice/inv_a11YYufWQzNY63zpQ6QSNRQhkUpVph4WRmzW0zWJO2znZKdVujZ0N0S22u/invoice-line-items" }, "retrieved": { "type": "integer", "description": "Number of line items returned in this payload", "format": "int32" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "ili_690522278211cd51c8239b58" }, "invoiceId": { "type": "string", "description": "Parent invoice id (present on list invoice line items responses)" }, "accountId": { "type": "string", "description": "Merchant account id (present on list invoice line items responses)" }, "productName": { "type": "string" }, "productDescription": { "type": "string", "description": "Product description for the line item (customizable for display)." }, "price": { "type": "object", "description": "Price id string when not expanded; full price object when expanded (same idea as subscription `site`)." }, "accountDiscounts": { "type": "object", "description": "Id string, array of id strings, or full objects when accountDiscounts path is expanded." }, "accountFees": { "type": "object", "description": "Id string, array of id strings, or full objects when accountFees path is expanded." }, "unitAmountOverride": { "type": "string" }, "unitPriceOverride": { "type": "string", "description": "Override used for proration and similar scenarios." }, "unitPrice": { "type": "number", "description": "Effective unit price from unitPriceOverride, unitAmountOverride, or price.amount as applicable." }, "quantity": { "type": "integer", "format": "int32" }, "amountSubtotal": { "type": "number" }, "amountTax": { "type": "number" }, "currency": { "type": "string" }, "dualPricingAmounts": { "type": "object", "properties": { "expectedCardDiscountAmountLineTotal": { "type": "number" }, "expectedCardFeeAmountLineTotal": { "type": "number" }, "expectedCardAmountLineTotal": { "type": "number" }, "expectedACHDiscountAmountLineTotal": { "type": "number" }, "expectedACHFeeAmountLineTotal": { "type": "number" }, "expectedACHAmountLineTotal": { "type": "number" } } }, "object": { "type": "string", "example": "item" } } } } } } } }, "testClock": { "type": "object", "description": "Expanded test clock object. Only present when `expand` includes `test_clock` on GET /invoices/{invoiceId} and the invoice's subscription has an associated test clock. " }, "initialPaymentErrorDetails": { "type": "object", "properties": { "paymentRequest": { "type": "object", "description": "The failed payment request returned by the payment processor." } }, "description": "Payment processor failure details for pay-invoice. Present only when the response `errorType` indicates a payment error. " }, "object": { "type": "string", "example": "invoice" } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "required": [ "code", "message", "success" ], "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "format": "int32", "example": 200 }, "message": { "type": "string", "example": "Invoice retrieved successfully." }, "errorType": { "type": "string", "description": "Error classification. Present only when pay-invoice fails with a payment error." }, "errorCode": { "type": "string", "description": "Specific error code identifying the failure reason. Present only on payment error." }, "declineCode": { "type": "string", "description": "Decline code from the payment processor. Present only on payment error." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Invoice identifier", "example": "inv_a11YYufWQzNY63zpQ6QSNRQh" }, "accountId": { "type": "string" }, "created": { "type": "integer", "format": "int64", "example": 1679600215 }, "periodStart": { "type": "integer", "format": "int64" }, "periodEnd": { "type": "integer", "format": "int64" }, "invoiceNumber": { "type": "string" }, "status": { "type": "string", "description": "Current status of the invoice", "example": "open" }, "finalizedOn": { "type": "integer", "format": "int64" }, "autoFinalizeAt": { "type": "integer", "format": "int64" }, "autoSendInvoiceAt": { "type": "integer", "format": "int64" }, "autoAdvance": { "type": "boolean" }, "dueDate": { "type": "integer", "format": "int64" }, "isPastDue": { "type": "boolean" }, "paidOn": { "type": "integer", "format": "int64" }, "voidedOn": { "type": "integer", "format": "int64" }, "markedUncollectibleOn": { "type": "integer", "format": "int64" }, "billingReason": { "type": "string", "example": "manual" }, "subscriptionInvoiceType": { "type": "string" }, "subscription": { "type": "string" }, "collectionMethod": { "type": "string" }, "externalReferenceId": { "type": "string" }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } } } }, "hostedInvoiceUrl": { "type": "string" }, "pdfInvoiceUrl": { "type": "string" }, "customer": { "type": "object", "description": "Customer id or full customer details from DynamoDB when `expand` includes `customer` (id when not expanded; full object when expanded — same semantics as `defaultPaymentMethod`). " }, "customerEmail": { "type": "string" }, "customerName": { "type": "string" }, "customerPhone": { "type": "string" }, "customerAddress": { "type": "object", "properties": { "line1": { "type": "string" }, "line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "postalCode": { "type": "string" } } }, "shippingDetails": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "address": { "type": "object", "properties": { "line1": { "type": "string" }, "line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "postalCode": { "type": "string" } } } } }, "amountSubtotal": { "type": "number", "example": 2000 }, "totalAmountToBeCharged": { "type": "object", "properties": { "card": { "type": "object", "properties": { "total": { "type": "number" }, "details": { "type": "object", "properties": { "subtotal": { "type": "number" }, "amountFees": { "type": "number" }, "amountDiscount": { "type": "number" }, "amountShipping": { "type": "number" }, "amountTax": { "type": "number" } } } } }, "usBankAccount": { "type": "object", "properties": { "total": { "type": "number" }, "details": { "type": "object", "properties": { "subtotal": { "type": "number" }, "amountFees": { "type": "number" }, "amountDiscount": { "type": "number" }, "amountShipping": { "type": "number" }, "amountTax": { "type": "number" } } } } } } }, "partialAmountsToBeCharged": { "type": "object" }, "amountDue": { "type": "number", "example": 0 }, "amountPaid": { "type": "number", "example": 0 }, "feesPaid": { "type": "number" }, "discountsApplied": { "type": "number" }, "amountRemaining": { "type": "number" }, "attempted": { "type": "boolean" }, "nextPaymentAttempt": { "type": "integer", "format": "int64" }, "currency": { "type": "string", "example": "usd" }, "paymentMethodTypes": { "type": "array", "items": { "type": "string" } }, "paymentWallets": { "type": "object", "properties": { "applePay": { "type": "string" }, "googlePay": { "type": "string" } } }, "defaultPaymentMethod": { "type": "object", "description": "Payment method id or full payment method details; same semantics as GET subscription `defaultPaymentMethod`. " }, "accountFeeAndDiscountDisplayLayout": { "type": "string" }, "accountFees": { "type": "object", "properties": { "fees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "string" }, "percentage": { "type": "string" }, "appliesTo": { "type": "string" }, "removable": { "type": "string" } } } } } }, "accountDiscounts": { "type": "object", "properties": { "discounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "string" }, "percentage": { "type": "string" }, "appliesTo": { "type": "string" }, "removable": { "type": "string" } } } } } }, "lineItemsGroup": { "type": "object", "properties": { "currency": { "type": "string", "example": "usd" }, "subtotal": { "type": "number" }, "shippingRate": { "type": "number" }, "totalAccountDiscounts": { "type": "array", "items": { "type": "object" } }, "totalAccountFees": { "type": "array", "items": { "type": "object" } }, "dualPricingAmounts": { "type": "object", "properties": { "expectedCardFeeAmountTotal": { "type": "number" }, "expectedCardDiscountAmountTotal": { "type": "number" }, "expectedCardAmountTotal": { "type": "number" }, "expectedACHFeeAmountTotal": { "type": "number" }, "expectedACHDiscountAmountTotal": { "type": "number" }, "expectedACHAmountTotal": { "type": "number" } } }, "invoiceLineItems": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "urlPath": { "type": "string", "description": "Path template for additional line items; replace `{invoiceId}` with the actual invoice id in responses. ", "example": "/invoice/inv_a11YYufWQzNY63zpQ6QSNRQhkUpVph4WRmzW0zWJO2znZKdVujZ0N0S22u/invoice-line-items" }, "retrieved": { "type": "integer", "description": "Number of line items returned in this payload", "format": "int32" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "ili_690522278211cd51c8239b58" }, "invoiceId": { "type": "string", "description": "Parent invoice id (present on list invoice line items responses)" }, "accountId": { "type": "string", "description": "Merchant account id (present on list invoice line items responses)" }, "productName": { "type": "string" }, "productDescription": { "type": "string", "description": "Product description for the line item (customizable for display)." }, "price": { "type": "object", "description": "Price id string when not expanded; full price object when expanded (same idea as subscription `site`)." }, "accountDiscounts": { "type": "object", "description": "Id string, array of id strings, or full objects when accountDiscounts path is expanded." }, "accountFees": { "type": "object", "description": "Id string, array of id strings, or full objects when accountFees path is expanded." }, "unitAmountOverride": { "type": "string" }, "unitPriceOverride": { "type": "string", "description": "Override used for proration and similar scenarios." }, "unitPrice": { "type": "number", "description": "Effective unit price from unitPriceOverride, unitAmountOverride, or price.amount as applicable." }, "quantity": { "type": "integer", "format": "int32" }, "amountSubtotal": { "type": "number" }, "amountTax": { "type": "number" }, "currency": { "type": "string" }, "dualPricingAmounts": { "type": "object", "properties": { "expectedCardDiscountAmountLineTotal": { "type": "number" }, "expectedCardFeeAmountLineTotal": { "type": "number" }, "expectedCardAmountLineTotal": { "type": "number" }, "expectedACHDiscountAmountLineTotal": { "type": "number" }, "expectedACHFeeAmountLineTotal": { "type": "number" }, "expectedACHAmountLineTotal": { "type": "number" } } }, "object": { "type": "string", "example": "item" } } } } } } } }, "testClock": { "type": "object", "description": "Expanded test clock object. Only present when `expand` includes `test_clock` on GET /invoices/{invoiceId} and the invoice's subscription has an associated test clock. " }, "initialPaymentErrorDetails": { "type": "object", "properties": { "paymentRequest": { "type": "object", "description": "The failed payment request returned by the payment processor." } }, "description": "Payment processor failure details for pay-invoice. Present only when the response `errorType` indicates a payment error. " }, "object": { "type": "string", "example": "invoice" } } } } } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "required": [ "code", "message", "success" ], "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "format": "int32", "example": 200 }, "message": { "type": "string", "example": "Invoice retrieved successfully." }, "errorType": { "type": "string", "description": "Error classification. Present only when pay-invoice fails with a payment error." }, "errorCode": { "type": "string", "description": "Specific error code identifying the failure reason. Present only on payment error." }, "declineCode": { "type": "string", "description": "Decline code from the payment processor. Present only on payment error." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Invoice identifier", "example": "inv_a11YYufWQzNY63zpQ6QSNRQh" }, "accountId": { "type": "string" }, "created": { "type": "integer", "format": "int64", "example": 1679600215 }, "periodStart": { "type": "integer", "format": "int64" }, "periodEnd": { "type": "integer", "format": "int64" }, "invoiceNumber": { "type": "string" }, "status": { "type": "string", "description": "Current status of the invoice", "example": "open" }, "finalizedOn": { "type": "integer", "format": "int64" }, "autoFinalizeAt": { "type": "integer", "format": "int64" }, "autoSendInvoiceAt": { "type": "integer", "format": "int64" }, "autoAdvance": { "type": "boolean" }, "dueDate": { "type": "integer", "format": "int64" }, "isPastDue": { "type": "boolean" }, "paidOn": { "type": "integer", "format": "int64" }, "voidedOn": { "type": "integer", "format": "int64" }, "markedUncollectibleOn": { "type": "integer", "format": "int64" }, "billingReason": { "type": "string", "example": "manual" }, "subscriptionInvoiceType": { "type": "string" }, "subscription": { "type": "string" }, "collectionMethod": { "type": "string" }, "externalReferenceId": { "type": "string" }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } } } }, "hostedInvoiceUrl": { "type": "string" }, "pdfInvoiceUrl": { "type": "string" }, "customer": { "type": "object", "description": "Customer id or full customer details from DynamoDB when `expand` includes `customer` (id when not expanded; full object when expanded — same semantics as `defaultPaymentMethod`). " }, "customerEmail": { "type": "string" }, "customerName": { "type": "string" }, "customerPhone": { "type": "string" }, "customerAddress": { "type": "object", "properties": { "line1": { "type": "string" }, "line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "postalCode": { "type": "string" } } }, "shippingDetails": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "address": { "type": "object", "properties": { "line1": { "type": "string" }, "line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "postalCode": { "type": "string" } } } } }, "amountSubtotal": { "type": "number", "example": 2000 }, "totalAmountToBeCharged": { "type": "object", "properties": { "card": { "type": "object", "properties": { "total": { "type": "number" }, "details": { "type": "object", "properties": { "subtotal": { "type": "number" }, "amountFees": { "type": "number" }, "amountDiscount": { "type": "number" }, "amountShipping": { "type": "number" }, "amountTax": { "type": "number" } } } } }, "usBankAccount": { "type": "object", "properties": { "total": { "type": "number" }, "details": { "type": "object", "properties": { "subtotal": { "type": "number" }, "amountFees": { "type": "number" }, "amountDiscount": { "type": "number" }, "amountShipping": { "type": "number" }, "amountTax": { "type": "number" } } } } } } }, "partialAmountsToBeCharged": { "type": "object" }, "amountDue": { "type": "number", "example": 0 }, "amountPaid": { "type": "number", "example": 0 }, "feesPaid": { "type": "number" }, "discountsApplied": { "type": "number" }, "amountRemaining": { "type": "number" }, "attempted": { "type": "boolean" }, "nextPaymentAttempt": { "type": "integer", "format": "int64" }, "currency": { "type": "string", "example": "usd" }, "paymentMethodTypes": { "type": "array", "items": { "type": "string" } }, "paymentWallets": { "type": "object", "properties": { "applePay": { "type": "string" }, "googlePay": { "type": "string" } } }, "defaultPaymentMethod": { "type": "object", "description": "Payment method id or full payment method details; same semantics as GET subscription `defaultPaymentMethod`. " }, "accountFeeAndDiscountDisplayLayout": { "type": "string" }, "accountFees": { "type": "object", "properties": { "fees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "string" }, "percentage": { "type": "string" }, "appliesTo": { "type": "string" }, "removable": { "type": "string" } } } } } }, "accountDiscounts": { "type": "object", "properties": { "discounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "string" }, "percentage": { "type": "string" }, "appliesTo": { "type": "string" }, "removable": { "type": "string" } } } } } }, "lineItemsGroup": { "type": "object", "properties": { "currency": { "type": "string", "example": "usd" }, "subtotal": { "type": "number" }, "shippingRate": { "type": "number" }, "totalAccountDiscounts": { "type": "array", "items": { "type": "object" } }, "totalAccountFees": { "type": "array", "items": { "type": "object" } }, "dualPricingAmounts": { "type": "object", "properties": { "expectedCardFeeAmountTotal": { "type": "number" }, "expectedCardDiscountAmountTotal": { "type": "number" }, "expectedCardAmountTotal": { "type": "number" }, "expectedACHFeeAmountTotal": { "type": "number" }, "expectedACHDiscountAmountTotal": { "type": "number" }, "expectedACHAmountTotal": { "type": "number" } } }, "invoiceLineItems": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "urlPath": { "type": "string", "description": "Path template for additional line items; replace `{invoiceId}` with the actual invoice id in responses. ", "example": "/invoice/inv_a11YYufWQzNY63zpQ6QSNRQhkUpVph4WRmzW0zWJO2znZKdVujZ0N0S22u/invoice-line-items" }, "retrieved": { "type": "integer", "description": "Number of line items returned in this payload", "format": "int32" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "ili_690522278211cd51c8239b58" }, "invoiceId": { "type": "string", "description": "Parent invoice id (present on list invoice line items responses)" }, "accountId": { "type": "string", "description": "Merchant account id (present on list invoice line items responses)" }, "productName": { "type": "string" }, "productDescription": { "type": "string", "description": "Product description for the line item (customizable for display)." }, "price": { "type": "object", "description": "Price id string when not expanded; full price object when expanded (same idea as subscription `site`)." }, "accountDiscounts": { "type": "object", "description": "Id string, array of id strings, or full objects when accountDiscounts path is expanded." }, "accountFees": { "type": "object", "description": "Id string, array of id strings, or full objects when accountFees path is expanded." }, "unitAmountOverride": { "type": "string" }, "unitPriceOverride": { "type": "string", "description": "Override used for proration and similar scenarios." }, "unitPrice": { "type": "number", "description": "Effective unit price from unitPriceOverride, unitAmountOverride, or price.amount as applicable." }, "quantity": { "type": "integer", "format": "int32" }, "amountSubtotal": { "type": "number" }, "amountTax": { "type": "number" }, "currency": { "type": "string" }, "dualPricingAmounts": { "type": "object", "properties": { "expectedCardDiscountAmountLineTotal": { "type": "number" }, "expectedCardFeeAmountLineTotal": { "type": "number" }, "expectedCardAmountLineTotal": { "type": "number" }, "expectedACHDiscountAmountLineTotal": { "type": "number" }, "expectedACHFeeAmountLineTotal": { "type": "number" }, "expectedACHAmountLineTotal": { "type": "number" } } }, "object": { "type": "string", "example": "item" } } } } } } } }, "testClock": { "type": "object", "description": "Expanded test clock object. Only present when `expand` includes `test_clock` on GET /invoices/{invoiceId} and the invoice's subscription has an associated test clock. " }, "initialPaymentErrorDetails": { "type": "object", "properties": { "paymentRequest": { "type": "object", "description": "The failed payment request returned by the payment processor." } }, "description": "Payment processor failure details for pay-invoice. Present only when the response `errorType` indicates a payment error. " }, "object": { "type": "string", "example": "invoice" } } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "required": [ "code", "message", "success" ], "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "format": "int32", "example": 200 }, "message": { "type": "string", "example": "Invoice retrieved successfully." }, "errorType": { "type": "string", "description": "Error classification. Present only when pay-invoice fails with a payment error." }, "errorCode": { "type": "string", "description": "Specific error code identifying the failure reason. Present only on payment error." }, "declineCode": { "type": "string", "description": "Decline code from the payment processor. Present only on payment error." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Invoice identifier", "example": "inv_a11YYufWQzNY63zpQ6QSNRQh" }, "accountId": { "type": "string" }, "created": { "type": "integer", "format": "int64", "example": 1679600215 }, "periodStart": { "type": "integer", "format": "int64" }, "periodEnd": { "type": "integer", "format": "int64" }, "invoiceNumber": { "type": "string" }, "status": { "type": "string", "description": "Current status of the invoice", "example": "open" }, "finalizedOn": { "type": "integer", "format": "int64" }, "autoFinalizeAt": { "type": "integer", "format": "int64" }, "autoSendInvoiceAt": { "type": "integer", "format": "int64" }, "autoAdvance": { "type": "boolean" }, "dueDate": { "type": "integer", "format": "int64" }, "isPastDue": { "type": "boolean" }, "paidOn": { "type": "integer", "format": "int64" }, "voidedOn": { "type": "integer", "format": "int64" }, "markedUncollectibleOn": { "type": "integer", "format": "int64" }, "billingReason": { "type": "string", "example": "manual" }, "subscriptionInvoiceType": { "type": "string" }, "subscription": { "type": "string" }, "collectionMethod": { "type": "string" }, "externalReferenceId": { "type": "string" }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } } } }, "hostedInvoiceUrl": { "type": "string" }, "pdfInvoiceUrl": { "type": "string" }, "customer": { "type": "object", "description": "Customer id or full customer details from DynamoDB when `expand` includes `customer` (id when not expanded; full object when expanded — same semantics as `defaultPaymentMethod`). " }, "customerEmail": { "type": "string" }, "customerName": { "type": "string" }, "customerPhone": { "type": "string" }, "customerAddress": { "type": "object", "properties": { "line1": { "type": "string" }, "line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "postalCode": { "type": "string" } } }, "shippingDetails": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "address": { "type": "object", "properties": { "line1": { "type": "string" }, "line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "postalCode": { "type": "string" } } } } }, "amountSubtotal": { "type": "number", "example": 2000 }, "totalAmountToBeCharged": { "type": "object", "properties": { "card": { "type": "object", "properties": { "total": { "type": "number" }, "details": { "type": "object", "properties": { "subtotal": { "type": "number" }, "amountFees": { "type": "number" }, "amountDiscount": { "type": "number" }, "amountShipping": { "type": "number" }, "amountTax": { "type": "number" } } } } }, "usBankAccount": { "type": "object", "properties": { "total": { "type": "number" }, "details": { "type": "object", "properties": { "subtotal": { "type": "number" }, "amountFees": { "type": "number" }, "amountDiscount": { "type": "number" }, "amountShipping": { "type": "number" }, "amountTax": { "type": "number" } } } } } } }, "partialAmountsToBeCharged": { "type": "object" }, "amountDue": { "type": "number", "example": 0 }, "amountPaid": { "type": "number", "example": 0 }, "feesPaid": { "type": "number" }, "discountsApplied": { "type": "number" }, "amountRemaining": { "type": "number" }, "attempted": { "type": "boolean" }, "nextPaymentAttempt": { "type": "integer", "format": "int64" }, "currency": { "type": "string", "example": "usd" }, "paymentMethodTypes": { "type": "array", "items": { "type": "string" } }, "paymentWallets": { "type": "object", "properties": { "applePay": { "type": "string" }, "googlePay": { "type": "string" } } }, "defaultPaymentMethod": { "type": "object", "description": "Payment method id or full payment method details; same semantics as GET subscription `defaultPaymentMethod`. " }, "accountFeeAndDiscountDisplayLayout": { "type": "string" }, "accountFees": { "type": "object", "properties": { "fees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "string" }, "percentage": { "type": "string" }, "appliesTo": { "type": "string" }, "removable": { "type": "string" } } } } } }, "accountDiscounts": { "type": "object", "properties": { "discounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "string" }, "percentage": { "type": "string" }, "appliesTo": { "type": "string" }, "removable": { "type": "string" } } } } } }, "lineItemsGroup": { "type": "object", "properties": { "currency": { "type": "string", "example": "usd" }, "subtotal": { "type": "number" }, "shippingRate": { "type": "number" }, "totalAccountDiscounts": { "type": "array", "items": { "type": "object" } }, "totalAccountFees": { "type": "array", "items": { "type": "object" } }, "dualPricingAmounts": { "type": "object", "properties": { "expectedCardFeeAmountTotal": { "type": "number" }, "expectedCardDiscountAmountTotal": { "type": "number" }, "expectedCardAmountTotal": { "type": "number" }, "expectedACHFeeAmountTotal": { "type": "number" }, "expectedACHDiscountAmountTotal": { "type": "number" }, "expectedACHAmountTotal": { "type": "number" } } }, "invoiceLineItems": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "urlPath": { "type": "string", "description": "Path template for additional line items; replace `{invoiceId}` with the actual invoice id in responses. ", "example": "/invoice/inv_a11YYufWQzNY63zpQ6QSNRQhkUpVph4WRmzW0zWJO2znZKdVujZ0N0S22u/invoice-line-items" }, "retrieved": { "type": "integer", "description": "Number of line items returned in this payload", "format": "int32" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "ili_690522278211cd51c8239b58" }, "invoiceId": { "type": "string", "description": "Parent invoice id (present on list invoice line items responses)" }, "accountId": { "type": "string", "description": "Merchant account id (present on list invoice line items responses)" }, "productName": { "type": "string" }, "productDescription": { "type": "string", "description": "Product description for the line item (customizable for display)." }, "price": { "type": "object", "description": "Price id string when not expanded; full price object when expanded (same idea as subscription `site`)." }, "accountDiscounts": { "type": "object", "description": "Id string, array of id strings, or full objects when accountDiscounts path is expanded." }, "accountFees": { "type": "object", "description": "Id string, array of id strings, or full objects when accountFees path is expanded." }, "unitAmountOverride": { "type": "string" }, "unitPriceOverride": { "type": "string", "description": "Override used for proration and similar scenarios." }, "unitPrice": { "type": "number", "description": "Effective unit price from unitPriceOverride, unitAmountOverride, or price.amount as applicable." }, "quantity": { "type": "integer", "format": "int32" }, "amountSubtotal": { "type": "number" }, "amountTax": { "type": "number" }, "currency": { "type": "string" }, "dualPricingAmounts": { "type": "object", "properties": { "expectedCardDiscountAmountLineTotal": { "type": "number" }, "expectedCardFeeAmountLineTotal": { "type": "number" }, "expectedCardAmountLineTotal": { "type": "number" }, "expectedACHDiscountAmountLineTotal": { "type": "number" }, "expectedACHFeeAmountLineTotal": { "type": "number" }, "expectedACHAmountLineTotal": { "type": "number" } } }, "object": { "type": "string", "example": "item" } } } } } } } }, "testClock": { "type": "object", "description": "Expanded test clock object. Only present when `expand` includes `test_clock` on GET /invoices/{invoiceId} and the invoice's subscription has an associated test clock. " }, "initialPaymentErrorDetails": { "type": "object", "properties": { "paymentRequest": { "type": "object", "description": "The failed payment request returned by the payment processor." } }, "description": "Payment processor failure details for pay-invoice. Present only when the response `errorType` indicates a payment error. " }, "object": { "type": "string", "example": "invoice" } } } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "required": [ "code", "message", "success" ], "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "code": { "type": "integer", "format": "int32", "example": 200 }, "message": { "type": "string", "example": "Invoice retrieved successfully." }, "errorType": { "type": "string", "description": "Error classification. Present only when pay-invoice fails with a payment error." }, "errorCode": { "type": "string", "description": "Specific error code identifying the failure reason. Present only on payment error." }, "declineCode": { "type": "string", "description": "Decline code from the payment processor. Present only on payment error." }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Invoice identifier", "example": "inv_a11YYufWQzNY63zpQ6QSNRQh" }, "accountId": { "type": "string" }, "created": { "type": "integer", "format": "int64", "example": 1679600215 }, "periodStart": { "type": "integer", "format": "int64" }, "periodEnd": { "type": "integer", "format": "int64" }, "invoiceNumber": { "type": "string" }, "status": { "type": "string", "description": "Current status of the invoice", "example": "open" }, "finalizedOn": { "type": "integer", "format": "int64" }, "autoFinalizeAt": { "type": "integer", "format": "int64" }, "autoSendInvoiceAt": { "type": "integer", "format": "int64" }, "autoAdvance": { "type": "boolean" }, "dueDate": { "type": "integer", "format": "int64" }, "isPastDue": { "type": "boolean" }, "paidOn": { "type": "integer", "format": "int64" }, "voidedOn": { "type": "integer", "format": "int64" }, "markedUncollectibleOn": { "type": "integer", "format": "int64" }, "billingReason": { "type": "string", "example": "manual" }, "subscriptionInvoiceType": { "type": "string" }, "subscription": { "type": "string" }, "collectionMethod": { "type": "string" }, "externalReferenceId": { "type": "string" }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } } } }, "hostedInvoiceUrl": { "type": "string" }, "pdfInvoiceUrl": { "type": "string" }, "customer": { "type": "object", "description": "Customer id or full customer details from DynamoDB when `expand` includes `customer` (id when not expanded; full object when expanded — same semantics as `defaultPaymentMethod`). " }, "customerEmail": { "type": "string" }, "customerName": { "type": "string" }, "customerPhone": { "type": "string" }, "customerAddress": { "type": "object", "properties": { "line1": { "type": "string" }, "line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "postalCode": { "type": "string" } } }, "shippingDetails": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "address": { "type": "object", "properties": { "line1": { "type": "string" }, "line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "postalCode": { "type": "string" } } } } }, "amountSubtotal": { "type": "number", "example": 2000 }, "totalAmountToBeCharged": { "type": "object", "properties": { "card": { "type": "object", "properties": { "total": { "type": "number" }, "details": { "type": "object", "properties": { "subtotal": { "type": "number" }, "amountFees": { "type": "number" }, "amountDiscount": { "type": "number" }, "amountShipping": { "type": "number" }, "amountTax": { "type": "number" } } } } }, "usBankAccount": { "type": "object", "properties": { "total": { "type": "number" }, "details": { "type": "object", "properties": { "subtotal": { "type": "number" }, "amountFees": { "type": "number" }, "amountDiscount": { "type": "number" }, "amountShipping": { "type": "number" }, "amountTax": { "type": "number" } } } } } } }, "partialAmountsToBeCharged": { "type": "object" }, "amountDue": { "type": "number", "example": 0 }, "amountPaid": { "type": "number", "example": 0 }, "feesPaid": { "type": "number" }, "discountsApplied": { "type": "number" }, "amountRemaining": { "type": "number" }, "attempted": { "type": "boolean" }, "nextPaymentAttempt": { "type": "integer", "format": "int64" }, "currency": { "type": "string", "example": "usd" }, "paymentMethodTypes": { "type": "array", "items": { "type": "string" } }, "paymentWallets": { "type": "object", "properties": { "applePay": { "type": "string" }, "googlePay": { "type": "string" } } }, "defaultPaymentMethod": { "type": "object", "description": "Payment method id or full payment method details; same semantics as GET subscription `defaultPaymentMethod`. " }, "accountFeeAndDiscountDisplayLayout": { "type": "string" }, "accountFees": { "type": "object", "properties": { "fees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "string" }, "percentage": { "type": "string" }, "appliesTo": { "type": "string" }, "removable": { "type": "string" } } } } } }, "accountDiscounts": { "type": "object", "properties": { "discounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "string" }, "percentage": { "type": "string" }, "appliesTo": { "type": "string" }, "removable": { "type": "string" } } } } } }, "lineItemsGroup": { "type": "object", "properties": { "currency": { "type": "string", "example": "usd" }, "subtotal": { "type": "number" }, "shippingRate": { "type": "number" }, "totalAccountDiscounts": { "type": "array", "items": { "type": "object" } }, "totalAccountFees": { "type": "array", "items": { "type": "object" } }, "dualPricingAmounts": { "type": "object", "properties": { "expectedCardFeeAmountTotal": { "type": "number" }, "expectedCardDiscountAmountTotal": { "type": "number" }, "expectedCardAmountTotal": { "type": "number" }, "expectedACHFeeAmountTotal": { "type": "number" }, "expectedACHDiscountAmountTotal": { "type": "number" }, "expectedACHAmountTotal": { "type": "number" } } }, "invoiceLineItems": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "urlPath": { "type": "string", "description": "Path template for additional line items; replace `{invoiceId}` with the actual invoice id in responses. ", "example": "/invoice/inv_a11YYufWQzNY63zpQ6QSNRQhkUpVph4WRmzW0zWJO2znZKdVujZ0N0S22u/invoice-line-items" }, "retrieved": { "type": "integer", "description": "Number of line items returned in this payload", "format": "int32" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "ili_690522278211cd51c8239b58" }, "invoiceId": { "type": "string", "description": "Parent invoice id (present on list invoice line items responses)" }, "accountId": { "type": "string", "description": "Merchant account id (present on list invoice line items responses)" }, "productName": { "type": "string" }, "productDescription": { "type": "string", "description": "Product description for the line item (customizable for display)." }, "price": { "type": "object", "description": "Price id string when not expanded; full price object when expanded (same idea as subscription `site`)." }, "accountDiscounts": { "type": "object", "description": "Id string, array of id strings, or full objects when accountDiscounts path is expanded." }, "accountFees": { "type": "object", "description": "Id string, array of id strings, or full objects when accountFees path is expanded." }, "unitAmountOverride": { "type": "string" }, "unitPriceOverride": { "type": "string", "description": "Override used for proration and similar scenarios." }, "unitPrice": { "type": "number", "description": "Effective unit price from unitPriceOverride, unitAmountOverride, or price.amount as applicable." }, "quantity": { "type": "integer", "format": "int32" }, "amountSubtotal": { "type": "number" }, "amountTax": { "type": "number" }, "currency": { "type": "string" }, "dualPricingAmounts": { "type": "object", "properties": { "expectedCardDiscountAmountLineTotal": { "type": "number" }, "expectedCardFeeAmountLineTotal": { "type": "number" }, "expectedCardAmountLineTotal": { "type": "number" }, "expectedACHDiscountAmountLineTotal": { "type": "number" }, "expectedACHFeeAmountLineTotal": { "type": "number" }, "expectedACHAmountLineTotal": { "type": "number" } } }, "object": { "type": "string", "example": "item" } } } } } } } }, "testClock": { "type": "object", "description": "Expanded test clock object. Only present when `expand` includes `test_clock` on GET /invoices/{invoiceId} and the invoice's subscription has an associated test clock. " }, "initialPaymentErrorDetails": { "type": "object", "properties": { "paymentRequest": { "type": "object", "description": "The failed payment request returned by the payment processor." } }, "description": "Payment processor failure details for pay-invoice. Present only when the response `errorType` indicates a payment error. " }, "object": { "type": "string", "example": "invoice" } } } } } } } } }, "deprecated": false } } }, "x-readme": { "headers": [], "explorer-enabled": true, "proxy-enabled": true }, "x-readme-fauxas": true, "tags": [ { "name": "Invoices", "description": "the Invoices API" } ] } ```