Skip to content

Ramp: Associate Bills

Ramp bill.postBillAssociationsResource: arguments, response, policy and SDK examples.

← Bill operations · Get started

Operation ramp.post_bill_associations_resource

Provider route: POST /developer/v1/bills/{bill_id}/associations. Alter supplies the connection’s credentials and routing.

Install @alter-ai/sdk @alter-ai/ramp with npm, or alter-sdk-ramp with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { RampIntegration } from "@alter-ai/ramp";
async function execute(input: Parameters<RampIntegration["bill"]["postBillAssociationsResource"]>[0]) {
const app = new App({ apiKey: process.env.ALTER_API_KEY! });
try {
const provider = new RampIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
const call = await provider.bill.postBillAssociationsResource(input);
const result = await call.wait();
return result.bodyJson();
} finally {
await app.close();
}
}
import os
from alter_sdk import App
from alter_sdk_ramp import RampIntegration
async def execute(arguments):
async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
provider = RampIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
call = await provider.bill.post_bill_associations_resource(arguments)
result = await call.wait()
return result.body_json()
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
pathobjectRequired within parentAdditional keys: not allowed
path.bill_idstringRequired within parent
bodyModelRequired within parentExpand Associate Bills — request body — body

Referenced models: Associate Bills — request body — body

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

FieldTypePresenceDescription and constraints
$ModelRootExpand Hold Bill — response body

Referenced models: Hold Bill — response body

16 more schemas are linked from the tables above, on the schema pages.

Associate Bills — request body — body
FieldTypePresenceDescription and constraints
$objectRoot
bill_idstringRequired within parentUnique identifier of the bill to associate.
Format: uuid
labelstringRequired within parentLabel shown on this bill for the associated bill (e.g. 'Insurance bill').
Maximum length: 64
Minimum length: 1
reverse_labelstringRequired within parentLabel shown on the associated bill for this bill (e.g. 'Rental bill').
Maximum length: 64
Minimum length: 1
Hold Bill — response body
FieldTypePresenceDescription and constraints
$objectRoot
accounting_datestringRequired within parentThe date for the bill for accounting purposes. If not specified, falls back to the bill issue date.
Format: date-time
Read only: true
accounting_field_selectionsarrayRequired within parentList of accounting field options selected to code the bill.
accounting_field_selections[]ModelEach itemExpand Hold Bill — response body — accounting field selections item
amountModelRequired within parentExpand Hold Bill — response body — amount
Amount of the bill, represented in the lowest denomination of the currency (e.g., cents for USD).
Read only: true
applied_vendor_creditsarrayRequired within parentVendor Credits that have been applied to this Bill
Read only: true
applied_vendor_credits[]ModelEach itemExpand Hold Bill — response body — applied vendor credits item
approval_statusJSONRequired within parent
approval_status (anyOf 1)stringAlternativeApproval status of the bill. Note that this is separate from the approval status for payment release.
Known values: APPROVED, INITIALIZED, PENDING, REJECTED, TERMINATED
approval_status (anyOf 2)nullAlternative
archived_atJSONRequired within parent
archived_at (anyOf 1)stringAlternativeThe datetime the bill was archived.
Format: date-time
archived_at (anyOf 2)nullAlternative
attachmentsarrayRequired within parentBusiness-visible bill attachments with their types and download URLs.
Read only: true
attachments[]ModelEach itemExpand Hold Bill — response body — attachments item
bill_ownerModelRequired within parentExpand Hold Bill — response body — bill owner
Information about the bill owner.
created_atstringRequired within parentFormat: date-time
deep_link_urlstringOptionalLink to bill in ERP, if exists.
draft_bill_created_atJSONRequired within parent
draft_bill_created_at (anyOf 1)stringAlternativeThe date the draft bill was created if this bill was created from a draft bill, otherwise None.
Format: date-time
draft_bill_created_at (anyOf 2)nullAlternative
draft_bill_idJSONRequired within parent
draft_bill_id (anyOf 1)stringAlternativeUnique identifier of the draft bill this bill was created from, if one exists.
Format: uuid
draft_bill_id (anyOf 2)nullAlternative
due_atstringRequired within parentFormat: date-time
enable_accounting_syncbooleanOptionalFlag specifying whether the bill should sync to the ERP
entity_idstringRequired within parentAssociated business entity.
Format: uuid
fx_conversion_ratestringRequired within parentFX conversion rate from bill invoice currency to payer currency.
Format: decimal
Read only: true
idstringRequired within parentFormat: uuid
inventory_line_itemsarrayRequired within parentList of inventory line items related to the bill.
inventory_line_items[]ModelEach itemExpand Hold Bill — response body — inventory line items item
invoice_numberstringOptionalThe invoice number on the bill.
invoice_urlsarrayRequired within parentPre-signed URLs for all business-visible bill attachments, including supporting files. Use attachments and filter by attachment_type INVOICE to identify the invoice document.
Read only: true
invoice_urls[]stringEach item
is_payment_sync_readybooleanRequired within parentWhether the bill is ready for payment accounting export. Can be true while status is OPEN. For bills with multiple payments, one eligible ready payment is sufficient; this field does not identify which payments are ready. Excludes manual payments, fully synced bills, and bills paid entirely with vendor credits.
Read only: true
is_withholding_releaseJSONOptional
is_withholding_release (anyOf 1)booleanAlternativeWhether this bill is a retainage withholding release bill, if applicable.
Read only: true
is_withholding_release (anyOf 2)nullAlternative
issued_atstringRequired within parentThe date the bill was issued on invoice.
Format: date-time
item_receipt_idsarrayRequired within parentList of unique identifiers for item receipts associated with this bill through matched purchase orders.
Read only: true
item_receipt_ids[]stringEach itemFormat: uuid
line_itemsarrayRequired within parentList of line items related to the bill.
line_items[]ModelEach itemExpand Hold Bill — response body — line items item
memostringOptionalMemo of the bill.
paid_atstringOptionalThe datetime the bill's payment status is set to PAID. None if the bill's payment status is OPEN
Format: date-time
paymentJSONRequired within parent
payment (anyOf 1)ModelAlternativeExpand Hold Bill — response body — payment amount, bank debit trace id, customer friendly payment id, details, effective date, id, payment date, payment method, trace id
Payment information for the bill. For bills with multiple payments, this is the first non-vendor-credit payment.
Read only: true
payment (anyOf 2)nullAlternative
posting_datestringOptionalThe date the bill was posted to the ERP. Alternatively known as accounting date, accounting sync date.
Format: date-time
purchase_order_idstringOptionalUnique identifier of matched purchase order, if one exists.
Format: uuid
Read only: true
related_billsarrayOptionalBills associated with this bill, labelled from this bill's side (e.g. the insurance bill for a rental). Only returned when bill associations are enabled for the business.
Read only: true
related_bills[]ModelEach itemExpand Hold Bill — response body — related bills item
remote_idstringOptionalThe external ID that identifies the bill on the client's side.
statusstringRequired within parentKnown values: OPEN, PAID
status_summarystringRequired within parentStatus summary of the bill.
Known values: APPROVAL_PENDING, APPROVAL_REJECTED, ARCHIVED, AWAITING_PAYMENT, AWAITING_RELEASE, BLOCKED, HELD_BY_PROVIDER, ON_HOLD, PAYMENT_COMPLETED, PAYMENT_DETAILS_MISSING, PAYMENT_ERROR, PAYMENT_NOT_INSTRUCTED, PAYMENT_PROCESSING, PAYMENT_READY, PAYMENT_SCHEDULED, PENDING_VENDOR_APPROVAL, WAITING_FOR_TRANSACTION_MATCH, WAITING_FOR_TRANSFER_MATCH, WAITING_FOR_VENDOR
Read only: true
sync_statusstringRequired within parentSync status of the bill.
Known values: BILL_AND_PAYMENT_SYNCED, BILL_SYNCED, NOT_SYNCED
Read only: true
vendorModelRequired within parentExpand Hold Bill — response body — vendor
Vendor information of the bill.
vendor_contact_idJSONRequired within parent
vendor_contact_id (anyOf 1)stringAlternativeUnique identifier of associated vendor contact.
Format: uuid
vendor_contact_id (anyOf 2)nullAlternative
vendor_memostringOptionalMemo to the vendor.

