Bills

List bills

get

Get a paginated list of bills with optional filtering

Required scopes

This endpoint requires the following scopes:

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Query parameters

limitintegerOptional

Number of items to return

Default: 100

afterstringOptional

Cursor for forward pagination

beforestringOptional

Cursor for backward pagination

vendor_idstringOptional

Filter by vendor ID

statusstringOptional

Filter by bill status (draft, needs_approval, processing, paid, deleted, failed)

bill_numberstringOptional

Filter by bill number

sourcestringOptional

Filter by bill source (manual, quickbooks, ocr)

include_deletedbooleanOptional

Include soft-deleted bills

Responses

200

OK

application/json

end_cursorstringOptionalExample: gaFpxBACEaXBVABEYbHG+X9LyLnH

has_next_pagebooleanOptionalExample: true

has_previous_pagebooleanOptional

start_cursorstringOptionalExample: gaFpxBACEaXBVABEYbHG+X9LyLnH

get/bills

GET /bills HTTP/1.1
Host: public-api.alternativepayments.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

200

OK

{
  "data": [
    {
      "amount": 1,
      "created_at": "text",
      "description": "text",
      "due_date": "text",
      "id": "text",
      "issue_date": "text",
      "last_status": {
        "created_at": "text",
        "reason": "text",
        "status": "draft",
        "user_id": "text"
      },
      "line_items": [
        {
          "description": "text",
          "expense_account_id": "text",
          "name": "text",
          "quantity": 1,
          "sequence": 1,
          "tax": 1,
          "total": 1,
          "unit_price": 1,
          "unit_type": "text"
        }
      ],
      "number": "text",
      "pay_date": "text",
      "source": "manual",
      "status": "draft",
      "updated_at": "text",
      "vendor_id": "text",
      "vendor_payments": [
        {
          "attempt_number": 1,
          "estimated_arrival_date": "text",
          "failure_reason": "text",
          "hold_until": "text",
          "id": "text",
          "payment_method_id": "text",
          "payment_speed": "standard",
          "sent_at": "text",
          "status": "hold"
        }
      ]
    }
  ],
  "end_cursor": "gaFpxBACEaXBVABEYbHG+X9LyLnH",
  "has_next_page": true,
  "has_previous_page": false,
  "start_cursor": "gaFpxBACEaXBVABEYbHG+X9LyLnH"
}

Create a bill

post

Create a new bill. Optionally set status to "needs_approval" to skip draft and submit directly for approval.

Required scopes

This endpoint requires the following scopes:

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Body

Bill creation request

amountnumberOptional

descriptionstringOptional

due_datestringOptional

issue_datestringOptional

numberstringOptional

statusstringOptional

vendor_idstringOptional

Responses

201

Created

application/json

Bill details

amountnumberOptional

created_atstringOptional

descriptionstringOptional

due_datestringOptional

idstringOptional

issue_datestringOptional

numberstringOptional

pay_datestringOptional

sourcestring · enumOptional

Bill source enum

Possible values:

statusstring · enumOptional

Bill status enum

Possible values:

updated_atstringOptional

vendor_idstringOptional

400

Bad Request

application/json

422

Unprocessable Entity

application/json

post/bills

POST /bills HTTP/1.1
Host: public-api.alternativepayments.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 267

{
  "amount": 1,
  "description": "text",
  "due_date": "text",
  "issue_date": "text",
  "line_items": [
    {
      "description": "text",
      "expense_account_id": "text",
      "name": "text",
      "quantity": 1,
      "tax": 1,
      "total": 1,
      "unit_price": 1,
      "unit_type": "text"
    }
  ],
  "number": "text",
  "status": "text",
  "vendor_id": "text"
}

{
  "amount": 1,
  "created_at": "text",
  "description": "text",
  "due_date": "text",
  "id": "text",
  "issue_date": "text",
  "last_status": {
    "created_at": "text",
    "reason": "text",
    "status": "draft",
    "user_id": "text"
  },
  "line_items": [
    {
      "description": "text",
      "expense_account_id": "text",
      "name": "text",
      "quantity": 1,
      "sequence": 1,
      "tax": 1,
      "total": 1,
      "unit_price": 1,
      "unit_type": "text"
    }
  ],
  "number": "text",
  "pay_date": "text",
  "source": "manual",
  "status": "draft",
  "updated_at": "text",
  "vendor_id": "text",
  "vendor_payments": [
    {
      "attempt_number": 1,
      "estimated_arrival_date": "text",
      "failure_reason": "text",
      "hold_until": "text",
      "id": "text",
      "payment_method_id": "text",
      "payment_speed": "standard",
      "sent_at": "text",
      "status": "hold"
    }
  ]
}

