--- updatedAt: 2025-03-05T16:47:53.000Z agentTools: projectIndex: https://docs.staxpayments.com/llms.txt --- # Get an Invoice Retrieves the invoice matching the given id. Retrieves the details of a specific invoice by its ID. This endpoint allows you to view all relevant information about the invoice, including customer details, items, amounts, and metadata. The retrieved invoice can also be used with the `PUT /invoice/{id}` endpoint for further updates. *** ## Key Features * Fetches detailed information about an invoice by its unique ID. * Displays invoice attributes, including: * Customer information (e.g., name, email, address). * Items and associated costs. * Payment status and method (if applicable). * Any metadata or additional fields associated with the invoice. * Supports keyword-based filtering to find invoices tied to specific criteria. *** ## Usage Notes **Filtering by Keywords** Use the `keywords[]` parameter to search for invoices based on specific attributes. Supported keywords include: | Parameter | Description | Example | | :--------------- | :------------------------------------------------------------------------------------------------------------------ | :---------------------------- | | `name` | Search by the customer's name. | `keywords[]=John` | | `company_name` | Search by the company name. | `keywords[]=ABC Corp` | | `email` | Search by email address. | `keywords[]=user@example.com` | | `address` | Search by address. | `keywords[]=123 Main St` | | `price` | Search by price range or exact price. | `keywords[]=100.00` | | `schedule_id` | Search for invoices tied to a specific schedule. | `keywords[]=schedule12345` | | `payment_method` | Search by the payment method used (`card` or `bank`). If an invoice is unpaid, `payment_method` will return `null`. | | **Integration with Update** * The retrieved invoice data can be passed to the `PUT /invoice/{id}` endpoint for modifications. *** ## Response Structure | Code | Response | Reason | | ---- | --------------------- | ------------------------------------------------ | | 200 | Success | Invoice details were successfully retrieved. | | 400 | Bad Request | Invalid or missing parameters in the request. | | 401 | Unauthorized | Authentication failed. | | 404 | Not Found | An invoice with the specified ID does not exist. | | 500 | Internal Server Error | Unexpected server error. | *** ## Important Considerations * **Keyword Search**: Utilize the `keywords[]` parameter to streamline your invoice searches by specific criteria. This feature is especially useful for large datasets. * **Payment Method Visibility**: If the invoice has not been paid, the `payment_method` field will be `null`. * **Audit Trail**: Ensure proper handling of retrieved invoice data for compliance and record-keeping purposes. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "stax-api", "version": "0.1" }, "servers": [ { "url": "https://apiprod.fattlabs.com/" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "API key for merchant-level operations. Provides access to merchant-specific endpoints including transactions, payments, customer management, and merchant account settings. This key is scoped to a single merchant account and cannot access partner-level functionality." } } }, "security": [ { "ApiKeyAuth": [] } ], "paths": { "/invoice/{id}": { "get": { "summary": "Get an Invoice", "description": "Retrieves the invoice matching the given id.", "operationId": "get-an-invoice", "parameters": [ { "name": "keyword[]", "in": "query", "schema": { "type": "string" } }, { "name": "id", "in": "path", "schema": { "type": "string", "default": "the invoice id." }, "required": true } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": { "id": "e40bd293-f754-4d15-a6cb-56514757b73b", "status": "PAID", "total": 1, "created_at": "2025-06-25 18:00:03", "sent_at": null, "viewed_at": null, "paid_at": "2025-06-25 18:08:27", "due_at": null, "invoice_date_at": "2025-06-25 18:00:03", "payment_attempt_failed": false, "payment_attempt_message": "", "balance_due": 0, "total_paid": 1, "url": "https://app.staxpayments.com/#/bill/", "is_partial_payment_enabled": true, "merchant": { "id": "003b87f7-f4ed-43fc-b1b8-82604c8d1821", "company_name": "Sandbox Gateway Test Account", "display_name": "Sandbox Gateway Test Account", "contact_phone": "", "contact_email": "testemail@staxpayments.com", "address_1": "", "address_2": "", "address_city": "", "address_state": "", "address_zip": "", "branding": null, "options": { "social": null, "brand": { "logo": [ { "id": "staxconnect-sandbox_logoPngWideWhite", "url": "https://fattpaydocuments.s3.us-west-2.amazonaws.com/logo/staxconnect-sandbox_logoPngWideWhite.png?1709312609426", "filename": "Stax - with X Brandmark - White (5).png", "size": 52735, "type": "image/png", "thumbnails": { "small": { "url": "https://dl.airtable.com/.attachmentThumbnails/7780470946d0da3dd26e2569c605b1ea/6b93d9f9", "width": 72, "height": 36 }, "large": { "url": "https://dl.airtable.com/.attachmentThumbnails/ef736fa9fc4df641986299dd58c00aec/761118fa", "width": 1019, "height": 512 }, "full": { "url": "https://dl.airtable.com/.attachmentThumbnails/e05ef3e015bcf603932fb9d06a9e6872/80f30247", "width": 3000, "height": 3000 } } } ], "background_color": "101634", "primary_color": "101634", "platform_name": "Stax Connect Demo Sandbox" }, "advanced_customization": null, "invoice_display_data": null, "are_invoice_credit_card_payments_allowed_by_default": null, "hosted_hideCompanyName": null, "invoice_payment_methods": null }, "allow_ach": true, "hosted_payments_token": "Sandbox-Hosted-Payments-Token", "is_enterprise": false, "is_advanced_customization_enabled": false, "cnp_credit_surcharge_rate": null, "allow_paypal": true, "is_surcharge_enabled": false, "require_address": false }, "customer": { "id": "257833da-1a8f-4f3f-af5d-191cad3f9275", "phone": "5555555555", "email": "", "firstname": "Stax", "lastname": "Testuser", "company": "Your Company Here", "allow_invoice_credit_card_payments": true }, "payment_method": { "id": "1789f7da-eb8e-4b83-9b12-498b6ee1c947", "method": "card", "card_type": "visa", "card_last_four": "1111", "card_exp": "022027", "nickname": "VISA: Stax Testuser (ending in: 1111)", "created_at": "2025-06-25 18:08:24" }, "schedule": null, "transactions": [ { "id": "23616b07-3c2b-4d8b-a20c-3d8b747d2272", "invoice_id": "e40bd293-f754-4d15-a6cb-56514757b73b", "success": true, "message": null, "type": "charge", "created_at": "2025-06-25 18:08:25", "last_four": "1111", "issuer_auth_code": null, "total": 1, "method": "card", "payment_method_id": "1789f7da-eb8e-4b83-9b12-498b6ee1c947", "total_refunded": 0, "is_refundable": false, "is_voided": false, "is_voidable": false, "schedule_id": null, "child_captures": [], "parent_auth": null, "customer": null, "child_transactions": [], "files": [], "payment_method": { "id": "1789f7da-eb8e-4b83-9b12-498b6ee1c947", "method": "card", "card_type": "visa", "bank_type": null, "card_exp": "022027", "card_last_four": "1111", "nickname": "VISA: Stax Testuser (ending in: 1111)", "person_name": "Stax Testuser", "created_at": "2025-06-25 18:08:24", "customer": null }, "user": null } ], "files": [], "meta": { "memo": "" } } } }, "schema": { "type": "object", "properties": {} } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "default": " \"id\": [ \"The selected id is invalid.\"" } } } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "examples": { "New Example": { "summary": "New Example", "value": "{ \"id\": [\n \"The selected id is invalid.\"}" } } } } } }, "deprecated": false } } }, "x-readme": { "headers": [], "explorer-enabled": true, "proxy-enabled": true }, "x-readme-fauxas": true } ```