Bulk invoice custom actions

This topic documents the Cloud API custom actions you can use to process bulk invoices in ClaimCenter. It provides instructions and examples for how to use the endpoints, as well as some common business flows.

To learn more about the bulk invoice process flow in ClaimCenter, refer to the Application Guide.

Validating bulk invoices

Before submitting a bulk invoice, you can use the following endpoint to validate the bulk invoice:
  • POST /claim/v1/bulk-invoices/{bulkInvoiceId}/validate

For example, the following request validates a bulk invoice:

Command

POST /claim/v1/bulk-invoices/xc:SyBBD27Rqqu0_IfugJKIs/validate

The request body must be empty.

When the request is successful and the bulk invoice is valid, the API responds with the bulk invoice with valid: true.

To learn more about validating bulk invoices in ClaimCenter, refer to the Application Guide.

Submitting bulk invoices

Once you have validated a bulk invoice, you can use the following endpoint to submit the bulk invoice for approval:

  • POST /claim/v1/bulk-invoices/{bulkInvoiceId}/submit

For example, the following request submits a bulk invoice for approval:

Command

POST /claim/v1/bulk-invoices/xc:SyBBD27Rqqu0_IfugJKIs/submit

The request body must be empty.

Response

{
    "data": {
        "attributes": {
            "approvalDate": "2026-03-10T23:27:03.296Z",
            "approvalStatus": {
                "code": "approved",
                "name": "Approved"
            },
            "approvedReportingAmount": {
                "amount": "1000.00",
                "currency": "usd"
            },
            "approvedTransactionAmount": {
                "amount": "1000.00",
                "currency": "usd"
            },
            "bulkInvoiceTotal": "1000.00",
            "currency": {
                "code": "usd",
                "name": "USD"
            },
            "defaultCostCategory": {
                "code": "medical",
                "name": "Medical"
            },
            "defaultCostType": {
                "code": "claimcost",
                "name": "Claim Cost"
            },
            "defaultPaymentType": {
                "code": "final",
                "name": "Final"
            },
            "deliveryMethod": {
                "code": "send",
                "name": "Send"
            },
            "id": "cc:SyBBD27Rqqu0_IfugJKIs",
            "invoiceNumber": "bulk-invoice-jth",
            "lastValidatedDate": "2026-03-10T23:19:40.344Z",
            "mailTo": "Ray Timothy",
            "mailingAddress": {
                "addressLine1": "287 Kensington Rd. #1A",
                "addressType": {
                    "code": "home",
                    "name": "Home"
                },
                "city": "South Pasadena",
                "country": "US",
                "displayName": "287 Kensington Rd. #1A, South Pasadena, CA 91145",
                "id": "cc:S1LCs38XCMInN5oPh4xO3",
                "postalCode": "91145",
                "state": {
                    "code": "CA",
                    "name": "California"
                }
            },
            "payTo": "Ray Timothy",
            "payee": {
                "addressBookUID": "ab:14",
                "authorizationID": "S0yW4NRM0QDR3fmgWao7B",
                "cellPhone": {
                    "countryCode": {
                        "code": "US",
                        "name": "United States (1)"
                    },
                    "displayName": "476-498-6086",
                    "number": "4764986086"
                },
                "displayName": "Ray Timothy",
                "emailAddress1": "0000@guidewire.com",
                "emailAddress2": "0000@hotmail.com",
                "firstName": "Ray",
                "id": "cc:SKafWu-LUIdp2cQ47c4e8",
                "lastName": "Timothy",
                "primaryAddress": {
                    "addressBookUID": "cc:SErD6YA5wqChnFLdSW6IP",
                    "addressLine1": "287 Kensington Rd. #1A",
                    "addressType": {
                        "code": "home",
                        "name": "Home"
                    },
                    "city": "South Pasadena",
                    "country": "US",
                    "displayName": "287 Kensington Rd. #1A, South Pasadena, CA 91145",
                    "id": "cc:StPTnAfcYGWmEpJdshd0z",
                    "postalCode": "91145",
                    "state": {
                        "code": "CA",
                        "name": "California"
                    }
                },
                "primaryPhone": "309-627-7271",
                "primaryPhoneType": {
                    "code": "work",
                    "name": "Work"
                },
                "subtype": {
                    "code": "Person",
                    "name": "Person"
                },
                "taxId": "***-**-8492",
                "workPhone": {
                    "displayName": "309-627-7271",
                    "number": "3096277271"
                }
            },
            "payeeAddressBookUID": "ab:14",
            "paymentMethod": {
                "code": "check",
                "name": "Check"
            },
            "receivedDate": "2026-03-10T00:00:00.000Z",
            "reportability": {
                "code": "reportable",
                "name": "Reportable"
            },
            "requestingUser": {
                "displayName": "Andy Applegate",
                "id": "demo_sample:1",
                "type": "User",
                "uri": "/admin/v1/users/demo_sample:1"
            },
            "scheduledSendDate": "2026-03-10T00:00:00.000Z",
            "splitEqually": true,
            "status": {
                "code": "initiatingcheckcreation",
                "name": "Initiating check creation"
            },
            "totalReportingAmount": {
                "amount": "1000.00",
                "currency": "usd"
            },
            "totalTransactionAmount": {
                "amount": "1000.00",
                "currency": "usd"
            },
            "valid": true
        }
    }
}