Get a bill

get

Get bill details by ID, including line items, payment status, and status history

Required scopes

This endpoint requires the following scopes:

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

idstringRequired

Bill ID

Responses

200

OK

application/json

Bill details

amountnumberOptional

created_atstringOptional

descriptionstringOptional

due_datestringOptional

idstringOptional

issue_datestringOptional

numberstringOptional

pay_datestringOptional

sourcestring · enumOptional

Bill source enum

Possible values:

statusstring · enumOptional

Bill status enum

Possible values:

updated_atstringOptional

vendor_idstringOptional

404

Not Found

application/json

get/bills/{id}

GET /bills/{id} HTTP/1.1
Host: public-api.alternativepayments.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "amount": 1,
  "created_at": "text",
  "description": "text",
  "due_date": "text",
  "id": "text",
  "issue_date": "text",
  "last_status": {
    "created_at": "text",
    "reason": "text",
    "status": "draft",
    "user_id": "text"
  },
  "line_items": [
    {
      "description": "text",
      "expense_account_id": "text",
      "name": "text",
      "quantity": 1,
      "sequence": 1,
      "tax": 1,
      "total": 1,
      "unit_price": 1,
      "unit_type": "text"
    }
  ],
  "number": "text",
  "pay_date": "text",
  "source": "manual",
  "status": "draft",
  "updated_at": "text",
  "vendor_id": "text",
  "vendor_payments": [
    {
      "attempt_number": 1,
      "estimated_arrival_date": "text",
      "failure_reason": "text",
      "hold_until": "text",
      "id": "text",
      "payment_method_id": "text",
      "payment_speed": "standard",
      "sent_at": "text",
      "status": "hold"
    }
  ]
}

Delete a bill

delete

Soft-delete a bill. Cannot delete bills in PROCESSING or PAID status.

Required scopes

This endpoint requires the following scopes:

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

idstringRequired

Bill ID

Responses

200

OK

application/json

Bill deletion result

bill_idstringOptional

successbooleanOptional

404

Not Found

application/json

409

Conflict

application/json

delete/bills/{id}

DELETE /bills/{id} HTTP/1.1
Host: public-api.alternativepayments.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "bill_id": "text",
  "success": true
}

Update a bill

patch

Partially update bill details. Cannot update bills in PROCESSING or PAID status.

Required scopes

This endpoint requires the following scopes:

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

idstringRequired

Bill ID

Body

Bill patch request (partial update)

amountnumberOptional

descriptionstringOptional

due_datestringOptional

issue_datestringOptional

vendor_idstringOptional

Responses

200

OK

application/json

Bill details

amountnumberOptional

created_atstringOptional

descriptionstringOptional

due_datestringOptional

idstringOptional

issue_datestringOptional

numberstringOptional

pay_datestringOptional

sourcestring · enumOptional

Bill source enum

Possible values:

statusstring · enumOptional

Bill status enum

Possible values:

updated_atstringOptional

vendor_idstringOptional

400

Bad Request

application/json

404

Not Found

application/json

409

Conflict

application/json

patch/bills/{id}

PATCH /bills/{id} HTTP/1.1
Host: public-api.alternativepayments.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 260

{
  "amount": 1,
  "description": "text",
  "due_date": "text",
  "issue_date": "text",
  "line_items": {
    "items": [
      {
        "description": "text",
        "expense_account_id": "text",
        "name": "text",
        "quantity": 1,
        "tax": 1,
        "total": 1,
        "unit_price": 1,
        "unit_type": "text"
      }
    ],
    "replace": true
  },
  "vendor_id": "text"
}

{
  "amount": 1,
  "created_at": "text",
  "description": "text",
  "due_date": "text",
  "id": "text",
  "issue_date": "text",
  "last_status": {
    "created_at": "text",
    "reason": "text",
    "status": "draft",
    "user_id": "text"
  },
  "line_items": [
    {
      "description": "text",
      "expense_account_id": "text",
      "name": "text",
      "quantity": 1,
      "sequence": 1,
      "tax": 1,
      "total": 1,
      "unit_price": 1,
      "unit_type": "text"
    }
  ],
  "number": "text",
  "pay_date": "text",
  "source": "manual",
  "status": "draft",
  "updated_at": "text",
  "vendor_id": "text",
  "vendor_payments": [
    {
      "attempt_number": 1,
      "estimated_arrival_date": "text",
      "failure_reason": "text",
      "hold_until": "text",
      "id": "text",
      "payment_method_id": "text",
      "payment_speed": "standard",
      "sent_at": "text",
      "status": "hold"
    }
  ]
}