Referenced models: Hold Bill — response body — bill owner, Hold Bill — response body — accounting field selections item, Hold Bill — response body — attachments item, Hold Bill — response body — inventory line items item, Hold Bill — response body — line items item, Hold Bill — response body — payment amount, bank debit trace id, customer friendly payment id, details, effective date, id, payment date, payment method, trace id, Hold Bill — response body — vendor, Hold Bill — response body — related bills item, Hold Bill — response body — applied vendor credits item, Hold Bill — response body — amount

Hold Bill — response body — bill owner
FieldTypePresenceDescription and constraints
$objectRoot
first_namestringOptionalBill owner's first name.
idstringRequired within parentBill owner's ID.
Format: uuid
last_namestringOptionalBill owner's last name.
Hold Bill — response body — attachments item
FieldTypePresenceDescription and constraints
$objectRoot
attachment_typestringRequired within parentType of attachment.
Known values: EMAIL, FILE, INVOICE, VENDOR_CREDIT
idstringRequired within parentUnique identifier of the bill attachment.
Format: uuid
urlstringRequired within parentPre-signed URL to download the attachment.
Read only: true

SDK function policy ID: ramp.post_bill_associations_resource. Catalog operation: post_bill_associations_resource. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Required provider scopes: ["bills:write"]

Official provider source

Report an issue with this page

Necessary

Required for sign-in, security, authorization, and remembering your choices.

Always active

Analytics

Helps us understand which product and documentation features are useful.

Performance diagnostics

Uses performance tracing and privacy-masked session replay to diagnose problems.

You can change these choices at any time from Cookie settings.