When the request is successful, the API returns the bulk invoice along with updated approval details. The status will also update to reflect its current state in the bulk invoice submission process. To learn more about the possible bulk invoice statuses in ClaimCenter, refer to the Application Guide.

To learn more about the bulk invoice process in ClaimCenter, refer to the Application Guide.

Stopping or voiding bulk invoices

In ClaimCenter, you can request a stop for a bulk invoice when the bulk check has been sent downstream and you now need to stop the payment. For example, you would want to stop a payment if there is suspected fraud or the check was lost in the mail.

You can request a void for a bulk invoice when the payment itself is invalid and must be treated as invalid. For example, you would want to void a payment if the payee is wrong or the amount is wrong.

You can request a stop or a void for a bulk invoice any time after it has been sent to the external system but before the associated bulk check is cleared. This means that you can stop a bulk invoice for any of the following statuses:

  • Requesting
  • Requested
  • Issued
  • On Hold

Use the following endpoints to request a stop or a void for a bulk invoice:

  • POST /claim/v1/bulk-invoices/{bulkInvoiceId}/request-stop
  • POST /claim/v1/bulk-invoices/{bulkInvoiceId}/request-void

To learn more about the stopping and voiding bulk invoices in ClaimCenter, refer to the Application Guide.

Stopping a bulk invoice

The following request is an example of how you can stop a bulk invoice that is currently in the Requesting status:

Command

POST /claim/v1/bulk-invoices/xc:SF3EIyYvshoSm2pwaUnT_/request-stop

The request body must be empty.

When the request is successful, the API responds with the updated bulk invoice and its changed status, Initiating stop. The status will then update to Pending stop, and if the downstream stop succeeds before the invoice is issued or cleared, the status will change to Stopped.

Voiding a bulk invoice

The following request is an example of how you can void a bulk invoice that is currently in the Requesting status:

Command

POST /claim/v1/bulk-invoices/xc:SF3EIyYvshoSm2pwaUnT_/request-stop

The request body must be empty.

When the request is successful, the API responds with the updated bulk invoice and its changed status, Initiating void. The status will then update to Pending void, and if the downstream void succeeds before the invoice is issued or cleared, the status will change to Voided.

Retrying bulk invoices

If a bulk invoice encounters errors during its previous processing, you can use the following endpoint to retry processing for the bulk invoice:

  • POST /claim/v1/bulk-invoices/{bulkInvoiceId}/retry

For example, the following request retries processing for a bulk invoice:

Command

POST /claim/v1/bulk-invoices/xc:SzBYD26zQGiLi4kN_a6j7/retry

The request body must be empty.

When the request is successful, the API returns the updated bulk invoice and its new status. The status after a successful retry will depend on what type of processing was happening before the errors:

Operation before retry Status after successful retry
Submission or check creation Awaiting submission
Escalation or sending checks downstream Requesting
Voiding bulk invoice Pending void
Stopping bulk invoice Pending stop
Deleting bulk invoice Retired