# Authentication Source: https://docs.justpaid.io/api-reference/api/authentication Authentication of API endpoints ## Authentication We use Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The bearer token is a cryptic string, usually generated by the server in response to a login request. ### How to get a Bearer token Kindly visit [app.justpaid.io/settings/developer/api](https://app.justpaid.io/settings/developer/api) to get a Bearer token. Kindly [contact us](mailto:support@justpaid.io) in case you face any issues. ### Usage The client must send the bearer token in the Authorization header when making requests to protected resources: ``` Authorization: Bearer ``` Example: ```curl theme={null} curl --request POST \ --url https://exampleapi.justpaid.io/api/v1/customer/create \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "name": "", "email": "" }' ``` # Errors Source: https://docs.justpaid.io/api-reference/api/errors API Error Handling This document outlines the error handling mechanisms implemented in our API. It provides details on the error codes, response formats, and handling of various exception types. We use conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the `2xx` range indicate success. Codes in the `4xx` range indicate an error that failed given the information provided (e.g., a required parameter was omitted, an action failed, etc). Codes in the `5xx` range indicate an error with our servers (these are rare). Some common error responses are listed below: `400 Bad Request` - Your request may be malformed `401 Unauthorized` - Your API key is wrong, or your user does not have access to this resource `403 Forbidden` - The record requested is hidden `404 Not Found` - The specified record could not be found `405 Method Not Allowed` - You tried to access a record with an invalid method ## Error Response Format The API adheres to a consistent error response format to enhance user experience and simplify error interpretation. Here's the general structure: ```json theme={null} { "error_code": "", // Unique identifier for the error type "detail": [ // Array of detailed error messages (optional) { "message": "", // Descriptive message explaining the error "field": "" // (Optional) Field associated with the error (relevant for validation errors) }, ... ] } ``` AND ```json theme={null} { "error": "", // Unique identifier for the error type "message": "", // Descriptive message explaining the error } ``` ### Error Codes and Descriptions The API returns specific error codes to convey the nature of the issue. Here's a breakdown of the commonly encountered codes: #### INVALID\_INPUT (HTTP Status: 400): Indicates errors related to invalid or malformed user input during API requests. The detail section will provide specific messages and potentially the fields where the errors occurred. Example: ```json theme={null} { "error_code": "INVALID_INPUT", "detail": [ { "message": "Input should be a valid number, unable to parse string as a number", "field": "invoice.amount" }, { "message": "Field required", "field": "invoice.invoice_number" } ] } ``` #### VALIDATION\_ERROR (HTTP Status: 400): Occurs when validation constraints are violated during data processing. The detail section will contain a general error message. Example: ```json theme={null} { "error_code": "VALIDATION_ERROR", "message": "Payments are disabled for this company" } ``` #### AUTHENTICATION\_ERROR (HTTP Status: 401): Occurs when user authentication fails due to invalid credentials, missing authentication headers, or insufficient permissions. #### NOT\_FOUND (HTTP Status: 404): Returned when the requested resource does not exist on the server. Example: ```json theme={null} { "error_code": "NOT_FOUND", "message": "Invoice not found" } ``` #### REQUEST\_DATA\_TOO\_BIG (HTTP Status: 413): The error response indicates that the request body was larger than the limit (`10 MB`). ## Additional Notes For security reasons, avoid exposing sensitive details in the error messages, especially when dealing with authentication errors. # Pagination Source: https://docs.justpaid.io/api-reference/api/pagination Pagination in the API The API comes with pagination support. This allows you to split large result sets into individual pages. You can query the list endpoints with limit and offset GET parameters ```bash theme={null} /api/bills?limit=10&offset=0 ``` # JustPaid API SDK Source: https://docs.justpaid.io/api-reference/api/sdk This SDK provides a simple interface to interact with the JustPaid API for usage-based billing. ### Features * Retrieve billable items * Ingest usage events * Batch ingest multiple usage events asynchronously ``` pip install justpaid ``` ### Quick Start ``` from justpaid import JustPaidAPI print(justpaid.__version__) # Should print "0.x.x" # Initialize the API client api = JustPaidAPI(api_token="your_api_token_here") # Get billable items by customer_id items = api.get_billable_items(customer_id="customer-123") # Or get billable items by external_customer_id items = api.get_billable_items(external_customer_id="ext-customer-123") print(items) ``` ### # Webhooks Source: https://docs.justpaid.io/api-reference/api/webhooks Webhooks setup and usage ## Overview Webhooks are a way for your application to receive real-time notifications when events occur in your account. When an event occurs, we send an HTTP POST request to the webhook's configured URL. You can use webhooks to trigger custom code, workflows, or integrations in your application. ## Creating Webhooks You can create and manage webhooks directly from the JustPaid dashboard: 1. Navigate to **Settings** → **Developer** → **Webhooks** 2. Click **Create Webhook URL** 3. Enter your webhook endpoint URL 4. Select the event types you want to subscribe to 5. Click **Save** Each webhook includes a signing secret that you can use to verify the authenticity of incoming requests. ## Two Different Naming Schemes JustPaid uses **two distinct sets of event-type strings**, and mixing them up is the single most common integration bug. * **Subscription identifiers** are `UPPER_SNAKE_CASE` (e.g. `INVOICE_STATUS_CHANGE`). These are what you select in the dashboard and what appear in the API when configuring which events an endpoint receives. * **Delivered event types** are `lowercase.dotted` (e.g. `invoice.status_changed`). This is the value that actually arrives in the `type` field of the JSON body we POST to your endpoint. **Match your receiver on the `lowercase.dotted` values.** If you compare the incoming `type` against `INVOICE_STATUS_CHANGE`, no event will ever match and your receiver will silently ignore every delivery. ### Common integration mistake A receiver written like this will drop every JustPaid event: ```js theme={null} // WRONG — the wire value is never UPPER_SNAKE if (body.type === "INVOICE_STATUS_CHANGE") { /* never runs */ } return { status: 200, ignored: true, eventType: body.type }; ``` Compare against the delivered value instead: ```js theme={null} // CORRECT — matches what we actually send if (body.type === "invoice.status_changed") { /* handle it */ } ``` Returning `200` while ignoring the event means retries will not fire and the delivery is recorded as successful on our side, so this failure mode is silent. Log unmatched `type` values during integration to catch it. ## Event Types The table below is exhaustive. Every value listed is a real, deliverable event type; there are no others. | Subscription identifier (dashboard) | Delivered `type` (wire value) | Fires when | | ----------------------------------- | -------------------------------- | ---------------------------------------------------------------------- | | `INVOICE_CREATED` | `invoice.created` | A new invoice is created — **including DRAFT invoices** | | `INVOICE_UPDATED` | `invoice.updated` | An invoice is updated **and** a tracked field changed (see note below) | | `INVOICE_STATUS_CHANGE` | `invoice.status_changed` | An invoice's status changes | | `INVOICE_PAYMENT_STATUS_CHANGE` | `invoice_payment.status_changed` | A payment's status changes on an invoice | | `CUSTOMER_CREATED` | `customer.created` | A new customer is created | | `CUSTOMER_CONTRACT_CREATED` | `contract.created` | A new contract is created for a customer | | `PRODUCT_CREATED` | `product.created` | A new product is created | | `PRODUCT_UPDATED` | `product.updated` | An existing product is updated | | `CREDIT_MEMO_CREATED` | `credit_memo.created` | A new credit memo is created | | `CREDIT_MEMO_UPDATED` | `credit_memo.updated` | An existing credit memo is updated | | `CREDIT_MEMO_STATUS_CHANGE` | `credit_memo.status_changed` | A credit memo's status changes | Note that `CUSTOMER_CONTRACT_CREATED` maps to `contract.created` — the wire value drops the `customer_` prefix. It is the one pair where the two names are not a mechanical transformation of each other. ### Behavior worth knowing **`invoice.created` fires for DRAFT invoices.** Creation is creation regardless of status — the event is emitted as soon as the invoice row is committed, so the `invoice_status` in your first event for an invoice is frequently `draft`. If you only care about issued invoices, filter on `invoice_status` or subscribe to `invoice.status_changed` instead. **`invoice.updated` requires a tracked-field change.** An update only emits an event when one of these fields actually changed value: * `amount` * `due_date` * `invoice_date` * `description` * `notes` Editing anything else on an invoice produces no `invoice.updated` event. Do not rely on this event as a general "something about this invoice changed" signal. **Status-change events carry the old value.** `invoice.status_changed`, `invoice_payment.status_changed`, and `credit_memo.status_changed` include a `data.previous_attributes` object holding the prior status (`invoice_status`, `payment_status`, and `memo_status` respectively). It is only present when the status genuinely changed. ## Payload Envelope Every delivery uses the same envelope, regardless of event type: | Field | Type | Description | | -------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------- | | `id` | string | Unique event identifier, always prefixed `evt_` followed by 32 hex characters. Use it for idempotency. | | `object` | string | Always the literal `"event"`. | | `api_version` | string | Always `"v1"`. | | `created` | string | ISO 8601 timestamp with timezone offset, e.g. `2026-01-27T10:30:00.123456+00:00`. **A string, not a Unix integer.** | | `type` | string | The `lowercase.dotted` event type. This is the key that carries the event type. | | `data.object` | object | The entity, using the same schema as the corresponding REST API resource. | | `data.previous_attributes` | object | **Only present on change events.** Maps changed field names to their previous values. Absent entirely on `*.created` events. | The request body is serialized with sorted keys and no whitespace before signing, so field order on the wire is alphabetical. ### Example: `invoice.status_changed` ```json theme={null} { "api_version": "v1", "created": "2026-01-27T10:30:00.123456+00:00", "data": { "object": { "uuid": "d0b1c4c0-4b1e-4b3e-8b4b-1f1d8b1d8b1d", "invoice_number": "INV-2026-001", "invoice_status": "sent", "amount": 1500.0, "currency": "USD", "invoice_date": "2026-01-27", "due_date": "2026-02-26", "description": "January services", "notes": null, "payment_link": "https://pay.justpaid.io/...", "created_at": "2026-01-27T10:00:00Z", "updated_at": "2026-01-27T10:30:00Z", "customer": { "uuid": "9c1e4b3e-8b4b-1f1d-8b1d-8b1dd0b1c4c0", "name": "Acme Corporation", "email": "billing@acme.com" }, "line_items": [] }, "previous_attributes": { "invoice_status": "Draft" } }, "id": "evt_4f3a9c1e8b7d6a5f4e3d2c1b0a9f8e7d", "object": "event", "type": "invoice.status_changed" } ``` ### Example: `invoice.created` A `*.created` event has no `previous_attributes` key at all: ```json theme={null} { "api_version": "v1", "created": "2026-01-27T10:00:00.000000+00:00", "data": { "object": { "uuid": "d0b1c4c0-4b1e-4b3e-8b4b-1f1d8b1d8b1d", "invoice_number": "INV-2026-001", "invoice_status": "draft", "amount": 1500.0, "currency": "USD", "customer": { "uuid": "9c1e4b3e-8b4b-1f1d-8b1d-8b1dd0b1c4c0", "name": "Acme Corporation", "email": "billing@acme.com" }, "line_items": [] } }, "id": "evt_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d", "object": "event", "type": "invoice.created" } ``` ## Webhook Headers | Header | Description | | ---------------------- | ----------------------------------------------------------------- | | `Content-Type` | Always `application/json` | | `X-JustPaid-Timestamp` | Unix timestamp (seconds, as a string) when the request was signed | | `X-JustPaid-Signature` | HMAC-SHA256 signature in the format `v1={sha256_hex}` | The two signature headers are sent **only when a signing secret is configured** on the webhook endpoint. Endpoints without a secret receive only `Content-Type`. ### Signature Verification The signed input is the timestamp and the raw body joined by a literal period: `{timestamp}.{body}`. The key is your endpoint's signing secret. Verify against the **raw request body bytes exactly as received** — we sign the compact, key-sorted JSON we transmit, so re-serializing a parsed object will produce a different string and the signature will not match. ```python theme={null} import hmac import hashlib def verify_justpaid_webhook(payload_body: bytes, timestamp: str, signature: str, secret: str) -> bool: expected_sig = hmac.new( secret.encode('utf-8'), f"{timestamp}.{payload_body.decode('utf-8')}".encode('utf-8'), hashlib.sha256 ).hexdigest() provided_sig = signature.replace("v1=", "") return hmac.compare_digest(expected_sig, provided_sig) ``` ## Delivery and Retries * Webhooks are delivered **asynchronously** on a background queue, after the originating database transaction commits. * Each subscribed endpoint is dispatched **independently**. A failure on one endpoint does not prevent delivery to the others, and a retry never re-sends to an endpoint that already accepted the event. * **Up to 3 retries**, at a **fixed 60-second delay** between attempts (not exponential backoff). * Connection timeout is 5 seconds; response timeout is 30 seconds. **Return a 2xx within 30 seconds** or the attempt is treated as failed. * **Every attempt is logged**, including the request body, request headers, response status code, and response body. These are visible per endpoint in the dashboard and are the fastest way to diagnose an integration. * The event `id` is **stable across retries**, so it is safe to use for idempotency/deduplication. ### Which failures are retried | Response | Retried? | | ---------------------------------------------- | ------------------------------------------------------------- | | 2xx | No — delivered | | `408 Request Timeout`, `429 Too Many Requests` | Yes | | Any other 4xx | **No** — a re-POST cannot fix a request the endpoint rejected | | 5xx, connection errors, timeouts | Yes | **Endpoints are never auto-disabled.** No matter how many deliveries fail or for how long, we keep attempting future events to a configured endpoint. If an endpoint is dead, remove or update it in the dashboard — it will not deactivate itself, and repeated failures will not stop us from trying. ## Best Practices 1. **Match on the delivered `type`** — the `lowercase.dotted` value, never the `UPPER_SNAKE` subscription identifier 2. **Respond quickly** — return a 2xx status code within 30 seconds 3. **Process asynchronously** — acknowledge immediately, then queue the event for background processing 4. **Verify signatures** — validate `X-JustPaid-Signature` against the raw body bytes 5. **Handle duplicates** — use the event `id` for idempotency; it is stable across retries 6. **Log unmatched event types** — the surest way to catch a naming mismatch before it becomes silent data loss 7. **Handle out-of-order delivery** — events are delivered in order when possible, but independent dispatch and retries mean ordering is not guaranteed # Billable Metric Create Api Source: https://docs.justpaid.io/api-reference/billable-metric-create-api post /api/v1/usage/billable_metrics/create # Billable Metric Get Api Source: https://docs.justpaid.io/api-reference/billable-metric-get-api get /api/v1/usage/billable_metrics/{billable_metric_uuid} # Contract Detail Api Source: https://docs.justpaid.io/api-reference/contract-get-api get /api/v1/contract/{contract_id} Get detailed contract information including plan and plan items. # Contract Line Items Api Source: https://docs.justpaid.io/api-reference/contract-line-items-api get /api/v1/contract/{contract_id}/line-items Get line items (plan items) for a specific contract. # Contract List Api Source: https://docs.justpaid.io/api-reference/contract-list-api get /api/v1/contract/ List contracts with optional filtering. # Contract Upload Api Source: https://docs.justpaid.io/api-reference/contract-upload-api post /api/v1/contract/upload Upload a contract PDF file for processing. # Customer Create Api Source: https://docs.justpaid.io/api-reference/customer-create-api post /api/v1/customer/create Creates a new customer in the system. # Customer Get Api Source: https://docs.justpaid.io/api-reference/customer-get-api get /api/v1/customer/{customer_uuid} Retrieves a customer by their UUID. # Customer Payment Methods Get Api Source: https://docs.justpaid.io/api-reference/customer-payment-methods get /api/v1/customer/{customer_uuid}/payment-methods Retrieves all payment methods for a customer. # Customer Update Api Source: https://docs.justpaid.io/api-reference/customer-update-api patch /api/v1/customer/{customer_uuid} Updates a customer's information. # Get Items Source: https://docs.justpaid.io/api-reference/get-billable-items get /api/v1/usage/items ### Retrieve Usage-Based Billable Items Fetch a list of usage-based billable items, optionally filtered by a specific customer ID or external customer ID. #### Overview This endpoint allows you to retrieve billable items along with associated customer details from the database. You can filter the results by either a customer ID or external customer ID. If no filter is provided, the endpoint returns billable items for all customers. #### Parameters - **customer_id** (optional): The unique identifier of the customer to filter events by. - **external_customer_id** (optional): The external identifier of the customer to filter events by. # Ingest Event Source: https://docs.justpaid.io/api-reference/ingest-event post /api/v1/usage/ingest Ingests a list of customer events, creating new events and identifying duplicates. This endpoint processes a batch of customer events, checks for idempotency to prevent duplicates, and attempts to create new events in the system. It returns detailed information about the process, including the number of successfully created events, any duplicates identified, and errors encountered. Parameters: request: The request object, which includes details about the HTTP request. This is typically provided by the FastAPI framework. customer_event_list (CustomerEventList): An object containing a list of customer events to be ingested. Each event must include an idempotency key to prevent duplicate processing. Returns: A dictionary with two keys: - 'info': A dictionary containing details about the ingestion process, including the number of events successfully created ('created_events') and a list of idempotency keys for events identified as duplicates ('duplicates'). - 'errors': A list of dictionaries, each representing an error encountered during the ingestion process. Each dictionary includes the 'idempotency_key' of the event that caused the error and a description of the error ('error'). # Invoice Create Api Source: https://docs.justpaid.io/api-reference/invoice-create-api post /api/v1/invoice/ Creates a new invoice with line items. PDF is auto-generated. # Invoice Get Api Source: https://docs.justpaid.io/api-reference/invoice-get-api get /api/v1/invoice/{invoice_uuid} Retrieves a specific invoice by UUID. # Line Item Create Api Source: https://docs.justpaid.io/api-reference/invoice-line-item-create-api post /api/v1/invoice/{invoice_uuid}/line-items Creates a new line item on an invoice. # Line Item Delete Api Source: https://docs.justpaid.io/api-reference/invoice-line-item-delete-api delete /api/v1/invoice/{invoice_uuid}/line-items/{line_item_uuid} Deletes a line item from an invoice. # Line Item Get Api Source: https://docs.justpaid.io/api-reference/invoice-line-item-get-api get /api/v1/invoice/{invoice_uuid}/line-items/{line_item_uuid} Retrieves a specific line item by UUID. # Line Item Update Api Source: https://docs.justpaid.io/api-reference/invoice-line-item-update-api put /api/v1/invoice/{invoice_uuid}/line-items/{line_item_uuid} Updates a line item. Tax updates trigger amount recalculation and PDF regeneration. # Invoice List Api Source: https://docs.justpaid.io/api-reference/invoice-list-api get /api/v1/invoice/ Lists invoices with optional filtering. # Invoice Payment Cancel Api Source: https://docs.justpaid.io/api-reference/invoice-payment-cancel-api post /api/v1/payment/invoice_payment/{invoice_payment_uuid}/cancel # Invoice Payment Create Api Source: https://docs.justpaid.io/api-reference/invoice-payment-create-api post /api/v1/payment/invoice_payment/create # Invoice Payment Get Api Source: https://docs.justpaid.io/api-reference/invoice-payment-get-api get /api/v1/payment/invoice_payment/{invoice_payment_uuid} # Invoice Payment List Api Source: https://docs.justpaid.io/api-reference/invoice-payment-list-api get /api/v1/payment/invoice_payment # Invoice Pdf Get Api Source: https://docs.justpaid.io/api-reference/invoice-pdf-api get /api/v1/invoice/{invoice_uuid}/pdf Gets the invoice PDF URL. Generates PDF if not exists. # Invoice Update Api Source: https://docs.justpaid.io/api-reference/invoice-update-api put /api/v1/invoice/{invoice_uuid} Updates an existing invoice. # Mrr Report Api Source: https://docs.justpaid.io/api-reference/metrics-mrr-api get /api/v1/metrics/mrr Retrieve Monthly Recurring Revenue (MRR) metrics report. This endpoint provides comprehensive MRR analytics including: MRR Beginning of Period, New MRR, Churn MRR, Expansion MRR, Contraction MRR, MRR End of Period, ARR, MRR Change, and Net Revenue Retention (NRR). Data is grouped by metric type for easy integration with dashboards and analytics tools. # Create Contract Api Source: https://docs.justpaid.io/api-reference/template-create-contract post /api/v1/template/create-contract Creates a contract based on a template and selected option. # Template Get Api Source: https://docs.justpaid.io/api-reference/template-get-api get /api/v1/template/{template_uuid} Retrieves a specific template by UUID. # Asynchronously Ingest Usage Data Source: https://docs.justpaid.io/api-reference/usage-ingest-async-api post /api/v1/usage/ingest-async Submit usage data for asynchronous processing. This endpoint accepts a list of customer events and processes them asynchronously as a batch job. The response includes a job ID that can be used to check the status of the batch job. # Retrieve Usage Data Batch Job Status Source: https://docs.justpaid.io/api-reference/usage-job-status-api get /api/v1/usage/job_status/{job_id} Get the status and results of a previously submitted usage data batch job by providing the job ID returned during submission. # JustPaid.io API Source: https://docs.justpaid.io/intro Welcome to the official JustPaid.io API documentation! Here, you'll find everything you need to seamlessly integrate our secure and reliable solutions into your applications. ## Getting Started with the API ### Setting up Please contact us to get/activate your API key. ### Dive into the Documentation This comprehensive documentation provides details on all API endpoints, request/response formats, and error handling. # Documentation Source: https://docs.justpaid.io/reminder-workflows/documentation # JustPaid Reminder Workflows Documentation ## Overview JustPaid's Automatic Reminders feature enables businesses to manage and track payment reminders efficiently, ensuring timely collections from customers. The system allows for customizable reminder workflows with advanced filtering, automated scheduling, and comprehensive activity tracking. ## Table of Contents 1. [Reminder Workflows Overview](#reminder-workflows-overview) 2. [Creating a Reminder Workflow](#creating-a-reminder-workflow) 3. [Email Configuration](#email-configuration) 4. [Filter Conditions](#filter-conditions) 5. [Reminder Schedules](#reminder-schedules) 6. [Workflow Priority System](#workflow-priority-system) 7. [Upcoming Reminders](#upcoming-reminders) 8. [Activities & Tracking](#activities--tracking) ## Reminder Workflows Overview The Reminder Workflows page serves as the central hub for managing all automated payment reminder processes. Here you can: * Create and manage multiple reminder workflows * Set up custom filters to target specific invoice types * Configure email settings for professional communication * Monitor workflow performance and effectiveness Reminder Workflows Main Page ### Key Features * **Custom Workflows**: Create unlimited reminder workflows tailored to different customer segments * **Smart Filtering**: Target specific invoices based on multiple criteria * **Priority-Based Execution**: Control which workflows take precedence * **Real-time Monitoring**: Track upcoming reminders and email activities ## Creating a Reminder Workflow To create a new reminder workflow, follow these steps: 1. Navigate to **Reminders** > **Workflows** from the sidebar 2. Click the **"Add Workflow"** button in the top right corner 3. You'll be directed to the workflow creation page Create Workflow Page ### Workflow Configuration Steps #### Step 1: Basic Information **Workflow Name** (Required) * Enter a descriptive name that reflects the workflow's purpose * Examples: "30-Day Overdue Reminders", "Pre-Due Date Courtesy Notice" * This name will help you identify the workflow in lists and reports #### Step 2: Email Configuration The email configuration section allows you to customize how reminder emails are sent: Email Configuration **Available Options:** 1. **Sender Email** * Override the default company sender email * Must be from a verified domain * Leave blank to use company defaults 2. **CC Recipients** * Add email addresses to carbon copy on all reminders * Useful for keeping account managers or supervisors informed * Click "Add Email" to include multiple recipients 3. **BCC Recipients** * Add email addresses for blind carbon copy * Perfect for internal tracking without customer visibility * Click "Add Email" to include multiple recipients 4. **Email Signature** * Create a professional signature for all reminder emails * Full HTML editor with formatting options: * Bold, Italic, Underline text * Numbered and bulleted lists * Links and images * Font size and color customization **Signature Tips:** * Copy and paste existing signatures from Gmail or other email clients * External images are automatically converted to embedded images * Upload images directly using the image button for best results * Include links to your website, social media, or contact information * Keep it professional and concise for the best impression #### Step 3: AI Enhancement (Optional) * Enable AI-powered email personalization * Currently shows "AI enhancement disabled - using manual templates" * When enabled, AI can customize email content based on customer history and context ## Filter Conditions Filter conditions determine which invoices will receive reminders through this workflow. An invoice must match ALL conditions to use the workflow. Filter Conditions ### Available Filter Fields Filter Field Options 1. **Days Overdue** * Filter by the number of days past due date * Operators: Greater than, Less than, Equals, Between * Example: "Days overdue > 30" for invoices 30+ days past due 2. **Invoice Status** * Filter by current invoice status * Options: Draft, Sent, Paid, Overdue, Void * Useful for targeting specific invoice states 3. **Customer** * Filter by specific customers or customer groups * Select from dropdown or search by name * Can include or exclude specific customers 4. **Invoice Amount** * Filter by invoice total amount * Set minimum/maximum thresholds * Example: Target high-value invoices over \$10,000 5. **Invoice Payment Status** * Filter by payment processing status * Options: Pending, Failed, Successful, Not Attempted * Useful for retry scenarios after failed payments ### Filter Logic * Multiple conditions use AND logic (all must be true) * Click **"Add condition"** to include additional filters * Use **"Clear all conditions"** to reset filters * No filters means the workflow applies to all invoices (based on priority) ### Best Practices * Start with broad filters and refine based on results * Test workflows with a small customer segment first * Document filter logic for team understanding * Review filter effectiveness regularly ## Reminder Schedules Reminder schedules are the core components of a workflow that define when and how reminders are sent to customers. Each schedule represents a specific touchpoint in your collection process. ### Schedule Overview #### Default Schedule View Reminder Schedule Default When you create a new workflow, a default reminder schedule is automatically added. This schedule is pre-configured to send an email 3 days before the invoice due date, providing a professional courtesy notice to your customers. Each schedule card displays: * **Trigger timing**: Shows when the reminder will be sent (e.g., "3 days before due date") * **Action type**: Currently supports "Send email" with plans for SMS and other channels * **Quick actions**: Copy, Edit, and Delete buttons for schedule management ### Visual UI Components #### Schedule Card Elements Reminder Schedule Default The schedule card interface includes: * **Calendar Icon**: Visual indicator for timing-based actions * **Trigger Label**: Blue badge showing the exact timing (e.g., "3 days before due date") * **Action Card**: Expandable section showing "Send email" with email icon * **Action Buttons**: Three icons on the right for Copy, Edit, and Delete operations * **Expand/Collapse**: Click anywhere on the card to expand and see the quick preview #### Expanded Edit View Schedule Edit Interface The expanded edit interface features: * **Tab Navigation**: Edit and Preview tabs for switching between configuration and visualization * **Action Buttons**: "Update Variables" and "Enhance with AI" for advanced features * **Rich Text Toolbar**: Full formatting options for professional email creation * **Variable Pills**: Clickable tags for easy insertion of dynamic content * **Save/Cancel Actions**: Clear action buttons at the bottom of the form ### Creating a Schedule 1. Click **"Add Schedule"** in the Reminder Schedule section 2. A default schedule is automatically created with "3 days before due date" timing 3. Click the **Edit** button (pencil icon) to customize the schedule ### Schedule Configuration Interface When you click the Edit button on any schedule, you'll see the comprehensive configuration interface: Schedule Edit Interface The schedule editor provides comprehensive configuration options: #### 1. Communication Medium Currently supports: * **Email**: Primary communication channel for reminder delivery * Future channels: SMS, In-app notifications (coming soon) #### 2. Timing Configuration The timing configuration determines when your reminder will be sent relative to the invoice due date: Schedule Trigger Options **When Options:** * **Before Due Date**: Proactive reminders sent X days before the invoice is due * Configurable days: 1-30 days before * Ideal for courtesy notices and payment preparation * **On Due Date**: Reminder sent on the exact due date * No day configuration needed * Perfect for same-day payment reminders * **After Due Date**: Follow-up reminders for overdue invoices * Configurable days: 1-365 days after * Essential for collections and escalation **Days Field:** * Numeric input with increment/decrement buttons * Automatically disabled for "On due date" option * Validates reasonable ranges (e.g., max 365 days) #### 3. Message Template Editor **Edit Tab Features:** **Subject Line Template:** * Customizable email subject with variable support * Default: `Payment reminder: Invoice {{invoice_number}} due {{due_date}}` * Leave empty to use system default subject **Message Template:** * Rich text editor with formatting options: * Text styles: Normal, Heading 1, Heading 2 * Formatting: Bold, Italic, Underline * Lists: Numbered and Bulleted * Links: Add payment links and URLs * Text alignment options **Available Variables:** Click or drag variables into your message: * `{{customer_name}}` - Company name * `{{contact_name}}` - Primary contact name * `{{customer_email}}` - Customer email address * `{{invoice_number}}` - Invoice identifier * `{{amount_due}}` - Outstanding amount * `{{due_date}}` - Payment due date * `{{invoice_date}}` - Original invoice date * `{{days_overdue}}` - Days past due (for overdue reminders) * `{{business_name}}` - Your company name * `{{business_email}}` - Your company email * `{{payment_link}}` - Direct payment URL * `{{payment_method_last_4}}` - Last 4 digits of saved card * `{{payment_method_brand}}` - Card brand (Visa, Mastercard, etc.) * `{{payment_method_type}}` - Payment method type * `{{has_saved_payment_method}}` - Boolean for conditional logic **Special Features:** * **Update Variables**: Refreshes available variables based on your account settings * **Enhance with AI**: Uses AI to improve and professionalize your message template * **Auto-attachment**: Invoice PDF is automatically attached to all reminder emails #### 4. Preview Tab The Preview tab provides a real-time visualization of how your reminder email will appear to recipients: Email Preview The Preview tab shows: * **Subject Line**: How it will appear with sample data * **Email Preview**: Full email rendering with: * Sample customer and invoice data * Formatted message content * Payment link button * Business signature (if configured) ### Visual Examples of Schedule Configurations #### Example 1: Pre-Due Date Reminder Schedule Edit Interface *Configuration for a friendly reminder sent 3 days before the due date* #### Example 2: Email Preview with Variables Email Preview *How your reminder appears to customers with all variables populated* #### Example 3: Timing Options Selection Schedule Trigger Options *Available timing options for scheduling your reminders* ### Managing Multiple Schedules You can create comprehensive reminder sequences: 1. **Add Another Schedule**: Click to add additional reminder touchpoints 2. **Common Patterns**: * **Gentle Approach**: 7 days before, 3 days before, on due date * **Standard Collections**: 3 days before, on due date, 3 days after, 7 days after, 14 days after * **Aggressive Collections**: Daily reminders after 30 days overdue ### Schedule Actions Each schedule has three action buttons: 1. **Copy** (duplicate icon): * Creates an exact duplicate of the schedule * Useful for creating similar schedules with minor variations * Copied schedule appears immediately below the original 2. **Edit** (pencil icon): * Opens the full schedule configuration interface * Modify timing, message content, and all settings * Changes are saved with the "Save" button 3. **Delete** (trash icon): * Removes the schedule from the workflow * Confirmation dialog prevents accidental deletion * Cannot be undone once confirmed ### Best Practices for Reminder Schedules 1. **Message Tone Progression**: * Start friendly and helpful (before due date) * Become more direct (on and shortly after due date) * Escalate urgency (significantly overdue) 2. **Timing Considerations**: * Avoid weekends for B2B customers * Consider time zones for international customers * Space reminders appropriately (not too frequent) 3. **Content Personalization**: * Use customer name and specific invoice details * Reference previous business relationship * Include clear payment instructions 4. **Testing Recommendations**: * Preview all messages before activating * Test with internal accounts first * Monitor open and click rates for optimization ### Visual Guide: Building a Complete Reminder Workflow #### Step 1: Initial Workflow Setup Create Workflow Page *Start with the workflow creation page where you name your workflow and see the default schedule* #### Step 2: Configure Email Settings Email Configuration *Expand the email configuration to customize sender details, CC/BCC recipients, and email signature* #### Step 3: Edit Schedule Details Schedule Edit Interface *Click edit on any schedule to access the full configuration interface with timing and message options* #### Step 4: Select Timing Triggers Schedule Trigger Options *Choose when reminders should be sent: before, on, or after the invoice due date* #### Step 5: Preview Your Reminder Email Preview *Use the preview tab to see exactly how your reminder will appear to customers* ### Schedule Configuration Quick Reference | Feature | Description | Best Use Case | | ---------------------- | ---------------------------------------- | ------------------------------------- | | **Before Due Date** | Send proactive reminders 1-30 days early | Courtesy notices, payment preparation | | **On Due Date** | Send on the exact due date | Same-day payment reminders | | **After Due Date** | Send 1-365 days after due date | Collections and escalation | | **Copy Schedule** | Duplicate existing schedule | Create similar reminders quickly | | **Multiple Schedules** | Add unlimited schedules per workflow | Build complete reminder sequences | | **Variable Support** | 15+ dynamic variables available | Personalize every message | | **Preview Mode** | Real-time email preview | Verify formatting before sending | | **AI Enhancement** | Improve message professionalism | Create polished templates quickly | ## Workflow Priority System The workflow priority system determines which workflow applies when an invoice matches multiple workflow filters. Workflow Priority Order ### How Priority Works 1. **Evaluation Order**: Workflows are evaluated from top to bottom 2. **First Match Wins**: Invoices use the first matching workflow 3. **No Further Evaluation**: Once matched, lower priority workflows are ignored ### Managing Priority * **Drag and Drop**: Reorder workflows by dragging the grip icon (⋮⋮⋮) * **Visual Indicators**: Higher position = higher priority * **Invoice Count**: See how many invoices each workflow affects ### Priority Best Practices 1. **Most Specific First**: Place workflows with the most specific filters at the top 2. **Catch-All Last**: Put broad or no-filter workflows at the bottom 3. **Test Changes**: Monitor invoice counts after reordering 4. **Document Logic**: Note why certain workflows have higher priority ### Example Priority Structure 1. **Before Due Date** - Customer-specific, payment failed 2. **0-30 Days Overdue** - Recent overdue invoices 3. **30-60 Days Overdue** - Moderate overdue period 4. **60-90 Days Overdue** - Serious overdue period 5. **90+ Days Overdue** - Critical collection stage 6. **After Due Template** - General catch-all workflow ## Upcoming Reminders The Upcoming Reminders tab provides visibility into scheduled reminder activities. Upcoming Reminders with Email Preview ### Reminder Count Overview The dashboard displays reminder counts for different time periods: * **Next 1 day**: Immediate upcoming reminders * **Next 7 days**: Week ahead view * **Next 15 days**: Two-week forecast * **Next 30 days**: Monthly overview ### Viewing Upcoming Reminders **Filter Options:** * **Time Range**: Select from 1, 7, 15, or 30 days (in the example above, 30 days is selected) * **Template Filter**: View reminders from specific workflows (shows "All Templates" by default) * **Search**: Find reminders by customer or invoice number ### Reminder List View The left panel shows all scheduled reminders with: * Customer name and contact email * Invoice number with quick preview link * Workflow template being used (e.g., "After Due template") * Scheduled send date and trigger timing (e.g., "on due date", "10 days after due") ### Email Preview Details When you select a reminder from the list, the right panel displays comprehensive preview information: #### Email Configuration Section Shows the complete email setup: * **To**: Recipient email address * **From**: Sender email address using the company's domain (e.g., [username@company.domain](mailto:username@company.domain)) * **BCC**: Any blind carbon copy recipients configured in the workflow #### Email Preview Section Displays exactly how the email will appear to the recipient: * **Subject Line**: The complete email subject with merged variables * **Email Content**: Full HTML preview of the email body including: * Personalized greeting with customer name * Invoice details (number, amount due, dates) * Payment link button * Company signature if configured * Professional closing with business contact information ### AI Reminders Tab * Separate view for AI-enhanced reminders * Shows personalized reminder content * Tracks AI optimization performance ## Activities & Tracking The Activities tab provides comprehensive tracking of all reminder email activities. Activities Tab ### Email Activity Summary Real-time metrics dashboard showing: 1. **Volume Metrics** * **Emails Sent**: Total reminders dispatched * **Emails Opened**: Customer engagement tracking * **Links Clicked**: Action taken on reminders * **Emails Bounced**: Delivery failures 2. **Performance Rates** * **Open Rate**: Percentage of emails opened * **Click Rate**: Percentage with link clicks ### Activity Tracking Features **Date Range Selection** * Default: Last 30 days * Custom date range picker available * Historical data retention **Search and Filter** * Search by customer name or email * Filter by event type (sent, opened, clicked, bounced) * Export capabilities for reporting ### Activity Timeline When activities are present, the timeline shows: * Timestamp of each event * Customer and invoice details * Event type with visual indicators * Email subject and preview * Detailed interaction data ### Using Activity Data 1. **Optimize Send Times**: Identify when customers engage most 2. **Improve Templates**: Test different content approaches 3. **Customer Insights**: Understand payment behavior patterns 4. **Workflow Refinement**: Adjust triggers based on effectiveness ## Best Practices ### Workflow Design 1. **Start Simple**: Begin with basic workflows and add complexity gradually 2. **Test Thoroughly**: Use test customers before broad deployment 3. **Monitor Performance**: Review activity data weekly 4. **Iterate Based on Data**: Refine triggers and content based on results ### Email Content 1. **Professional Tone**: Maintain courteous, professional communication 2. **Clear Call-to-Action**: Make payment options obvious 3. **Personalization**: Use customer and invoice variables 4. **Mobile-Friendly**: Ensure emails display well on all devices ### Compliance and Ethics 1. **Frequency Limits**: Avoid overwhelming customers with too many reminders 2. **Grace Periods**: Consider business relationships in timing 3. **Escalation Path**: Plan for non-responsive scenarios 4. **Documentation**: Keep records of all communications ## Troubleshooting ### Common Issues **No Reminders Sending** * Check workflow is enabled (toggle switch on) * Verify filter conditions aren't too restrictive * Ensure email configuration is complete * Confirm invoices match workflow criteria **Low Engagement Rates** * Review email content and subject lines * Test different send times * Verify email deliverability * Check for spam folder placement **Incorrect Recipients** * Audit filter conditions * Review workflow priority order * Verify customer email addresses * Check CC/BCC configurations ## Conclusion JustPaid's Reminder Workflows provide a powerful, flexible system for automating payment collection communications. By leveraging smart filtering, priority management, and comprehensive tracking, businesses can significantly improve their collection rates while maintaining positive customer relationships. Regular monitoring and optimization based on activity data will ensure your reminder workflows continue to perform effectively as your business grows and evolves. # Usage based billing Source: https://docs.justpaid.io/usage-based-billing # JustPaid Usage Billing Guide Usage-based billing allows companies to charge their customers based on actual usage of services or products. This guide will walk you through setting up usage-based billing in the JustPaid platform. ### Example Use Cases * A payments company might charge based on the number of ACH transactions or check payments. * A KYC compliance API might bill based on the number of KYC checks performed. * An OCR platform might charge based on the number of invoices or receipts processed. ### Step 1: Create a Customer #### Method 1: Dashboard 1. **Upload a Contract**: Start by uploading a contract to the JustPaid dashboard. 2. **Create Line Items**: Define the billable items (usage-based or fixed-fee). 3. **Invoice Schedule**: Set up the invoice schedule. 4. **Accept Contract**: Accepting the contract creates the customer and associates the contract with the customer. #### Method 2: API 1. **Create Customer Endpoint**: Call the `create customer` endpoint with the customer's email and name. 2. **Customer ID**: The system will return a unique customer ID to be used in subsequent steps. ### Step 2: Retrieve Billable Items * Use the `/items` endpoint to get all usage-based items associated with a customer. * Filter items by passing the customer ID to retrieve specific events. * The endpoint returns event details like `item name` and `item ID`. ### Step 3: Ingest Usage Data 1. **Ingest Endpoint**: Use the `usage/ingest` endpoint to record usage data. 2. **Parameters**: * `Customer ID` * `Event Name` * `Event Value` (quantity of usage) * `Timestamp` (ISO 8601 format, converted to UTC) 3. **Additional Properties**: Optionally pass additional key-value pairs for further filtering or billing metrics. 4. **Idempotency Key**: Use a unique UUID to prevent duplicate records. #### Example For an OCR company: * **Customer ID**: Provided by the system. * **Event Name**: `invoices` * **Event Value**: Number of invoices (e.g., 50) * **Timestamp**: When the event occurred (e.g., `2024-07-15T11:30:00Z`) ### Step 4: Create Billable Metrics 1. **Billing Metrics Endpoint**: Use the `/billing/metrics` endpoint to create billing metrics. 2. **Metric Types**: * **Sum**: Aggregate usage events (e.g., total number of invoices processed). * **Custom**: Define specific billing rules (e.g., bulk billing rates). ### Step 5: Invoice Generation 1. **Pre-Generated Invoices**: The system generates invoices for the service period before it ends. 2. **Usage Data Association**: Recorded usage data is mapped to the corresponding invoice. 3. **Invoice Details**: View detailed usage information under invoice details. 4. **Automatic Send**: If enabled, invoices are sent automatically after the service period ends. 5. **Manual Review**: If automatic send is disabled, invoices are held for manual review and approval. ## Error Handling * **Invalid Input**: The system will return error messages for any invalid data (e.g., missing idempotency key, incorrect event ID). * **Duplicate Events**: The system uses idempotency keys to identify and handle duplicate events. ## Conclusion By following these steps, you can effectively implement usage-based billing in JustPaid, ensuring accurate and timely billing based on actual usage. For further assistance, refer to the API documentation or contact support.