Get bill document

get

Get the download URL for a bill's attached document

Required scopes

This endpoint requires the following scopes:

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

idstringRequired

Bill ID

Responses

200

OK

application/json

Bill document download details

download_urlstringOptional

filenamestringOptional

mime_typestringOptional

404

Not Found

application/json

get/bills/{id}/document

GET /bills/{id}/document HTTP/1.1
Host: public-api.alternativepayments.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "download_url": "text",
  "filename": "text",
  "mime_type": "text"
}

Update bill pay date

post

Set or update the scheduled payment date for a bill

Required scopes

This endpoint requires the following scopes:

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

idstringRequired

Bill ID

Body

Pay date update request

pay_datestringOptional

Responses

200

OK

application/json

Pay date update result

bill_idstringOptional

400

Bad Request

application/json

404

Not Found

application/json

409

Conflict

application/json

post/bills/{id}/pay-date

POST /bills/{id}/pay-date HTTP/1.1
Host: public-api.alternativepayments.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 19

{
  "pay_date": "text"
}

{
  "bill_id": "text"
}

Reject a bill

post

Reject a bill in NEEDS_APPROVAL status, transitioning it back to DRAFT

Required scopes

This endpoint requires the following scopes:

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

idstringRequired

Bill ID

Body

Bill rejection request

reasonstringOptional

Responses

200

OK

application/json

Bill rejection result

bill_idstringOptional

400

Bad Request

application/json

404

Not Found

application/json

409

Conflict

application/json

post/bills/{id}/reject

POST /bills/{id}/reject HTTP/1.1
Host: public-api.alternativepayments.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 17

{
  "reason": "text"
}

{
  "bill_id": "text"
}

Submit bill for approval

post

Transition a bill from DRAFT to NEEDS_APPROVAL status

Required scopes

This endpoint requires the following scopes:

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

idstringRequired

Bill ID

Responses

200

OK

application/json

Bill submission result

bill_idstringOptional

successbooleanOptional

404

Not Found

application/json

409

Conflict

application/json

post/bills/{id}/submit

POST /bills/{id}/submit HTTP/1.1
Host: public-api.alternativepayments.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "bill_id": "text",
  "success": true
}

Bulk delete bills

post

Soft-delete multiple bills in a single request

Required scopes

This endpoint requires the following scopes:

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Body

Bulk bill deletion request

bill_idsstring[]Optional

Responses

200

OK

application/json

Bulk operation results

400

Bad Request

application/json

post/bills/bulk-delete

POST /bills/bulk-delete HTTP/1.1
Host: public-api.alternativepayments.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 21

{
  "bill_ids": [
    "text"
  ]
}

{
  "results": [
    {
      "bill_id": "text",
      "error_reason": "text",
      "success": true
    }
  ]
}

Bulk submit bills for approval

post

Submit multiple bills for approval in a single request

Required scopes

This endpoint requires the following scopes:

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Body

Bulk bill submission request

bill_idsstring[]Optional

Responses

200

OK

application/json

Bulk operation results

400

Bad Request

application/json

post/bills/bulk-submit

POST /bills/bulk-submit HTTP/1.1
Host: public-api.alternativepayments.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 21

{
  "bill_ids": [
    "text"
  ]
}

{
  "results": [
    {
      "bill_id": "text",
      "error_reason": "text",
      "success": true
    }
  ]
}

Upload bill document with OCR

post

Upload a document (PDF, PNG, JPEG), extract data via OCR, and create a bill

Required scopes

This endpoint requires the following scopes:

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Body

Bill document upload request

contentstringOptional

content_typestringOptional

filenamestringOptional

Responses

201

Created

application/json

Bill upload result with OCR data

bill_idstringOptional

bill_numberstringOptional

document_pathstringOptional

warningsstring[]Optional

400

Bad Request

application/json

post/bills/upload

POST /bills/upload HTTP/1.1
Host: public-api.alternativepayments.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 58

{
  "content": "text",
  "content_type": "text",
  "filename": "text"
}

{
  "bill_id": "text",
  "bill_number": "text",
  "document_path": "text",
  "extracted_data": {
    "description": "text",
    "due_date": "text",
    "invoice_number": "text",
    "issue_date": "text",
    "line_items": [
      {
        "description": "text",
        "name": "text",
        "quantity": 1,
        "total": 1,
        "unit_price": 1
      }
    ],
    "total": 1,
    "vendor_email": "text",
    "vendor_name": "text"
  },
  "warnings": [
    "text"
  ]
}