> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arcuserp.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create an AP payment
> Required API key scope: `purchasing:write`
The `migration:write` scope unlocks the `suppress_gl`, `skip_plaid`, and `idempotency_key` parameters (migration loads only).
## OpenAPI
````yaml /openapi.yaml post /ap-payments
openapi: 3.1.0
info:
title: Arcus ERP Public API
version: 1.0.0
description: >
Arcus ERP public REST API. Designed for external integrations and data
migration.
**Authentication.** Bearer token (API key) via the `Authorization` header.
Format: `Authorization: Bearer ark_live_ent__` (or
`ark_test_*` for sandbox).
API keys are issued per-entity in **Settings > Developers > API Keys**.
**Entity scoping.** The entity is encoded in the API key prefix; routes are
flat
(e.g. `/v1/accounts`, `/v1/orders`, `/v1/products`). A small set of platform
endpoints
(migration, reconciliation, events, webhook endpoints, API keys) use the
`/v1/entities/{entity_id}/...` form -- those are noted in their tags.
**Key capabilities.**
- Related-resource hydration via `?expand[]=` (see `x-arcus-expand` on each resource).
- Cursor-based pagination (`starting_after` / `ending_before` / `limit`).
- Idempotency via the `Idempotency-Key` header.
- Webhook events for asynchronous notification.
- Conditional requests / ETag for cache validation.
servers:
- url: https://api.arcuserp.com/v1
description: Arcus ERP API (accepts both live `ark_live_*` and test `ark_test_*` keys)
- url: https://dev-api.arcuserp.com/v1
description: >-
Dev sandbox API (test-only data, accepts `ark_test_*` keys against dev
RDS)
security: []
paths:
/ap-payments:
post:
tags:
- Purchasing
summary: Create an AP payment
description: >-
Required API key scope: `purchasing:write`
The `migration:write` scope unlocks the `suppress_gl`, `skip_plaid`, and
`idempotency_key` parameters (migration loads only).
operationId: createAPPaymentV1
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: string
maxLength: 64
description: Client-provided idempotency key. Requires migration:write scope.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- vendor_id
- payment_method
description: >-
Provide bill applications using **one** of two shapes:
**Shape A (recommended) -- `bill_applications` array:**
Omit top-level `amount`; the server derives it from the sum of
`bill_applications[].amount`.
```json
{
"vendor_id": "",
"payment_method": "check",
"bill_applications": [
{ "bill_id": "", "amount": 35.50 }
]
}
```
**Shape B -- `amount` + `bill_ids` array (canonical):**
Provide top-level `amount` and `bill_ids` as objects with
per-bill `amount`.
```json
{
"vendor_id": "",
"amount": 35.50,
"payment_method": "check",
"bill_ids": [{ "id": "", "amount": 35.50 }]
}
```
Both shapes are accepted. `bill_applications` is normalized to
`bill_ids` at the API boundary.
properties:
vendor_id:
type: string
format: uuid
amount:
type: number
description: >-
Total payment amount. Optional when `bill_applications` is
provided (derived from sum). Required when using `bill_ids`.
payment_method:
type: string
enum:
- check
- ach
- wire
- credit_card
- cash
- other
bill_applications:
type: array
description: >-
Preferred shape. Each item maps one vendor bill to a payment
amount. Mutually exclusive with `bill_ids`; if both are
provided, `bill_applications` takes precedence.
items:
type: object
required:
- bill_id
- amount
properties:
bill_id:
type: string
format: uuid
description: Vendor bill UUID to apply payment toward.
amount:
type: number
description: >-
Amount to apply to this bill. Must not exceed the bill
balance_due.
bill_ids:
type: array
description: >-
Alternative canonical shape. Each item maps one vendor bill
to a payment amount. Use `bill_applications` for new
integrations.
items:
type: object
required:
- id
- amount
properties:
id:
type: string
format: uuid
description: Vendor bill UUID.
amount:
type: number
description: Amount to apply to this bill.
vendor_credit_ids:
type: array
items:
type: string
format: uuid
bank_account_id:
type: string
format: uuid
payment_date:
type: string
format: date
memo:
type: string
reference_number:
type: string
notes:
type: string
suppress_gl:
type: boolean
description: >-
migration:write scope required. Skip cash/check GL posting
for historical import.
skip_plaid:
type: boolean
description: >-
migration:write scope required. Skip Plaid ACH initiation
for historical payment import.
idempotency_key:
type: string
maxLength: 64
description: >-
migration:write scope required. Client-provided idempotency
key stored on ap_payments row.
responses:
'201':
description: Created AP payment
content:
application/json:
schema:
$ref: '#/components/schemas/APPayment'
'400':
$ref: '#/components/responses/Error'
'401':
$ref: '#/components/responses/Error'
'403':
$ref: '#/components/responses/Error'
'409':
description: Idempotent replay (idempotency_key collision)
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/APPayment'
- type: object
properties:
idempotent_replay:
type: boolean
enum:
- true
security:
- ApiKeyAuth: []
components:
schemas:
APPayment:
type: object
description: A payment Arcus made to a vendor (AP-side).
properties:
id:
type: string
format: uuid
object:
type: string
enum:
- ap_payment
entity_id:
type: string
format: uuid
readOnly: true
vendor_id:
type: string
format: uuid
bill_id:
type: string
format: uuid
nullable: true
description: >-
Set when payment is applied to a single bill; null for
batch/on-account.
batch_id:
type: string
format: uuid
nullable: true
method:
type: string
enum:
- check
- ach
- wire
- credit_card
- cash
- other
amount:
type: number
currency:
type: string
default: USD
reference:
type: string
nullable: true
description: Check number, ACH trace, etc.
status:
type: string
enum:
- pending
- sent
- cleared
- voided
- returned
readOnly: true
payment_date:
type: string
format: date
cleared_date:
type: string
format: date
nullable: true
notes:
type: string
nullable: true
metadata:
type: object
nullable: true
created_at:
type: string
format: date-time
readOnly: true
ErrorEnvelope:
type: object
description: |
Canonical error response envelope. All API errors use this shape.
required:
- error
- code
properties:
error:
type: string
description: Machine-readable error key
example: not_found
code:
type: string
description: Machine-readable error code (often same as error)
example: not_found
type:
type: string
enum:
- validation_error
- permission_error
- not_found
- conflict
- rate_limit
- internal
- expand_error
- not_implemented
example: not_found
hint:
type: string
description: Human-readable one-sentence explanation (English)
example: >-
The requested order does not exist or does not belong to this
entity.
param:
type: string
description: The parameter that caused the error, if applicable
example: expand[0]
required:
type: string
description: The scope required (only on insufficient_scope errors)
example: accounts:read
request_id:
type: string
description: >-
Unique request ID for support tracing (maps to CloudWatch log
stream)
example: req_abc123
responses:
Error:
description: Error response (400/401/403/404/409/422/429/500)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
description: |
API key issued per entity via Settings > Developers > API Keys.
Each key carries scopes (e.g. orders:read, products:write).
Bearer token format: Authorization: Bearer ark_live_ent__
Test keys use ark_test_ent__. Both are issued per entity
via Settings > Developers > API Keys.
````