Skip to content
Sign in
  • There are no suggestions because the search field is empty.

GSAPI Invoice Batches

Manage invoice batches through GSAPI: list batches, inspect details, send invoices, and roll back eligible batches.

Version: 2026_1
Audience: Customers and integrators managing invoice delivery programmatically
Purpose: Explain how to retrieve invoice batch information, process batch sending, and perform rollbacks using the GSAPI Invoice Batch endpoints.

1. Overview

Good Sign groups invoices created in the same schedule run into an invoice batch.
Each batch contains:

  • one Batch ID (also called invoice_id)
  • a set of invoices with individual Document IDs (iheader_id)
  • delivery statuses (new, pending manual check, sent, delivered, failed)

Using GSAPI, you can:

  • retrieve batches
  • filter by organization or date
  • inspect batch details
  • send all unsent invoices in a batch
  • roll back batches (when allowed)

This article explains the API endpoints and their behavior.

2. Required User Rights

To use Invoice Batch GSAPI endpoints, your user must have:

Right ID Description
6000 GSAPI access
6001 GSAPI write access
3680 Menu – Invoice Batch
3681 Menu – Invoice Batch Send
3682 Menu – Invoice Batch Rollback

These rights mirror the UI functionality.

3. Listing Invoice Batches

Use the base endpoint to list all invoice batches for a given organization:

GET https://api.goodsign.cloud/api/interface/gsapi/invoicebatch/list

Required query parameter

Provide either:

  • organization (full organization path), or
  • org_id (organization ID)

Optional filters

Parameter Description
hierarchy Include child organizations (1 or 0)
runstart Filter by batch creation date (start)
runend Filter by batch creation date (end)
batchId / invoice_id Filter to a single batch
deliverymethod Filter by delivery method
rule_id Filter by invoice schedule ID

Figure 1: Example JSON response from invoicebatch/list

Example call

GET .../invoicebatch/list?org_id=1202&runstart=2025-10-01&runend=2025-12-31

Example result (JSON excerpt)

 [
  {
    "invoice_id": 88123,
    "InvoiceCount": 42,
    "unsent": 3,
    "pending": 2,
    "delivered": 36,
    "failed": 1,
    "runstart": "2025-12-01"
  }
]

4. Inspecting a Single Batch

To get full details for a specific batch:

GET https://api.goodsign.cloud/api/interface/gsapi/invoicebatch/actions

Required parameter

  • batchId (or invoice_id)

Optional

  • detaillevel (0–4)
Value Description
0 Summary only
1 Full invoice list
2 Only not delivered
3 Only delivered
4 Only failed

 

5. Sending Invoices in a Batch

To send all unsent invoices in a batch:

POST https://api.goodsign.cloud/api/interface/gsapi/invoicebatch/actions

Required parameters

  • batchId
  • action=send (implicit in POST)

Behavior

  • Only invoices with status New or Manual Approval Required are sent.
  • Already delivered invoices remain unchanged.
  • If >100 invoices, the system adds the send job to the work queue.

Example response

{
  "ret": 1,
  "message": "Sent to printing. Check delivery status."
} 

Figure 3: Example API response showing sending operation

6. Rolling Back a Batch

A batch can be rolled back only if none of its invoices have been sent.

To roll back:

DELETE https://api.goodsign.cloud/api/interface/gsapi/invoicebatch/actions?batchId=XXXX

Behavior

  • Removes all invoices in the batch
  • Releases tickets back to Invoice Preparation
  • Deletes the batch ID
  • Allows users to fix data issues before regenerating invoices

If any invoice is already sent, rollback is not allowed.

Figure 4: Rollback API example and response

7. Typical Use Cases

  • Monitoring invoice delivery status in external systems
  • Automated sending of new invoices after manual validation
  • Re-running schedules programmatically
  • Detecting failed deliveries for retry logic
  • Building invoice analytics dashboards using list outputs

8. Summary

Topic Description
List batches /invoicebatch/list
Inspect batch /invoicebatch/actions
Send invoices POST /invoicebatch/actions
Rollback batch DELETE /invoicebatch/actions
Required rights 3680–3682 + GSAPI rights
detaillevel Controls output granularity

9. Consultant Notes (Advanced)

Work Queue Behavior

Large batches (>100 invoices) default to asynchronous processing.
Check delivery status with a GET after a short delay.

Status Codes

Failed delivery entries include technical messages indicating the failure reason (e.g., formatting, missing delivery address, connector errors).

Hierarchical Queries

When using hierarchy=1, the system searches all sub‑organizations recursively.

Linking to UI

Batch IDs correspond exactly to the UI’s “ID” column under Billing → Invoice Batches.

Performance

Frequent polling of /invoicebatch/list is supported, but consider caching results for large organizations.