--- updatedAt: 2025-08-12T18:55:16.000Z agentTools: projectIndex: https://docs.staxpayments.com/llms.txt --- # Send an Invoice via SMS Sends the invoice to the customer's phone number and other CC phone numbers. Sends an existing invoice to a customer's phone number via SMS. This endpoint enables businesses to notify customers about pending charges or remind them to make payments through a text message containing a payment link. *** ## Key Features * Sends an invoice link directly to the customer's primary phone number. * Allows inclusion of additional recipients using CC phone numbers. * Can be called immediately after creating or updating an invoice. * Updates the invoice's status to **SENT** and records the timestamp in the `sent_at` field. *** ## Usage Notes **Invoice Requirements** The invoice must exist and be linked to a valid `id`. The invoice must not be marked as deleted (`deleted_at` must be null). **CC Phone Numbers** Use the `ccPhones` field in the request body to send the invoice link to additional phone numbers. Example: ```json { "ccPhones": ["+15555555555", "+14444444444"] } ``` **Resending Invoices** Invoices can be sent multiple times as reminders. Each resend updates the `sent_at` timestamp. **SMS Content** The text message includes the hosted invoice link for customers to view and pay their invoices. *** ## Response Structure | Code | Response | Reason | | ---- | --------------------- | ------------------------------------------------ | | 200 | Success | The invoice was successfully sent via SMS. | | 400 | Bad Request | Invalid or missing invoice ID or phone details. | | 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 * **Phone Number Format**: Ensure all phone numbers, including CC numbers, follow international formats (e.g., `[+15555555555](dialpad://%2B15555555555 "Call with Dialpad")`). * **Draft Invoices**: Only finalized invoices can be sent. Draft invoices (`status=DRAFT`) are not eligible. * **Customer Access**: The SMS will contain a link to the hosted invoice page for payment. Verify hosted invoice settings in Stax Pay. * **Audit Trail**: Each send request is logged, and the `sent_at` field is updated to track when the invoice was sent. # 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}/send/sms": { "put": { "summary": "Send an Invoice via SMS", "description": "Sends the invoice to the customer's phone number and other CC phone numbers.", "operationId": "send-an-invoice-via-sms", "parameters": [ { "name": "id", "in": "path", "description": "The id of the invoice that should be sent", "schema": { "type": "string" }, "required": true }, { "name": "message", "in": "query", "description": "Message which will show in the sms message", "schema": { "type": "string" } }, { "name": "phone", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"id\": \"4bbd1a64-7472-44ed-afef-02b82d3eae24\",\n \"merchant_id\": \"dee75215-b3bc-4e44-9bc5-75d0fb498b61\",\n \"user_id\": \"7c30a7f6-eabc-4355-b530-d351f8f0a4f1\",\n \"customer_id\": \"a41c93d0-e45d-4d41-b46c-f781a02019f5\",\n \"total\": 12,\n \"meta\": {\n \"tax\": 2,\n \"subtotal\": 10,\n \"lineItems\": [\n {\n \"id\": \"optional-fm-catalog-item-id\",\n \"item\": \"Demo Item\",\n \"details\": \"this is a regular demo item\",\n \"quantity\": 1,\n \"price\": 10\n }\n ]\n },\n \"status\": \"SENT\",\n \"sent_at\": \"2016-05-09 17:10:43\",\n \"viewed_at\": null,\n \"paid_at\": null,\n \"url\": \"http://127.0.0.1:5477/#/bill/\",\n \"deleted_at\": null,\n \"created_at\": \"2016-05-09 17:10:37\",\n \"updated_at\": \"2016-05-09 17:10:43\",\n \"customer\": {\n \"id\": \"a41c93d0-e45d-4d41-b46c-f781a02019f5\",\n \"firstname\": \"Jason\",\n \"lastname\": \"Mann\",\n \"company\": \"CIA\",\n \"email\": \"JasonGuy@CIA.com\",\n \"phone\": \"1234567898\",\n \"address_1\": \"123 Rite Way\",\n \"address_2\": \"Unit 12\",\n \"address_city\": \"Orlando\",\n \"address_state\": \"FL\",\n \"address_zip\": \"32801\",\n \"notes\": \"\",\n \"options\": \"\",\n \"created_at\": \"2016-04-26 13:55:21\",\n \"updated_at\": \"2016-04-26 13:55:21\",\n \"deleted_at\": null,\n \"payment_attempt_failed\": false,\n \"payment_attempt_message\": \"\",\n \"gravatar\": \"//www.gravatar.com/avatar/1b91155f027795b2d36a08b1e5e8e9df\"\n },\n \"user\": {\n \"id\": \"7c30a7f6-eabc-4355-b530-d351f8f0a4f1\",\n \"system_admin\": true,\n \"name\": \"DANIEL WALKER\",\n \"email\": \"contact@example.com\",\n \"created_at\": \"2016-04-12 13:52:26\",\n \"updated_at\": \"2016-04-25 16:46:42\",\n \"deleted_at\": null,\n \"gravatar\": \"//www.gravatar.com/avatar/772cbf95746d7da86789cc3634c46ba8\"\n },\n \"child_transactions\": [],\n \"merchant\": {\n \"id\": \"dee75215-b3bc-4e44-9bc5-75d0fb498b61\",\n \"mid\": \"520000294774\",\n \"status\": \"ACTIVE\",\n \"subdomain\": \"demo\",\n \"company_name\": \"Stax\",\n \"contact_name\": \"Stax\",\n \"contact_email\": \"contact@example.com\",\n \"contact_phone\": \"8555503288\",\n \"address_1\": \"25 Wall Street\",\n \"address_2\": \"Suite 1\",\n \"address_city\": \"Orlando\",\n \"address_state\": \"FL\",\n \"address_zip\": \"32801\",\n \"hosted_payments_token\": \"gfdbfed\",\n \"currency\": [\n \"USD\"\n ],\n \"branding\": \"https://s3-us-west-2.amazonaws.com/fattpaydocuments/avatars/0624acc8-c0be-45dc-a153-134da1990218.jpeg\",\n \"options\": {\n \"hosted_payments_success_note\": \"Thank you for your payment! It's gladly appreciated!\",\n \"hosted_payments_url_long\": \"http://localhost.app:5477/#/pay/t___-_\",\n \"hosted_payments_url_short\": \"http://bit.ly/1K34yKV\",\n \"hosted_payments_note\": \"Thank you for your payment\"\n },\n \"notes\": \"\",\n \"gateway_type\": null,\n \"gateway_name\": null,\n \"vendor_keys\": {},\n \"created_at\": \"2016-04-12 13:52:26\",\n \"updated_at\": \"2016-04-27 15:12:51\",\n \"deleted_at\": null\n }\n}" } }, "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "4bbd1a64-7472-44ed-afef-02b82d3eae24" }, "merchant_id": { "type": "string", "example": "dee75215-b3bc-4e44-9bc5-75d0fb498b61" }, "user_id": { "type": "string", "example": "7c30a7f6-eabc-4355-b530-d351f8f0a4f1" }, "customer_id": { "type": "string", "example": "a41c93d0-e45d-4d41-b46c-f781a02019f5" }, "total": { "type": "integer", "example": 12, "default": 0 }, "meta": { "type": "object", "properties": { "tax": { "type": "integer", "example": 2, "default": 0 }, "subtotal": { "type": "integer", "example": 10, "default": 0 }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "optional-fm-catalog-item-id" }, "item": { "type": "string", "example": "Demo Item" }, "details": { "type": "string", "example": "this is a regular demo item" }, "quantity": { "type": "integer", "example": 1, "default": 0 }, "price": { "type": "integer", "example": 10, "default": 0 } } } } } }, "status": { "type": "string", "example": "SENT" }, "sent_at": { "type": "string", "example": "2016-05-09 17:10:43" }, "viewed_at": {}, "paid_at": {}, "url": { "type": "string", "example": "http://127.0.0.1:5477/#/bill/" }, "deleted_at": {}, "created_at": { "type": "string", "example": "2016-05-09 17:10:37" }, "updated_at": { "type": "string", "example": "2016-05-09 17:10:43" }, "customer": { "type": "object", "properties": { "id": { "type": "string", "example": "a41c93d0-e45d-4d41-b46c-f781a02019f5" }, "firstname": { "type": "string", "example": "Jason" }, "lastname": { "type": "string", "example": "Mann" }, "company": { "type": "string", "example": "CIA" }, "email": { "type": "string", "example": "JasonGuy@CIA.com" }, "phone": { "type": "string", "example": "1234567898" }, "address_1": { "type": "string", "example": "123 Rite Way" }, "address_2": { "type": "string", "example": "Unit 12" }, "address_city": { "type": "string", "example": "Orlando" }, "address_state": { "type": "string", "example": "FL" }, "address_zip": { "type": "string", "example": "32801" }, "notes": { "type": "string", "example": "" }, "options": { "type": "string", "example": "" }, "created_at": { "type": "string", "example": "2016-04-26 13:55:21" }, "updated_at": { "type": "string", "example": "2016-04-26 13:55:21" }, "deleted_at": {}, "payment_attempt_failed": { "type": "boolean", "example": false, "default": true }, "payment_attempt_message": { "type": "string", "example": "" }, "gravatar": { "type": "string", "example": "//www.gravatar.com/avatar/1b91155f027795b2d36a08b1e5e8e9df" } } }, "user": { "type": "object", "properties": { "id": { "type": "string", "example": "7c30a7f6-eabc-4355-b530-d351f8f0a4f1" }, "system_admin": { "type": "boolean", "example": true, "default": true }, "name": { "type": "string", "example": "DANIEL WALKER" }, "email": { "type": "string", "example": "contact@example.com" }, "created_at": { "type": "string", "example": "2016-04-12 13:52:26" }, "updated_at": { "type": "string", "example": "2016-04-25 16:46:42" }, "deleted_at": {}, "gravatar": { "type": "string", "example": "//www.gravatar.com/avatar/772cbf95746d7da86789cc3634c46ba8" } } }, "child_transactions": { "type": "array" }, "merchant": { "type": "object", "properties": { "id": { "type": "string", "example": "dee75215-b3bc-4e44-9bc5-75d0fb498b61" }, "mid": { "type": "string", "example": "520000294774" }, "status": { "type": "string", "example": "ACTIVE" }, "subdomain": { "type": "string", "example": "demo" }, "company_name": { "type": "string", "example": "Stax" }, "contact_name": { "type": "string", "example": "Stax" }, "contact_email": { "type": "string", "example": "contact@example.com" }, "contact_phone": { "type": "string", "example": "8555503288" }, "address_1": { "type": "string", "example": "25 Wall Street" }, "address_2": { "type": "string", "example": "Suite 1" }, "address_city": { "type": "string", "example": "Orlando" }, "address_state": { "type": "string", "example": "FL" }, "address_zip": { "type": "string", "example": "32801" }, "hosted_payments_token": { "type": "string", "example": "gfdbfed" }, "currency": { "type": "array", "items": { "type": "string", "example": "USD" } }, "branding": { "type": "string", "example": "https://s3-us-west-2.amazonaws.com/fattpaydocuments/avatars/0624acc8-c0be-45dc-a153-134da1990218.jpeg" }, "options": { "type": "object", "properties": { "hosted_payments_success_note": { "type": "string", "example": "Thank you for your payment! It's gladly appreciated!" }, "hosted_payments_url_long": { "type": "string", "example": "http://localhost.app:5477/#/pay/t___-_" }, "hosted_payments_url_short": { "type": "string", "example": "http://bit.ly/1K34yKV" }, "hosted_payments_note": { "type": "string", "example": "Thank you for your payment" } } }, "notes": { "type": "string", "example": "" }, "gateway_type": {}, "gateway_name": {}, "vendor_keys": { "type": "object", "properties": {} }, "created_at": { "type": "string", "example": "2016-04-12 13:52:26" }, "updated_at": { "type": "string", "example": "2016-04-27 15:12:51" }, "deleted_at": {} } } } } } } }, "422": { "description": "422", "content": { "application/json": { "examples": { "Result": { "value": "[\n {\n \"id\": [\n \"Invoice could not be found\"\n ]\n },\n {\n \"phoneNumber\": \"111111111111111\",\n \"status\": \"failure\",\n \"message\": \"please contact your customer for a valid phone number to use.\"\n }\n]" } }, "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "array", "items": { "type": "string", "example": "Invoice could not be found" } } } } } } } } }, "deprecated": false } } }, "x-readme": { "headers": [], "explorer-enabled": true, "proxy-enabled": true }, "x-readme-fauxas": true } ```